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

package/dist/multicast-transport.d.ts

@@ -0,0 +1,271 @@
+/**
+ * Thin transport wrapper for SSM multicast — join, socket, watchdog,
+ * takeover/failback.  Delegates raw packets to a callback (MmtpRouter
+ * or any direct consumer).
+ */
+import { type WindowMulticastDelivery } from '@blockcast/mmt-transport';
+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 = 'native' | 'amt';
+/**
+ * Why a joined transport handed control back to MoQ.
+ *
+ * - `silence`: the data plane was live (at least one accepted packet since the
+ *   join) and then stayed silent for the catalog-derived failback window.
+ * - `subscription-error`: the provider reported the subscription failed. This
+ *   is the provider's own explicit, typed outcome (a `MulticastError`, branch
+ *   on its `code`), e.g. a bridge whose AMT tunnel it declared dead.
+ */
+export type MulticastFailbackReason = {
+    readonly kind: 'silence';
+    readonly windowMs: number;
+} | {
+    readonly kind: 'subscription-error';
+    readonly error: unknown;
+};
+/**
+ * Why a join() resolved false, named by the step at which the join stopped,
+ * never by what an error message says.
+ *
+ * - `disposed`: the transport was disposed before the join started, or while
+ *   the provider's subscribe() was pending.
+ * - `unavailable`: there is no window.multicast gateway with a subscribe().
+ * - `superseded`: a newer join() started while this join's subscribe() was
+ *   pending; the newer join owns the transport.
+ * - `invalid-request`: the join config does not make a valid window.multicast
+ *   request (toWindowMulticastSubscribeConfig refused it), so the provider was
+ *   never asked.
+ * - `provider-rejected`: the provider's subscribe() rejected or threw. The only
+ *   cause that carries the provider's own verdict (`providerError`).
+ * - `invalid-subscription`: subscribe() resolved something that is not a usable
+ *   subscription: no event surface, a malformed `eventTypes`, an unknown
+ *   `delivery`, or an `addEventListener` that threw.
+ * - `delivery-hook-failed`: the consumer's onDelivery hook threw for the
+ *   delivery the subscription declared, e.g. 'ordered-relay' to FEC tracks
+ *   configured without ordered geometry. A local configuration failure, not
+ *   the provider's.
+ */
+export type MulticastJoinDeclineReason = 'disposed' | 'unavailable' | 'superseded' | 'invalid-request' | 'provider-rejected' | 'invalid-subscription' | 'delivery-hook-failed';
+/**
+ * The typed part of a provider's subscribe() rejection. `name` and `code` are
+ * the provider's own typed fields; the frozen multicast contract makes `code`
+ * the one to branch on (e.g. a bridge's `amt_relay_refused`). `message` is
+ * free text carried for humans only: never branch on it.
+ */
+export interface MulticastJoinProviderError {
+    readonly name: string;
+    readonly message: string;
+    /** Present only when the provider's error carries a string `code`. */
+    readonly code?: string;
+}
+/**
+ * How a join() resolved: joined, or the typed reason it resolved false.
+ * `providerError` is present only for `provider-rejected`, and only when the
+ * provider's rejection value carries a string `name` and `message`.
+ */
+export type MulticastJoinOutcome = {
+    readonly ok: true;
+} | {
+    readonly ok: false;
+    readonly reason: MulticastJoinDeclineReason;
+    readonly providerError?: MulticastJoinProviderError;
+};
+/**
+ * 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;
+    /**
+     * packet_id 0, the MMTP signaling flow. Expected traffic on a protected
+     * session (moq_mmt sends the AL-FEC message on it), so it is counted apart
+     * from the unregistered-PID fault counter and never takes a
+     * `droppedPacketIds` slot.
+     */
+    packetsDroppedSignaling: number;
+}
+/**
+ * join() calls by how they resolved, cumulative for the life of the transport:
+ * across rejoins, failed joins and dispose. `succeeded` plus every `declined`
+ * count is the number of join() calls that resolved, superseded ones
+ * included; a join() that rejects counts in none (see
+ * MulticastTransport.lastJoinOutcome).
+ */
+export interface MulticastJoinStats {
+    /** join() calls that resolved true. */
+    readonly succeeded: number;
+    /** join() calls that resolved false, by the reason each one did. */
+    readonly declined: Readonly<Record<MulticastJoinDeclineReason, number>>;
+}
+export declare class MulticastTransport<TPacketContext = never> {
+    #private;
+    constructor(onPacket: (packet: Uint8Array, context?: TPacketContext) => void);
+    static isAvailable(): boolean;
+    join(config: MulticastTransportConfig, context?: TPacketContext): Promise<boolean>;
+    /** Feed a raw packet from an external source (e.g., AMT tunnel or ASM subscription). */
+    feedPacket(data: ArrayBuffer | Uint8Array, context?: TPacketContext): void;
+    confirmVideo(): void;
+    confirmAudio(): void;
+    onTakeover(cb: () => void): void;
+    onFailback(cb: (reason: MulticastFailbackReason) => void): void;
+    /**
+     * Called on every successful join, before the joined subscription can
+     * deliver a packet, with how that subscription delivers packets.
+     */
+    onDelivery(cb: (delivery: WindowMulticastDelivery) => void): void;
+    /** How the current subscription delivers packets, once joined. */
+    get delivery(): WindowMulticastDelivery | undefined;
+    /**
+     * Fires once per join, at the first packet the join accepts (after the PID
+     * filter; a rejected packet is not liveness). This is the data-plane-live
+     * edge, where this transport's silence window starts. A join whose source
+     * never sends never reaches it, so a host may start a media-arrival budget
+     * here only if the provider bounds the join phase with a typed subscription
+     * error (see SessionManager.joinActive); otherwise the host starts it when
+     * the subscribe settles.
+     */
+    onDataPlaneLive(cb: () => void): void;
+    /** Whether the current join has accepted a packet (see onDataPlaneLive). */
+    get dataPlaneLive(): boolean;
+    setFailbackWindowMs(windowMs: number): void;
+    get stats(): MulticastTransportStats;
+    /**
+     * How the newest join() to resolve did: `{ ok: true }`, or `{ ok: false }`
+     * with the typed reason it resolved false (and, for `provider-rejected`, the
+     * provider's typed error fields). Undefined until a join resolves. Branch on
+     * `reason` and `providerError.code`, never on log text or
+     * `providerError.message`.
+     *
+     * Newest is by start order: a join that resolves after a newer join has
+     * recorded its outcome does not replace it, so once `await join()` resolves
+     * this names that join's outcome unless a newer join has already resolved.
+     * It records how a join resolved, not whether it is still joined (see
+     * `joined`); a join() that rejects instead of resolving records nothing,
+     * the rejection being its report. Frozen: a later outcome replaces the
+     * object, never changes it.
+     */
+    get lastJoinOutcome(): MulticastJoinOutcome | undefined;
+    /**
+     * join() calls by how they resolved (see MulticastJoinStats). A fresh frozen
+     * snapshot on every read, so a later join never changes one already read.
+     * Kept apart from `stats`, which is the live counter object.
+     */
+    get joinStats(): MulticastJoinStats;
+    /**
+     * Accepted bytes summed over `packetIds`: the `bytesReceived` share of those
+     * MMTP packet_ids. Counted by the same rule, on every path that counts
+     * `bytesReceived` (only packets that pass the ingress filter; packet_id 0
+     * signaling never), and cumulative for the life of the transport, across
+     * rejoins, as `bytesReceived` is. An id never accepted contributes 0. An
+     * unparseable packet admitted by a join without an allow-list has no
+     * packet_id, so it counts toward `bytesReceived` only.
+     *
+     * Use it to scope an ABR throughput sample to the active tier's source and
+     * repair packet_ids when the join admits more than the active tier (a
+     * shared group joined across rendition switches); `bytesReceived` is then
+     * the whole allow-list's arrival, not the active tier's. A Set, so an id
+     * shared by two tracks of the tier is counted once.
+     *
+     * Monotonic only for a fixed set: each id has counted since it was first
+     * admitted, so after a tier switch the new set's sum is not a continuation
+     * of the old one. A cumulative consumer takes a fresh baseline for the new
+     * set and never differences across sets.
+     */
+    bytesReceivedForPacketIds(packetIds: ReadonlySet<number>): number;
+    /**
+     * 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>;
+    /**
+     * Distinct packet IDs dropped as provisioning faults: arriving on the wire
+     * but in no allow-list the join or an in-place update (setPacketIds)
+     * declared, the drops that raise the unadvertised-PID warning. A packet ID
+     * an in-place update withdrew is not one (see withdrawnPacketIdDrops).
+     * Cumulative across rejoins and capped with droppedPacketIds.
+     */
+    get unadvertisedPacketIds(): ReadonlySet<number>;
+    /**
+     * Packets dropped because an in-place update (setPacketIds) withdrew their
+     * packet ID while the provider may still deliver it: the expected tail of
+     * a deliberate change. A subset of packetsDroppedUnregisteredPid,
+     * cumulative across rejoins.
+     */
+    get withdrawnPacketIdDrops(): number;
+    /** Whether a subscription is live: joined, and not yet released or replaced. */
+    get joined(): boolean;
+    /**
+     * What the live join delivers with every accepted packet (the join's
+     * `context`, or the last setContext), or undefined without a live join.
+     */
+    get context(): TPacketContext | undefined;
+    /**
+     * The live join's page-side packet-ID allow-list, or null when it admits
+     * every packet ID (a join that carried none, or no live join).
+     */
+    get packetIds(): ReadonlySet<number> | null;
+    /**
+     * Replace what the live join delivers with each accepted packet, from the
+     * next packet on. The subscription (socket, group membership, AMT tunnel)
+     * is untouched: this is how an in-place rendition switch moves the router's
+     * ingress identities without leaving and re-joining the group.
+     */
+    setContext(context: TPacketContext): void;
+    /**
+     * Replace the live join's packet-ID allow-list in place, without rejoining.
+     *
+     * The page-side filter changes synchronously, before this returns: the
+     * next packet is admitted or dropped by the new list. The provider's own
+     * filter is updated through the subscription's `setPacketIds` when it has
+     * one; the returned promise settles with the provider's acknowledgement of
+     * this update. It resolves at once, telling the provider nothing, only
+     * when the provider cannot be told, or when no earlier update is still in
+     * flight and the provider already forwards exactly this list.
+     *
+     * While an update is in flight the provider's filter is not known, so every
+     * later update is sent: one skipped because it matched the last
+     * acknowledged filter would let the in-flight update land after it, and
+     * leave the provider forwarding a list nobody asked for last. Updates are
+     * numbered in send order and the newest acknowledged one describes the
+     * provider, so an acknowledgement that overtakes an older one is not undone
+     * by it.
+     *
+     * A provider without `setPacketIds` can still be narrowed: its wider filter
+     * keeps delivering the dropped IDs and the page-side filter discards them.
+     * It cannot be widened, since it would never deliver the added IDs; that is
+     * refused with a throw before anything changes. An ID this update withdraws
+     * may keep arriving until the provider applies the narrower list; those
+     * packets are counted as filtered like any other and in
+     * withdrawnPacketIdDrops, but are not unadvertised packet IDs: their
+     * arrival is the expected tail of this change rather than a provisioning
+     * fault.
+     */
+    setPacketIds(packetIds: readonly number[]): Promise<void>;
+    get resolvedTransport(): ResolvedMulticastTransport | undefined;
+    dispose(): void;
+}
+//# sourceMappingURL=multicast-transport.d.ts.map

