@blockcast/mmt-container 2.2.0-main.4a79a288e69e → 2.2.0-main.4ccba0f2f32a

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (54) hide show
  1. package/dist/browser-runtime.js +1119 -165
  2. package/dist/browser-runtime.js.map +3 -3
  3. package/dist/delta-fallback-config.js.map +1 -1
  4. package/dist/fec-manager.d.ts +67 -11
  5. package/dist/fec-manager.d.ts.map +1 -1
  6. package/dist/fec-manager.js +377 -54
  7. package/dist/fec-manager.js.map +2 -2
  8. package/dist/fec-worker-setup.js.map +1 -1
  9. package/dist/index.d.ts +2 -2
  10. package/dist/index.d.ts.map +1 -1
  11. package/dist/index.js.map +2 -2
  12. package/dist/iso-block-locator.d.ts +48 -13
  13. package/dist/iso-block-locator.d.ts.map +1 -1
  14. package/dist/iso-block-locator.js +97 -25
  15. package/dist/iso-block-locator.js.map +2 -2
  16. package/dist/media-router.js.map +1 -1
  17. package/dist/mmtp-container-parser.d.ts +64 -8
  18. package/dist/mmtp-container-parser.d.ts.map +1 -1
  19. package/dist/mmtp-container-parser.js +159 -21
  20. package/dist/mmtp-container-parser.js.map +2 -2
  21. package/dist/mmtp-container-parser.no-modules.js +158 -23
  22. package/dist/mmtp-container-parser.no-modules.js.map +2 -2
  23. package/dist/mmtp-decode-pipeline.js +158 -21
  24. package/dist/mmtp-decode-pipeline.js.map +2 -2
  25. package/dist/mmtp-router.d.ts +31 -8
  26. package/dist/mmtp-router.d.ts.map +1 -1
  27. package/dist/mmtp-router.js +481 -68
  28. package/dist/mmtp-router.js.map +2 -2
  29. package/dist/multicast-manager.d.ts +26 -3
  30. package/dist/multicast-manager.d.ts.map +1 -1
  31. package/dist/multicast-manager.js +940 -139
  32. package/dist/multicast-manager.js.map +2 -2
  33. package/dist/multicast-transport.js +2 -2
  34. package/dist/multicast-transport.js.map +2 -2
  35. package/dist/no-modules.js +158 -21
  36. package/dist/no-modules.js.map +2 -2
  37. package/dist/repair-fetch.d.ts +36 -8
  38. package/dist/repair-fetch.d.ts.map +1 -1
  39. package/dist/repair-fetch.js +285 -26
  40. package/dist/repair-fetch.js.map +3 -3
  41. package/dist/track-session.d.ts.map +1 -1
  42. package/dist/track-session.js +1 -0
  43. package/dist/track-session.js.map +2 -2
  44. package/dist/wasm-mmtp-container-parser.js +158 -21
  45. package/dist/wasm-mmtp-container-parser.js.map +2 -2
  46. package/package.json +5 -5
  47. package/src/fec-manager.ts +407 -28
  48. package/src/index.ts +3 -0
  49. package/src/iso-block-locator.ts +133 -31
  50. package/src/mmtp-container-parser.ts +273 -26
  51. package/src/mmtp-router.ts +541 -55
  52. package/src/multicast-manager.ts +118 -14
  53. package/src/repair-fetch.ts +363 -49
  54. package/src/track-session.ts +3 -0
@@ -18,8 +18,10 @@ import {
18
18
  type FecFallbackDecoder,
19
19
  type MulticastSymbolDelivery,
20
20
  type RepairVia,
21
+ type ExpiredIsoHole,
21
22
  type UndelimitedIsoLoss,
22
23
  type FecFailClosedEvent,
24
+ type IsoSpanFailure,
23
25
  } from "./fec-manager.js";
