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

package/src/multicast-manager.ts

@@ -18,8 +18,10 @@ import {
   type FecFallbackDecoder,
   type MulticastSymbolDelivery,
   type RepairVia,
+  type ExpiredIsoHole,
   type UndelimitedIsoLoss,
   type FecFailClosedEvent,
+  type IsoSpanFailure,
 } from "./fec-manager.js";
 import {
   deriveBlockClassifierGeometry,
@@ -50,7 +52,11 @@ import {
   type StreamSwitchCommit,
   type TrackPacketCallback,
 } from "./mmtp-router.js";
-import { isMulticastTrackPacketId, type WindowMulticastGateway } from "@blockcast/mmt-transport";
+import {
+  isMulticastTrackPacketId,
+  userAgentVerifiedIngress,
+  type WindowMulticastGateway,
+} from "@blockcast/mmt-transport";
 import {
   MulticastTransport,
   type MulticastFailbackReason,
@@ -94,6 +100,8 @@ export interface MulticastRepairEndpoint {
   mode?: string;
   amtRelay?: string;
   amtRelayPort?: number;
+  /** The media join's `'driad'` discovery (no relay pinned), carried so the repair group rides the same relay. */
+  amtDiscovery?: 'driad';
   /** The repair packet IDs this group carries. */
   packetIds: number[];
   /** Each repair packet ID bound to the media packet ID it repairs. */
@@ -401,6 +409,14 @@ export type RepairLifecycleEvent =
       readonly block: RepairBlockIdentity;
       readonly blockClass: BlockClass;
       readonly symbols: RepairSymbolCounts;
+      /**
+       * Set when what failed is an iso-ssbg1-v1 repair-less span starting at
+       * `block.sbn`: `length` SS_IDs between two stated blocks, `sources` of
+       * them received. No repair stated the blocks inside it, so the receiver
+       * cannot tell which of them lost a source; it is not the failure of the
+       * block at `block.sbn` alone.
+       */
+      readonly span?: IsoSpanFailure;
     }
   | {
       readonly version: 2;
@@ -785,6 +801,19 @@ function isSymbolCounts(value: unknown): boolean {
   );
 }
 
+/** A failed repair-less span: `sources` of its `length` SS_IDs arrived, never all. */
+function isSpanFailure(value: unknown): boolean {
+  if (!isRecord(value) || !hasExactKeys(value, ["length", "sources"])) return false;
+  const length = value["length"];
+  const sources = value["sources"];
+  return (
+    Number.isSafeInteger(length) &&
+    (length as number) > 0 &&
+    isNonNegativeSafeInteger(sources) &&
+    (sources as number) < (length as number)
+  );
+}
+
 function isNullableNonNegative(value: unknown): boolean {
   return value === null || (typeof value === "number" && Number.isFinite(value) && value >= 0);
 }
@@ -827,10 +856,16 @@ export function isRepairLifecycleEvent(
       );
     case "failed":
       return (
-        hasExactKeys(value, ["version", "type", "block", "blockClass", "symbols"]) &&
+        hasExactKeys(
+          value,
+          "span" in value
+            ? ["version", "type", "block", "blockClass", "symbols", "span"]
+            : ["version", "type", "block", "blockClass", "symbols"],
+        ) &&
         isRepairBlockIdentity(block) &&
         BLOCK_CLASSES.has(value["blockClass"]) &&
-        isSymbolCounts(value["symbols"])
+        isSymbolCounts(value["symbols"]) &&
+        (!("span" in value) || isSpanFailure(value["span"]))
       );
     case "repair-preempted":
     case "repair-deferred":
@@ -1360,7 +1395,7 @@ export class MulticastManager {
       onPublisherRestart: (packetId, catalogTrackName) => {
         this.#resetStreamOutsideRouter(packetId, catalogTrackName);
       },
-      onBlockFailed: (sbn, packetId, catalogTrackName, blockClass) => {
+      onBlockFailed: (sbn, packetId, catalogTrackName, blockClass, span) => {
         const pathCount = this.#fec.blockPathCount(
           sbn,
           packetId,
@@ -1379,6 +1414,7 @@ export class MulticastManager {
             multicast: pathCount?.multicastSymbols ?? 0,
             moq: pathCount?.moqSymbols ?? 0,
           },
+          ...(span === undefined ? {} : { span }),
         });
       },
       onFrameGap: (decision) => {
@@ -2353,10 +2389,20 @@ export class MulticastManager {
    * repair roles and owners are registered here; in-band owners stay the
    * caller's. Joining is best effort: a group that fails to join is logged
    * and leaves the media join as it was.
+   *
+   * `options.gateway` names the gateway a subscribe callback reads through.
+   * When it is the browser's own MulticastReceiver provider, the callback's
+   * packets are fed as admitted by the user agent
+   * (`userAgentVerifiedIngress`); nothing the callback passes can mark them.
+   * The mark rests on this statement, not on the data path: every packet the
+   * callback delivers must come from a subscription opened on
+   * `options.gateway`. A callback that also merges another source (a MoQ or
+   * WebSocket repair feed) must not name a native provider here.
    */
   joinRepairEndpoints(
     endpoints: readonly MulticastRepairEndpoint[],
     provider?: WindowMulticastGateway | MulticastRepairSubscribe,
+    options?: { gateway?: WindowMulticastGateway },
   ): () => void {
     const releases: Array<() => void> = [];
     let released = false;
@@ -2382,22 +2428,26 @@ export class MulticastManager {
         ...(endpoint.flow === undefined ? {} : { flow: endpoint.flow }),
       };
       let sender: string | undefined;
-      const onPacket = (packet: Uint8Array, sourceAddress?: string) => {
+      const feed = (packet: Uint8Array, sourceAddress: string | undefined, ingressToFeed: MmtpIngressContext) => {
         if (released) return;
         // The media join's sender owns the repair too; this group's own first
         // sender stands in only until the media join has one.
         if (sourceAddress !== undefined && !sameDatagramSource(sourceAddress, this.#transport.sender ?? (sender ??= sourceAddress))) return;
-        this.#router.feedPacket(packet, "multicast", ingress);
+        this.#router.feedPacket(packet, "multicast", ingressToFeed);
       };
       const fail = (error: unknown) =>
         console.warn(`[MulticastManager] repair group ${endpoint.group}:${endpoint.port} not joined`, error);
       if (typeof provider === "function") {
+        const marked = userAgentVerifiedIngress(ingress, options?.gateway);
+        const onPacket = (packet: Uint8Array, sourceAddress?: string) => feed(packet, sourceAddress, marked);
         Promise.resolve()
           .then(() => provider(endpoint, onPacket))
           .then((release) => (released ? safely(release) : releases.push(release)), fail);
         continue;
       }
-      const transport = new MulticastTransport((packet) => onPacket(packet), {
+      // The transport marks what it delivers when its gateway is the user
+      // agent's MulticastReceiver provider; feedPacket would not.
+      const transport = new MulticastTransport<MmtpIngressContext>((packet, delivered) => feed(packet, undefined, delivered ?? ingress), {
         gateway: provider,
         lockedTo: () => this.#transport.sender,
       });
@@ -2409,11 +2459,12 @@ export class MulticastManager {
         mode: endpoint.mode as MulticastEndpointConfig["mode"],
         amtRelay: endpoint.amtRelay,
         amtRelayPort: endpoint.amtRelayPort ?? (endpoint.amtRelay?.trim() ? DEFAULT_AMT_RELAY_PORT : undefined),
+        amtDiscovery: endpoint.amtDiscovery,
         packetIds: endpoint.packetIds,
         tracks: endpoint.tracks.map(({ name, packetId }) => ({ name, packetId })),
         // A protected repair group's records ride in band on its port (7.2.3).
         ...(endpoint.flow === undefined ? {} : { protected: true }),
-      }).then((joined) => {
+      }, ingress).then((joined) => {
         if (!joined && !released) fail(transport.lastJoinOutcome);
       });
     }
@@ -3172,10 +3223,15 @@ export class MulticastManager {
    * Register the range repair scheduler (draft-ramadan-moq-fec §7.5): from now
    * on an iso-ssbg1-v1 gap missing a source and every repair is kept as a
    * pending hole and reported here, and `closeIsoHoles` must be called for it
-   * once its range FETCH ends (or none is sent).
+   * once its range FETCH ends (or none is sent). `onExpired` is told of a
+   * pending hole the stream runs past the locator's horizon: returning true,
+   * the caller closes it (`closeIsoHoles`); otherwise it is discarded.
    */
-  onUndelimitedLoss(cb: (loss: UndelimitedIsoLoss) => void): void {
-    this.#fec.setUndelimitedLossHandler(cb);
+  onUndelimitedLoss(
+    cb: (loss: UndelimitedIsoLoss) => void,
+    onExpired?: (hole: ExpiredIsoHole) => boolean,
+  ): void {
+    this.#fec.setUndelimitedLossHandler(cb, onExpired ?? null);
   }
 
   /**
@@ -3494,6 +3550,9 @@ export class MulticastManager {
                 ...("symbols" in event
                   ? { symbols: Object.freeze({ ...event.symbols }) }
                   : {}),
+                ...("span" in event && event.span !== undefined
+                  ? { span: Object.freeze({ ...event.span }) }
+                  : {}),
               },
         ) as RepairLifecycleEvent);
     // Serialize before invoking observers so a re-entrant observer cannot log

package/src/multicast-transport.ts

@@ -6,7 +6,10 @@
 
 import {
   isMulticastTrackPacketId,
+  isUserAgentVerifiedGateway,
+  resolveMulticastGateway,
   subscriptionDeliversPacketBatches,
+  userAgentVerifiedIngress,
   toWindowMulticastSubscribeConfig,
   type WindowMulticastDelivery,
   type WindowMulticastGateway,
@@ -52,7 +55,13 @@ export interface MulticastTransportConfig {
   protected?: boolean
 }
 
-export type ResolvedMulticastTransport = 'native' | 'amt'
+/**
+ * The leg a join resolved to. `'user-agent'`: the browser's own
+ * `MulticastReceiver` delivers it, which picks native or AMT itself and does
+ * not say which. CMCD has no user-agent value, so a caller reports a
+ * `'user-agent'` join as `'native'` (`TransportSnapshot.transport`).
+ */
+export type ResolvedMulticastTransport = 'native' | 'amt' | 'user-agent'
 
 /**
  * Why a joined transport handed control back to MoQ.
@@ -211,16 +220,8 @@ function providerErrorOf(error: unknown): MulticastJoinProviderError | undefined
  */
 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'
+  return typeof resolveMulticastGateway()?.subscribe === 'function'
 }
 
 /**
@@ -371,6 +372,9 @@ export class MulticastTransport<TPacketContext = never> {
   // listener closure, so an in-place admission change (setContext) applies
   // from the next packet on without rejoining.
   #context: TPacketContext | undefined = undefined
+  #deliveredContext: TPacketContext | undefined = undefined
+  /** The live join's gateway, when it is the user agent's MulticastReceiver provider. */
+  #userAgentGateway: WindowMulticastGateway | undefined = undefined
   // The live join's provider-side filter. An in-place widening must reach it,
   // or the provider never delivers the new ID; null without a live join.
   #providerFilter: ProviderFilter | null = null
@@ -415,7 +419,7 @@ export class MulticastTransport<TPacketContext = never> {
     this.#sender = undefined
 
     if (this.#disposed) return this.#declined(generation, 'disposed')
-    const gateway = this.#gateway ?? getMulticastGlobals().multicast
+    const gateway = this.#gateway ?? resolveMulticastGateway()
     if (typeof gateway?.subscribe !== 'function') {
       console.warn('[MulticastTransport] Multicast API not available')
       return this.#declined(generation, 'unavailable')
@@ -435,15 +439,18 @@ export class MulticastTransport<TPacketContext = never> {
       console.log(
         `[MulticastTransport] window.multicast.subscribe(${config.sourceAddress ?? config.senderAddress ?? '*'}, ${config.groupAddress}, ${config.port})`,
       )
+      // The browser's MulticastReceiver picks native or AMT, and the relay,
+      // itself: ask it for the group only.
+      const userAgent = isUserAgentVerifiedGateway(gateway)
       const subscribeConfig = toWindowMulticastSubscribeConfig({
         source: config.sourceAddress,
         senderAddress: config.senderAddress,
         group: config.groupAddress,
         port: config.port,
-        mode: config.mode,
-        amtRelay: config.amtRelay,
-        amtRelayPort: config.amtRelayPort,
-        amtDiscovery: config.amtDiscovery,
+        mode: userAgent ? 'native' : config.mode,
+        amtRelay: userAgent ? undefined : config.amtRelay,
+        amtRelayPort: userAgent ? undefined : config.amtRelayPort,
+        amtDiscovery: userAgent ? undefined : config.amtDiscovery,
         packetIds: config.packetIds,
         tracks: config.tracks,
         atsc3: config.atsc3,
@@ -506,7 +513,8 @@ export class MulticastTransport<TPacketContext = never> {
         acknowledgedUpdate: 0,
         inFlight: 0,
       }
-      this.#context = context
+      this.#userAgentGateway = userAgent ? gateway : undefined
+      this.#setContext(context)
       // Seed the allow-list's counters so accepted packets never insert. An
       // id already counted by an earlier join keeps its count: the counters
       // are cumulative across rejoins, as bytesReceived is.
@@ -521,7 +529,7 @@ export class MulticastTransport<TPacketContext = never> {
       // gateway no longer exposes a mutable transport/transportchange
       // surface, so assign this only after subscribe() has resolved and the
       // returned subscription has passed the event-surface check above.
-      this.#resolvedTransport = subscribeConfig.origin === 'amt' ? 'amt' : 'native'
+      this.#resolvedTransport = userAgent ? 'user-agent' : subscribeConfig.origin === 'amt' ? 'amt' : 'native'
       // The provider alone knows whether its packets are independent
       // datagrams or an ordered relay of one socket; undeclared promises no
       // ordering. Announce it before the listener can deliver a packet. A
@@ -630,7 +638,7 @@ export class MulticastTransport<TPacketContext = never> {
     // Read per packet: a callback that changes the admission (an in-place
     // rendition switch committing on this very packet) takes effect from the
     // next packet, including the rest of a batch.
-    this.#onPacket(packet, this.#context)
+    this.#onPacket(packet, this.#deliveredContext)
     return liveness
   }
 
@@ -872,8 +880,10 @@ export class MulticastTransport<TPacketContext = never> {
   }
 
   /**
-   * What the live join delivers with every accepted packet (the join's
-   * `context`, or the last setContext), or undefined without a live join.
+   * The live join's context as the caller gave it (the join's `context`, or
+   * the last setContext), or undefined without a live join. On a native
+   * provider each accepted packet is delivered with a marked copy of it
+   * (`userAgentVerifiedIngress`); this getter never carries the mark.
    */
   get context(): TPacketContext | undefined {
     return this.#context
@@ -899,7 +909,19 @@ export class MulticastTransport<TPacketContext = never> {
         '[MulticastTransport] setContext needs a live join; join() carries the first context',
       )
     }
+    this.#setContext(context)
+  }
+
+  /**
+   * The join's context, and what the subscription delivers with each packet:
+   * marked admitted by the user agent when the gateway is its native
+   * MulticastReceiver provider. feedPacket never marks.
+   */
+  #setContext(context: TPacketContext | undefined): void {
     this.#context = context
+    this.#deliveredContext = this.#userAgentGateway !== undefined && typeof context === 'object' && context !== null
+      ? userAgentVerifiedIngress(context, this.#userAgentGateway)
+      : context
   }
 
   /**
@@ -1040,6 +1062,8 @@ export class MulticastTransport<TPacketContext = never> {
     this.#matchedSource = undefined
     this.#providerFilter = null
     this.#context = undefined
+    this.#deliveredContext = undefined
+    this.#userAgentGateway = undefined
     this.#withdrawnPacketIds.clear()
   }