package/dist/multicast-transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"multicast-transport.d.ts","sourceRoot":"","sources":["../src/multicast-transport.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAIL,KAAK,uBAAuB,EAG7B,MAAM,0BAA0B,CAAA;AAOjC,MAAM,WAAW,wBAAwB;IACvC,aAAa,EAAE,MAAM,CAAA;IACrB,YAAY,EAAE,MAAM,CAAA;IACpB,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,CAAC,EAAE,MAAM,GAAG,QAAQ,GAAG,QAAQ,CAAA;IACnC,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,SAAS,CAAC,EAAE,MAAM,EAAE,CAAA;IACpB,MAAM,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,EAAE,CAAA;CAC9C;AAED,MAAM,MAAM,0BAA0B,GAAG,QAAQ,GAAG,KAAK,CAAA;AAEzD;;;;;;;;GAQG;AACH,MAAM,MAAM,uBAAuB,GAC/B;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GACvD;IAAE,QAAQ,CAAC,IAAI,EAAE,oBAAoB,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;CAAE,CAAA;AAEpE;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,MAAM,0BAA0B,GAClC,UAAU,GACV,aAAa,GACb,YAAY,GACZ,iBAAiB,GACjB,mBAAmB,GACnB,sBAAsB,GACtB,sBAAsB,CAAA;AAE1B;;;;;GAKG;AACH,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,sEAAsE;IACtE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CACvB;AAED;;;;GAIG;AACH,MAAM,MAAM,oBAAoB,GAC5B;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAA;CAAE,GACrB;IACE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAA;IAClB,QAAQ,CAAC,MAAM,EAAE,0BAA0B,CAAA;IAC3C,QAAQ,CAAC,aAAa,CAAC,EAAE,0BAA0B,CAAA;CACpD,CAAA;AAEL;;;;;;;;;;GAUG;AACH,MAAM,WAAW,uBAAuB;IACtC,eAAe,EAAE,MAAM,CAAA;IACvB,aAAa,EAAE,MAAM,CAAA;IACrB,8EAA8E;IAC9E,6BAA6B,EAAE,MAAM,CAAA;IACrC,uFAAuF;IACvF,yBAAyB,EAAE,MAAM,CAAA;IACjC;;;;;OAKG;IACH,uBAAuB,EAAE,MAAM,CAAA;CAChC;AAED;;;;;;GAMG;AACH,MAAM,WAAW,kBAAkB;IACjC,uCAAuC;IACvC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,oEAAoE;IACpE,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,0BAA0B,EAAE,MAAM,CAAC,CAAC,CAAA;CACxE;AAqHD,qBAAa,kBAAkB,CAAC,cAAc,GAAG,KAAK;;gBAyExC,QAAQ,EAAE,CAAC,MAAM,EAAE,UAAU,EAAE,OAAO,CAAC,EAAE,cAAc,KAAK,IAAI;IAI5E,MAAM,CAAC,WAAW,IAAI,OAAO;IAIvB,IAAI,CAAC,MAAM,EAAE,wBAAwB,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,OAAO,CAAC;IAwPxF,wFAAwF;IACxF,UAAU,CAAC,IAAI,EAAE,WAAW,GAAG,UAAU,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,IAAI;IAQ1E,YAAY,IAAI,IAAI;IAKpB,YAAY,IAAI,IAAI;IAKpB,UAAU,CAAC,EAAE,EAAE,MAAM,IAAI,GAAG,IAAI;IAIhC,UAAU,CAAC,EAAE,EAAE,CAAC,MAAM,EAAE,uBAAuB,KAAK,IAAI,GAAG,IAAI;IAI/D;;;OAGG;IACH,UAAU,CAAC,EAAE,EAAE,CAAC,QAAQ,EAAE,uBAAuB,KAAK,IAAI,GAAG,IAAI;IAIjE,kEAAkE;IAClE,IAAI,QAAQ,IAAI,uBAAuB,GAAG,SAAS,CAElD;IAED;;;;;;;;OAQG;IACH,eAAe,CAAC,EAAE,EAAE,MAAM,IAAI,GAAG,IAAI;IAIrC,4EAA4E;IAC5E,IAAI,aAAa,IAAI,OAAO,CAE3B;IAED,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAiB3C,IAAI,KAAK,IAAI,uBAAuB,CAEnC;IAED;;;;;;;;;;;;;;OAcG;IACH,IAAI,eAAe,IAAI,oBAAoB,GAAG,SAAS,CAEtD;IAED;;;;OAIG;IACH,IAAI,SAAS,IAAI,kBAAkB,CAKlC;IAED;;;;;;;;;;;;;;;;;;;OAmBG;IACH,yBAAyB,CAAC,SAAS,EAAE,WAAW,CAAC,MAAM,CAAC,GAAG,MAAM;IAQjE;;;;OAIG;IACH,IAAI,gBAAgB,IAAI,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAElD;IAED;;;;;;OAMG;IACH,IAAI,qBAAqB,IAAI,WAAW,CAAC,MAAM,CAAC,CAE/C;IAED;;;;;OAKG;IACH,IAAI,sBAAsB,IAAI,MAAM,CAEnC;IAED,gFAAgF;IAChF,IAAI,MAAM,IAAI,OAAO,CAEpB;IAED;;;OAGG;IACH,IAAI,OAAO,IAAI,cAAc,GAAG,SAAS,CAExC;IAED;;;OAGG;IACH,IAAI,SAAS,IAAI,WAAW,CAAC,MAAM,CAAC,GAAG,IAAI,CAE1C;IAED;;;;;OAKG;IACH,UAAU,CAAC,OAAO,EAAE,cAAc,GAAG,IAAI;IASzC;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IACH,YAAY,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAyEzD,IAAI,iBAAiB,IAAI,0BAA0B,GAAG,SAAS,CAE9D;IAED,OAAO,IAAI,IAAI;CA+JhB"}