24
26
  import {
25
27
  deriveBlockClassifierGeometry,
@@ -108,6 +110,13 @@ export interface MulticastRepairEndpoint {
108
110
  tracks: MmtpIngressContext["tracks"];
109
111
  /** The protected flow (`MmtpRouter.registerProvenanceFlow`) this group's datagrams belong to. */
110
112
  flow?: string;
113
+ /**
114
+ * The group's own protected flow, which joinRepairEndpoints registers and
115
+ * releases itself, as join() does for the media flow. Its (S, G, port) must
116
+ * be the endpoint's. Never beside `flow`, which names a flow the caller
117
+ * registered.
118
+ */
119
+ provenance?: MulticastProvenanceJoin;
111
120
  }
112
121
 
113
122
  /**
@@ -407,6 +416,14 @@ export type RepairLifecycleEvent =
407
416
  readonly block: RepairBlockIdentity;
408
417
  readonly blockClass: BlockClass;
409
418
  readonly symbols: RepairSymbolCounts;
419
+ /**
420
+ * Set when what failed is an iso-ssbg1-v1 repair-less span starting at
421
+ * `block.sbn`: `length` SS_IDs between two stated blocks, `sources` of
422
+ * them received. No repair stated the blocks inside it, so the receiver
423
+ * cannot tell which of them lost a source; it is not the failure of the
424
+ * block at `block.sbn` alone.
425
+ */
426
+ readonly span?: IsoSpanFailure;
410
427
  }
411
428
  | {
412
429
  readonly version: 2;
@@ -791,6 +808,19 @@ function isSymbolCounts(value: unknown): boolean {
791
808
  );
792
809
  }
793
810
 
811
+ /** A failed repair-less span: `sources` of its `length` SS_IDs arrived, never all. */
812
+ function isSpanFailure(value: unknown): boolean {
813
+ if (!isRecord(value) || !hasExactKeys(value, ["length", "sources"])) return false;
814
+ const length = value["length"];
815
+ const sources = value["sources"];
816
+ return (
817
+ Number.isSafeInteger(length) &&
818
+ (length as number) > 0 &&
819
+ isNonNegativeSafeInteger(sources) &&
820
+ (sources as number) < (length as number)
821
+ );
822
+ }
823
+
794
824
  function isNullableNonNegative(value: unknown): boolean {
795
825
  return value === null || (typeof value === "number" && Number.isFinite(value) && value >= 0);
796
826
  }
@@ -833,10 +863,16 @@ export function isRepairLifecycleEvent(
833
863
  );
834
864
  case "failed":
835
865
  return (
836
- hasExactKeys(value, ["version", "type", "block", "blockClass", "symbols"]) &&
866
+ hasExactKeys(
867
+ value,
868
+ "span" in value
869
+ ? ["version", "type", "block", "blockClass", "symbols", "span"]
870
+ : ["version", "type", "block", "blockClass", "symbols"],
871
+ ) &&
837
872
  isRepairBlockIdentity(block) &&
838
873
  BLOCK_CLASSES.has(value["blockClass"]) &&
839
- isSymbolCounts(value["symbols"])
874
+ isSymbolCounts(value["symbols"]) &&
875
+ (!("span" in value) || isSpanFailure(value["span"]))
840
876
  );
841
877
  case "repair-preempted":
842
878
  case "repair-deferred":
