@blockcast/mmt-container 2.2.0-main.f480a7ede8b1 → 2.2.0-main.fb5c7dfbe2de

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (54) hide show
  1. package/dist/browser-runtime.js +891 -141
  2. package/dist/browser-runtime.js.map +3 -3
  3. package/dist/delta-fallback-config.js.map +1 -1
  4. package/dist/fec-manager.d.ts +67 -11
  5. package/dist/fec-manager.d.ts.map +1 -1
  6. package/dist/fec-manager.js +283 -54
  7. package/dist/fec-manager.js.map +2 -2
  8. package/dist/fec-worker-setup.js.map +1 -1
  9. package/dist/index.d.ts +1 -1
  10. package/dist/index.d.ts.map +1 -1
  11. package/dist/index.js.map +2 -2
  12. package/dist/iso-block-locator.d.ts +39 -13
  13. package/dist/iso-block-locator.d.ts.map +1 -1
  14. package/dist/iso-block-locator.js +80 -25
  15. package/dist/iso-block-locator.js.map +2 -2
  16. package/dist/media-router.js.map +1 -1
  17. package/dist/mmtp-container-parser.d.ts +42 -8
  18. package/dist/mmtp-container-parser.d.ts.map +1 -1
  19. package/dist/mmtp-container-parser.js +121 -17
  20. package/dist/mmtp-container-parser.js.map +2 -2
  21. package/dist/mmtp-container-parser.no-modules.js +120 -18
  22. package/dist/mmtp-container-parser.no-modules.js.map +2 -2
  23. package/dist/mmtp-decode-pipeline.js +121 -17
  24. package/dist/mmtp-decode-pipeline.js.map +2 -2
  25. package/dist/mmtp-router.d.ts +28 -8
  26. package/dist/mmtp-router.d.ts.map +1 -1
  27. package/dist/mmtp-router.js +407 -52
  28. package/dist/mmtp-router.js.map +2 -2
  29. package/dist/multicast-manager.d.ts +13 -3
  30. package/dist/multicast-manager.d.ts.map +1 -1
  31. package/dist/multicast-manager.js +712 -115
  32. package/dist/multicast-manager.js.map +2 -2
  33. package/dist/multicast-transport.js +2 -2
  34. package/dist/multicast-transport.js.map +2 -2
  35. package/dist/no-modules.js +121 -17
  36. package/dist/no-modules.js.map +2 -2
  37. package/dist/repair-fetch.d.ts +36 -8
  38. package/dist/repair-fetch.d.ts.map +1 -1
  39. package/dist/repair-fetch.js +285 -26
  40. package/dist/repair-fetch.js.map +3 -3
  41. package/dist/track-session.d.ts.map +1 -1
  42. package/dist/track-session.js +1 -0
  43. package/dist/track-session.js.map +2 -2
  44. package/dist/wasm-mmtp-container-parser.js +121 -17
  45. package/dist/wasm-mmtp-container-parser.js.map +2 -2
  46. package/package.json +5 -5
  47. package/src/fec-manager.ts +304 -28
  48. package/src/index.ts +2 -0
  49. package/src/iso-block-locator.ts +114 -31
  50. package/src/mmtp-container-parser.ts +210 -21
  51. package/src/mmtp-router.ts +488 -45
  52. package/src/multicast-manager.ts +44 -6
  53. package/src/repair-fetch.ts +363 -49
  54. package/src/track-session.ts +3 -0
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@blockcast/mmt-container",
3
- "version": "2.2.0-main.f480a7ede8b1",
3
+ "version": "2.2.0-main.fb5c7dfbe2de",
4
4
  "description": "MMTP/LOC container parsing for MMT over MoQ and SSM",
5
5
  "type": "module",
6
6
  "main": "dist/index.js",
@@ -169,10 +169,10 @@
169
169
  "test:watch": "vitest"
170
170
  },
