@blockcast/mmt-container 0.1.0 → 0.3.0-main.ef68de90edb3

package/src/transport-pool.ts

@@ -0,0 +1,128 @@
+/**
+ * TransportPool — ref-counted subscription management for per-track transport.
+ *
+ * Tracks which consumers (identified by trackName) hold references to which
+ * subscriptions (identified by a string key). When the last consumer releases
+ * a subscription, it is closed.
+ */
+
+/** Transport subscription mode — matches TrackState in the state machine. */
+export type SubscriptionMode = 'multicast' | 'amt' | 'moq'
+
+/** Direct Socket health report (IWA transport). */
+export interface DirectSocketHealth {
+  connected: boolean
+  bytesReceived: number
+  packetsReceived: number
+  errors: number
+}
+
+/** Subscription handle returned by acquireSubscription. */
+export interface Subscription {
+  key: string
+  mode: SubscriptionMode
+  consumers: ReadonlySet<string>
+}
+
+/** Stats for a subscription. */
+export interface SubscriptionStats {
+  activeSubscriptions: number
+  totalAcquires: number
+  totalReleases: number
+}
+
+/** Options for acquiring a subscription. */
+export interface AcquireOptions {
+  /** Subscription key (e.g., "(S,G,port)" for multicast). */
+  key: string
+  /** Transport mode. */
+  mode: SubscriptionMode
+  /** Consumer identity (trackName). */
+  consumer: string
+}
+
+export interface TransportPoolOptions {
+  /** Maximum concurrent subscriptions. 0 = unlimited. */
+  maxSubscriptions?: number
+}
+
+type FailedCallback = (sub: { key: string; consumers: Set<string>; error: unknown }) => void
+
+export class TransportPool {
+  readonly #subs = new Map<string, Subscription>()
+  readonly #options: TransportPoolOptions
+  #failedCb: FailedCallback | null = null
+  #stats: SubscriptionStats = { activeSubscriptions: 0, totalAcquires: 0, totalReleases: 0 }
+
+  constructor(options?: TransportPoolOptions) {
+    this.#options = options ?? {}
+  }
+
+  /** Register callback for subscription failures. */
+  onSubscriptionFailed(cb: FailedCallback): void {
+    this.#failedCb = cb
+  }
+
+  /** Acquire a subscription for a consumer. Returns the subscription. */
+  acquireSubscription(opts: AcquireOptions): Subscription
+  acquireSubscription(key: string, consumer: string): Subscription
+  acquireSubscription(keyOrOpts: string | AcquireOptions, consumer?: string): Subscription {
+    const key = typeof keyOrOpts === 'string' ? keyOrOpts : keyOrOpts.key
+    const cons = typeof keyOrOpts === 'string' ? consumer! : keyOrOpts.consumer
+    const mode: SubscriptionMode = typeof keyOrOpts === 'object' ? keyOrOpts.mode : 'moq'
+
+    let sub = this.#subs.get(key)
+    if (!sub) {
+      sub = { key, mode, consumers: new Set() }
+      this.#subs.set(key, sub)
+      this.#stats.activeSubscriptions++
+    }
+    ;(sub.consumers as Set<string>).add(cons)
+    this.#stats.totalAcquires++
+    return sub
+  }
+
+  /** Release a subscription for a consumer. Closes if last consumer. */
+  releaseSubscription(key: string, consumer: string): void {
+    const sub = this.#subs.get(key)
+    if (!sub) return
+    ;(sub.consumers as Set<string>).delete(consumer)
+    this.#stats.totalReleases++
+    if (sub.consumers.size === 0) {
+      this.#subs.delete(key)
+      this.#stats.activeSubscriptions--
+    }
+  }
+
+  /** Release all subscriptions held by a consumer. */
+  releaseAllForConsumer(consumer: string): void {
+    for (const [key, sub] of this.#subs) {
+      ;(sub.consumers as Set<string>).delete(consumer)
+      if (sub.consumers.size === 0) {
+        this.#subs.delete(key)
+        this.#stats.activeSubscriptions--
+      }
+    }
+  }
+
+  /** Report a subscription failure. */
+  reportFailure(key: string, error: unknown): void {
+    const sub = this.#subs.get(key)
+    if (sub) this.#failedCb?.({ key, consumers: sub.consumers as Set<string>, error })
+  }
+
+  /** Get stats. */
+  get stats(): Readonly<SubscriptionStats> { return this.#stats }
+
+  /** Clean up all subscriptions. */
+  dispose(): void {
+    this.#subs.clear()
+    this.#failedCb = null
+    this.#stats.activeSubscriptions = 0
+  }
+
+  /** Number of active subscriptions. */
+  get size(): number {
+    return this.#subs.size
+  }
+}

package/src/wasm-mfu-reassembler.ts

@@ -0,0 +1,405 @@
+import type {
+  MFUFragment,
+  MfuReassemblerBackend,
+  PendingMfuDebug,
+  ReassembledMFU,
+  ReassemblerStats,
+} from './mfu-reassembler.js'
+import {
+  isMfuReassemblyErrorCode,
+  MfuReassemblyError,
+} from './mfu-reassembler.js'
+
+export interface MmtWasmFragment {
+  with_sample_identity(movieFragmentSequence: number, sampleNumber: number, offset: number): void
+  set_item_id(itemId: number): void
+  set_packet_delivery?(packetSequenceNumber: number, recovered: boolean): void
+  set_priority(priority: number): void
+  set_attribution(attribution: number): void
+  set_stream_identity(streamIdentity: number): void
+}
+
+export interface MmtWasmReassembledMfu {
+  readonly mpu_sequence_number: number
+  readonly timestamp: number
+  readonly fragment_count: number
+  readonly rap_flag: boolean
+  readonly priority?: number
+  readonly sample_number?: number
+  readonly movie_fragment_sequence_number?: number
+  readonly packet_sequence_numbers?: Uint32Array | number[]
+  readonly repaired_packet_sequence_numbers?: Uint32Array | number[]
+  readonly attribution?: number
+  readonly stream_identity?: number
+  readonly data: Uint8Array
+  free(): void
+}
+
+export interface MmtWasmStats {
+  readonly total_fragments: bigint | number
+  readonly reassembled_mfus: bigint | number
+  readonly timed_out_mfus: bigint | number
+  readonly evicted_memory_limit: bigint | number
+  /**
+   * Incomplete data units released by the MMT policy's clock-free replacement
+   * at `maxBuffered` (BLO-31513). Distinct from `evicted_memory_limit`, which
+   * counts the generic engine's own memory-limit eviction.
+   *
+   * Optional: `bindings` are host-injected and `mmt-wasm` publishes
+   * independently of this package, so a host can load an artifact predating
+   * this field. Read it through `?? 0` — summing `undefined` would silently
+   * poison `evictedMemoryLimit` with `NaN` rather than degrading.
+   */
+  readonly evicted_data_units?: bigint | number
+  readonly out_of_order_fragments: bigint | number
+  readonly duplicate_fragments: bigint | number
+  free?: () => void
+}
+
+export interface MmtWasmReassembler {
+  add_fragment(now: number, fragment: MmtWasmFragment): MmtWasmReassembledMfu | undefined
+  cleanup_timeouts(now: number): void
+  set_timeout(timeoutMs: number): void
+  set_clock_free(): void
+  next_timeout_at(): number | undefined
+  flush(): void
+  reset_stream(streamIdentity: number): void
+  reset(): void
+  stats(): MmtWasmStats
+  readonly buffered_count: number
+  readonly pending_fragment_count: number
+}
+
+export interface MmtWasmBindings {
+  MfuFragmentJs: new (
+    mpuSequenceNumber: number,
+    fragmentationIndicator: number,
+    fragmentCounter: number,
+    data: Uint8Array,
+    timestamp: number,
+    rapFlag: boolean,
+  ) => MmtWasmFragment
+  MmtReassembler: {
+    new (timeoutMs: number, maxBuffered: number): MmtWasmReassembler
+    clock_free(maxBuffered: number): MmtWasmReassembler
+  }
+}
+
+export interface WasmMfuReassemblerOptions {
+  bindings: MmtWasmBindings
+  timeoutMs: number | null
+  maxBuffered?: number
+  now?: () => number
+}
+
+function asNumber(value: bigint | number): number {
+  return typeof value === 'bigint' ? Number(value) : value
+}
+
+function timestampU32(timestamp: bigint): number {
+  return Number(BigInt.asUintN(32, timestamp))
+}
+
+/** Thin host adapter over mmt-core's Rust/WASM IFC reassembler. */
+export class WasmMfuReassembler implements MfuReassemblerBackend {
+  readonly #bindings: MmtWasmBindings
+  readonly #core: MmtWasmReassembler
+  readonly #now: () => number
+  #timeoutMs: number | null
+  #cleanupTimer: ReturnType<typeof setTimeout> | null = null
+  #nextStreamIdentity = 1
+  #streamIdentityByKey = new Map<string, number>()
+  #streamNameByIdentity = new Map<number, string>()
+  // Every fragment handed to the core, including ones it rejected. This is
+  // what `coreTotal + rejectedBeforeCore` computed with a core stats() round
+  // trip before and after every fragment (BLO-36599).
+  #offeredFragments = 0
+  #rejectedFragments = 0
+
+  readonly #stats: ReassemblerStats = {
+    totalFragments: 0,
+    reassembledMFUs: 0,
+    rejectedFragments: 0,
+    timedOutMFUs: 0,
+    evictedMemoryLimit: 0,
+    outOfOrderFragments: 0,
+  }
+
+  onDeferredAssembly?: (result: ReassembledMFU) => void
+
+  constructor(options: WasmMfuReassemblerOptions) {
+    const maxBuffered = options.maxBuffered ?? 100
+    if (!Number.isInteger(maxBuffered) || maxBuffered <= 0) {
+      throw new Error('[WasmMfuReassembler] maxBuffered must be a positive integer')
+    }
+    this.#bindings = options.bindings
+    this.#timeoutMs = options.timeoutMs
+    this.#now = options.now ?? (() => globalThis.performance?.now() ?? Date.now())
+    this.#core =
+      options.timeoutMs === null
+        ? options.bindings.MmtReassembler.clock_free(maxBuffered)
+        : new options.bindings.MmtReassembler(options.timeoutMs, maxBuffered)
+  }
+
+  get timeoutMs(): number | null {
+    return this.#timeoutMs
+  }
+
+  /**
+   * Host-observable reassembly statistics, read from the core when asked.
+   * Reading them is a wasm crossing plus six counter getters, so neither
+   * addFragment nor the router's per-packet path refreshes them (BLO-36599).
+   */
+  get stats(): ReassemblerStats {
+    this.#refreshStats()
+    return this.#stats
+  }
+
+  set timeoutMs(timeoutMs: number | null) {
+    if (timeoutMs !== null && (!Number.isFinite(timeoutMs) || timeoutMs <= 0)) {
+      throw new Error('[WasmMfuReassembler] timeoutMs must be a finite number > 0')
+    }
+    this.#timeoutMs = timeoutMs
+    if (timeoutMs === null) this.#core.set_clock_free()
+    else this.#core.set_timeout(Math.ceil(timeoutMs))
+    this.#scheduleCleanup()
+  }
+
+  addFragment(fragment: MFUFragment): ReassembledMFU | null {
+    const wasmFragment = new this.#bindings.MfuFragmentJs(
+      fragment.mpuSequenceNumber,
+      fragment.fragmentationIndicator,
+      fragment.fragmentCounter,
+      fragment.data,
+      timestampU32(fragment.timestamp),
+      fragment.rapFlag,
+    )
+    if (
+      fragment.movieFragmentSequenceNumber !== undefined &&
+      fragment.sampleNumber !== undefined &&
+      fragment.sampleNumber > 0 &&
+      fragment.sampleOffset !== undefined
+    ) {
+      wasmFragment.with_sample_identity(
+        fragment.movieFragmentSequenceNumber,
+        fragment.sampleNumber,
+        fragment.sampleOffset,
+      )
+    }
+    if (fragment.itemId !== undefined) wasmFragment.set_item_id(fragment.itemId)
+    if (fragment.packetSequenceNumber !== undefined) {
+      wasmFragment.set_packet_delivery?.(
+        fragment.packetSequenceNumber,
+        fragment.recovered === true,
+      )
+    }
+    if (fragment.priority !== undefined) wasmFragment.set_priority(fragment.priority)
+    if (fragment.source !== undefined) {
+      wasmFragment.set_attribution(fragment.source === 'multicast' ? 1 : 2)
+    }
+    const streamIdentity = this.#streamIdentityFor(fragment)
+    if (streamIdentity !== undefined) {
+      wasmFragment.set_stream_identity(streamIdentity)
+    }
+
+    let output: MmtWasmReassembledMfu | undefined
+    try {
+      output = this.#core.add_fragment(this.#now(), wasmFragment)
+    } catch (error) {
+      const rejection = this.#asReassemblyError(error)
+      if (rejection === null) throw error
+      this.#offeredFragments++
+      this.#rejectedFragments++
+      this.#ensureCleanupArmed()
+      throw rejection
+    }
+    this.#offeredFragments++
+    this.#ensureCleanupArmed()
+    if (!output) return null
+
+    try {
+      const catalogTrackName = output.stream_identity === undefined
+        ? undefined
+        : this.#streamNameByIdentity.get(output.stream_identity)
+      const packetSequenceNumbers = output.packet_sequence_numbers === undefined
+        ? undefined
+        : Array.from(output.packet_sequence_numbers)
+      const repairedPacketSequenceNumbers =
+        output.repaired_packet_sequence_numbers === undefined
+          ? undefined
+          : Array.from(output.repaired_packet_sequence_numbers)
+      return {
+        mpuSequenceNumber: output.mpu_sequence_number,
+        ...(packetSequenceNumbers?.[0] === undefined
+          ? {}
+          : { packetSequenceNumber: packetSequenceNumbers[0] }),
+        ...(packetSequenceNumbers === undefined ? {} : { packetSequenceNumbers }),
+        ...(repairedPacketSequenceNumbers === undefined
+          ? {}
+          : { repairedPacketSequenceNumbers }),
+        data: output.data,
+        timestamp: BigInt(output.timestamp),
+        fragmentCount: output.fragment_count,
+        rapFlag: output.rap_flag,
+        ...(output.priority === undefined ? {} : { priority: output.priority }),
+        ...(output.sample_number === undefined ? {} : { sampleNumber: output.sample_number }),
+        ...(output.movie_fragment_sequence_number === undefined
+          ? {}
+          : {
+              movieFragmentSequenceNumber: output.movie_fragment_sequence_number,
+            }),
+        ...(output.attribution === 1
+          ? { source: 'multicast' as const }
+          : output.attribution === 2
+            ? { source: 'moq' as const }
+            : {}),
+        // The Rust core folds `attribution` over every contributing fragment
+        // and reports None unless they were unanimous, so a tag here is
+        // already whole-frame evidence. A missing tag means "not unanimous or
+        // never recorded" — both unproven, never multicast.
+        deliveryProvenance:
+          output.attribution === 1
+            ? 'multicast'
+            : output.attribution === 2
+              ? 'mixed'
+              : 'unknown',
+        ...(catalogTrackName === undefined ? {} : { catalogTrackName }),
+      }
+    } finally {
+      output.free()
+    }
+  }
+
+  flush(): void {
+    this.#clearCleanupTimer()
+    this.#core.flush()
+  }
+
+  resetStream(catalogTrackName: string): void {
+    const streamIdentity = this.#streamIdentityByKey.get(`catalog:${catalogTrackName}`)
+    if (streamIdentity === undefined) return
+    this.#clearCleanupTimer()
+    this.#core.reset_stream(streamIdentity)
+    this.#scheduleCleanup()
+  }
+
+  reset(): void {
+    this.#clearCleanupTimer()
+    this.#core.reset()
+    this.#nextStreamIdentity = 1
+    this.#streamIdentityByKey.clear()
+    this.#streamNameByIdentity.clear()
+    this.#offeredFragments = 0
+    this.#rejectedFragments = 0
+  }
+
+  get pendingCount(): number {
+    return this.#core.buffered_count
+  }
+
+  getStatus(): {
+    bufferedMFUs: number
+    pendingFragments: number
+    pendingSamples: PendingMfuDebug[]
+    stats: ReassemblerStats
+  } {
+    this.#refreshStats()
+    return {
+      bufferedMFUs: this.#core.buffered_count,
+      pendingFragments: this.#core.pending_fragment_count,
+      // Detailed fragment coordinates remain internal to the Rust core. Counts
+      // and health statistics stay available to MmtpRouter diagnostics.
+      pendingSamples: [],
+      stats: { ...this.#stats },
+    }
+  }
+
+  #refreshStats(): void {
+    const stats = this.#core.stats()
+    this.#stats.totalFragments = this.#offeredFragments
+    this.#stats.reassembledMFUs = asNumber(stats.reassembled_mfus)
+    this.#stats.rejectedFragments = this.#rejectedFragments
+    this.#stats.timedOutMFUs = asNumber(stats.timed_out_mfus)
+    // `evictedMemoryLimit` is documented as every incomplete MFU discarded to
+    // enforce the memory bound, and the pure-TypeScript engine counts its
+    // clock-free evictions there. The Rust core splits the same concept across
+    // two counters, so both are summed here — otherwise the identical stat
+    // would mean different things depending on which engine a host loaded.
+    this.#stats.evictedMemoryLimit =
+      asNumber(stats.evicted_memory_limit) + asNumber(stats.evicted_data_units ?? 0)
+    this.#stats.outOfOrderFragments = asNumber(stats.out_of_order_fragments)
+    stats.free?.()
+  }
+
+  #streamIdentityFor(fragment: MFUFragment): number | undefined {
+    const key = fragment.catalogTrackName !== undefined
+      ? `catalog:${fragment.catalogTrackName}`
+      : fragment.packetId !== undefined
+        ? `packet:${fragment.packetId}`
+        : undefined
+    if (key === undefined) return undefined
+    const existing = this.#streamIdentityByKey.get(key)
+    if (existing !== undefined) return existing
+    const identity = this.#nextStreamIdentity++
+    this.#streamIdentityByKey.set(key, identity)
+    if (fragment.catalogTrackName !== undefined) {
+      this.#streamNameByIdentity.set(identity, fragment.catalogTrackName)
+    }
+    return identity
+  }
+
+  #asReassemblyError(error: unknown): MfuReassemblyError | null {
+    if ((typeof error !== 'object' && typeof error !== 'function') || error === null) return null
+    const code = Reflect.get(error, 'code')
+    if (!isMfuReassemblyErrorCode(code)) return null
+    const message = Reflect.get(error, 'message')
+    return new MfuReassemblyError(
+      code,
+      typeof message === 'string' ? message : `MFU reassembly rejected: ${code}`,
+    )
+  }
+
+  /**
+   * Arm the cleanup wake-up only when none is armed. A fragment can only add
+   * a data unit whose deadline is its own arrival plus the one configured
+   * timeout, which is never earlier than the deadline already armed; the
+   * armed wake-up re-reads the core's next deadline after cleanup. Only a
+   * timeout change can move the next deadline earlier, and the timeoutMs
+   * setter re-arms for that. This replaces a next_timeout_at() crossing and a
+   * clear+set timer pair on every fragment (BLO-36599).
+   */
+  #ensureCleanupArmed(): void {
+    if (this.#cleanupTimer === null) this.#scheduleCleanup()
+  }
+
+  #scheduleCleanup(): void {
+    this.#clearCleanupTimer()
+    if (this.#timeoutMs === null) return
+    const next = this.#core.next_timeout_at()
+    if (next === undefined) return
+    const delay = Math.max(0, Math.ceil(next - this.#now()))
+    this.#cleanupTimer = setTimeout(() => {
+      this.#cleanupTimer = null
+      this.#core.cleanup_timeouts(this.#now())
+      this.#scheduleCleanup()
+    }, delay)
+  }
+
+  #clearCleanupTimer(): void {
+    if (this.#cleanupTimer === null) return
+    clearTimeout(this.#cleanupTimer)
+    this.#cleanupTimer = null
+  }
+}
+
+export function resolveGlobalMmtWasmBindings(): MmtWasmBindings {
+  const globals = globalThis as typeof globalThis & {
+    __blockcastMmtReassemblerWasmBindgen?: MmtWasmBindings
+    __MmtWasmBindings?: MmtWasmBindings
+  }
+  const bindings = globals.__MmtWasmBindings ?? globals.__blockcastMmtReassemblerWasmBindgen
+  if (!bindings?.MmtReassembler || !bindings.MfuFragmentJs) {
+    throw new Error('[WasmMfuReassembler] initialized mmt-wasm bindings are unavailable')
+  }
+  return bindings
+}