@@ -1296,6 +1332,8 @@ export class MulticastManager {
1296
1332
  /** Live joinRepairEndpoints() releases → the repair owners they registered,
1297
1333
  * re-applied after configureMultiTrack() clears catalog-derived owners. */
1298
1334
  readonly #repairReleases = new Map<() => void, RepairOwnerEntry[]>();
1335
+ /** Protected repair flows owned by each live repair-endpoint release. */
1336
+ readonly #repairProvenanceFlows = new Map<() => void, string[]>();
1299
1337
  /** Each source's catalog keyframe overlay, from its `ok` binding. */
1300
1338
  readonly #overlayBindings = new Map<number, OverlayBinding>();
1301
1339
  /** Installed overlay decoders (`setKeyframeOverlayDecoder`), by source. */
@@ -1366,7 +1404,7 @@ export class MulticastManager {
1366
1404
  onPublisherRestart: (packetId, catalogTrackName) => {
1367
1405
  this.#resetStreamOutsideRouter(packetId, catalogTrackName);
1368
1406
  },
1369
- onBlockFailed: (sbn, packetId, catalogTrackName, blockClass) => {
1407
+ onBlockFailed: (sbn, packetId, catalogTrackName, blockClass, span) => {
1370
1408
  const pathCount = this.#fec.blockPathCount(
1371
1409
  sbn,
1372
1410
  packetId,
@@ -1385,6 +1423,7 @@ export class MulticastManager {
1385
1423
  multicast: pathCount?.multicastSymbols ?? 0,
1386
1424
  moq: pathCount?.moqSymbols ?? 0,
1387
1425
  },
1426
+ ...(span === undefined ? {} : { span }),
1388
1427
  });
1389
1428
  },
1390
1429
  onFrameGap: (decision) => {
@@ -2179,6 +2218,9 @@ export class MulticastManager {
2179
2218
  this.#transport.onFailback((reason) => {
2180
2219
  const joined = this.#provenanceJoin;
2181
2220
  if (joined !== null) this.#router.unprotectProvenanceFlow(joined.flow);
2221
+ for (const flows of this.#repairProvenanceFlows.values()) {
2222
+ for (const flow of flows) this.#router.unprotectProvenanceFlow(flow);
2223
+ }
2182
2224
  this.#onFailback?.(reason);
2183
2225
  });
2184
2226
  }
@@ -2221,6 +2263,12 @@ export class MulticastManager {
2221
2263
  "[MulticastManager] join: provenance flow (S, G, port) must match sourceAddress ?? senderAddress, groupAddress and port",
2222
2264
  );
2223
2265
  }