171
171
  "dependencies": {
172
- "@blockcast/fec-worker": "2.2.0-main.f480a7ede8b1",
173
- "@blockcast/mmt-base": "2.2.0-main.f480a7ede8b1",
174
- "@blockcast/mmt-fec": "2.2.0-main.f480a7ede8b1",
175
- "@blockcast/mmt-manifest-verify": "2.2.0-main.f480a7ede8b1",
172
+ "@blockcast/fec-worker": "2.2.0-main.fb5c7dfbe2de",
173
+ "@blockcast/mmt-base": "2.2.0-main.fb5c7dfbe2de",
174
+ "@blockcast/mmt-fec": "2.2.0-main.fb5c7dfbe2de",
175
+ "@blockcast/mmt-manifest-verify": "2.2.0-main.fb5c7dfbe2de",
176
176
  "@noble/curves": "^1.9.7",
177
177
  "@noble/hashes": "^1.8.0",
178
178
  "ajv": "^8.17.1",
@@ -170,6 +170,17 @@ export interface FecPacketStats {
170
170
 
171
171
  export type FecSymbolSource = 'multicast' | 'moq'
172
172
 
173
+ /**
174
+ * What feedRebuiltSourceSymbol did with a rebuilt source: whether its block
175
+ * took it, and the block the synchronous decoder recovered with it, if any.
176
+ */
177
+ export interface RebuiltSourceFeed {
178
+ readonly taken: boolean
179
+ readonly recovered: Uint8Array | null
180
+ }
181
+
182
+ const NOT_TAKEN: RebuiltSourceFeed = Object.freeze({ taken: false, recovered: null })
183
+
173
184
  /**
174
185
  * One iso-ssbg1-v1 first-arrival source symbol MmtpRouter holds until a repair
175
186
  * symbol states its block: the exact protected packet (no SS_ID, unpadded),
@@ -202,6 +213,25 @@ export interface UndelimitedIsoLoss {
202
213
  readonly previousBlockStart?: number
203
214
  }
204
215
 
216
+ /**
217
+ * A pending hole the stream ran more than the locator's horizon past before
218
+ * its range repair ended (BLO-52085): no repair can state its blocks any
219
+ * more, and the release gate no longer waits for it.
220
+ */
221
+ export type ExpiredIsoHole = Pick<UndelimitedIsoLoss, 'packetId' | 'catalogTrackName' | 'holeStart' | 'holeLength'>
222
+
223
+ /**
224
+ * What a failed iso-ssbg1-v1 repair-less span was: the `length` SS_IDs from
225
+ * its start, between two stated blocks, of which `sources` arrived. No repair
226
+ * stated the blocks inside it, so the receiver cannot tell its complete
227
+ * blocks from the ones that lost a source: the span failed, not the block
228
+ * that starts it.
229
+ */
230
+ export interface IsoSpanFailure {
231
+ readonly length: number
232
+ readonly sources: number
233
+ }
234
+
205
235
  /**
206
236
  * How the multicast leg hands its symbols to this manager.
207
237
  *
@@ -511,10 +541,21 @@ export class FECManager {
511
541
  // 'pending' forever, which would park every later frame of its stream in
512
542
  // the in-order release gate. Each entry owns its handle; the callback
513
543
  // checks it still owns the key, so a settled or reset key is never touched.
514
- #pendingWorkerCleanupBounds = new Map<string, { handle: ReturnType<typeof setTimeout> }>()
544
+ /**
545
+ * Per owed Worker cleanup: the bound on its acknowledgement, when its block
546
+ * was due, and when its cleanup was asked for (see `onCleanupComplete`).
547
+ */
548
+ #pendingWorkerCleanupBounds = new Map<
549
+ string,
550
+ { handle: ReturnType<typeof setTimeout>; dueAtMs: number; askedAtMs: number }
551
+ >()
515
552
  // Source symbol count per track-scoped block — marks complete when K symbols arrive.
516
553
  #blockSourceCounts = new Map<string, number>()
517
554
  #blockSourceEsis = new Map<string, Set<number>>()
555
+ // Source ESIs per block that another FEC instance rebuilt and fed in
556
+ // (feedRebuiltSourceSymbol). Kept apart from #blockSourceEsis: they are
557
+ // not network arrivals and never make a block clean.
558
+ #blockRebuiltEsis = new Map<string, Set<number>>()
518
559
  // Authored SSB_length per block (ISO/IEC 23008-1 §C.5.3), learned from the
519
560
  // first repair symbol. The FFmpeg moq_mmt publisher closes a block every D
520
561
  // media units, usually before it holds K symbols; under iso-ssbg1-v1
@@ -523,6 +564,9 @@ export class FECManager {
523
564
  // SSB_length source arrivals and recoverable from SSB_length received
524
565
  // symbols; waiting for K fails every one of them.
525
566
  #blockAuthoredLengths = new Map<string, number>()
567
+ // Keys whose authored length is a repair-less span's (#openIsoSpan), until
568
+ // a repair states the block there or the span resolves.
569
+ #isoSpanKeys = new Set<string>()
526
570
  #ssbLengthConflictCount = 0
527
571
  #blockRepairRsIds = new Map<string, Set<number>>()
528
572
  // RSB_length per block (C.5.3 Repair FEC Payload ID): how many repair
@@ -730,13 +774,17 @@ export class FECManager {
730
774
  onBlockComplete:
731
775
  | ((sbn: number, packetId: number, catalogTrackName?: string) => void)
732
776
  | null = null
733
- /** A block reached its fail bound. `blockClass` is its class at failure. */
777
+ /**
778
+ * A block reached its fail bound. `blockClass` is its class at failure.
779
+ * `span` is set when what failed is a repair-less span starting at `sbn`.
780
+ */
734
781
  onBlockFailed:
735
782
  | ((
736
783
  sbn: number,
737
784
  packetId: number,
738
785
  catalogTrackName: string | undefined,
739
786
  blockClass: BlockClass,
787
+ span?: IsoSpanFailure,
740
788
  ) => void)
741
789
  | null = null
742
790
  /**
@@ -820,6 +868,8 @@ export class FECManager {
820
868
  * for it, which it must be.
821
869
  */
822
870
  #onUndelimitedLoss: ((loss: UndelimitedIsoLoss) => void) | null = null
871
+ /** Set with the loss handler: true takes an expired hole to close (`closeIsoHoles`). */
872
+ #onIsoHoleExpired: ((hole: ExpiredIsoHole) => boolean) | null = null
823
873
  /** A block every symbol of which vanished was created by SBN evidence. */
824
874
  onBlockVanished:
825
875
  | ((sbn: number, packetId: number, catalogTrackName: string | undefined) => void)
@@ -1474,7 +1524,12 @@ export class FECManager {
1474
1524
  timer.handle = null
1475
1525
  this.#requestRepair(sbn, packetId, catalogTrackName)
1476
1526
  }
1477
- timer.handle = setTimeout(onFire, Math.max(0, deadlineMs - performance.now()))
1527
+ timer.handle = setTimeout(
1528
+ onFire,
1529
+ this.#receiptAtMs === undefined
1530
+ ? Math.max(0, deadlineMs - performance.now())
1531
+ : this.#receiptTimerDelayMs(deadlineMs, 0),
1532
+ )
1478
1533
  this.#repairDeadlines.set(key, timer)
1479
1534
  }
1480
1535
 
@@ -1668,6 +1723,12 @@ export class FECManager {
1668
1723
  * Vanished blocks are not enumerated here: their starts are unknown until a
1669
1724
  * repair states them. The SS_IDs between two stated blocks become one
1670
1725
  * repair-less span when the later block's repair arrives (placeIsoRepair).
1726
+ *
1727
+ * A `held` source arrived before its block was known and is fed only now
1728
+ * that a repair, a span or a closed hole placed it: how far its block start
1729
+ * then lies behind the frontier measures how long the receiver held it, not
1730
+ * where the stream was, so only its SS_ID and packet_sequence_number judge
1731
+ * it (BLO-52085).
1671
1732
  */
1672
1733
  #noteSbnSeen(
1673
1734
  sbn: number,
@@ -1676,6 +1737,7 @@ export class FECManager {
1676
1737
  symbol: 'source' | 'repair',
1677
1738
  packetSequenceNumber?: number,
1678
1739
  ssId = sbn,
1740
+ held = false,
1679
1741
  ): void {
1680
1742
  const streamKey = this.#streamKey(packetId, catalogTrackName)
1681
1743
  // Arrival at FEC, not receipt (withReceiptTime): this bounds how far SS_ID
@@ -1732,7 +1794,7 @@ export class FECManager {
1732
1794
  }
1733
1795
  if (!this.#blockPrecedes(previous.sbn, sbn)) {
1734
1796
  if (symbol === 'source' && window !== null && this.#blockPrecedes(sbn, previous.sbn) && (
1735
- this.#blocksBehind(sbn, previous.sbn, packetId) > this.#isoRetentionBlocks(packetId) ||
1797
+ (!held && this.#blocksBehind(sbn, previous.sbn, packetId) > this.#isoRetentionBlocks(packetId)) ||
1736
1798
  (psn !== undefined && anchor !== undefined && serial32Precedes(ssId, anchor.ssId) &&
1737
1799
  psn !== anchor.psn && !sentInOrder({ ssId, psn }, anchor))
1738
1800
  )) {
@@ -2086,21 +2148,28 @@ export class FECManager {
2086
2148
  this.#blockWaitDeadlinesMs.delete(key)
2087
2149
  this.#repairHoldUntilMs.delete(key)
2088
2150
  this.#traceLifecycle('timeout-queued', sbn, packetId, catalogTrackName)
2089
- this.#finalizeExpiredBlock(sbn, packetId, catalogTrackName)
2151
+ this.#finalizeExpiredBlock(sbn, packetId, catalogTrackName, currentDeadlineMs ?? firedAtMs)
2090
2152
  }
2091
- timer.handle = setTimeout(onFire, Math.max(1, Math.ceil(deadlineMs - nowMs)))
2153
+ timer.handle = setTimeout(
2154
+ onFire,
2155
+ this.#receiptAtMs === undefined
2156
+ ? Math.max(1, Math.ceil(deadlineMs - nowMs))
2157
+ : this.#receiptTimerDelayMs(deadlineMs, 1),
2158
+ )
2092
2159
  this.#activeBlocks.set(key, timer)
2093
2160
  this.#indexBlockKey(key, sbn, packetId)
2094
2161
  }
2095
2162
 
2096
2163
  /**
2097
2164
  * Hand a block whose delivery is over to its decoder for finalization: the
2098
- * datagram deadline fired, or the ordered relay moved past it.
2165
+ * datagram deadline fired, or the ordered relay moved past it. `dueAtMs`
2166
+ * is when it was due: its deadline, or now.
2099
2167
  */
2100
2168
  #finalizeExpiredBlock(
2101
2169
  sbn: number,
2102
2170
  packetId: number,
2103
2171
  catalogTrackName: string | undefined,
2172
+ dueAtMs = performance.now(),
2104
2173
  ): void {
2105
2174
  const key = this.#blockKey(sbn, packetId, catalogTrackName)
2106
2175
  // A vanished block that never received a symbol holds no decoder state
@@ -2124,7 +2193,7 @@ export class FECManager {
2124
2193
  if (workerClient) {
2125
2194
  this.#pendingWorkerCleanups.add(key)
2126
2195
  this.#pendingWorkerCleanupClients.set(key, workerClient)
2127
- this.#boundOwedCleanup(key, packetId, workerClient)
2196
+ this.#boundOwedCleanup(key, packetId, workerClient, dueAtMs)
2128
2197
  workerClient.cleanup(sbn)
2129
2198
  } else {
2130
2199
  const decoder = this.#decoderForPacket(packetId, catalogTrackName)?.client
@@ -2541,7 +2610,9 @@ export class FECManager {
2541
2610
  }
2542
2611
  resetMap(this.#blockSourceCounts)
2543
2612
  resetMap(this.#blockSourceEsis)
2613
+ resetMap(this.#blockRebuiltEsis)
2544
2614
  resetMap(this.#blockAuthoredLengths)
2615
+ resetSet(this.#isoSpanKeys)
2545
2616
  resetMap(this.#blockRepairRsIds)
2546
2617
  resetMap(this.#blockRsbLengths)
2547
2618
  resetMap(this.#heldLayerStates)
@@ -2673,7 +2744,9 @@ export class FECManager {
2673
2744
  dropMap(this.#pendingWorkerCleanupClients)
2674
2745
  dropMap(this.#blockSourceCounts)
2675
2746
  dropMap(this.#blockSourceEsis)
2747
+ dropMap(this.#blockRebuiltEsis)
2676
2748
  dropMap(this.#blockAuthoredLengths)
2749
+ dropSet(this.#isoSpanKeys)
2677
2750
  dropMap(this.#blockRepairRsIds)
2678
2751
  dropMap(this.#blockRsbLengths)
2679
2752
  dropMap(this.#blockPathCounts)
@@ -3105,8 +3178,9 @@ export class FECManager {
3105
3178
  return true
3106
3179
  }
3107
3180
  /**
3108
- * Drop a block's repair hold: its FETCH ended without delivering. The block
3109
- * falls back to its multicast wait, which may already have passed.
3181
+ * Drop a block's repair hold: its FETCH ended without delivering, or brought
3182
+ * back only a repair that cannot complete it. The block falls back to its
3183
+ * multicast wait, which may already have passed.
3110
3184
  */
3111
3185
  releaseRepairHold(sbn: number, packetId: number, catalogTrackName?: string): void {
3112
3186
  const key = this.#blockKey(sbn, packetId, catalogTrackName)
@@ -3268,6 +3342,7 @@ export class FECManager {
3268
3342
  const locator = this.#growingIsoLocatorFor(packetId, catalogTrackName)
3269
3343
  const evictedBefore = locator.heldEvicted
3270
3344
  const held = locator.hold(ssId, source)
3345
+ this.#settleExpiredIsoHoles(locator, packetId, catalogTrackName)
3271
3346
  if (held && source.source === 'multicast') this.#noteMulticastSource(locator, ssId, packetId, catalogTrackName)
3272
3347
  const evicted = locator.heldEvicted - evictedBefore
3273
3348
  if (evicted > 0) {
@@ -3296,17 +3371,26 @@ export class FECManager {
3296
3371
  ssStart: number,
3297
3372
  ssbLength: number,
3298
3373
  ): IsoRepairPlacement<IsoHeldSource> {
3299
- const placement = this.#growingIsoLocatorFor(packetId, catalogTrackName).placeRepair(ssStart, ssbLength)
3374
+ const locator = this.#growingIsoLocatorFor(packetId, catalogTrackName)
3375
+ const placement = locator.placeRepair(ssStart, ssbLength)
3376
+ this.#settleExpiredIsoHoles(locator, packetId, catalogTrackName)
3300
3377
  if (placement.status !== 'placed') {
3301
3378
  this.#isoRepairRefusedCount++
3302
3379
  if (this.#isoRepairRefusedCount <= 5 || this.#isoRepairRefusedCount % 100 === 0) {
3303
3380
  console.warn(`[FECManager] packetId=${packetId} iso-ssbg1-v1 repair refused (${placement.status}): ${placement.reason}`)
3304
3381
  }
3382
+ // The repair FETCH of a span's first group brought back a shorter block:
3383
+ // the span holds more than one, so that group cannot complete it, and
3384
+ // holding the span (and every frame behind it) for the FETCH buys
3385
+ // nothing. It falls back to its multicast wait.
3386
+ if (placement.ofSpan !== undefined) this.releaseRepairHold(placement.ofSpan.start, packetId, catalogTrackName)
3305
3387
  return placement
3306
3388
  }
3389
+ // A repair states the block at its SS_Start: a span the locator kept
3390
+ // there is now that one block (IsoBlockLocator.placeRepair).
3391
+ this.#isoSpanKeys.delete(this.#blockKey(placement.block.start, packetId, catalogTrackName))
3307
3392
  if (placement.span !== undefined) this.#openIsoSpan(placement.span, packetId, catalogTrackName)
3308
3393
  if (placement.hole !== undefined) {
3309
- const locator = this.#isoLocatorFor(packetId, catalogTrackName)
3310
3394
  const hole = placement.hole.block
3311
3395
  const previous = locator.blockEndingAt(hole.start)
3312
3396
  const loss: UndelimitedIsoLoss = {
@@ -3328,18 +3412,38 @@ export class FECManager {
3328
3412
  * `handler`, instead of a repair-less span; null restores spans. Set by the
3329
3413
  * range repair scheduler; applies to every stream from its next gap. The
3330
3414
  * handler and the deferral are one setting, so no hole is ever created with
3331
- * nobody to close it.
3415
+ * nobody to close it. `onExpired` is told of each pending hole the stream
3416
+ * runs past the locator's horizon (BLO-52085): returning true, it closes
3417
+ * the hole (`closeIsoHoles`), so the span it leaves still fails and is
3418
+ * reported; otherwise the hole is discarded with its sources.
3332
3419
  */
3333
- setUndelimitedLossHandler(handler: ((loss: UndelimitedIsoLoss) => void) | null): void {
3420
+ setUndelimitedLossHandler(
3421
+ handler: ((loss: UndelimitedIsoLoss) => void) | null,
3422
+ onExpired: ((hole: ExpiredIsoHole) => boolean) | null = null,
3423
+ ): void {
3334
3424
  this.#onUndelimitedLoss = handler
3425
+ this.#onIsoHoleExpired = handler === null ? null : onExpired
3335
3426
  this.#deferIsoGaps = handler !== null
3336
3427
  for (const locator of this.#isoLocators.values()) locator.deferIncompleteGaps = this.#deferIsoGaps
3337
3428
  }
3338
3429
 
3430
+ /** Hand each hole the locator's horizon passed to its owner, or discard it (setUndelimitedLossHandler). */
3431
+ #settleExpiredIsoHoles(
3432
+ locator: IsoBlockLocator<IsoHeldSource>,
3433
+ packetId: number,
3434
+ catalogTrackName: string | undefined,
3435
+ ): void {
3436
+ for (const hole of locator.takeExpiredHoles()) {
3437
+ const expired: ExpiredIsoHole = { packetId, catalogTrackName, holeStart: hole.start, holeLength: hole.length }
3438
+ if (this.#onIsoHoleExpired?.(expired) !== true) locator.closeHolesWithin(hole.start, hole.length)
3439
+ }
3440
+ }
3441
+
3339
3442
  /**
3340
- * The range repair for a hole ended: every hole still pending inside
3341
- * `[start, start + length)` becomes a repair-less span. Returns those spans
3342
- * with the held sources they placed, for the caller to feed (MmtpRouter).
3443
+ * The range repair for a hole ended: every hole inside `[start, start +
3444
+ * length)`, pending or expired, becomes a repair-less span. Returns those
3445
+ * spans with the held sources they placed, for the caller to feed
3446
+ * (MmtpRouter).
3343
3447
  */
3344
3448
  closeIsoHoles(
3345
3449
  packetId: number,
@@ -3368,7 +3472,10 @@ export class FECManager {
3368
3472
  catalogTrackName: string | undefined,
3369
3473
  ): void {
3370
3474
  const key = this.#blockKey(span.block.start, packetId, catalogTrackName)
3371
- if (!this.#blockAuthoredLengths.has(key)) this.#blockAuthoredLengths.set(key, span.block.length)
3475
+ if (!this.#blockAuthoredLengths.has(key)) {
3476
+ this.#blockAuthoredLengths.set(key, span.block.length)
3477
+ this.#isoSpanKeys.add(key)
3478
+ }
3372
3479
  if (span.placed.length === 0) this.#materializeBlock(span.block.start, packetId, catalogTrackName, true)
3373
3480
  }
3374
3481
 
@@ -3847,13 +3954,27 @@ export class FECManager {
3847
3954
 
3848
3955
  client.onCleanupComplete((sbn: number) => {
3849
3956
  if (this.#releasedWorkerClients.has(client)) return
3850
- const cleanupKeys = [...this.#pendingWorkerCleanups].filter((key) => {
3957
+ const owed = [...this.#pendingWorkerCleanups].filter((key) => this.#pendingWorkerCleanupClients.get(key) === client)
3958
+ const cleanupKeys = owed.filter((key) => {
3851
3959
  const block = this.#parseBlockKey(key)
3852
- return block.packetId === packetId &&
3853
- block.sbn === sbn &&
3854
- this.#pendingWorkerCleanupClients.get(key) === client
3960
+ return block.packetId === packetId && block.sbn === sbn
3855
3961
  })
3856
- for (const key of cleanupKeys) this.#settleOwedCleanup(key, 'cleanup-ack')
3962
+ // A cleanup is a queue-drain barrier: the Worker took every symbol fed
3963
+ // before it was asked for first, so every block already due by then
3964
+ // is settled by this acknowledgement too, not one barrier later. The
3965
+ // client sends one barrier at a time, and the blocks a repair walk
3966
+ // stated in one span are due together (BLO-52085). That holds only
3967
+ // while no block is fed a symbol after its dueAtMs, which is its
3968
+ // receipt-scoped deadline, not when feeding stopped: a symbol fed
3969
+ // between that deadline and the block's timer, after another block's
3970
+ // barrier was asked for, would find the block settled (failed) one
3971
+ // barrier early. Walks end before D-28 (walkDeadlineAt), so that window
3972
+ // is the timer's lateness alone; whatever feeds a block past its dueAtMs
3973
+ // must leave it to its own barrier.
3974
+ const askedAtMs = Math.max(...cleanupKeys.map((key) => this.#pendingWorkerCleanupBounds.get(key)?.askedAtMs ?? -Infinity))
3975
+ const due = owed.filter((key) =>
3976
+ !cleanupKeys.includes(key) && (this.#pendingWorkerCleanupBounds.get(key)?.dueAtMs ?? Infinity) <= askedAtMs)
3977
+ for (const key of [...cleanupKeys, ...due]) this.#settleOwedCleanup(key, 'cleanup-ack')
3857
3978
  })
3858
3979
 
3859
3980
  client.onError((msg: string, code?: FecWorkerErrorCode) => {
@@ -3935,9 +4056,11 @@ export class FECManager {
3935
4056
  * fail deadline already passed, so failing it is the decision that deadline
3936
4057
  * made. A late ack then finds nothing owed and is a no-op.
3937
4058
  */
3938
- #boundOwedCleanup(key: string, packetId: number, client: FecWorkerClient): void {
4059
+ #boundOwedCleanup(key: string, packetId: number, client: FecWorkerClient, dueAtMs: number): void {
3939
4060
  this.#clearOwedCleanupBound(key)
3940
4061
  const bound = {
4062
+ dueAtMs,
4063
+ askedAtMs: performance.now(),
3941
4064
  handle: setTimeout(() => {
3942
4065
  if (this.#pendingWorkerCleanupBounds.get(key) !== bound) return
3943
4066
  this.#pendingWorkerCleanupBounds.delete(key)
@@ -4068,7 +4191,22 @@ export class FECManager {
4068
4191
  this.#isoSourceOversizeCount++
4069
4192
  return null
4070
4193
  }
4071
- const sbn = located.block.start
4194
+ return this.#feedDecoderSource(packetId, ssId, symbolData, catalogTrackName, located.block.start)
4195
+ }
4196
+
4197
+ /**
4198
+ * Hand one placed source symbol to the stream's decoder: its Worker, which
4199
+ * answers through onFrame (null here), or its synchronous decoder, whose
4200
+ * recovered block is returned. `sbn` is the SS_Start of the block a repair
4201
+ * stated for `ssId`.
4202
+ */
4203
+ #feedDecoderSource(
4204
+ packetId: number,
4205
+ ssId: number,
4206
+ symbolData: Uint8Array,
4207
+ catalogTrackName: string | undefined,
4208
+ sbn: number,
4209
+ ): Uint8Array | null {
4072
4210
  const blockKey = this.#blockKey(sbn, packetId, catalogTrackName)
4073
4211
  const syncBlockOwner = this.#syncDecoderBlockOwners.get(blockKey)
4074
4212
 
@@ -4113,6 +4251,97 @@ export class FECManager {
4113
4251
  return recovered
4114
4252
  }
4115
4253
 
4254
+ /**
4255
+ * Feed a source symbol of this stream that another FEC instance over the
4256
+ * same packets rebuilt: a keyframe overlay recovery whose base SS_ID the
4257
+ * caller determined (draft-ramadan-moq-mmt-02 7.1, 7.4.4; joint decoding,
4258
+ * BLO-52085). It joins its block's decoder as a received source would, so
4259
+ * it reduces the erasures the block still has to solve, but it is not a
4260
+ * network arrival: no transport accounting, no classification evidence,
4261
+ * no deadline refresh, and it never makes a block clean.
4262
+ *
4263
+ * Only a block a repair stated takes one (a repair-less span has no
4264
+ * decoder block). A block that is terminal, or already holds that source,
4265
+ * does not. The symbol is the exact protected packet, unpadded, as
4266
+ * feedSourceSymbol takes it.
4267
+ *
4268
+ * `recovered` is the block the synchronous decoder completed with it; the
4269
+ * caller routes it and completes the block, as for any recovery. When
4270
+ * every source of the block is then present, received or rebuilt, and no
4271
+ * decoder returned it (a Worker answers asynchronously, and reports such a
4272
+ * block as clean on its own side), the block is completed here as
4273
+ * recovered, with nothing left to route.
4274
+ */
4275
+ feedRebuiltSourceSymbol(
4276
+ packetId: number,
4277
+ ssId: number,
4278
+ symbolData: Uint8Array,
4279
+ catalogTrackName?: string,
4280
+ ): RebuiltSourceFeed {
4281
+ if (!this.#hasBlockProfile(packetId)) return NOT_TAKEN
4282
+ const located = this.#isoLocatorFor(packetId, catalogTrackName).locate(ssId)
4283
+ if (located === null || located.block.span) return NOT_TAKEN
4284
+ if (!ssbg1FitsSymbol(symbolData.byteLength, this.#trackConfig(packetId).symbolSize)) return NOT_TAKEN
4285
+ const sbn = located.block.start
4286
+ const key = this.#blockKey(sbn, packetId, catalogTrackName)
4287
+ if (this.#completedBlocks.has(key) || this.#blockSourceEsis.get(key)?.has(located.esi)) return NOT_TAKEN
4288
+ let rebuilt = this.#blockRebuiltEsis.get(key)
4289
+ if (rebuilt?.has(located.esi)) return NOT_TAKEN
4290
+ if (rebuilt === undefined) {
4291
+ rebuilt = new Set()
4292
+ this.#blockRebuiltEsis.set(key, rebuilt)
4293
+ }
4294
+ const config = this.#trackConfigs.get(packetId)
4295
+ const wasShort = config !== undefined &&
4296
+ this.#lateSourceWaitMs(key, sbn, packetId, catalogTrackName, config) !== undefined
4297
+ rebuilt.add(located.esi)
4298
+ const recovered = this.#feedDecoderSource(packetId, ssId, symbolData, catalogTrackName, sbn)
4299
+ if (recovered === null && !this.#completeWhenSourcesPresent(key, sbn, located.block.length, packetId, catalogTrackName)) {
4300
+ // The late-source cut assumed only a late source could complete this
4301
+ // block; with this source its group can, so it gets a full multicast
4302
+ // wait again, counted from now.
4303
+ // ponytail: from now, not from its sources, so it can close up to one
4304
+ // multicast wait after its uncut deadline; at most once per block, since
4305
+ // a rebuilt source only adds to what the block holds and the cut cannot
4306
+ // apply to it again. Keep the uncut deadline and re-arm to it if a lab
4307
+ // run shows that wait.
4308
+ if (wasShort && this.#activeBlocks.has(key) &&
4309
+ this.#lateSourceWaitMs(key, sbn, packetId, catalogTrackName, config!) === undefined) {
4310
+ this.#armBlockTimeout(sbn, packetId, catalogTrackName, this.#multicastWaitMs(config!))
4311
+ }
4312
+ }
4313
+ return { taken: true, recovered }
4314
+ }
4315
+
4316
+ /**
4317
+ * A block that holds every one of its `length` sources, received or
4318
+ * rebuilt by another instance, with at least one rebuilt, is recovered:
4319
+ * every packet of it was delivered, by its own arrival or by the instance
4320
+ * that rebuilt it, so nothing is routed. Returns whether it completed it.
4321
+ */
4322
+ #completeWhenSourcesPresent(
4323
+ key: string,
4324
+ sbn: number,
4325
+ length: number,
4326
+ packetId: number,
4327
+ catalogTrackName: string | undefined,
4328
+ ): boolean {
4329
+ const rebuilt = this.#blockRebuiltEsis.get(key)
4330
+ if (rebuilt === undefined || this.#completedBlocks.has(key)) return false
4331
+ let present = rebuilt.size
4332
+ for (const esi of this.#blockSourceEsis.get(key) ?? []) if (!rebuilt.has(esi)) present++
4333
+ if (present < length) return false
4334
+ this.#traceLifecycle('recovered', sbn, packetId, catalogTrackName)
4335
+ this.countRecovery(packetId, sbn, catalogTrackName)
4336
+ this.cancelBlockTimeout(sbn, packetId, catalogTrackName)
4337
+ if (catalogTrackName === undefined) {
4338
+ this.onBlockComplete?.(sbn, packetId)
4339
+ } else {
4340
+ this.onBlockComplete?.(sbn, packetId, catalogTrackName)
4341
+ }
4342
+ return true
4343
+ }
4344
+
4116
4345
  /**
4117
4346
  * fec-01 4.5: a reed-solomon repair packet whose SSB_length + RSB_length
4118
4347
  * exceeds 255, or whose RS_ID is not below RSB_length, is discarded with the
@@ -4426,7 +4655,12 @@ export class FECManager {
4426
4655
  const authoredLength = this.#blockAuthoredLengths.get(key)
4427
4656
  const rsbLength = this.#blockRsbLengths.get(key)
4428
4657
  if (authoredLength === undefined || rsbLength === undefined) return undefined
4429
- if ((this.#blockSourceCounts.get(key) ?? 0) + rsbLength >= authoredLength) return undefined
4658
+ // A source another instance rebuilt (feedRebuiltSourceSymbol) is one the
4659
+ // decoder holds: the group need only cover what neither delivered.
4660
+ let present = this.#blockSourceCounts.get(key) ?? 0
4661
+ const received = this.#blockSourceEsis.get(key)
4662
+ for (const esi of this.#blockRebuiltEsis.get(key) ?? []) if (!received?.has(esi)) present++
4663
+ if (present + rsbLength >= authoredLength) return undefined
4430
4664
  const newestSource = this.#isoLocators.get(this.#streamKey(packetId, catalogTrackName))?.newestSource
4431
4665
  if (newestSource === undefined || !serial32Precedes(serial32Add(sbn, authoredLength - 1), newestSource)) {
4432
4666
  return undefined
@@ -4598,7 +4832,8 @@ export class FECManager {
4598
4832
  * the inactivity deadline on each symbol, records the symbol's in-band
4599
4833
  * classification evidence, and marks the block clean when all of its
4600
4834
  * authored source symbols arrived: the SSB_length a repair symbol declared,
4601
- * otherwise K.
4835
+ * otherwise K. `held` marks a source held unplaced since it arrived and
4836
+ * placed only now (see #noteSbnSeen).
4602
4837
  *
4603
4838
  * Throws for a packetId that was never configured, so a classified block
4604
4839
  * never reads the manager-global K or timeout.
@@ -4609,6 +4844,7 @@ export class FECManager {
4609
4844
  catalogTrackName: string | undefined,
4610
4845
  esi: number,
4611
4846
  evidence: SourceSymbolEvidence,
4847
+ held = false,
4612
4848
  ): void {
4613
4849
  const trackConfig = this.#trackConfigs.get(packetId)
4614
4850
  if (trackConfig === undefined) {
@@ -4630,6 +4866,7 @@ export class FECManager {
4630
4866
  'source',
4631
4867
  evidence.packetSequenceNumber,
4632
4868
  Number.isInteger(esi) ? (sbn + esi) >>> 0 : sbn,
4869
+ held,
4633
4870
  )
4634
4871
 
4635
4872
  // A source ESI at or past the block's authored SSB_length contradicts it;
@@ -4674,6 +4911,20 @@ export class FECManager {
4674
4911
  this.#completeCleanBlock(key, sbn, packetId, catalogTrackName)
4675
4912
  return
4676
4913
  }
4914
+ // A late arrival can be the last source a block lacked besides those
4915
+ // another instance rebuilt (feedRebuiltSourceSymbol).
4916
+ if (
4917
+ this.#blockRebuiltEsis.has(key) &&
4918
+ this.#completeWhenSourcesPresent(
4919
+ key,
4920
+ sbn,
4921
+ this.#isoLocatorFor(packetId, catalogTrackName).blockAt(sbn)?.length ?? authoredLength,
4922
+ packetId,
4923
+ catalogTrackName,
4924
+ )
4925
+ ) {
4926
+ return
4927
+ }
4677
4928
 
4678
4929
  this.noteBlockActivity(sbn, packetId, catalogTrackName, true)
4679
4930
 
@@ -4693,7 +4944,9 @@ export class FECManager {
4693
4944
  this.cancelBlockTimeout(sbn, packetId, catalogTrackName)
4694
4945
  this.#blockSourceCounts.delete(key)
4695
4946
  this.#blockSourceEsis.delete(key)
4947
+ this.#blockRebuiltEsis.delete(key)
4696
4948
  this.#blockAuthoredLengths.delete(key)
4949
+ this.#isoSpanKeys.delete(key)
4697
4950
  this.#blockRepairRsIds.delete(key)
4698
4951
  this.#blockRsbLengths.delete(key)
4699
4952
  // BLO-3323 L15: track which SBNs reached K source-symbol arrivals so the
@@ -4735,6 +4988,20 @@ export class FECManager {
4735
4988
  return this.#receiptAtMs ?? performance.now()
4736
4989
  }
4737
4990
 
4991
+ /**
4992
+ * The whole-ms delay of a timer for `deadlineMs` armed inside a receipt
4993
+ * scope: counted from the receipt time, as the timer of a symbol fed when
4994
+ * it was received was, less the whole ms since. So it fires on the tick
4995
+ * that timer would have, never later than a delay counted from now, and
4996
+ * its handler still re-arms a timer that fires before its deadline.
4997
+ * Counted from now, a deadline set from the receipt time is rounded up
4998
+ * from another fraction of a ms (BLO-52085).
4999
+ */
5000
+ #receiptTimerDelayMs(deadlineMs: number, minMs: number): number {
5001
+ const receivedAtMs = this.#receiptAtMs!
5002
+ return Math.max(minMs, Math.ceil(deadlineMs - receivedAtMs) - Math.ceil(performance.now() - receivedAtMs))
5003
+ }
5004
+
4738
5005
  /**
4739
5006
  * A held packet admitted late arms from its (earlier) receipt time; that
4740
5007
  * never pulls in a deadline later activity already armed. Outside a
@@ -4826,6 +5093,9 @@ export class FECManager {
4826
5093
  catalogTrackName?: string,
4827
5094
  ): void {
4828
5095
  const key = this.#blockKey(sbn, packetId, catalogTrackName)
5096
+ const span: IsoSpanFailure | undefined = this.#isoSpanKeys.delete(key)
5097
+ ? { length: this.#blockAuthoredLengths.get(key) ?? 0, sources: this.#blockSourceCounts.get(key) ?? 0 }
5098
+ : undefined
4829
5099
  this.#traceLifecycle('failed', sbn, packetId, catalogTrackName)
4830
5100
  this.#clearRepairDeadline(key)
4831
5101
  this.#clearBlockTimer(key)
@@ -4835,6 +5105,7 @@ export class FECManager {
4835
5105
  }
4836
5106
  this.#blockSourceCounts.delete(key)
4837
5107
  this.#blockSourceEsis.delete(key)
5108
+ this.#blockRebuiltEsis.delete(key)
4838
5109
  this.#blockAuthoredLengths.delete(key)
4839
5110
  this.#blockRepairRsIds.delete(key)
4840
5111
  this.#blockRsbLengths.delete(key)
@@ -4844,7 +5115,8 @@ export class FECManager {
4844
5115
  this.#markPathBlockComplete(sbn, packetId, catalogTrackName)
4845
5116
  this.#fecStats.blocksFailed++
4846
5117
  this.#statsForPacket(packetId).blocksFailed++
4847
- this.onBlockFailed?.(sbn, packetId, catalogTrackName, blockClass)
5118
+ if (span === undefined) this.onBlockFailed?.(sbn, packetId, catalogTrackName, blockClass)
5119
+ else this.onBlockFailed?.(sbn, packetId, catalogTrackName, blockClass, span)
4848
5120
  this.onBlockResolved?.(sbn, packetId, catalogTrackName)
4849
5121
  }
4850
5122
 
@@ -4874,7 +5146,9 @@ export class FECManager {
4874
5146
  this.#retireBlockClass(key, block.sbn, block.packetId, block.catalogTrackName)
4875
5147
  this.#blockSourceCounts.delete(key)
4876
5148
  this.#blockSourceEsis.delete(key)
5149
+ this.#blockRebuiltEsis.delete(key)
4877
5150
  this.#blockAuthoredLengths.delete(key)
5151
+ this.#isoSpanKeys.delete(key)
4878
5152
  this.#blockRepairRsIds.delete(key)
4879
5153
  this.#blockRsbLengths.delete(key)
4880
5154
  this.#clearBlockTimer(key)
@@ -4982,7 +5256,9 @@ export class FECManager {
4982
5256
  this.#blockKeysBySbn.clear()
4983
5257
  this.#blockSourceCounts.clear()
4984
5258
  this.#blockSourceEsis.clear()
5259
+ this.#blockRebuiltEsis.clear()
4985
5260
  this.#blockAuthoredLengths.clear()
5261
+ this.#isoSpanKeys.clear()
4986
5262
  this.#blockRepairRsIds.clear()
4987
5263
  this.#blockRsbLengths.clear()
4988
5264
  this.#heldLayerStates.clear()
package/src/index.ts CHANGED
@@ -260,6 +260,8 @@ export {
260
260
  type FecStats,
261
261
  type MulticastSymbolDelivery,
262
262
  type UndelimitedIsoLoss,
263
+ type ExpiredIsoHole,
264
+ type IsoSpanFailure,
263
265
  type FecBlockResolution,
264
266
  type RepairVia,
265
267
  type FecRepairLayer,