@blockcast/mmt-container 0.1.0-main.0399efef1f07

package/dist/sample-combiner.d.ts

@@ -0,0 +1,212 @@
+/**
+ * @mmt/container - Sample-level combining of subsample data units (moqcast #37)
+ *
+ * {@link MFUReassembler} reassembles exactly one data unit -- a whole-sample
+ * DU, or one subsample DU of a partitioned sample. When a timed sample
+ * exceeds one data unit's 256-payload capacity, the origin packetizer
+ * partitions it into multiple subsample data units (each its own FI chain,
+ * its own authored base offset). This module combines those
+ * already-reassembled data units back into one contiguous sample.
+ *
+ * Container-blind, matching {@link MFUReassembler}'s own doctrine: it never
+ * parses ISOBMFF itself. The authored sample size a subsample-partitioned
+ * sample must total to comes from the host's own FT=1 (movie-fragment-
+ * metadata) parse, supplied via {@link SampleCombiner.registerAuthoredSize}.
+ * Completion is a protocol event -- every constituent data unit reassembled,
+ * byte-adjacent from zero, totaling the registered size -- never a
+ * timer-based guess; on lossy paths the existing per-data-unit deadline in
+ * {@link MFUReassembler} already bounds each constituent, so this module adds
+ * no second timer tier, matching moqcast #37 section 5.2.1.
+ *
+ * A whole-sample data unit whose length already equals the registered
+ * authored size passes through immediately, with no buffering. When
+ * `requireAuthoredSize` is false, an offset-zero data unit with no registered
+ * size at all also passes through immediately -- the pre-amendment shape, for
+ * a host that does not drive FT=1. When true, that same data unit instead
+ * buffers and waits for a size to be registered: FT=1 always publishes before
+ * any FT=2 sample referencing it (moqcast #37), but on a lossy path FT=1 can
+ * still *arrive* after an offset-zero data unit (reordering, or FT=1's own DU
+ * FEC-recovered late) -- treating "no size yet" as "whole sample" in that
+ * window would silently truncate a subsample-partitioned sample.
+ *
+ * Both `#pending` (incomplete samples) and `#authoredSizes` (registered but
+ * not yet consumed) are bounded. `#pending` is bounded by `maxBuffered`
+ * samples and `maxSegmentsPerSample` data units per sample; a full table
+ * evicts its oldest sample by insertion order rather than throwing, so one
+ * FEC-lost subsample DU cannot wedge every future sample. `#authoredSizes` is
+ * bounded by retiring each key the moment its sample completes, keeping only a
+ * bounded recent-retirement set so a late duplicate or FEC-recovered
+ * retransmission for that same sample is dropped rather than silently
+ * re-emitted or misread as a fresh whole sample.
+ *
+ * @packageDocumentation
+ */
+import type { MmtpSourcePath, ReassembledMFU, MmtpDeliveryProvenance } from './mfu-reassembler.js';
+/**
+ * An authored sample that provably will not be delivered, reported to the
+ * owner of any per-sample state keyed on this identity so that state can be
+ * released. See {@link SampleCombinerOptions.onAbandon}.
+ */
+export interface AbandonedSample {
+    catalogTrackName: string | undefined;
+    mpuSequenceNumber: number;
+    movieFragmentSequenceNumber: number;
+    sampleNumber: number;
+}
+/** One authored sample combined from its constituent data unit(s). */
+export interface CombinedSample {
+    mpuSequenceNumber: number;
+    movieFragmentSequenceNumber: number;
+    sampleNumber: number;
+    /** The full sample's media bytes, in ascending-offset order. */
+    data: Uint8Array;
+    /** Raw MMTP short-NTP header timestamp for the offset-zero data unit. */
+    mmtpTimestamp?: bigint;
+    timestamp: bigint;
+    /**
+     * The sample's RAP flag is the RAP flag of the FI=0 or FI=1 object of its
+     * offset-0 data unit (moqcast #37).
+     */
+    rapFlag: boolean;
+    priority?: number;
+    /** Every authoritative source-packet sequence across all constituent data units, in offset order. */
+    packetSequenceNumbers?: number[];
+    /** Subset of packetSequenceNumbers reconstructed by FEC. */
+    repairedPacketSequenceNumbers?: number[];
+    catalogTrackName?: string;
+    /** Number of subsample data units combined (1 for a whole-sample DU or a non-timed passthrough). */
+    subsampleCount: number;
+    /** MMTP fragments that formed the sample, summed across constituent data units. */
+    fragmentCount: number;
+    /**
+     * Transport that supplied the offset-zero data unit's head fragment. Taken
+     * from that data unit alone -- like {@link CombinedSample.rapFlag} -- rather
+     * than from whichever sibling happened to complete last.
+     */
+    source?: MmtpSourcePath;
+    /**
+     * Strict provenance folded across EVERY constituent data unit, and within
+     * each of them across every MMTP fragment. Unlike {@link CombinedSample.source},
+     * which is the offset-zero DU's routing tag, this is whole-sample evidence:
+     * only 'multicast' proves that no byte of this sample arrived another way.
+     */
+    deliveryProvenance: MmtpDeliveryProvenance;
+}
+export declare const SAMPLE_COMBINE_ERROR_CODES: readonly ["duplicate-subsample-offset", "overlapping-subsample", "exceeds-authored-size", "too-many-subsample-segments"];
+export type SampleCombineErrorCode = typeof SAMPLE_COMBINE_ERROR_CODES[number];
+/**
+ * Fail-closed rejection reasons for subsample combining. Distinct from
+ * {@link MfuReassemblyError}, which governs one data unit's own fragment
+ * chain; these govern combining already-reassembled data units into a
+ * sample.
+ */
+export declare class SampleCombineError extends Error {
+    readonly code: SampleCombineErrorCode;
+    readonly name = "SampleCombineError";
+    constructor(code: SampleCombineErrorCode, message: string);
+}
+export interface SampleCombinerStats {
+    combinedSamples: number;
+    passthroughSamples: number;
+    timedOutSamples: number;
+    /** Incomplete samples discarded to enforce `maxBuffered`. */
+    evictedSamples: number;
+}
+export interface SampleCombinerOptions {
+    /**
+     * Max concurrent incomplete samples. Enforced by evicting the oldest by
+     * insertion order, never by throwing, so a host that never calls
+     * {@link SampleCombiner.cleanupTimeouts} still recovers from a permanently
+     * lost subsample data unit instead of wedging.
+     */
+    maxBuffered: number;
+    /**
+     * When true, an offset-zero data unit with no registered authored size
+     * buffers and waits for one rather than passing through immediately. See
+     * the module doc.
+     */
+    requireAuthoredSize: boolean;
+    /**
+     * Max subsample data units held for one sample at once. Bounds both memory
+     * and the per-insert overlap scan; a legitimate subsample-partitioned
+     * sample needs at most `ceil(sampleSize / (256 * maxPayload))` data units.
+     */
+    maxSegmentsPerSample: number;
+    /**
+     * Called once per sample discarded by eviction or timeout -- the two paths
+     * where a sample is abandoned while its stream keeps running.
+     *
+     * Completion and passthrough are deliberately excluded: those samples were
+     * delivered, and their consumer releases whatever per-sample state it held.
+     * Wholesale resets (`flush`, `resetStream`) are excluded too, because they
+     * already discard that state in bulk.
+     *
+     * Exists because per-sample state elsewhere -- notably the ISO-BMFF
+     * timing-sample budget -- is otherwise only released on delivery, making it
+     * a one-way ratchet that wedges the stream once it saturates. The combiner
+     * is where abandonment is actually detected, so it is where the signal has
+     * to come from; inferring it downstream would require a timer or an age
+     * bound, neither of which is derivable from the catalog.
+     */
+    onAbandon?: (sample: AbandonedSample) => void;
+}
+/** Combines subsample data units of one sample into a contiguous whole. */
+export declare class SampleCombiner {
+    #private;
+    constructor(options: SampleCombinerOptions);
+    /**
+     * Register the authored sample size from the host's own FT=1 parse. Per
+     * moqcast #37, FT=1 for a movie fragment publishes before any FT=2 sample
+     * referencing it, so a host driving FT=1 as it arrives registers each
+     * sample's size before that sample's own data unit(s) arrive.
+     *
+     * On a lossy path FT=1 can still *arrive* late, after data units this
+     * combiner has already buffered. Registering a size therefore re-drives the
+     * completion check and returns the combined sample when the buffered data
+     * units already satisfy the newly-known size. Callers MUST consume the
+     * return value: for a sample carried by a single data unit there is no
+     * later {@link SampleCombiner.addMfu} to re-enter, so discarding it
+     * silently drops the sample.
+     *
+     * Registering also clears the key from the retired set. Retirement exists
+     * to drop data units that arrive *passively* after a sample completed — a
+     * late duplicate, an FEC-recovered retransmission. A host calling this
+     * method is instead asserting that a sample with this identity is authored
+     * now, which is what happens when a publisher restarts and its MPU
+     * sequence numbers begin again, or when MPU sequence wraps. Without this,
+     * such a stream would silently drop every sample whose identity collided
+     * with a retired one until the bounded set aged the key out.
+     */
+    registerAuthoredSize(catalogTrackName: string | undefined, mpuSequenceNumber: number, movieFragmentSequenceNumber: number, sampleNumber: number, size: number): CombinedSample | null;
+    /**
+     * Add one reassembled data unit. Returns the combined sample once every
+     * constituent data unit has arrived and totals the authored size.
+     */
+    addMfu(mfu: ReassembledMFU): CombinedSample | null;
+    /**
+     * Discard samples whose oldest held segment has waited past `timeoutMs`.
+     * Mirrors {@link MFUReassembler}'s clock-driven shape; the per-data-unit
+     * deadline inside {@link MFUReassembler} already bounds each constituent,
+     * so this is a backstop against a host that registers an authored size but
+     * never supplies every subsample DU.
+     */
+    cleanupTimeouts(timeoutMs: number): void;
+    flush(): void;
+    /**
+     * Drop one stream's in-flight, registered-size, and retired state while
+     * preserving every other stream (mirrors
+     * {@link MFUReassembler.resetStream}).
+     */
+    resetStream(catalogTrackName: string): void;
+    get stats(): SampleCombinerStats;
+    get pendingCount(): number;
+    /**
+     * Registered authored sizes still held. Diagnostic only: it exists so tests
+     * and health reporting can assert this table stays bounded, since an
+     * unbounded one is invisible from `pendingCount` alone.
+     */
+    get debugAuthoredSizeCount(): number;
+    /** Retired keys still remembered. Diagnostic only, bounded by `maxBuffered`. */
+    get debugRetiredCount(): number;
+}
+//# sourceMappingURL=sample-combiner.d.ts.map

package/dist/sample-combiner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sample-combiner.d.ts","sourceRoot":"","sources":["../src/sample-combiner.ts"],"names":[],"mappings":"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"}