2266
+ if (provenanceFlow !== undefined) {
2267
+ const flow = multicastProvenanceFlowKey(provenanceFlow);
2268
+ if ([...this.#repairProvenanceFlows.values()].some((flows) => flows.includes(flow))) {
2269
+ throw new TypeError(`[MulticastManager] join: provenance flow already registered by a repair endpoint: ${flow}`);
2270
+ }
2271
+ }
2224
2272
  // A join replaces the admission a staged switch was built on. The new
2225
2273
  // join's config decides what is admitted, so nothing is restored or
2226
2274
  // retired here: the switch just ends.
@@ -2245,8 +2293,8 @@ export class MulticastManager {
2245
2293
  : selectedPacketIds === null
2246
2294
  ? undefined
2247
2295
  : [...selectedPacketIds].map((packetId) => ({ name: "", packetId }));
2248
- this.#releaseProvenanceJoin();
2249
2296
  const provenance = config.provenance;
2297
+ this.#releaseProvenanceJoin();
2250
2298
  const protectedTracks = ingressTracks ?? provenance?.flow.tracks;
2251
2299
  const ingress: MmtpIngressContext | undefined = protectedTracks === undefined
2252
2300
  ? undefined
@@ -2315,8 +2363,14 @@ export class MulticastManager {
2315
2363
  provenance: MulticastProvenanceJoin,
2316
2364
  ingress: MmtpIngressContext & { flow: string },
2317
2365
  ): void {
2366
+ this.#router.registerProvenanceFlow(ingress, this.#provenanceReceiver(provenance));
2367
+ this.#hookFailback();
2368
+ this.#provenanceJoin = { flow: ingress.flow };
2369
+ }
2370
+
2371
+ #provenanceReceiver(provenance: MulticastProvenanceJoin): BcProvenanceV2Receiver {
2318
2372
  const { flow, auth } = provenance;
2319
- const receiver = new BcProvenanceV2Receiver({
2373
+ return new BcProvenanceV2Receiver({
2320
2374
  ...provenance.receiver,
2321
2375
  // The caller's ctx when it passes one, else the catalog's: an explicit
2322
2376
  // `catalogCtx: undefined` must not switch off the 7.2.4 ctx check.
@@ -2333,9 +2387,6 @@ export class MulticastManager {
2333
2387
  maxAuthDelayMs: flow.maxAuthDelayMs,
2334
2388
  manifestTimerMs: flow.manifestTimerMs,
2335
2389
  });
2336
- this.#router.registerProvenanceFlow(ingress, receiver);
2337
- this.#hookFailback();
2338
- this.#provenanceJoin = { flow: ingress.flow };
2339
2390
  }
2340
2391
 
2341
2392
  /** Un-protect: drop the flow's hold queues (no expiry counted). */
@@ -2368,12 +2419,33 @@ export class MulticastManager {
2368
2419
  * callback delivers must come from a subscription opened on
2369
2420
  * `options.gateway`. A callback that also merges another source (a MoQ or
2370
2421
  * WebSocket repair feed) must not name a native provider here.
2422
+ *
2423
+ * An endpoint's `provenance` makes its group a protected flow of its own
2424
+ * (multicast-02 7.2.7), registered here and released with the group; its
2425
+ * records ride in band on the group's port. On the user-agent path a
2426
+ * flow-less repair group of a protected track is set aside, never read, so
2427
+ * a player joining a protected catalog's repair groups passes it.
2371
2428
  */
2372
2429
  joinRepairEndpoints(
2373
2430
  endpoints: readonly MulticastRepairEndpoint[],
2374
2431
  provider?: WindowMulticastGateway | MulticastRepairSubscribe,
2375
2432
  options?: { gateway?: WindowMulticastGateway },
2376
2433
  ): () => void {
2434
+ for (const { provenance, flow, source, group, port } of endpoints) {
2435
+ if (provenance === undefined) continue;
2436
+ if (flow !== undefined) {
2437
+ throw new TypeError("[MulticastManager] joinRepairEndpoints: an endpoint names provenance or flow, never both");
2438
+ }
2439
+ if (
2440
+ !sameIpAddress(source, provenance.flow.source) ||
2441
+ !sameIpAddress(group, provenance.flow.groupAddress) ||
2442
+ port !== provenance.flow.port
2443
+ ) {
2444
+ throw new RangeError(
2445
+ "[MulticastManager] joinRepairEndpoints: provenance flow (S, G, port) must match the endpoint's source, group and port",
2446
+ );
2447
+ }
2448
+ }
2377
2449
  const releases: Array<() => void> = [];
2378
2450
  let released = false;
2379
2451
  const safely = (each: () => void) => {
@@ -2383,6 +2455,19 @@ export class MulticastManager {
2383
2455
  console.warn("[MulticastManager] repair group release failed", error);
2384
2456
  }
2385
2457
  };
2458
+ const usedFlows = new Set<string>();
2459
+ const preparedProvenance = endpoints.map((endpoint) => {
2460
+ if (endpoint.provenance === undefined) return undefined;
2461
+ const flow = multicastProvenanceFlowKey(endpoint.provenance.flow);
2462
+ if (usedFlows.has(flow) || this.#provenanceJoin?.flow === flow ||
2463
+ [...this.#repairProvenanceFlows.values()].some((flows) => flows.includes(flow))) {
2464
+ throw new TypeError(`[MulticastManager] joinRepairEndpoints: provenance flow already registered: ${flow}`);
2465
+ }
2466
+ usedFlows.add(flow);
2467
+ // Construct every receiver before registering or joining any endpoint.
2468
+ return { flow, receiver: this.#provenanceReceiver(endpoint.provenance) };
2469
+ });
2470
+ const provenanceFlows: string[] = [];
2386
2471
  // An overlay leg's source and repair track names come from the
2387
2472
  // endpoint's ingress tracks.
2388
2473
  const repairOwners: RepairOwnerEntry[] = endpoints.flatMap((endpoint) =>
@@ -2392,11 +2477,19 @@ export class MulticastManager {
2392
2477
  repairTrackName: endpoint.tracks.find((t) => t.packetId === owner.packetId)?.name,
2393
2478
  }));
2394
2479
  this.#applyRepairOwners(repairOwners);
2395
- for (const endpoint of endpoints) {
2480
+ for (const [index, endpoint] of endpoints.entries()) {
2481
+ const flow = endpoint.provenance === undefined ? endpoint.flow : multicastProvenanceFlowKey(endpoint.provenance.flow);
2396
2482
  const ingress: MmtpIngressContext = {
2397
2483
  tracks: Object.freeze(endpoint.tracks.map(({ name, packetId }) => Object.freeze({ name, packetId }))),
2398
- ...(endpoint.flow === undefined ? {} : { flow: endpoint.flow }),
2484
+ ...(flow === undefined ? {} : { flow }),
2399
2485
  };
2486
+ if (endpoint.provenance !== undefined) {
2487
+ const prepared = preparedProvenance[index];
2488
+ if (prepared === undefined) throw new Error("[MulticastManager] repair provenance preparation missing");
2489
+ this.#router.registerProvenanceFlow(ingress as MmtpIngressContext & { flow: string }, prepared.receiver);
2490
+ provenanceFlows.push(prepared.flow);
2491
+ releases.push(() => this.#router.releaseProvenanceFlow(flow!));
2492
+ }
2400
2493
  let sender: string | undefined;
2401
2494
  const feed = (packet: Uint8Array, sourceAddress: string | undefined, ingressToFeed: MmtpIngressContext) => {
2402
2495
  if (released) return;
@@ -2433,7 +2526,7 @@ export class MulticastManager {
2433
2526
  packetIds: endpoint.packetIds,
2434
2527
  tracks: endpoint.tracks.map(({ name, packetId }) => ({ name, packetId })),
2435
2528
  // A protected repair group's records ride in band on its port (7.2.3).
2436
- ...(endpoint.flow === undefined ? {} : { protected: true }),
2529
+ ...(flow === undefined ? {} : { protected: true }),
2437
2530
  }, ingress).then((joined) => {
2438
2531
  if (!joined && !released) fail(transport.lastJoinOutcome);
2439
2532
  });
@@ -2442,9 +2535,12 @@ export class MulticastManager {
2442
2535
  if (released) return;
2443
2536
  released = true;
2444
2537
  this.#repairReleases.delete(release);
2538
+ this.#repairProvenanceFlows.delete(release);
2445
2539
  for (const each of releases.splice(0)) safely(each);
2446
2540
  };
2447
2541
  this.#repairReleases.set(release, repairOwners);
2542
+ this.#repairProvenanceFlows.set(release, provenanceFlows);
2543
+ if (provenanceFlows.length) this.#hookFailback();
2448
2544
  return release;
2449
2545
  }
2450
2546
 
@@ -3193,10 +3289,15 @@ export class MulticastManager {
3193
3289
  * Register the range repair scheduler (draft-ramadan-moq-fec §7.5): from now
3194
3290
  * on an iso-ssbg1-v1 gap missing a source and every repair is kept as a
3195
3291
  * pending hole and reported here, and `closeIsoHoles` must be called for it
3196
- * once its range FETCH ends (or none is sent).
3292
+ * once its range FETCH ends (or none is sent). `onExpired` is told of a
3293
+ * pending hole the stream runs past the locator's horizon: returning true,
3294
+ * the caller closes it (`closeIsoHoles`); otherwise it is discarded.
3197
3295
  */
3198
- onUndelimitedLoss(cb: (loss: UndelimitedIsoLoss) => void): void {
3199
- this.#fec.setUndelimitedLossHandler(cb);
3296
+ onUndelimitedLoss(
3297
+ cb: (loss: UndelimitedIsoLoss) => void,
3298
+ onExpired?: (hole: ExpiredIsoHole) => boolean,
3299
+ ): void {
3300
+ this.#fec.setUndelimitedLossHandler(cb, onExpired ?? null);
3200
3301
  }
3201
3302
 
3202
3303
  /**
@@ -3515,6 +3616,9 @@ export class MulticastManager {
3515
3616
  ...("symbols" in event
3516
3617
  ? { symbols: Object.freeze({ ...event.symbols }) }
3517
3618
  : {}),
3619
+ ...("span" in event && event.span !== undefined
3620
+ ? { span: Object.freeze({ ...event.span }) }
3621
+ : {}),
3518
3622
  },
3519
3623
  ) as RepairLifecycleEvent);
3520
3624
  // Serialize before invoking observers so a re-entrant observer cannot log