package/src/wasm-mmtp-container-parser.ts

@@ -0,0 +1,23 @@
+import { MmtpContainerParser, type MmtpParserConfig } from './mmtp-container-parser.js'
+import { WasmMfuReassembler, resolveGlobalMmtWasmBindings, type MmtWasmBindings } from './wasm-mfu-reassembler.js'
+import { mfuReassemblyTimeoutMs, type MfuReassemblyPolicy } from './mfu-reassembly-policy.js'
+
+export type WasmMmtpParserConfig = Omit<MmtpParserConfig, 'mfuTimeoutMs' | 'reassembler' | 'reassemblyPolicy'> & {
+  reassemblyPolicy: MfuReassemblyPolicy
+  wasmBindings?: MmtWasmBindings
+}
+
+/** Construct the common MMTP parser over the shared Rust/WASM IFC core. */
+export function createWasmMmtpContainerParser(config: WasmMmtpParserConfig): MmtpContainerParser {
+  const timeoutMs = mfuReassemblyTimeoutMs(config.reassemblyPolicy)
+  const reassembler = new WasmMfuReassembler({
+    bindings: config.wasmBindings ?? resolveGlobalMmtWasmBindings(),
+    timeoutMs,
+    ...(config.maxBufferedMfus === undefined ? {} : { maxBuffered: config.maxBufferedMfus }),
+  })
+  return new MmtpContainerParser({
+    ...config,
+    reassemblyPolicy: config.reassemblyPolicy,
+    reassembler,
+  })
+}