@blockcast/mmt-container 0.1.0

package/src/mfu-reassembler.ts

@@ -0,0 +1,416 @@
+/**
+ * @mmt/container - MFU Fragment Reassembler
+ *
+ * Handles out-of-order delivery of fragmented MFUs (Media Fragment Units)
+ * according to ISO/IEC 23008-1:2023 Section 9.2.3.3
+ *
+ * Fragmentation Indicator (FI) values:
+ * - 0: Complete MFU (single packet, no fragmentation)
+ * - 1: First fragment
+ * - 2: Middle fragment
+ * - 3: Last fragment
+ *
+ * @packageDocumentation
+ */
+
+import {
+  type MMTPPacket,
+  unwrapMMTP,
+  parseMPUHeader,
+  isFecRepairPacket,
+  MPU_HEADER_SIZE,
+  MFU_DU_HEADER_SIZE,
+} from './mmtp.js'
+
+/**
+ * MFU Fragment for reassembly
+ */
+export interface MFUFragment {
+  fragmentationIndicator: number
+  mpuSequenceNumber: number
+  fragmentCounter: number
+  data: Uint8Array
+  timestamp: bigint
+  receivedAt: number
+  /** Random Access Point flag from MMTP header - indicates keyframe */
+  rapFlag: boolean
+}
+
+/**
+ * Reassembled MFU result
+ */
+export interface ReassembledMFU {
+  mpuSequenceNumber: number
+  data: Uint8Array
+  timestamp: bigint
+  fragmentCount: number
+  /** Random Access Point flag - indicates keyframe (from first fragment) */
+  rapFlag: boolean
+}
+
+/**
+ * Reassembler statistics
+ */
+export interface ReassemblerStats {
+  totalFragments: number
+  reassembledMFUs: number
+  timedOutMFUs: number
+  outOfOrderFragments: number
+}
+
+export interface MFUReassemblerOptions {
+  /** Timeout in milliseconds for incomplete MFUs (default: 1000) */
+  timeoutMs?: number
+  /** Maximum buffered MFUs before eviction (default: 100) */
+  maxBuffered?: number
+}
+
+/**
+ * MFU Reassembler for out-of-order fragment delivery
+ * Based on ISO/IEC 23008-1:2023 Section 9.2.3.3
+ */
+export class MFUReassembler {
+  #buffers: Map<number, MFUFragment[]> = new Map()
+  #timeouts: Map<number, ReturnType<typeof setTimeout>> = new Map()
+  #timeoutMs: number
+  #maxBuffered: number
+
+  /** Statistics for debugging */
+  readonly stats: ReassemblerStats = {
+    totalFragments: 0,
+    reassembledMFUs: 0,
+    timedOutMFUs: 0,
+    outOfOrderFragments: 0,
+  }
+
+  constructor(options?: MFUReassemblerOptions) {
+    this.#timeoutMs = options?.timeoutMs ?? 1000
+    this.#maxBuffered = options?.maxBuffered ?? 100
+  }
+
+  /**
+   * Add a fragment and return reassembled MFU if complete
+   */
+  addFragment(fragment: MFUFragment): ReassembledMFU | null {
+    this.stats.totalFragments++
+
+    const { mpuSequenceNumber, fragmentationIndicator, fragmentCounter } = fragment
+
+    // Handle complete MFU (FI=0)
+    if (fragmentationIndicator === 0) {
+      this.stats.reassembledMFUs++
+      return {
+        mpuSequenceNumber,
+        data: fragment.data,
+        timestamp: fragment.timestamp,
+        fragmentCount: 1,
+        rapFlag: fragment.rapFlag,
+      }
+    }
+
+    // Get or create fragment buffer for this MPU
+    let fragments = this.#buffers.get(mpuSequenceNumber)
+    if (!fragments) {
+      fragments = []
+      this.#buffers.set(mpuSequenceNumber, fragments)
+      this.#setTimeout(mpuSequenceNumber)
+    }
+
+    // Check for duplicate fragment
+    const existingIdx = fragments.findIndex((f) => f.fragmentCounter === fragmentCounter)
+    if (existingIdx >= 0) {
+      fragments[existingIdx] = fragment
+    } else {
+      fragments.push(fragment)
+    }
+
+    // Track out-of-order delivery
+    if (fragments.length > 1) {
+      const lastFI = fragments[fragments.length - 2]!.fragmentationIndicator
+      if (fragmentationIndicator !== lastFI + 1) {
+        this.stats.outOfOrderFragments++
+      }
+    }
+
+    // Enforce memory limits
+    this.#enforceMemoryLimit()
+
+    // Try to reassemble
+    return this.#tryReassemble(mpuSequenceNumber)
+  }
+
+  #tryReassemble(mpuSequenceNumber: number): ReassembledMFU | null {
+    const fragments = this.#buffers.get(mpuSequenceNumber)
+    if (!fragments || fragments.length === 0) {
+      return null
+    }
+
+    // Sort by fragment counter
+    fragments.sort((a, b) => a.fragmentCounter - b.fragmentCounter)
+
+    const firstFI = fragments[0]!.fragmentationIndicator
+    const lastFI = fragments[fragments.length - 1]!.fragmentationIndicator
+
+    // Need first (FI=1) and last (FI=3) fragments
+    if (firstFI !== 1 || lastFI !== 3) {
+      return null
+    }
+
+    // Verify middle fragments have FI=2
+    for (let i = 1; i < fragments.length - 1; i++) {
+      if (fragments[i]!.fragmentationIndicator !== 2) {
+        return null
+      }
+    }
+
+    // Reassemble: concatenate all fragment data
+    const totalSize = fragments.reduce((sum, f) => sum + f.data.length, 0)
+    const data = new Uint8Array(totalSize)
+
+    let offset = 0
+    for (const fragment of fragments) {
+      data.set(fragment.data, offset)
+      offset += fragment.data.length
+    }
+
+    // Cleanup
+    this.#clearTimeout(mpuSequenceNumber)
+    this.#buffers.delete(mpuSequenceNumber)
+    this.stats.reassembledMFUs++
+
+    return {
+      mpuSequenceNumber,
+      data,
+      timestamp: fragments[0]!.timestamp,
+      fragmentCount: fragments.length,
+      rapFlag: fragments[0]!.rapFlag,
+    }
+  }
+
+  #setTimeout(mpuSequenceNumber: number): void {
+    const timeoutId = setTimeout(() => {
+      this.#onTimeout(mpuSequenceNumber)
+    }, this.#timeoutMs)
+    this.#timeouts.set(mpuSequenceNumber, timeoutId)
+  }
+
+  #clearTimeout(mpuSequenceNumber: number): void {
+    const timeoutId = this.#timeouts.get(mpuSequenceNumber)
+    if (timeoutId !== undefined) {
+      clearTimeout(timeoutId)
+      this.#timeouts.delete(mpuSequenceNumber)
+    }
+  }
+
+  #onTimeout(mpuSequenceNumber: number): void {
+    const fragments = this.#buffers.get(mpuSequenceNumber)
+    if (!fragments) return
+
+    this.stats.timedOutMFUs++
+    this.#buffers.delete(mpuSequenceNumber)
+    this.#timeouts.delete(mpuSequenceNumber)
+  }
+
+  #enforceMemoryLimit(): void {
+    if (this.#buffers.size <= this.#maxBuffered) return
+
+    const sequences = Array.from(this.#buffers.keys()).sort((a, b) => a - b)
+    const toRemove = sequences.slice(0, sequences.length - this.#maxBuffered)
+
+    for (const mpuSeq of toRemove) {
+      this.#clearTimeout(mpuSeq)
+      this.#buffers.delete(mpuSeq)
+      this.stats.timedOutMFUs++
+    }
+  }
+
+  /**
+   * Flush all buffered fragments
+   */
+  flush(): void {
+    for (const mpuSeq of this.#buffers.keys()) {
+      this.#clearTimeout(mpuSeq)
+    }
+    this.#buffers.clear()
+    this.#timeouts.clear()
+  }
+
+  /**
+   * Get number of pending MFUs
+   */
+  get pendingCount(): number {
+    return this.#buffers.size
+  }
+
+  /**
+   * Get current buffer status
+   */
+  getStatus(): {
+    bufferedMFUs: number
+    pendingFragments: number
+    stats: ReassemblerStats
+  } {
+    let pendingFragments = 0
+    for (const fragments of this.#buffers.values()) {
+      pendingFragments += fragments.length
+    }
+
+    return {
+      bufferedMFUs: this.#buffers.size,
+      pendingFragments,
+      stats: { ...this.stats },
+    }
+  }
+}
+
+/**
+ * Create MFU fragment from MMTP packet for reassembly
+ */
+export function createFragment(mmtpPacket: Uint8Array): MFUFragment {
+  const { header, payload } = unwrapMMTP(mmtpPacket)
+  const mpuHeader = parseMPUHeader(payload)
+  const { mpuSequenceNumber, fragmentationIndicator, fragmentCounter } = mpuHeader
+
+  // MFU DU header is present only for FI = 0 (complete) or FI = 1 (first)
+  const hasMfuHeader = fragmentationIndicator === 0 || fragmentationIndicator === 1
+  const headerSize = MPU_HEADER_SIZE + (hasMfuHeader ? MFU_DU_HEADER_SIZE : 0)
+
+  if (payload.length < headerSize) {
+    throw new Error(`Payload too small for headers: ${payload.length} bytes (need ${headerSize})`)
+  }
+
+  const data = payload.subarray(headerSize)
+
+  return {
+    fragmentationIndicator,
+    mpuSequenceNumber,
+    fragmentCounter,
+    data,
+    timestamp: header.timestamp,
+    receivedAt: typeof performance !== 'undefined' ? performance.now() : Date.now(),
+    rapFlag: header.rapFlag,
+  }
+}
+
+/**
+ * Process MMTP packet with fragment reassembly
+ */
+export function processMMTPWithReassembly(
+  mmtpPacket: Uint8Array,
+  reassembler: MFUReassembler,
+): ReassembledMFU | null {
+  // Skip FEC repair packets
+  if (isFecRepairPacket(mmtpPacket)) {
+    return null
+  }
+
+  const fragment = createFragment(mmtpPacket)
+  return reassembler.addFragment(fragment)
+}
+
+// =============================================================================
+// Inline Tests (vitest)
+// =============================================================================
+
+if (import.meta.vitest) {
+  const { describe, test, expect } = import.meta.vitest
+
+  describe('MFUReassembler', () => {
+    test('should return complete MFU for FI=0', () => {
+      const reassembler = new MFUReassembler()
+      const result = reassembler.addFragment({
+        fragmentationIndicator: 0,
+        mpuSequenceNumber: 1,
+        fragmentCounter: 0,
+        data: new Uint8Array([1, 2, 3, 4]),
+        timestamp: 1000n,
+        receivedAt: 0,
+        rapFlag: true,
+      })
+      expect(result).not.toBeNull()
+      expect(result?.data).toEqual(new Uint8Array([1, 2, 3, 4]))
+      expect(result?.fragmentCount).toBe(1)
+      expect(result?.rapFlag).toBe(true)
+    })
+
+    test('should buffer and reassemble 2 fragments', () => {
+      const reassembler = new MFUReassembler()
+
+      // First fragment (FI=1)
+      const result1 = reassembler.addFragment({
+        fragmentationIndicator: 1,
+        mpuSequenceNumber: 1,
+        fragmentCounter: 0,
+        data: new Uint8Array([1, 2]),
+        timestamp: 1000n,
+        receivedAt: 0,
+        rapFlag: true,
+      })
+      expect(result1).toBeNull()
+
+      // Last fragment (FI=3)
+      const result2 = reassembler.addFragment({
+        fragmentationIndicator: 3,
+        mpuSequenceNumber: 1,
+        fragmentCounter: 1,
+        data: new Uint8Array([3, 4]),
+        timestamp: 1000n,
+        receivedAt: 0,
+        rapFlag: false,
+      })
+      expect(result2).not.toBeNull()
+      expect(result2?.data).toEqual(new Uint8Array([1, 2, 3, 4]))
+      expect(result2?.fragmentCount).toBe(2)
+      expect(result2?.rapFlag).toBe(true) // Should use first fragment's rapFlag
+    })
+
+    test('should handle out-of-order fragments', () => {
+      const reassembler = new MFUReassembler()
+
+      // Last fragment first (FI=3)
+      reassembler.addFragment({
+        fragmentationIndicator: 3,
+        mpuSequenceNumber: 1,
+        fragmentCounter: 1,
+        data: new Uint8Array([3, 4]),
+        timestamp: 1000n,
+        receivedAt: 0,
+        rapFlag: false,
+      })
+
+      // Then first fragment (FI=1)
+      const result = reassembler.addFragment({
+        fragmentationIndicator: 1,
+        mpuSequenceNumber: 1,
+        fragmentCounter: 0,
+        data: new Uint8Array([1, 2]),
+        timestamp: 1000n,
+        receivedAt: 0,
+        rapFlag: true,
+      })
+
+      expect(result).not.toBeNull()
+      expect(result?.data).toEqual(new Uint8Array([1, 2, 3, 4]))
+      expect(result?.rapFlag).toBe(true)
+    })
+
+    test('should track pending count', () => {
+      const reassembler = new MFUReassembler()
+      expect(reassembler.pendingCount).toBe(0)
+
+      reassembler.addFragment({
+        fragmentationIndicator: 1,
+        mpuSequenceNumber: 1,
+        fragmentCounter: 0,
+        data: new Uint8Array([1]),
+        timestamp: 1000n,
+        receivedAt: 0,
+        rapFlag: false,
+      })
+      expect(reassembler.pendingCount).toBe(1)
+
+      reassembler.flush()
+      expect(reassembler.pendingCount).toBe(0)
+    })
+  })
+}

package/src/mmtp.ts

@@ -0,0 +1,277 @@
+/**
+ * @mmt/container - MMTP Parser
+ *
+ * MMTP (MMT Protocol) packet parser based on ISO/IEC 23008-1:2023 Section 9.2
+ *
+ * MMTP header format (12 bytes):
+ * - Byte 0: V(2) | C(1) | FEC_type(2) | r(1) | X(1) | R(1)
+ * - Byte 1: packet_type(6) | reserved(2)
+ * - Bytes 2-3: packet_id (big-endian)
+ * - Bytes 4-7: timestamp (big-endian, 32-bit)
+ * - Bytes 8-11: sequence_number (big-endian)
+ *
+ * FEC_type values:
+ * - 0: No FEC / source packet
+ * - 1: FEC mode 0 (source with FEC payload ID)
+ * - 2: FEC repair packet mode 0
+ * - 3: FEC repair packet mode 1
+ *
+ * @packageDocumentation
+ */
+
+export interface MMTPHeader {
+  version: number
+  packetId: number
+  timestamp: bigint
+  sequenceNumber: number
+  payloadLength: number
+  fecType: number
+  /** Random Access Point flag - indicates keyframe (ISO 23008-1, byte 0 bit 0) */
+  rapFlag: boolean
+}
+
+export interface MPUHeader {
+  mpuSequenceNumber: number
+  fragmentationIndicator: number // FI: 0=complete, 1=first, 2=middle, 3=last
+  fragmentCounter: number
+}
+
+export interface MMTPPacket {
+  header: MMTPHeader
+  payload: Uint8Array
+}
+
+export const MMTP_HEADER_SIZE = 12
+export const MPU_HEADER_SIZE = 8
+export const MFU_DU_HEADER_SIZE = 14
+
+/**
+ * Parse MMTP header from buffer
+ */
+export function parseMMTPHeader(buffer: Uint8Array): MMTPHeader {
+  if (buffer.length < MMTP_HEADER_SIZE) {
+    throw new Error(`MMTP packet too small: ${buffer.length} bytes`)
+  }
+
+  const view = new DataView(buffer.buffer, buffer.byteOffset, buffer.byteLength)
+
+  // Extract FEC type from byte 0, bits 3-4
+  const fecType = (buffer[0]! >> 3) & 0x03
+
+  // Extract RAP flag from byte 0, bit 0 (R bit - Random Access Point)
+  const rapFlag = (buffer[0]! & 0x01) === 1
+
+  // Skip bytes 0-1 (flags and packet_type)
+  let offset = 2
+
+  // Packet ID (2 bytes, big-endian)
+  const packetId = view.getUint16(offset, false)
+  offset += 2
+
+  // Timestamp (4 bytes, big-endian)
+  const timestamp = BigInt(view.getUint32(offset, false))
+  offset += 4
+
+  // Sequence number (4 bytes, big-endian)
+  const sequenceNumber = view.getUint32(offset, false)
+  offset += 4
+
+  return {
+    version: 1,
+    packetId,
+    timestamp,
+    sequenceNumber,
+    payloadLength: buffer.length - offset,
+    fecType,
+    rapFlag,
+  }
+}
+
+/**
+ * Unwrap MMTP packet to extract payload
+ */
+export function unwrapMMTP(buffer: Uint8Array): MMTPPacket {
+  const header = parseMMTPHeader(buffer)
+  const payload = buffer.subarray(MMTP_HEADER_SIZE)
+
+  return { header, payload }
+}
+
+/**
+ * Parse MPU header from payload
+ * ISO/IEC 23008-1:2023 Section 9.2.3.3
+ */
+export function parseMPUHeader(payload: Uint8Array): MPUHeader {
+  if (payload.length < MPU_HEADER_SIZE) {
+    throw new Error(`Payload too small for MPU header: ${payload.length} bytes`)
+  }
+
+  const view = new DataView(payload.buffer, payload.byteOffset, payload.byteLength)
+
+  // MPU sequence number (4 bytes, big-endian)
+  const mpuSequenceNumber = view.getUint32(0, false)
+
+  // Fragmentation indicator (byte 5, bits 0-1)
+  const fragmentationIndicator = payload[5]! & 0x03
+
+  // Fragment counter (bytes 6-7, big-endian)
+  const fragmentCounter = view.getUint16(6, false)
+
+  return {
+    mpuSequenceNumber,
+    fragmentationIndicator,
+    fragmentCounter,
+  }
+}
+
+/**
+ * Extract NAL unit payload from MMTP packet
+ */
+export function extractNALUnit(mmtpPacket: Uint8Array): Uint8Array {
+  const { payload } = unwrapMMTP(mmtpPacket)
+
+  if (payload.length < MPU_HEADER_SIZE) {
+    throw new Error(`Payload too small for MPU header: ${payload.length} bytes`)
+  }
+
+  // Parse MPU header to check fragmentation indicator
+  const fragmentationIndicator = payload[5]! & 0x03
+
+  // MFU DU header is present only for FI = 0 (complete) or FI = 1 (first)
+  const hasMfuHeader = fragmentationIndicator === 0 || fragmentationIndicator === 1
+  const headerSize = MPU_HEADER_SIZE + (hasMfuHeader ? MFU_DU_HEADER_SIZE : 0)
+
+  if (payload.length < headerSize) {
+    throw new Error(`Payload too small for headers: ${payload.length} bytes (need ${headerSize})`)
+  }
+
+  return payload.subarray(headerSize)
+}
+
+/**
+ * Extract timestamp from MMTP packet
+ */
+export function extractTimestamp(mmtpPacket: Uint8Array): bigint {
+  const { header } = unwrapMMTP(mmtpPacket)
+  return header.timestamp
+}
+
+/**
+ * Check if MMTP packet is an FEC repair packet
+ * FEC_type 2 and 3 are repair packets
+ */
+export function isFecRepairPacket(mmtpPacket: Uint8Array): boolean {
+  if (mmtpPacket.length < 1) return false
+  const fecType = (mmtpPacket[0]! >> 3) & 0x03
+  return fecType >= 2
+}
+
+/**
+ * Check if MMTP packet has FEC payload ID (FEC_type 1 or higher)
+ */
+export function hasFecPayloadId(mmtpPacket: Uint8Array): boolean {
+  if (mmtpPacket.length < 1) return false
+  const fecType = (mmtpPacket[0]! >> 3) & 0x03
+  return fecType >= 1
+}
+
+// =============================================================================
+// Inline Tests (vitest)
+// =============================================================================
+
+if (import.meta.vitest) {
+  const { describe, test, expect } = import.meta.vitest
+
+  describe('MMTP Parser', () => {
+    // Helper to create a minimal MMTP packet
+    function createTestPacket(opts: {
+      fecType?: number
+      packetId?: number
+      timestamp?: number
+      sequenceNumber?: number
+      payload?: Uint8Array
+    }): Uint8Array {
+      const fecType = opts.fecType ?? 0
+      const packetId = opts.packetId ?? 1
+      const timestamp = opts.timestamp ?? 12345
+      const sequenceNumber = opts.sequenceNumber ?? 1
+      const payload = opts.payload ?? new Uint8Array([0x00, 0x00, 0x00, 0x01])
+
+      const header = new Uint8Array(12)
+      const view = new DataView(header.buffer)
+
+      // Byte 0: V=1, C=0, FEC_type, r=0, X=0, R=0
+      header[0] = (1 << 6) | (fecType << 3)
+      // Byte 1: packet_type=0 (MPU)
+      header[1] = 0
+      view.setUint16(2, packetId, false)
+      view.setUint32(4, timestamp, false)
+      view.setUint32(8, sequenceNumber, false)
+
+      const result = new Uint8Array(header.length + payload.length)
+      result.set(header, 0)
+      result.set(payload, header.length)
+      return result
+    }
+
+    describe('parseMMTPHeader', () => {
+      test('should parse MMTP header correctly', () => {
+        const packet = createTestPacket({
+          packetId: 42,
+          timestamp: 1000000,
+          sequenceNumber: 100,
+        })
+        const header = parseMMTPHeader(packet)
+        expect(header.packetId).toBe(42)
+        expect(header.timestamp).toBe(1000000n)
+        expect(header.sequenceNumber).toBe(100)
+        expect(header.fecType).toBe(0)
+      })
+
+      test('should extract FEC type', () => {
+        const packet = createTestPacket({ fecType: 2 })
+        const header = parseMMTPHeader(packet)
+        expect(header.fecType).toBe(2)
+      })
+
+      test('should throw on too small packet', () => {
+        expect(() => parseMMTPHeader(new Uint8Array(10))).toThrow()
+      })
+    })
+
+    describe('isFecRepairPacket', () => {
+      test('should return false for source packets (FEC type 0)', () => {
+        const packet = createTestPacket({ fecType: 0 })
+        expect(isFecRepairPacket(packet)).toBe(false)
+      })
+
+      test('should return false for FEC mode 0 source (FEC type 1)', () => {
+        const packet = createTestPacket({ fecType: 1 })
+        expect(isFecRepairPacket(packet)).toBe(false)
+      })
+
+      test('should return true for repair packets (FEC type 2)', () => {
+        const packet = createTestPacket({ fecType: 2 })
+        expect(isFecRepairPacket(packet)).toBe(true)
+      })
+
+      test('should return true for repair packets (FEC type 3)', () => {
+        const packet = createTestPacket({ fecType: 3 })
+        expect(isFecRepairPacket(packet)).toBe(true)
+      })
+    })
+
+    describe('hasFecPayloadId', () => {
+      test('should return false for no FEC (type 0)', () => {
+        const packet = createTestPacket({ fecType: 0 })
+        expect(hasFecPayloadId(packet)).toBe(false)
+      })
+
+      test('should return true for FEC type 1+', () => {
+        expect(hasFecPayloadId(createTestPacket({ fecType: 1 }))).toBe(true)
+        expect(hasFecPayloadId(createTestPacket({ fecType: 2 }))).toBe(true)
+        expect(hasFecPayloadId(createTestPacket({ fecType: 3 }))).toBe(true)
+      })
+    })
+  })
+}