@blockcast/mmt-base 0.1.0 → 0.3.0-main.3f0b3688e8b7

package/src/mmtp.ts

@@ -91,6 +91,18 @@ export const PACKET_TYPE_REPAIR = 0x03
 // AL-FEC Signaling Message ID (ISO/IEC 23008-1:2023 Amendment 1:2025)
 export const ALFEC_MESSAGE_ID = 0x0203
 
+/**
+ * MMTP `packet_id` of the signaling flow, which carries PACKET_TYPE_SIGNALING
+ * packets such as the AL-FEC message (ALFEC_MESSAGE_ID). The FFmpeg `moq_mmt`
+ * muxer sends that message on this packet_id into the same multicast group as
+ * the media, and moqcast-draft (PR #44) makes advertising it for a track a
+ * MUST NOT. A track's packet_id is therefore 1..MMTP_PACKET_ID_MAX.
+ */
+export const MMTP_SIGNALING_PACKET_ID = 0
+
+/** Largest value of the 16-bit MMTP `packet_id` header field. */
+export const MMTP_PACKET_ID_MAX = 0xffff
+
 // FEC Code IDs
 export const FEC_CODE_XOR = 1
 export const FEC_CODE_RAPTORQ = 2
@@ -171,6 +183,32 @@ export function parseMMTPHeader(buffer: Uint8Array): MMTPHeader {
   }
 }
 
+/**
+ * The MMTP `packet_id` of `buffer`, or null exactly when parseMMTPHeader would
+ * throw for it (short buffer, V != 0, truncated packet_counter or header
+ * extension).
+ *
+ * This is the per-packet filter a receiver runs before any other work, so it
+ * builds no header object, DataView or BigInt timestamp (BLO-36599). Use
+ * parseMMTPHeader when any other header field is needed.
+ */
+export function readMMTPPacketId(buffer: Uint8Array): number | null {
+  if (buffer.length < MMTP_HEADER_SIZE) return null
+  const flags = buffer[0]!
+  if (((flags >> 6) & 0x03) !== 0) return null
+  let offset = MMTP_HEADER_SIZE
+  if ((flags & 0x20) !== 0) {
+    if (offset + 4 > buffer.length) return null
+    offset += 4
+  }
+  if ((flags & 0x02) !== 0) {
+    if (offset + 4 > buffer.length) return null
+    const length = (buffer[offset + 2]! << 8) | buffer[offset + 3]!
+    if (offset + 4 + length > buffer.length) return null
+  }
+  return (buffer[2]! << 8) | buffer[3]!
+}
+
 /**
  * Unwrap MMTP packet to extract payload
  */
@@ -236,6 +274,30 @@ export function parseTimedMfuDuHeader(payload: Uint8Array, offset: number): MFUD
   }
 }
 
