@blockcast/mmt-container 0.1.0-main.149f78a4adae

package/src/multicast-transport.ts

@@ -0,0 +1,320 @@
+/**
+ * Thin transport wrapper for SSM multicast — join, socket, watchdog,
+ * takeover/failback.  Delegates raw packets to a callback (MmtpRouter
+ * or any direct consumer).
+ */
+
+import type {
+  WindowMulticastGateway,
+  WindowMulticastResolvedTransport,
+  WindowMulticastSubscription,
+} from '@blockcast/mmt-transport'
+import { parseMMTPHeader } from '@blockcast/mmt-base'
+
+export interface MulticastTransportConfig {
+  sourceAddress: string
+  groupAddress: string
+  port: number
+  mode?: 'auto' | 'native' | 'tunnel'
+  amtRelay?: string
+  amtRelayPort?: number
+  packetIds?: number[]
+  tracks?: { name: string; packetId: number }[]
+}
+
+export type ResolvedMulticastTransport = WindowMulticastResolvedTransport
+
+/**
+ * Receive counters plus the ingress-filter drop counters.
+ *
+ * `packetsReceived` / `bytesReceived` count only packets that passed the
+ * allow-list and were handed to the page — a rejected packet must never
+ * inflate them.  The `dropped*` counters are the other half of that story:
+ * without them a filtered PID is indistinguishable from a PID that was never
+ * transmitted, which is exactly the ambiguity that makes an all-zero FEC
+ * repair count unreadable (a repair leg dropped here and a repair leg the
+ * publisher never sent produce byte-identical downstream telemetry).
+ */
+export interface MulticastTransportStats {
+  packetsReceived: number
+  bytesReceived: number
+  /** Parsed cleanly, but the packet ID is absent from the join's allow-list. */
+  packetsDroppedUnregisteredPid: number
+  /** MMTP header did not parse; the packet ID is unknown, so it cannot be attributed. */
+  packetsDroppedUnparseable: number
+}
+
+/**
+ * Distinct unregistered PIDs retained for diagnostics.  A conformant catalog
+ * advertises a handful of PIDs per endpoint, so this only has to be large
+ * enough to name every leg of a mis-provisioned one; the cap exists so a
+ * malformed or hostile stream cycling the 16-bit PID space cannot grow the map
+ * without bound.  Drops keep counting in aggregate after the cap.
+ */
+const MAX_TRACKED_DROPPED_PIDS = 16
+
+type MulticastGlobals = typeof globalThis & {
+  multicast?: WindowMulticastGateway
+}
+
+function getMulticastGlobals(): MulticastGlobals {
+  return globalThis as MulticastGlobals
+}
+
+function hasMulticastGateway(): boolean {
+  return typeof getMulticastGlobals().multicast?.subscribe === 'function'
+}
+
+function normalizeResolvedTransport(value: unknown): ResolvedMulticastTransport | undefined {
+  if (value === 'native') return 'native'
+  if (value === 'amt') return 'amt'
+  return undefined
+}
+
+export class MulticastTransport<TPacketContext = never> {
+  #onPacket: (packet: Uint8Array, context?: TPacketContext) => void
+  #subscription: WindowMulticastSubscription | null = null
+  #bytesListener: ((event: CustomEvent<ArrayBuffer>) => void) | null = null
+  #transportListener: ((event: CustomEvent<ResolvedMulticastTransport>) => void) | null = null
+  #resolvedTransport: ResolvedMulticastTransport | undefined
+  #videoConfirmed = false
+  #audioConfirmed = false
+  #watchdog: ReturnType<typeof setTimeout> | null = null
+  #failbackWindowMs: number | null = null
+  #onTakeover: (() => void) | null = null
+  #onFailback: (() => void) | null = null
+  #disposed = false
+  #stats: MulticastTransportStats = {
+    packetsReceived: 0,
+    bytesReceived: 0,
+    packetsDroppedUnregisteredPid: 0,
+    packetsDroppedUnparseable: 0,
+  }
+  #droppedPidCounts = new Map<number, number>()
+  #packetIds: ReadonlySet<number> | null = null
+  #joinGeneration = 0
+
+  constructor(onPacket: (packet: Uint8Array, context?: TPacketContext) => void) {
+    this.#onPacket = onPacket
+  }
+
+  static isAvailable(): boolean {
+    return hasMulticastGateway()
+  }
+
+  async join(config: MulticastTransportConfig, context?: TPacketContext): Promise<boolean> {
+    const generation = ++this.#joinGeneration
+    this.#releaseSubscription()
+
+    if (this.#disposed) return false
+    if (!MulticastTransport.isAvailable()) {
+      console.warn('[MulticastTransport] Multicast API not available')
+      return false
+    }
+
+    try {
+      const packetIds = config.packetIds?.length ? new Set(config.packetIds) : null
+      console.log(
+        `[MulticastTransport] window.multicast.subscribe(${config.sourceAddress}, ${config.groupAddress}, ${config.port})`,
+      )
+      const subscription = await getMulticastGlobals().multicast!.subscribe!({
+        source: config.sourceAddress,
+        group: config.groupAddress,
+        port: config.port,
+        consume: 'bytes',
+        mode: config.mode,
+        amtRelay: config.amtRelay,
+        amtRelayPort: config.amtRelayPort,
+        packetIds: config.packetIds,
+        tracks: config.tracks?.map(({ name, packetId }) => ({ name, packetId })),
+      })
+      console.log(`[MulticastTransport] window.multicast.subscribe returned:`, !!subscription)
+
+      if (this.#disposed || generation !== this.#joinGeneration) {
+        void subscription.unsubscribe()
+        return false
+      }
+      if (typeof subscription.addEventListener !== 'function') {
+        if (typeof subscription.unsubscribe === 'function') {
+          void subscription.unsubscribe()
+        }
+        throw new Error('window.multicast subscription does not support bytes events')
+      }
+
+      const onBytes = (event: CustomEvent<ArrayBuffer>) => {
+        if (this.#disposed || generation !== this.#joinGeneration) return
+        const detail = event.detail
+        const packet = detail instanceof Uint8Array ? detail : new Uint8Array(detail)
+        if (!this.#acceptPacket(packet)) return
+        this.#stats.packetsReceived++
+        this.#stats.bytesReceived += packet.byteLength
+        this.#onPacket(packet, context)
+        this.#resetWatchdog()
+      }
+      const onTransportChange = (event: CustomEvent<ResolvedMulticastTransport>) => {
+        if (this.#disposed || generation !== this.#joinGeneration) return
+        const transport = normalizeResolvedTransport(event.detail)
+        if (transport) this.#resolvedTransport = transport
+      }
+      this.#subscription = subscription
+      this.#bytesListener = onBytes
+      this.#transportListener = onTransportChange
+      this.#packetIds = packetIds
+      this.#resolvedTransport = normalizeResolvedTransport(subscription.transport)
+      subscription.addEventListener('bytes', onBytes)
+      subscription.addEventListener('transportchange', onTransportChange)
+      this.#resetWatchdog()
+      console.log(
+        `[MulticastTransport] Joined ${config.groupAddress}:${config.port}`,
+      )
+      return true
+    } catch (err) {
+      if (this.#disposed || generation !== this.#joinGeneration) return false
+      this.#releaseSubscription()
+      console.error('[MulticastTransport] Failed to join SSM group:', err)
+      return false
+    }
+  }
+
+  /** Feed a raw packet from an external source (e.g., AMT tunnel or ASM subscription). */
+  feedPacket(data: ArrayBuffer | Uint8Array, context?: TPacketContext): void {
+    if (this.#disposed) return
+    const packet = data instanceof Uint8Array ? data : new Uint8Array(data)
+    if (!this.#acceptPacket(packet)) return
+    this.#stats.packetsReceived++
+    this.#stats.bytesReceived += packet.byteLength
+    this.#onPacket(packet, context)
+    this.#resetWatchdog()
+  }
+
+  confirmVideo(): void {
+    this.#videoConfirmed = true
+    this.#checkTakeover()
+  }
+
+  confirmAudio(): void {
+    this.#audioConfirmed = true
+    this.#checkTakeover()
+  }
+
+  onTakeover(cb: () => void): void {
+    this.#onTakeover = cb
+  }
+
+  onFailback(cb: () => void): void {
+    this.#onFailback = cb
+  }
+
+  setFailbackWindowMs(windowMs: number): void {
+    if (!Number.isFinite(windowMs) || windowMs <= 0) {
+      throw new Error(
+        `[MulticastTransport] failbackWindowMs=${windowMs}. ` +
+        `Derive a positive failback window from the stream catalog.`,
+      )
+    }
+    this.#failbackWindowMs = windowMs
+  }
+
+  get stats(): MulticastTransportStats {
+    return this.#stats
+  }
+
+  /**
+   * Per-PID drop breakdown, newest-capped at MAX_TRACKED_DROPPED_PIDS distinct
+   * PIDs.  This is what names the offender: `packetsDroppedUnregisteredPid`
+   * says the ingress filter fired, this says it fired on 0x8001.
+   */
+  get droppedPacketIds(): ReadonlyMap<number, number> {
+    return this.#droppedPidCounts
+  }
+
+  get resolvedTransport(): ResolvedMulticastTransport | undefined {
+    return this.#resolvedTransport
+  }
+
+  dispose(): void {
+    ++this.#joinGeneration
+    this.#disposed = true
+    this.#releaseSubscription()
+  }
+
+  #releaseSubscription(): void {
+    if (this.#watchdog) clearTimeout(this.#watchdog)
+    this.#watchdog = null
+    if (this.#subscription) {
+      if (this.#bytesListener) {
+        this.#subscription.removeEventListener('bytes', this.#bytesListener)
+      }
+      if (this.#transportListener) {
+        this.#subscription.removeEventListener('transportchange', this.#transportListener)
+      }
+      void this.#subscription.unsubscribe()
+    }
+    this.#subscription = null
+    this.#bytesListener = null
+    this.#transportListener = null
+    this.#resolvedTransport = undefined
+    this.#packetIds = null
+  }
+
+  #acceptPacket(packet: Uint8Array): boolean {
+    if (!this.#packetIds) return true
+    let packetId: number
+    try {
+      // This early parse is intentional: rejected PIDs must not affect page
+      // delivery, receive statistics, or the failback liveness watchdog.
+      packetId = parseMMTPHeader(packet).packetId
+    } catch {
+      this.#stats.packetsDroppedUnparseable++
+      return false
+    }
+    if (this.#packetIds.has(packetId)) return true
+    this.#recordUnregisteredPidDrop(packetId)
+    return false
+  }
+
+  #recordUnregisteredPidDrop(packetId: number): void {
+    this.#stats.packetsDroppedUnregisteredPid++
+    const seen = this.#droppedPidCounts.get(packetId)
+    if (seen !== undefined) {
+      this.#droppedPidCounts.set(packetId, seen + 1)
+      return
+    }
+    if (this.#droppedPidCounts.size >= MAX_TRACKED_DROPPED_PIDS) return
+    this.#droppedPidCounts.set(packetId, 1)
+    // Warn once per distinct PID. A PID arriving on the wire but missing from
+    // the catalog's advertised set is a provisioning fault, not stream noise,
+    // and it is silent in every downstream counter.
+    console.warn(
+      `[MulticastTransport] Dropping packetId=${packetId} (0x${packetId.toString(16)}): ` +
+      `not in the advertised set [${[...this.#packetIds!].join(', ')}]. ` +
+      `If this is an FEC repair leg, the catalog is not advertising its packetId.`,
+    )
+  }
+
+  #checkTakeover(): void {
+    if (this.#videoConfirmed && this.#audioConfirmed && this.#onTakeover) {
+      const cb = this.#onTakeover
+      this.#onTakeover = null // fire exactly once
+      cb()
+    }
+  }
+
+  #resetWatchdog(): void {
+    if (this.#watchdog) clearTimeout(this.#watchdog)
+    if (!this.#onFailback) return
+    if (this.#failbackWindowMs === null) {
+      throw new Error(
+        '[MulticastTransport] Failback watchdog requires a catalog-derived window',
+      )
+    }
+    this.#watchdog = setTimeout(() => {
+      if (!this.#disposed && this.#onFailback) {
+        console.warn(
+          `[MulticastTransport] No packets for ${this.#failbackWindowMs}ms; failing back to MoQ`,
+        )
+        this.#onFailback()
+      }
+    }, this.#failbackWindowMs)
+  }
+}

package/src/multicast-unwrap.ts

@@ -0,0 +1,132 @@
+/**
+ * @mmt/container - Container-aware multicast MMTP unwrapper
+ *
+ * Dispatches raw multicast MMTP packets into typed media or Annex C repair
+ * frames. Handles FEC source payload ID extraction and repair packet parsing.
+ *
+ * @packageDocumentation
+ */
+
+import {
+  type MMTPHeader,
+  type MFUExtraction,
+  parseMMTPHeader,
+  parseMoqRepairFrame,
+  extractMFUPayload,
+  hasSourceFecPayloadId,
+  MMTP_HEADER_SIZE,
+  PACKET_TYPE_REPAIR,
+} from '@blockcast/mmt-base'
+
+/** The immutable reader contract selected by a multicast consumer. */
+export interface MulticastContainerContract {
+  version: 1
+  kind: 'mmtp'
+}
+
+export type MulticastContainerErrorCode =
+  | 'unsupported_version'
+  | 'unsupported_kind'
+  | 'ambiguous_kind'
+  | 'malformed_selector'
+
+/** Versioned, fail-closed contract selection error. */
+export class MulticastContainerContractError extends TypeError {
+  readonly version = 1
+  readonly code: MulticastContainerErrorCode
+
+  constructor(code: MulticastContainerErrorCode, detail: string) {
+    super(`multicast-container/v1/${code}: ${detail}`)
+    this.name = 'MulticastContainerContractError'
+    this.code = code
+  }
+}
+
+/** Validate the only reader currently frozen by the container contract. */
+export function validateMulticastContainerContract(
+  contract: unknown,
+): MulticastContainerContract {
+  if (contract === null || typeof contract !== 'object') {
+    throw new MulticastContainerContractError('malformed_selector', 'selector is required')
+  }
+
+  const value = contract as Record<string, unknown>
+  if (value['version'] !== 1) {
+    throw new MulticastContainerContractError('unsupported_version', 'only version 1 is supported')
+  }
+  if (value['kind'] === undefined || value['kind'] === null || value['kind'] === '') {
+    throw new MulticastContainerContractError('ambiguous_kind', 'container kind is required')
+  }
+  if (value['kind'] !== 'mmtp') {
+    throw new MulticastContainerContractError('unsupported_kind', `reader is not implemented for ${String(value['kind'])}`)
+  }
+  return { version: 1, kind: 'mmtp' }
+}
+
+/** Source FEC Payload ID — flat 32-bit SS_ID per ISO 23008-1 §C.5.2 */
+export interface FecPayloadId {
+  ssId: number
+}
+
+/** Discriminated union of unwrapped multicast frames */
+export type MulticastFrame =
+  | { kind: 'mmtp'; header: MMTPHeader; mfu: MFUExtraction; fecId: FecPayloadId | null }
+  | {
+      kind: 'repair'
+      header: MMTPHeader
+      ssStart: number
+      rsbLength: number
+      rsId: number
+      ssbLength: number
+      data: Uint8Array
+    }
+
+/**
+ * Unwrap a raw MMTP multicast packet into a typed MulticastFrame.
+ *
+ * This function handles MMTP-framed multicast only (container 0x01). The
+ * versioned contract is validated before any packet bytes are parsed, so an
+ * unsupported version or container kind fails closed rather than being
+ * reinterpreted under a reader that does not match the wire format.
+ *
+ * @param packet - Raw MMTP packet bytes from multicast UDP
+ * @param contract - Required `multicast-container/v1` selector
+ * @throws {MulticastContainerContractError} if the selector is absent or unsupported
+ * @returns Parsed frame, or null if the packet is too small / malformed
+ */
+export function unwrapMulticastPacket(
+  packet: Uint8Array,
+  contract: unknown,
+): MulticastFrame | null {
+  validateMulticastContainerContract(contract)
+  if (packet.length < MMTP_HEADER_SIZE) return null
+
+  let header: MMTPHeader
+  try {
+    header = parseMMTPHeader(packet)
+  } catch {
+    return null
+  }
+
+  if (header.packetType === PACKET_TYPE_REPAIR || header.fecType >= 2) {
+    const repair = parseMoqRepairFrame(packet)
+    if (!repair) return null
+    return {
+      kind: 'repair',
+      header,
+      ssStart: repair.ssStart,
+      rsbLength: repair.rsbLength,
+      rsId: repair.rsId,
+      ssbLength: repair.ssbLength,
+      data: repair.symbolData,
+    }
+  }
+
+  const hasFec = hasSourceFecPayloadId(packet)
+
+  // MMTP source packet — extract MFU payload
+  const mfu = extractMFUPayload(packet)
+  if (!mfu) return null
+  const fecId = hasFec ? mfu.fecPayloadId : null
+  return { kind: 'mmtp', header, mfu, fecId }
+}

package/src/no-modules.ts

@@ -0,0 +1,20 @@
+export { MmtpContainerParser } from './mmtp-container-parser.js'
+export { createWasmMmtpContainerParser } from './wasm-mmtp-container-parser.js'
+export {
+  datagramMfuReassembly,
+  reliableMoqMfuReassembly,
+  mmtpFrameReorderWindowFrames,
+} from './mfu-reassembly-policy.js'
+export {
+  validateCmsfMmtpCatalog,
+  CmsfCatalogValidationError,
+  resolveGroupDurationMs,
+} from './carp-catalog.js'
+export { catalogFecInterleaveMs, computeFecTimeout } from '@blockcast/mmt-fec'
+export { MmtpToCmaf } from './mmtp-to-cmaf.js'
+export { createManifestAuthPlan } from './manifest-auth-plan.js'
+export {
+  ManifestVerifier,
+  createWebCryptoEd25519Verifier,
+  manifestBindingId,
+} from '@blockcast/mmt-manifest-verify'