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

package/src/mmtp-fec-session.ts

@@ -23,6 +23,15 @@
  * uses. A packet below B_0 at or after the anchor fails the session closed:
  * `stats.failClosed` reports why, and every later repair is refused.
  *
+ * Catalog-less (draft-ramadan-moq-mmt-02 8.3, 13.2): a receiver holding
+ * layer 0 under the AL-FEC message alone builds the session from the message's
+ * fec_flow entry (`alFecFlow`) instead. K, T, the code point and the repair
+ * packet_id come from that entry, and layer 0 is held at
+ * maximum_p_for_repair_flow, standing for O_0 + P_0, by the anchored clause of
+ * draft-ramadan-moq-fec-core-00 7.3.2 alone. A later version that raises the
+ * field raises the held total (updateAlFecFlow()); the message carries no
+ * millisecond budget, so the caller states the retention (fec-core-00 9.4).
+ *
  * Every repair packet that cannot be used is counted under the reason it was
  * refused, and every block ends under exactly one outcome, so a stream whose
  * FEC is doing nothing can be told apart from one with nothing to repair.
@@ -30,6 +39,8 @@
 
 import {
   admitMmtpRepairObject,
+  alFecRaptorQFlowConfig,
+  FEC_CODE_RAPTORQ,
   isoBlockContains,
   isoBlocksBehindLowerBound,
   parseFecBlockProfile,
@@ -39,6 +50,8 @@ import {
   serial32Precedes,
   ssbg1FitsSymbol,
   trimSsbg1SourceSymbol,
+  type AlFecFlow,
+  type AlFecRaptorQFlowConfig,
   type FecBlockProfile,
 } from '@blockcast/mmt-base'
 import { deriveFecRetentionBlocks, fecBlockBudgetMs } from '@blockcast/mmt-fec'
@@ -105,6 +118,25 @@ export interface MmtpFecSessionConfig {
   heldLayers?: readonly number[]
 }
 
+/**
+ * A catalog-less session: one fec_flow entry of the AL-FEC message
+ * (`parseAlFecMessage(...).flows[i]`), draft-ramadan-moq-mmt-02 8.3.
+ */
+export interface MmtpFecSessionMessageConfig {
+  /** The source track's entry; it must pass `alFecRaptorQFlowConfig`. */
+  alFecFlow: AlFecFlow
+  /**
+   * The decoder retention in blocks. The message carries no elapsed-time
+   * budget (mmt-02 7.5), so open-block state is bounded by local policy
+   * (fec-core-00 9.4); required, never defaulted.
+   */
+  retentionBlocks: number
+  Decoder: MmtpFecSessionDecoderConstructor
+}
+
+/** What updateAlFecFlow() did with a later version of the message. */
+export type MmtpFecSessionMessageUpdate = 'raised' | 'unchanged' | 'refused'
+
 /**
  * The path a symbol arrived on: its MoQT subscription, or the multicast
  * group (native SSM or AMT) carrying the same asset. The caller states it;
@@ -197,12 +229,17 @@ export class MmtpFecSession {
   readonly algorithm: 'raptorq' | 'reed-solomon'
   readonly sourceSymbols: number
   /** P_0 = B_0, the held total every repair packet is checked against. */
-  readonly repairSymbols: number
+  get repairSymbols(): number {
+    return this.#repairSymbols
+  }
   readonly symbolSize: number
   /** The decoder's retention, in blocks, derived from the catalog budget. */
   readonly retentionBlocks: number
 
   #decoder: MmtpFecSessionDecoder | null
+  #repairSymbols: number
+  /** The message entry a catalog-less session was built from; undefined under a catalog. */
+  #message: AlFecRaptorQFlowConfig | undefined
   /** Blocks a repair has defined and that are not settled yet, by SS_Start. */
   #blocks = new Map<number, BlockState>()
   /** SS_Starts of settled blocks, so a later repair for one is refused. */
@@ -240,7 +277,26 @@ export class MmtpFecSession {
    *   the scheme, the block profile, K, P_0 (`repairSymbols`), T,
    *   `interleaveDepthMs` or `reorderToleranceMs`. None is defaulted.
    */
-  constructor(config: MmtpFecSessionConfig) {
+  constructor(config: MmtpFecSessionConfig | MmtpFecSessionMessageConfig) {
+    if (config && 'alFecFlow' in config) {
+      const message = alFecRaptorQFlowConfig(config.alFecFlow)
+      if (!message) {
+        throw new Error('MmtpFecSession: the AL-FEC entry is outside draft-ramadan-moq-mmt-02 8.3 (iso-ssbg1-v1)')
+      }
+      this.#message = message
+      // Coding byte 0x14 is the iso-ssbg1-v1 profile (mmt-02 8.3).
+      this.blockProfile = parseFecBlockProfile('iso-ssbg1-v1', 'alFecFlow')
+      this.algorithm = message.fecCodeId === FEC_CODE_RAPTORQ ? 'raptorq' : 'reed-solomon'
+      this.sourceSymbols = message.maximumK
+      this.#repairSymbols = message.maximumP
+      this.symbolSize = message.repairSymbolSize
+      this.retentionBlocks = requirePositiveInteger(config.retentionBlocks, 'retentionBlocks')
+      this.#repairPacketId = message.repairFlowId
+      this.#heldLayers = layerZero(message.maximumP)
+      this.#anchorHorizon = heldLayerAnchorHorizon(this.retentionBlocks, this.sourceSymbols)
+      this.#decoder = buildDecoder(config.Decoder, this)
+      return
+    }
     const fec = config?.fec
     if (!fec || typeof fec !== 'object') {
       throw new Error('MmtpFecSession: the catalog fec instance is required')
@@ -251,7 +307,7 @@ export class MmtpFecSession {
     }
     this.algorithm = fec.scheme
     this.sourceSymbols = requirePositiveInteger(fec.sourceSymbols, 'fec.sourceSymbols')
-    this.repairSymbols = requirePositiveInteger(fec.repairSymbols, 'fec.repairSymbols')
+    this.#repairSymbols = requirePositiveInteger(fec.repairSymbols, 'fec.repairSymbols')
     this.symbolSize = requirePositiveInteger(fec.symbolSize, 'fec.symbolSize')
     const interleaveDepthMs = requireNumber(fec.interleaveDepthMs, 'fec.interleaveDepthMs')
     const reorderToleranceMs = requireNumber(fec.reorderToleranceMs, 'fec.reorderToleranceMs')
@@ -271,17 +327,38 @@ export class MmtpFecSession {
       config.heldLayers,
     )
     this.#anchorHorizon = heldLayerAnchorHorizon(this.retentionBlocks, this.sourceSymbols)
-    if (typeof config.Decoder !== 'function') {
-      throw new Error('MmtpFecSession: a decoder constructor (wasm_bindgen.MmtFecDecoder) is required')
-    }
-    const decoder = new config.Decoder(this.retentionBlocks, this.blockProfile, this.algorithm)
-    try {
-      decoder.configure_params(this.sourceSymbols, this.symbolSize)
-    } catch (error) {
-      decoder.free()
-      throw error
+    this.#decoder = buildDecoder(config.Decoder, this)
+  }
+
+  /**
+   * A later version of the AL-FEC message, catalog-less sessions only. A
+   * maximum_p_for_repair_flow above the held total raises it (`raised`): the
+   * anchored check restarts at the new total, so a block generated under the
+   * previous one stays valid before the first block carrying the new total
+   * (fec-core-00 7.3.2, mmt-02 8.3). A field at or below it changes nothing
+   * (`unchanged`): no publisher lowers it, and the check catches a wire that
+   * does. An entry with another asset, repair flow, code point, K or T, or
+   * one outside 8.3, is `refused`: that is a new source encoding, which needs
+   * a new session. A latched fail-closed stays latched either way.
+   */
+  updateAlFecFlow(flow: AlFecFlow): MmtpFecSessionMessageUpdate {
+    const held = this.#message
+    if (!held) throw new Error('MmtpFecSession: updateAlFecFlow() needs a session built from an AL-FEC entry')
+    const next = alFecRaptorQFlowConfig(flow)
+    if (
+      !next ||
+      next.sourcePacketIds[0] !== held.sourcePacketIds[0] ||
+      next.repairFlowId !== held.repairFlowId ||
+      next.fecCodeId !== held.fecCodeId ||
+      next.maximumK !== held.maximumK ||
+      next.repairSymbolSize !== held.repairSymbolSize
+    ) {
+      return 'refused'
     }
-    this.#decoder = decoder
+    if (next.maximumP <= this.#repairSymbols) return 'unchanged'
+    this.#repairSymbols = next.maximumP
+    this.#heldLayers = layerZero(next.maximumP)
+    return 'raised'
   }
 
   /** True once release() ran. */
@@ -386,7 +463,7 @@ export class MmtpFecSession {
       // An RSB_length below a held layer's total goes to the 7.3.2 stop, not
       // to the discard; the block state is unchanged either way.
       const verdict = this.#heldLayers.failsClosed(
-        repairTrackName, frame.ssStart, frame.rsbLength, this.#anchorHorizon, this.#newestSource,
+        this.#trackFor(repairTrackName), frame.ssStart, frame.rsbLength, this.#anchorHorizon, this.#newestSource,
       )
       if (verdict) {
         this.#stats.failClosed = verdict
@@ -399,7 +476,7 @@ export class MmtpFecSession {
     // fec-01 6.3.9, after the 4.5 discards and the size check, before a block
     // is placed. Without a track name only the anchored rule (b) applies.
     const verdict = this.#heldLayers.admit(
-      repairTrackName,
+      this.#trackFor(repairTrackName),
       frame.ssStart,
       frame.rsbLength,
       this.#anchorHorizon,
@@ -464,6 +541,11 @@ export class MmtpFecSession {
     return true
   }
 
+  /** Catalog-less: layer 0 has no own-track clause (mmt-02 8.3), so no track name is judged. */
+  #trackFor(repairTrackName: string | undefined): string | undefined {
+    return this.#message ? undefined : repairTrackName
+  }
+
   #drop(reason: string): Uint8Array[] {
     this.#stats.dropped[reason] = (this.#stats.dropped[reason] ?? 0) + 1
     return []
@@ -600,6 +682,24 @@ export class MmtpFecSession {
   }
 }
 
+function layerZero(total: number): HeldLayerAdmission {
+  return new HeldLayerAdmission([{ layer: 0, repairTrackName: '', rsIdOffset: 0, repairSymbols: total }])
+}
+
+function buildDecoder(Decoder: MmtpFecSessionDecoderConstructor, session: MmtpFecSession): MmtpFecSessionDecoder {
+  if (typeof Decoder !== 'function') {
+    throw new Error('MmtpFecSession: a decoder constructor (wasm_bindgen.MmtFecDecoder) is required')
+  }
+  const decoder = new Decoder(session.retentionBlocks, session.blockProfile, session.algorithm)
+  try {
+    decoder.configure_params(session.sourceSymbols, session.symbolSize)
+  } catch (error) {
+    decoder.free()
+    throw error
+  }
+  return decoder
+}
+
 function requirePositiveInteger(value: unknown, path: string): number {
   if (typeof value !== 'number' || !Number.isSafeInteger(value) || value <= 0) {
     throw new Error(`MmtpFecSession: ${path} must be a positive integer (got ${String(value)})`)