+/**
+ * Why `extractMFUPayload` refused a packet.
+ *
+ * These identifiers are part of the public contract: callers surface them in
+ * diagnostics, so renaming one is a breaking change.
+ */
+export type MFURejectionGate =
+  | 'packet-shorter-than-mmtp-plus-mpu-header'
+  | 'mmtp-header-unparseable'
+  | 'not-an-mpu-packet'
+  | 'payload-shorter-than-mpu-header'
+  | 'aggregation-flag-set'
+  | 'mpu-payload-length-below-header-remainder'
+  | 'mpu-declared-end-exceeds-payload'
+  | 'mfu-offset-at-or-past-declared-end'
+  | 'source-fec-payload-id-width-mismatch'
+  | 'declared-trailers-unresolved'
+
+export interface MFURejection {
+  gate: MFURejectionGate
+  /** Human-readable detail, including the byte arithmetic that decided it. */
+  detail: string
+}
+
 interface MfuPayloadLayout {
   hasMfuDuHeader: boolean
   mfuOffset: number
@@ -246,23 +308,48 @@ function resolveMfuPayloadLayout(
   mpu: MPUHeader,
   fragmentType: number,
   payload: Uint8Array,
-): MfuPayloadLayout | null {
-  if (mpu.payloadLength < MPU_HEADER_REMAINDER_SIZE) return null
+): { layout: MfuPayloadLayout } | { rejection: MFURejection } {
+  if (mpu.payloadLength < MPU_HEADER_REMAINDER_SIZE) {
+    return {
+      rejection: {
+        gate: 'mpu-payload-length-below-header-remainder',
+        detail: `payload_length=${mpu.payloadLength} < ${MPU_HEADER_REMAINDER_SIZE}`,
+      },
+    }
+  }
 
   // ISO/IEC 23008-1 defines payload_length from immediately after its own
   // two-byte field. It therefore includes the remaining six MPU-header bytes.
   const declaredEnd = MPU_LENGTH_FIELD_SIZE + mpu.payloadLength
-  if (declaredEnd > payload.length) return null
+  if (declaredEnd > payload.length) {
+    return {
+      rejection: {
+        gate: 'mpu-declared-end-exceeds-payload',
+        detail:
+          `payload_length=${mpu.payloadLength} implies end=${declaredEnd}, ` +
+          `payload is ${payload.length} bytes`,
+      },
+    }
+  }
 
   const hasHeader = fragmentType === 2 && mpu.fragmentationIndicator <= 1
   const mfuHeaderSize = mpu.timedFlag ? MFU_DU_HEADER_SIZE_TIMED : MFU_DU_HEADER_SIZE_NONTIMED
   const mfuOffset = MPU_HEADER_SIZE + (hasHeader ? mfuHeaderSize : 0)
-  if (mfuOffset >= declaredEnd) return null
+  if (mfuOffset >= declaredEnd) {
+    return {
+      rejection: {
+        gate: 'mfu-offset-at-or-past-declared-end',
+        detail: `mfuOffset=${mfuOffset} >= declaredEnd=${declaredEnd}`,
+      },
+    }
+  }
 
   return {
-    hasMfuDuHeader: hasHeader,
-    mfuOffset,
-    dataEnd: declaredEnd,
+    layout: {
+      hasMfuDuHeader: hasHeader,
+      mfuOffset,
+      dataEnd: declaredEnd,
+    },
   }
 }
 
@@ -365,43 +452,172 @@ export interface MFUExtraction {
  *   draft-ramadan-moq-mmt-00 §3.1).
  * @returns Extracted MFU data + metadata, or null if packet is too small
  */
-export function extractMFUPayload(
+interface MfuPlan {
+  header: MMTPHeader
+  payload: Uint8Array
+  mpu: MPUHeader
+  fragmentType: number
+  layout: MfuPayloadLayout
+  trailerLayout: DeclaredTrailerLayout
+}
+
+/**
+ * Single source of truth for whether a packet yields an MFU payload.
+ *
+ * `extractMFUPayload` and `explainMFURejection` both delegate here, so the
+ * reason reported to operators can never drift from the decision the parser
+ * actually made.
+ */
+function planMfuExtraction(
   mmtpPacket: Uint8Array,
   options?: { skipFecId?: boolean },
-): MFUExtraction | null {
-  if (mmtpPacket.length < MMTP_HEADER_SIZE + MPU_HEADER_SIZE) return null
+  parsedHeader?: MMTPHeader,
+): { plan: MfuPlan } | { rejection: MFURejection } {
+  if (mmtpPacket.length < MMTP_HEADER_SIZE + MPU_HEADER_SIZE) {
+    return {
+      rejection: {
+        gate: 'packet-shorter-than-mmtp-plus-mpu-header',
+        detail: `${mmtpPacket.length} bytes < ${MMTP_HEADER_SIZE + MPU_HEADER_SIZE}`,
+      },
+    }
+  }
 
   let header: MMTPHeader
-  try {
-    header = parseMMTPHeader(mmtpPacket)
-  } catch {
-    return null
+  if (parsedHeader) {
+    header = parsedHeader
+  } else {
+    try {
+      header = parseMMTPHeader(mmtpPacket)
+    } catch (error) {
+      return {
+        rejection: {
+          gate: 'mmtp-header-unparseable',
+          detail: error instanceof Error ? error.message : String(error),
+        },
+      }
+    }
   }
-  if (header.packetType !== PACKET_TYPE_MPU) return null
+  if (header.packetType !== PACKET_TYPE_MPU) {
+    return {
+      rejection: {
+        gate: 'not-an-mpu-packet',
+        detail: `packetType=0x${header.packetType.toString(16).padStart(2, '0')}`,
+      },
+    }
+  }
+
   const payload = mmtpPacket.subarray(header.headerLength)
-  if (payload.length < MPU_HEADER_SIZE) return null
+  if (payload.length < MPU_HEADER_SIZE) {
+    return {
+      rejection: {
+        gate: 'payload-shorter-than-mpu-header',
+        detail: `${payload.length} bytes < ${MPU_HEADER_SIZE}`,
+      },
+    }
+  }
+
   const mpu = parseMPUHeader(payload)
-  if (mpu.aggregationFlag) return null
+  if (mpu.aggregationFlag) {
+    return {
+      rejection: { gate: 'aggregation-flag-set', detail: 'strict profile requires A=0' },
+    }
+  }
 
   // Fragment type from byte 2 upper nibble (not returned by parseMPUHeader)
   const fragmentType = (payload[2]! >> 4) & 0x0f
 
-  const layout = resolveMfuPayloadLayout(
-    mpu,
-    fragmentType,
+  const layoutResult = resolveMfuPayloadLayout(mpu, fragmentType, payload)
+  if ('rejection' in layoutResult) return layoutResult
+  const { layout } = layoutResult
+
+  const trailerLayout = resolveDeclaredTrailers(
     payload,
+    layout.dataEnd,
+    header.fecType,
+    options,
   )
-  if (!layout) return null
+  if (!trailerLayout) {
+    // The most common cause is a producer whose Source FEC Payload ID width
+    // disagrees with ISO/IEC 23008-1 §C.5.2. Name that explicitly rather than
+    // leaving operators to infer it from a generic trailer error.
+    if (!options?.skipFecId && header.fecType === 1) {
+      const observed = payload.length - layout.dataEnd
+      if (observed !== SOURCE_FEC_PAYLOAD_ID_SIZE) {
+        return {
+          rejection: {
+            gate: 'source-fec-payload-id-width-mismatch',
+            detail:
+              `producer wrote a ${observed}-byte Source FEC Payload ID, ` +
+              `ISO/IEC 23008-1 §C.5.2 requires ${SOURCE_FEC_PAYLOAD_ID_SIZE} ` +
+              `(payload=${payload.length}, declaredEnd=${layout.dataEnd})`,
+          },
+        }
+      }
+    }
+    return {
+      rejection: {
+        gate: 'declared-trailers-unresolved',
+        detail:
+          `trailer bytes [${layout.dataEnd}, ${payload.length}) are neither empty ` +
+          `nor an exact ALTA trailer (fecType=${header.fecType})`,
+      },
+    }
+  }
+
+  return { plan: { header, payload, mpu, fragmentType, layout, trailerLayout } }
+}
+
+/**
+ * Report why `extractMFUPayload` would refuse this packet, or null if it would
+ * accept it.
+ *
+ * `extractMFUPayload` returns bare `null` on ten distinct conditions, which
+ * makes a producer/consumer framing disagreement indistinguishable from a
+ * publisher that never started — both render as silence. Use this wherever
+ * that distinction matters: diagnostics, contract tests, and operator-facing
+ * logs.
+ */
+export function explainMFURejection(
+  mmtpPacket: Uint8Array,
+  options?: { skipFecId?: boolean },
+): MFURejection | null {
+  const result = planMfuExtraction(mmtpPacket, options)
+  return 'rejection' in result ? result.rejection : null
+}
 
-  const trailerLayout = resolveDeclaredTrailers(payload, layout.dataEnd, header.fecType, options)
-  if (!trailerLayout) return null
+export function extractMFUPayload(
+  mmtpPacket: Uint8Array,
+  options?: { skipFecId?: boolean },
+): MFUExtraction | null {
+  return extractPlannedMfu(mmtpPacket, planMfuExtraction(mmtpPacket, options))
+}
+
+/**
+ * extractMFUPayload for a caller that already holds this packet's parsed MMTP
+ * header, so the header is not parsed a second time (BLO-36599).
+ *
+ * `header` must be `parseMMTPHeader(mmtpPacket)` of this same packet; the
+ * result is then identical to `extractMFUPayload(mmtpPacket, options)`.
+ */
+export function extractMFUPayloadWithHeader(
+  mmtpPacket: Uint8Array,
+  header: MMTPHeader,
+  options?: { skipFecId?: boolean },
+): MFUExtraction | null {
+  return extractPlannedMfu(mmtpPacket, planMfuExtraction(mmtpPacket, options, header))
+}
+
+function extractPlannedMfu(
+  mmtpPacket: Uint8Array,
+  result: { plan: MfuPlan } | { rejection: MFURejection },
+): MFUExtraction | null {
+  if ('rejection' in result) return null
+  const { header, payload, mpu, fragmentType, layout, trailerLayout } = result.plan
 
   const mfuDuHeaderPresent = layout.hasMfuDuHeader
   const mfuOffset = layout.mfuOffset
   const dataEnd = layout.dataEnd
 
-  if (mfuOffset >= dataEnd) return null
-
   const mfuDuHeader =
     mfuDuHeaderPresent && mpu.timedFlag === 1
       ? parseTimedMfuDuHeader(payload, MPU_HEADER_SIZE)
@@ -449,24 +665,18 @@ export function isFecRepairPacket(mmtpPacket: Uint8Array): boolean {
  * source packet per ISO/IEC 23008-1:2023 Section C.5.2 Figure C.10.
  *
  * SS_ID is a flat 32-bit monotonic counter (incremented by 1 per packet
- * for ssbg_mode0 and ssbg_mode1).  Block membership and ESI are derived
- * at recovery time from repair packet SS_Start and SSB_length:
- *   SBN = floor(SS_ID / K),  ESI = SS_ID % K
+ * for ssbg_mode0 and ssbg_mode1). Block membership and ESI use the
+ * configured K; repair SS_Start identifies the first SS_ID of the block and
+ * SSB_length records the authored source-symbol count:
+ *   SBN = floor(SS_ID / K), ESI = SS_ID % K
  *   SS_Start = SBN * K  (first SS_ID of the block)
  *
  * This matches FFmpeg moqenc_mmt.c, the drafts (draft-ramadan-moq-fec §6.2),
  * and ATSC A/331 §8.1.2.5 which defers to ISO 23008-1 Annex C.
  */
 export function extractFecPayloadId(mmtpPacket: Uint8Array): { ssId: number } | null {
-  if (!hasSourceFecPayloadId(mmtpPacket)) return null
-  // Flat 4-byte SS_ID: encoder writes block_id * K + symbol_id
-  const off = mmtpPacket.length - SOURCE_FEC_PAYLOAD_ID_SIZE
-  const view = new DataView(
-    mmtpPacket.buffer,
-    mmtpPacket.byteOffset + off,
-    SOURCE_FEC_PAYLOAD_ID_SIZE,
-  )
-  return { ssId: view.getUint32(0, false) }
+  const header = parseHeaderForSourceFecId(mmtpPacket)
+  return header ? sourceFecPayloadIdOf(mmtpPacket, header) : null
 }
 
 /**
@@ -474,22 +684,52 @@ export function extractFecPayloadId(mmtpPacket: Uint8Array): { ssId: number } |
  * payload contains a four-byte Source FEC Payload ID.
  */
 export function hasSourceFecPayloadId(mmtpPacket: Uint8Array): boolean {
-  if (mmtpPacket.length < MMTP_HEADER_SIZE + MPU_HEADER_SIZE) return false
+  const header = parseHeaderForSourceFecId(mmtpPacket)
+  return header !== null && sourceFecPayloadIdOf(mmtpPacket, header) !== null
+}
 
-  let header: MMTPHeader
+function parseHeaderForSourceFecId(mmtpPacket: Uint8Array): MMTPHeader | null {
+  if (mmtpPacket.length < MMTP_HEADER_SIZE + MPU_HEADER_SIZE) return null
   try {
-    header = parseMMTPHeader(mmtpPacket)
+    return parseMMTPHeader(mmtpPacket)
   } catch {
-    return false
+    return null
   }
-  if (header.packetType !== PACKET_TYPE_MPU) return false
+}
+
+/**
+ * The Source FEC Payload ID of a packet whose MMTP header the caller already
+ * parsed, or null when the packet carries none: present only when FEC_type=1
+ * and the exact suffix after the ISO-declared MPU payload holds the four-byte
+ * ID (ISO/IEC 23008-1 §C.5.2). Same answer as extractFecPayloadId, without a
+ * second header parse (BLO-36599).
+ *
+ * `header` must be `parseMMTPHeader(mmtpPacket)` of this same packet.
+ */
+export function sourceFecPayloadIdOf(
+  mmtpPacket: Uint8Array,
+  header: MMTPHeader,
+): { ssId: number } | null {
+  if (mmtpPacket.length < MMTP_HEADER_SIZE + MPU_HEADER_SIZE) return null
+  if (header.packetType !== PACKET_TYPE_MPU) return null
 
   const payload = mmtpPacket.subarray(header.headerLength)
-  if (payload.length < MPU_HEADER_SIZE) return false
-  const mpu = parseMPUHeader(payload)
-  if (mpu.payloadLength < MPU_HEADER_REMAINDER_SIZE) return false
-  const declaredEnd = MPU_LENGTH_FIELD_SIZE + mpu.payloadLength
-  return resolveDeclaredTrailers(payload, declaredEnd, header.fecType)?.hasFecId ?? false
+  if (payload.length < MPU_HEADER_SIZE) return null
+  const payloadLength = (payload[0]! << 8) | payload[1]!
+  if (payloadLength < MPU_HEADER_REMAINDER_SIZE) return null
+  const declaredEnd = MPU_LENGTH_FIELD_SIZE + payloadLength
+  if (!resolveDeclaredTrailers(payload, declaredEnd, header.fecType)?.hasFecId) return null
+
+  // Flat 4-byte SS_ID: encoder writes block_id * K + symbol_id
+  const off = mmtpPacket.length - SOURCE_FEC_PAYLOAD_ID_SIZE
+  return {
+    ssId:
+      ((mmtpPacket[off]! << 24) |
+        (mmtpPacket[off + 1]! << 16) |
+        (mmtpPacket[off + 2]! << 8) |
+        mmtpPacket[off + 3]!) >>>
+      0,
+  }
 }
 
 /**
@@ -511,22 +751,34 @@ export const extractAltaTrailer = _leafExtractAltaTrailer
 /** Size of Repair FEC Payload ID per ISO/IEC 23008-1 Section C.5.3 */
 export const REPAIR_FEC_PID_SIZE = 13
 
-/** Parse the 13-byte Repair FEC Payload ID after the complete dynamic MMTP header. */
-function readRepairFecPayloadIdFields(mmtpPacket: Uint8Array): {
+/**
+ * Parse the 13-byte Repair FEC Payload ID after the complete dynamic MMTP header.
+ * `parsedHeader`, when given, must be `parseMMTPHeader(mmtpPacket)` of this
+ * same packet; it spares the second header parse (BLO-36599).
+ */
+function readRepairFecPayloadIdFields(mmtpPacket: Uint8Array, parsedHeader?: MMTPHeader): {
   packetId: number; ssStart: number; rsbLength: number; rsId: number; ssbLength: number; dataOffset: number
 } | null {
   let header: MMTPHeader
-  try {
-    header = parseMMTPHeader(mmtpPacket)
-  } catch {
-    return null
+  if (parsedHeader) {
+    header = parsedHeader
+  } else {
+    try {
+      header = parseMMTPHeader(mmtpPacket)
+    } catch {
+      return null
+    }
   }
   if (header.packetType !== PACKET_TYPE_REPAIR || header.fecType !== 2) return null
 
   const off = header.headerLength
   if (mmtpPacket.length < off + REPAIR_FEC_PID_SIZE) return null
-  const view = new DataView(mmtpPacket.buffer, mmtpPacket.byteOffset + off, REPAIR_FEC_PID_SIZE)
-  const ssStart = view.getUint32(0, false)  // 32 bits
+  const ssStart =
+    ((mmtpPacket[off]! << 24) |
+      (mmtpPacket[off + 1]! << 16) |
+      (mmtpPacket[off + 2]! << 8) |
+      mmtpPacket[off + 3]!) >>>
+    0  // 32 bits
   const rsbLength = (mmtpPacket[off + 4]! << 16) | (mmtpPacket[off + 5]! << 8) | mmtpPacket[off + 6]!  // 24 bits
   const rsId = (mmtpPacket[off + 7]! << 16) | (mmtpPacket[off + 8]! << 8) | mmtpPacket[off + 9]!  // 24 bits
   const ssbLength = (mmtpPacket[off + 10]! << 16) | (mmtpPacket[off + 11]! << 8) | mmtpPacket[off + 12]!  // 24 bits
@@ -572,7 +824,7 @@ export interface MoqRepairFrame {
   rsbLength: number
   /** RS_ID (24 bits): repair symbol index (0-based) */
   rsId: number
-  /** SSB_length (24 bits): number of source symbols (K) */
+  /** SSB_length (24 bits): authored source-symbol count (1..=configured K) */
   ssbLength: number
   /** Repair symbol data after the dynamic MMTP header and 13-byte FEC payload ID. */
   symbolData: Uint8Array
@@ -586,14 +838,36 @@ export interface MoqRepairFrame {
  *   then SS_Start (4 bytes) → block identifier
  *   then RSB_length (3 bytes) → P
  *   then RS_ID (3 bytes) → ESI = K + RS_ID
- *   then SSB_length (3 bytes) → K
+ *   then SSB_length (3 bytes) → authored source-symbol count (1..=K)
  *   then Repair Symbol Data (T bytes)
  *
  * @param frame - Raw MoQ repair frame bytes
  * @returns Parsed frame or null if invalid
  */
 export function parseMoqRepairFrame(frame: Uint8Array): MoqRepairFrame | null {
-  const repairId = readRepairFecPayloadIdFields(frame)
+  return moqRepairFrameFrom(frame, readRepairFecPayloadIdFields(frame))
+}
+
+/**
+ * parseMoqRepairFrame for a caller that already holds this frame's parsed MMTP
+ * header, so the header is not parsed a second time (BLO-36599). The router's
+ * multicast repair branch uses it: one repair packet in every K + P otherwise
+ * paid two header parses.
+ *
+ * `header` must be `parseMMTPHeader(frame)` of this same frame; the result is
+ * then identical to `parseMoqRepairFrame(frame)`.
+ */
+export function parseMoqRepairFrameWithHeader(
+  frame: Uint8Array,
+  header: MMTPHeader,
+): MoqRepairFrame | null {
+  return moqRepairFrameFrom(frame, readRepairFecPayloadIdFields(frame, header))
+}
+
+function moqRepairFrameFrom(
+  frame: Uint8Array,
+  repairId: ReturnType<typeof readRepairFecPayloadIdFields>,
+): MoqRepairFrame | null {
   if (!repairId) return null
 
   const symbolData = frame.subarray(repairId.dataOffset)
@@ -614,133 +888,5 @@ export function parseMoqRepairFrame(frame: Uint8Array): MoqRepairFrame | null {
   }
 }
 
-/**
- * AL-FEC signaling configuration parsed from ISO/IEC 23008-1:2023 Table C.3 message.
- */
-export interface AlFecConfig {
-  fecCodeId: number
-  fecPayloadIdMode: 0
-  repairSymbolSize: number
-  maximumK: number
-  maximumP: number
-  interleaveDepth: number
-  oti: Uint8Array
-}
-
-function canonicalRaptorQOtiK(oti: Uint8Array, repairSymbolSize: number): number | null {
-  if (oti.length !== 12 || oti[5] !== 0) return null
-  const transferLength = (oti[0]! * 0x1_0000_0000) +
-    (((oti[1]! << 24) | (oti[2]! << 16) | (oti[3]! << 8) | oti[4]!) >>> 0)
-  const symbolSize = (oti[6]! << 8) | oti[7]!
-  const sourceBlocks = oti[8]!
-  const subBlocks = (oti[9]! << 8) | oti[10]!
-  const alignment = oti[11]!
-  if (!Number.isSafeInteger(transferLength) || transferLength <= 0 ||
-      symbolSize !== repairSymbolSize || symbolSize === 0 || symbolSize % 8 !== 0 ||
-      sourceBlocks !== 1 || subBlocks !== 1 || alignment !== 8 ||
-      transferLength % symbolSize !== 0) {
-    return null
-  }
-  const k = transferLength / symbolSize
-  return Number.isInteger(k) && k >= 1 && k <= 56_403 ? k : null
-}
-
-/**
- * Parse AL-FEC signaling message from a full MMTP signaling packet.
- *
- * Wire format (ISO/IEC 23008-1:2023 Table C.3, Amendment 1:2025):
- *   [12-byte MMTP header (packet_type=0x02)]
- *   message_id(2)        = 0x0203
- *   version(1)
- *   message_length(2)    = length of remaining payload
- *   flags(1)             = fec_flag(1) | private_fec_flag(1) | reserved(6)
- *   fec_flow_descriptor:
- *     length(2)
- *     num_flows(1)
- *     per flow:
- *       fec_flow_id(1), source_flow_id(1), num_assets(1), packet_ids(2*N),
- *       coding_params(1), repair_symbol_size(2),
- *       [one-stage]: repair_flow_id(2), fec_code_id(1),
- *       [private_fec_flag]: private_header(1){flag(1)|len(7)},
- *         current RaptorQ profile OTI(12) + interleave_depth(1)
- *       max_k(3), max_p(3), protection_window_time(4), protection_window_size(4)
- *
- * @param mmtpPacket Full MMTP packet including 12-byte header
- * @returns Parsed config or null if not an AL-FEC signaling message
- */
-export function parseAlFecMessage(mmtpPacket: Uint8Array): AlFecConfig | null {
-  if (mmtpPacket.length < MMTP_HEADER_SIZE + 9) return null
-  let header: MMTPHeader
-  try {
-    header = parseMMTPHeader(mmtpPacket)
-  } catch {
-    return null
-  }
-  if (header.packetType !== PACKET_TYPE_SIGNALING || header.fecType !== 0) return null
-  const payload = mmtpPacket.subarray(header.headerLength)
-  if (payload.length < 9) return null
-  const view = new DataView(payload.buffer, payload.byteOffset, payload.byteLength)
-  let off = 0
-
-  const messageId = view.getUint16(off, false); off += 2
-  if (messageId !== ALFEC_MESSAGE_ID) return null
-  const version = payload[off]!; off += 1
-  const messageLength = view.getUint16(off, false); off += 2
-  if (version !== 1 || messageLength === 0 || messageLength !== payload.length - off) return null
-
-  const flags = payload[off]!; off += 1
-  const fecFlag = (flags >> 7) & 1
-  const privateFecFlag = (flags >> 6) & 1
-  if (fecFlag !== 1 || privateFecFlag !== 1 || (flags & 0x3f) !== 0x3f) return null
-
-  if (off + 2 > payload.length) return null
-  const descriptorLength = view.getUint16(off, false); off += 2
-  const descriptorEnd = off + descriptorLength
-  if (descriptorLength === 0 || descriptorEnd !== payload.length) return null
-
-  const numFlows = payload[off]!; off += 1
-  if (numFlows !== 1 || off + 3 > descriptorEnd) return null
-
-  off += 2 // fec_flow_id, source_flow_id
-  const numAssets = payload[off]!; off += 1
-  if (numAssets === 0 || off + (numAssets * 2) > descriptorEnd) return null
-  off += numAssets * 2
-
-  if (off + 3 > descriptorEnd) return null
-  const codingParams = payload[off]!; off += 1
-  const fecCodingStructure = (codingParams >> 4) & 0x0f
-  const ssbgMode = (codingParams >> 2) & 0x03
-  const ffsrptsFlag = (codingParams >> 1) & 0x01
-  const fecPayloadIdMode = codingParams & 0x01
-  if (fecCodingStructure !== 1 || ssbgMode !== 0 || ffsrptsFlag !== 0 || fecPayloadIdMode !== 0) {
-    return null
-  }
-  const repairSymbolSize = view.getUint16(off, false); off += 2
-  if (repairSymbolSize === 0 || repairSymbolSize % 8 !== 0) return null
-
-  if (off + 4 > descriptorEnd) return null
-  off += 2 // Amendment 1:2025 replaces Table C.3 with a 16-bit repair_flow_id
-  const fecCodeId = payload[off]!; off += 1
-  if (fecCodeId !== FEC_CODE_RAPTORQ) return null
-  const privateHeader = payload[off]!; off += 1
-  const privateFlag = privateHeader >> 7
-  const privateFieldLength = privateHeader & 0x7f
-  if (privateFlag !== 1 || privateFieldLength !== 13 || off + 13 > descriptorEnd) return null
-  const oti = payload.slice(off, off + 12); off += 12
-  const interleaveDepth = payload[off]!; off += 1
-  const otiK = canonicalRaptorQOtiK(oti, repairSymbolSize)
-  if (otiK === null || interleaveDepth === 0) return null
-
-  if (off + 14 !== descriptorEnd) return null
-  const maximumK = (payload[off]! << 16) | (payload[off + 1]! << 8) | payload[off + 2]!
-  off += 3
-  const maximumP = (payload[off]! << 16) | (payload[off + 1]! << 8) | payload[off + 2]!
-  off += 3
-  if (maximumK !== otiK || maximumP === 0 || maximumK + maximumP - 1 > 0x00ff_ffff) {
-    return null
-  }
-  off += 8 // protection_window_time, protection_window_size
-  if (off !== descriptorEnd) return null
-
-  return { fecCodeId, fecPayloadIdMode, repairSymbolSize, maximumK, maximumP, interleaveDepth, oti }
-}
+// The signalling-message parsers (9.3.4.2 payload header, AL-FEC message,
+// PA/MPT) live in ./signalling.ts.

package/src/net-constants.ts

@@ -0,0 +1,17 @@
+/**
+ * AMT well-known UDP port (RFC 7450 §4).
+ *
+ * The single definition for the whole repo. It lives here, in the one package
+ * both `@blockcast/mmt-transport` and `@blockcast/mmt-container` already
+ * depend on, because the two apply it on opposite sides of a boundary that
+ * does not otherwise share code:
+ *
+ * - container resolves it where `networkSource` semantics live, so a catalog
+ *   relay that names no port is reachable instead of handing a join a
+ *   portless relay that fails.
+ * - transport applies it when reading a catalog, dialling a gateway, and
+ *   answering DRIAD — but deliberately not at every boundary. Which call
+ *   sites do and do not take the default is transport's business; the
+ *   reasoning lives beside those call sites, not here.
+ */
+export const DEFAULT_AMT_RELAY_PORT = 2268;