diff --git a/js/hang/src/container/consumer.test.ts b/js/hang/src/container/consumer.test.ts index a5f246a8f7e..f8a93fdb864 100644 --- a/js/hang/src/container/consumer.test.ts +++ b/js/hang/src/container/consumer.test.ts @@ -35,6 +35,12 @@ function settle(ms = 20): Promise { return new Promise((resolve) => setTimeout(resolve, ms)); } +// Keep transport drift filtering out of container-consumer tests. These cases +// exercise the consumer's own latency policy against a complete retained track. +function subscribeAll(track: Track.Producer): Track.Subscriber { + return track.subscribe({ latencyMax: 30_000 }); +} + // --- LegacyFormat --- test("LegacyFormat decodes a valid frame", () => { @@ -183,7 +189,7 @@ async function drainFrames( test("Consumer delivers frames from a single group", async () => { const track = new Track.Producer("test"); - const consumer = new Consumer(track.subscribe(), { format: new LegacyFormat(), latency: 500 as Time.Milli }); + const consumer = new Consumer(subscribeAll(track), { format: new LegacyFormat(), latency: 500 as Time.Milli }); writeGroupWithLegacyFrames(track, 0, [0 as Time.Micro, 33_000 as Time.Micro]); track.close(); @@ -197,7 +203,7 @@ test("Consumer delivers frames from a single group", async () => { test("Consumer forces keyframe true at index 0", async () => { const track = new Track.Producer("test"); - const consumer = new Consumer(track.subscribe(), { format: new LegacyFormat(), latency: 500 as Time.Milli }); + const consumer = new Consumer(subscribeAll(track), { format: new LegacyFormat(), latency: 500 as Time.Milli }); writeGroupWithLegacyFrames(track, 0, [0 as Time.Micro, 33_000 as Time.Micro]); track.close(); @@ -221,7 +227,7 @@ test("Consumer index spans MoQ frames for keyframe detection", async () => { }; const track = new Track.Producer("test"); - const consumer = new Consumer(track.subscribe(), { format: multiFormat, latency: 500 as Time.Milli }); + const consumer = new Consumer(subscribeAll(track), { format: multiFormat, latency: 500 as Time.Milli }); const group = new Group.Producer(0); group.writeFrame({ payload: new Uint8Array([0x01]), timestamp: Time.Timestamp.now() }); // first MoQ frame → 3 samples @@ -249,7 +255,7 @@ test("Consumer keeps frames decoded before an error (truncated GoP)", async () = }; const track = new Track.Producer("test"); - const consumer = new Consumer(track.subscribe(), { format: truncatingFormat, latency: 500 as Time.Milli }); + const consumer = new Consumer(subscribeAll(track), { format: truncatingFormat, latency: 500 as Time.Milli }); // Group.Producer 0: 2 valid frames then a tail-truncating error. const g0 = new Group.Producer(0); @@ -276,7 +282,7 @@ test("Consumer keeps frames decoded before an error (truncated GoP)", async () = test("Consumer close returns undefined from next()", async () => { const track = new Track.Producer("test"); - const consumer = new Consumer(track.subscribe(), { format: new LegacyFormat(), latency: 500 as Time.Milli }); + const consumer = new Consumer(subscribeAll(track), { format: new LegacyFormat(), latency: 500 as Time.Milli }); const promise = consumer.next(); consumer.close(); @@ -287,7 +293,7 @@ test("Consumer close returns undefined from next()", async () => { test("Consumer throws on concurrent next() calls", async () => { const track = new Track.Producer("test"); - const consumer = new Consumer(track.subscribe(), { format: new LegacyFormat(), latency: 500 as Time.Milli }); + const consumer = new Consumer(subscribeAll(track), { format: new LegacyFormat(), latency: 500 as Time.Milli }); // First call blocks waiting for data void consumer.next(); @@ -300,7 +306,7 @@ test("Consumer throws on concurrent next() calls", async () => { test("Consumer skips groups via PTS-span when over latency", async () => { const track = new Track.Producer("test"); // Zero latency = skip everything that's not the latest - const consumer = new Consumer(track.subscribe(), { format: new LegacyFormat(), latency: 0 as Time.Milli }); + const consumer = new Consumer(subscribeAll(track), { format: new LegacyFormat(), latency: 0 as Time.Milli }); // Write groups with increasing timestamps. With 0 latency, any PTS span > 0 triggers skip. writeGroupWithLegacyFrames(track, 0, [0 as Time.Micro]); @@ -319,7 +325,7 @@ test("Consumer skips groups via PTS-span when over latency", async () => { test("Consumer delivers groups in sequence order regardless of arrival order", async () => { const track = new Track.Producer("test"); - const consumer = new Consumer(track.subscribe(), { format: new LegacyFormat(), latency: 500 as Time.Milli }); + const consumer = new Consumer(subscribeAll(track), { format: new LegacyFormat(), latency: 500 as Time.Milli }); writeGroupWithLegacyFrames(track, 2, [60_000 as Time.Micro]); writeGroupWithLegacyFrames(track, 0, [0 as Time.Micro]); @@ -338,7 +344,7 @@ test("Consumer delivers groups in sequence order regardless of arrival order", a test("Consumer rejects stale groups", async () => { const track = new Track.Producer("test"); - const consumer = new Consumer(track.subscribe(), { format: new LegacyFormat(), latency: 500 as Time.Milli }); + const consumer = new Consumer(subscribeAll(track), { format: new LegacyFormat(), latency: 500 as Time.Milli }); // Group.Producer 5 arrives first (sets active = 5) writeGroupWithLegacyFrames(track, 5, [0 as Time.Micro]); @@ -363,7 +369,7 @@ test("Consumer rejects stale groups", async () => { test("Consumer next() returns group-done signals", async () => { const track = new Track.Producer("test"); - const consumer = new Consumer(track.subscribe(), { format: new LegacyFormat(), latency: 500 as Time.Milli }); + const consumer = new Consumer(subscribeAll(track), { format: new LegacyFormat(), latency: 500 as Time.Milli }); writeGroupWithLegacyFrames(track, 0, [0 as Time.Micro, 33_000 as Time.Micro]); writeGroupWithLegacyFrames(track, 1, [66_000 as Time.Micro]); @@ -394,7 +400,7 @@ test("Consumer next() returns group-done signals", async () => { test("Consumer buffered signal updates as frames arrive", async () => { const track = new Track.Producer("test"); - const consumer = new Consumer(track.subscribe(), { format: new LegacyFormat(), latency: 500 as Time.Milli }); + const consumer = new Consumer(subscribeAll(track), { format: new LegacyFormat(), latency: 500 as Time.Milli }); expect(consumer.buffered.peek()).toEqual([]); @@ -416,7 +422,7 @@ test("Consumer buffered signal updates as frames arrive", async () => { test("Consumer recovers from gap in group sequence numbers", async () => { const track = new Track.Producer("test"); - const consumer = new Consumer(track.subscribe(), { format: new LegacyFormat(), latency: 100 as Time.Milli }); + const consumer = new Consumer(subscribeAll(track), { format: new LegacyFormat(), latency: 100 as Time.Milli }); writeGroupWithLegacyFrames(track, 0, [0 as Time.Micro, 20_000 as Time.Micro]); writeGroupWithLegacyFrames(track, 1, [40_000 as Time.Micro, 60_000 as Time.Micro]); @@ -446,7 +452,7 @@ test("Consumer handles empty decode result without deadlock", async () => { }; const track = new Track.Producer("test"); - const consumer = new Consumer(track.subscribe(), { format: emptyThenValid, latency: 500 as Time.Milli }); + const consumer = new Consumer(subscribeAll(track), { format: emptyThenValid, latency: 500 as Time.Milli }); const group = new Group.Producer(0); group.writeFrame({ payload: new Uint8Array([0x01]), timestamp: Time.Timestamp.now() }); // empty decode @@ -469,7 +475,7 @@ test("Consumer handles empty decode result without deadlock", async () => { test("Consumer with CmafFormat delivers correct timestamps", async () => { const track = new Track.Producer("test"); - const consumer = new Consumer(track.subscribe(), { + const consumer = new Consumer(subscribeAll(track), { format: new CmafFormat(TEST_INIT), latency: 500 as Time.Milli, }); @@ -542,7 +548,7 @@ const durationFormat: ContainerFormat = { test("Consumer duration-skips a stalled group once it is covered", async () => { const track = new Track.Producer("test"); // Latency dwarfs the gap, so only duration coverage can trigger the skip. - const consumer = new Consumer(track.subscribe(), { format: durationFormat, latency: 10_000 as Time.Milli }); + const consumer = new Consumer(subscribeAll(track), { format: durationFormat, latency: 10_000 as Time.Milli }); // Group.Producer 0: one frame at ts=0 lasting 33ms, never closed (stalled). const g0 = new Group.Producer(0); @@ -579,7 +585,7 @@ test("Consumer does not duration-skip when the gap is not covered", async () => }; const track = new Track.Producer("test"); - const consumer = new Consumer(track.subscribe(), { format: shortFormat, latency: 10_000 as Time.Milli }); + const consumer = new Consumer(subscribeAll(track), { format: shortFormat, latency: 10_000 as Time.Milli }); // Group.Producer 0 stays open and later receives a second frame; nothing covers the gap, // so that late frame must survive rather than being skipped. @@ -612,7 +618,10 @@ test("Consumer does not duration-skip when the gap is not covered", async () => // surface immediately, even while still open. test("Consumer delivers a PTS-contiguous next group whose sequence jumped (CMAF)", async () => { const track = new Track.Producer("test"); - const consumer = new Consumer(track.subscribe(), { format: new CmafFormat(TEST_INIT), latency: 500 as Time.Milli }); + const consumer = new Consumer(subscribeAll(track), { + format: new CmafFormat(TEST_INIT), + latency: 500 as Time.Milli, + }); // Group A (seq 1_000_000): one 3000-tick sample, so its content ends at 33_333µs (3000/90000 * 1e6). const a = new Group.Producer(1_000_000); @@ -668,7 +677,7 @@ test("Consumer delivers a PTS-contiguous next group whose sequence jumped (CMAF) test("Consumer waits on a PTS gap instead of skipping to a later buffered group (CMAF)", async () => { const track = new Track.Producer("test"); // Large latency so the gap can't be latency-skipped during the test window. - const consumer = new Consumer(track.subscribe(), { + const consumer = new Consumer(subscribeAll(track), { format: new CmafFormat(TEST_INIT), latency: 10_000 as Time.Milli, }); @@ -742,7 +751,7 @@ test("Consumer waits on a PTS gap instead of skipping to a later buffered group // blocks every later contiguous group. test("Consumer delivers a contiguous group after one that completed out of order (CMAF)", async () => { const track = new Track.Producer("test"); - const consumer = new Consumer(track.subscribe(), { + const consumer = new Consumer(subscribeAll(track), { format: new CmafFormat(TEST_INIT), latency: 10_000 as Time.Milli, }); @@ -790,7 +799,10 @@ test("Consumer delivers a contiguous group after one that completed out of order // that check is the only thing left that can break the stall. test("Consumer latency-skips a waited-out gap when only the head receives frames (CMAF)", async () => { const track = new Track.Producer("test"); - const consumer = new Consumer(track.subscribe(), { format: new CmafFormat(TEST_INIT), latency: 100 as Time.Milli }); + const consumer = new Consumer(subscribeAll(track), { + format: new CmafFormat(TEST_INIT), + latency: 100 as Time.Milli, + }); // A (seq 1000): one frame, ends at 3000 ticks (33_333µs). const a = new Group.Producer(1000); @@ -840,7 +852,7 @@ test("Consumer latency-skips a waited-out gap when only the head receives frames // sequential, and adjacency doesn't rule out a group the latency check dropped on the way past. test("Consumer reports continuity while nothing is dropped", async () => { const track = new Track.Producer("test"); - const consumer = new Consumer(track.subscribe(), { format: new LegacyFormat(), latency: 100 as Time.Milli }); + const consumer = new Consumer(subscribeAll(track), { format: new LegacyFormat(), latency: 100 as Time.Milli }); writeGroupWithLegacyFrames(track, 0, [0 as Time.Micro, 33_000 as Time.Micro]); await settle(); @@ -859,7 +871,7 @@ test("Consumer reports continuity while nothing is dropped", async () => { // The case the group-number heuristic got backwards: ids jump, but the PTS timeline is unbroken. test("Consumer reports continuity across a PTS-contiguous group id jump (CMAF)", async () => { const track = new Track.Producer("test"); - const consumer = new Consumer(track.subscribe(), { + const consumer = new Consumer(subscribeAll(track), { format: new CmafFormat(TEST_INIT), latency: 10_000 as Time.Milli, }); diff --git a/js/json/src/snapshot/compression.test.ts b/js/json/src/snapshot/compression.test.ts index 235d42dd2bb..823195f3aa5 100644 --- a/js/json/src/snapshot/compression.test.ts +++ b/js/json/src/snapshot/compression.test.ts @@ -8,6 +8,7 @@ type Value = Record; const enc = new TextEncoder(); const dec = new TextDecoder(); +const REPLAY_LATENCY = 30_000; // Reconstruct every value a compressed consumer yields, in order. async function drainCompressed(track: Track.Subscriber): Promise { @@ -44,7 +45,7 @@ test("compressed snapshot per group round-trips", async () => { producer.finish(); // Deltas off: one compressed snapshot per group, reconstructed in order. - expect(await drainCompressed(track.subscribe())).toEqual([{ a: 1 }, { a: 2 }]); + expect(await drainCompressed(track.subscribe({ latencyMax: REPLAY_LATENCY }))).toEqual([{ a: 1 }, { a: 2 }]); }); test("compressed live consumer sees each update in order", async () => { @@ -139,7 +140,7 @@ test("compressed deltas roll on the compressed budget", async () => { }; const layout = new Track.Producer("layout"); - const layoutSub = layout.subscribe(); + const layoutSub = layout.subscribe({ latencyMax: REPLAY_LATENCY }); fill(layout); expect(await groupCount(layoutSub)).toBeGreaterThan(1); diff --git a/js/json/src/snapshot/snapshot.test.ts b/js/json/src/snapshot/snapshot.test.ts index f1b3e1d0e81..d97bfa88dca 100644 --- a/js/json/src/snapshot/snapshot.test.ts +++ b/js/json/src/snapshot/snapshot.test.ts @@ -5,6 +5,10 @@ import { Producer } from "./producer.ts"; type Value = Record; +// These tests inspect complete finished timelines, so request a replay window +// instead of the transport's live-edge default. +const REPLAY_LATENCY = 30_000; + // Reconstruct every value a consumer yields, in order. async function drain(track: Track.Subscriber): Promise { const out: Value[] = []; @@ -35,7 +39,7 @@ test("deltas off: a snapshot group per change", async () => { producer.finish(); // Two changes => two single-frame snapshot groups, reconstructed in order. - expect(await drain(track.subscribe())).toEqual([{ a: 1 }, { a: 2 }]); + expect(await drain(track.subscribe({ latencyMax: REPLAY_LATENCY }))).toEqual([{ a: 1 }, { a: 2 }]); }); test("deltaRatio 0 disables deltas, like off", async () => { @@ -47,7 +51,7 @@ test("deltaRatio 0 disables deltas, like off", async () => { // `0` is treated as off, not a degenerate "enabled" value that keeps the group open: each change // is its own single-frame snapshot group. - expect(await structure(track.subscribe())).toEqual([1, 1]); + expect(await structure(track.subscribe({ latencyMax: REPLAY_LATENCY }))).toEqual([1, 1]); }); test("live consumer sees each update", async () => { @@ -161,7 +165,7 @@ test("tight ratio rolls snapshots", async () => { producer.update({ a: 4 }); // budget already exceeded, rolls group 1 producer.finish(); - expect(await structure(track.subscribe())).toEqual([3, 1]); + expect(await structure(track.subscribe({ latencyMax: REPLAY_LATENCY }))).toEqual([3, 1]); }); test("deltas stay within ratio times snapshot", async () => { @@ -175,7 +179,7 @@ test("deltas stay within ratio times snapshot", async () => { for (let n = 0; n <= 10; n++) producer.update({ n }); producer.finish(); - expect(await structure(track.subscribe())).toEqual([10, 1]); + expect(await structure(track.subscribe({ latencyMax: REPLAY_LATENCY }))).toEqual([10, 1]); }); test("array change is a wholesale delta", async () => { @@ -212,5 +216,5 @@ test("frame cap rolls snapshot", async () => { } producer.finish(); - expect(await structure(track.subscribe())).toEqual([256, 1]); + expect(await structure(track.subscribe({ latencyMax: REPLAY_LATENCY }))).toEqual([256, 1]); }); diff --git a/js/net/src/broadcast.test.ts b/js/net/src/broadcast.test.ts index ea40cbcf277..152e8466e88 100644 --- a/js/net/src/broadcast.test.ts +++ b/js/net/src/broadcast.test.ts @@ -159,8 +159,8 @@ test("two subscribers to one inserted track each get a full copy", async () => { const broadcast = new BroadcastProducer(); const producer = broadcast.createTrack("video"); - const a = broadcast.track("video").subscribe(); - const b = broadcast.track("video").subscribe(); + const a = broadcast.track("video").subscribe({ latencyMax: 5000 }); + const b = broadcast.track("video").subscribe({ latencyMax: 5000 }); producer.writeString("hello"); producer.writeString("world"); @@ -189,7 +189,7 @@ test("a late subscriber replays the cached window", async () => { test("a read throws Lagged on a gap, then resyncs to the next group", async () => { const broadcast = new BroadcastProducer(); const producer = broadcast.createTrack("video"); - const sub = broadcast.track("video").subscribe(); + const sub = broadcast.track("video").subscribe({ latencyMax: 5000 }); // Group 0 overflows its frame cap without being read, evicting the front: a gap. const g0 = producer.appendGroup(); diff --git a/js/net/src/broadcast.ts b/js/net/src/broadcast.ts index c6bf494f726..4d4e356273a 100644 --- a/js/net/src/broadcast.ts +++ b/js/net/src/broadcast.ts @@ -113,6 +113,7 @@ async function fetchGroup( options: track.FetchGroupOptions = {}, ): Promise { const subscriber = subscribe(state, name, { priority: options.priority }); + hooks.ignoreLatency(subscriber); try { for (;;) { const group = await subscriber.recvGroup(); diff --git a/js/net/src/group.ts b/js/net/src/group.ts index 6355dc0ca2b..f53810f0e8c 100644 --- a/js/net/src/group.ts +++ b/js/net/src/group.ts @@ -3,7 +3,8 @@ * * @module */ -import { type GetPromise, type Getter, Once, Signal } from "@moq/signals"; +import { type Dispose, type GetPromise, type Getter, Once, Signal } from "@moq/signals"; +import { hooks } from "./internal.ts"; import { Timestamp } from "./time.ts"; /** Maximum bytes of frames cached in a group before old frames are evicted from the front. */ @@ -28,6 +29,17 @@ export interface Frame { timestamp: Timestamp; } +/** + * Where a group cursor sits, for a subscription's drift budget to measure it against + * the live edge. Undefined fields mean the group has presented nothing yet. + * + * @internal + */ +export interface Position { + presentation?: Timestamp; + activity?: number; +} + /** Immutable group metadata. */ export interface Info { /** Sequence number of this group within its track. */ @@ -56,6 +68,13 @@ class GroupState { // them has a gap, so its next read throws Lagged rather than skipping silently. offset = 0; cacheBytes = 0; + // The first frame's timestamp, retained after reads and front eviction. + timestamp?: Timestamp; + // The newest frame's timestamp: where a reader that has taken every frame sits. + latest?: Timestamp; + // When the group last accepted a frame. A group is silent from here, not from + // whenever it was created. + activity?: number; constructor(sequence: number) { this.sequence = sequence; @@ -65,6 +84,9 @@ class GroupState { function appendFrame(state: GroupState, frame: Frame) { if (state.closed.peek() !== undefined) throw new Error("group is closed"); + state.timestamp ??= frame.timestamp; + state.latest = frame.timestamp; + state.activity = performance.now(); state.cacheBytes += frame.payload.byteLength; state.frames.mutate((frames) => { frames.push(frame); @@ -125,6 +147,9 @@ export class Producer { */ mirror(): Consumer { const dst = new GroupState(this.sequence); + dst.timestamp = this.#state.timestamp; + dst.latest = this.#state.latest; + dst.activity = this.#state.activity; for (const frame of this.#state.frames.peek()) appendFrame(dst, frame); dst.offset = this.#state.offset; @@ -235,6 +260,15 @@ export class Consumer { readonly sequence: number; #state: GroupState; + #expiry?: { expired: (at: Position) => boolean; changed: readonly Getter[] }; + // Sticky verdicts, set once. `#ended` is a drained group the budget gave up on, + // which is indistinguishable from one that ended: nothing was lost, so it reads as + // the end of the group. `#terminal` is a failure, including a budget that gave up + // while content was still unread. + #ended = false; + #terminal?: Error; + #closed = new Once(); + #watchingClosed = false; private constructor(state: GroupState) { this.#state = state; @@ -246,11 +280,130 @@ export class Consumer { * Peek it synchronously (`undefined` while open), observe it reactively, or `await` it. */ get closed(): GetPromise { - return this.#state.closed; + this.#watchClosed(); + return this.#closed; } static { makeConsumer = (state) => new Consumer(state); + hooks.groupTimestamp = (group) => group.#state.timestamp; + hooks.expireGroup = (group, expiry) => { + group.#expiry = expiry; + }; + hooks.guardGroup = (group, operation) => group.#guard(operation); + hooks.evictGroup = (group) => { + group.#evict(); + }; + } + + /// Where this cursor sits, for the budget to measure against the live edge. + // + // A group is not late because it *started* long ago; what can be late is the content + // its reader has yet to take. So a reader that has drained the group sits at the + // group's newest frame, not its first. + #position(): Position { + return { + presentation: this.#state.frames.peek()[0]?.timestamp ?? this.#state.latest, + activity: this.#state.activity, + }; + } + + // Evaluate the drift budget for a read that has nothing buffered and is about to + // wait. A group with frames in hand is always drained: the budget bounds a group + // that has stalled while the live edge moved on, not a reader slower than the wire. + // Returns true if a verdict was just reached, so the caller re-checks. + // + // `unread` is for a caller that still holds content the reader has not seen (a + // publisher part-way through writing a frame): giving up there is a truncation, so + // it fails rather than ending. + #expire(unread = false): boolean { + if (this.#terminal || this.#ended) return false; + if (this.#state.closed.peek() instanceof Error) return false; + if (!this.#expiry?.expired(this.#position())) return false; + + if (unread) { + this.#terminal = new Error("group exceeded the subscription latency budget"); + } else { + this.#ended = true; + } + if (this.#closed.peek() === undefined) this.#closed.set(this.#terminal ?? null); + return true; + } + + #guard(operation: Promise): Promise { + if (this.#expire(true)) return Promise.reject(this.#terminal); + if (this.#terminal) return Promise.reject(this.#terminal); + const expiry = this.#expiry; + if (!expiry) return operation; + + return new Promise((resolve, reject) => { + let settled = false; + const disposes: Dispose[] = []; + const finish = (fn: () => void) => { + if (settled) return; + settled = true; + for (const dispose of disposes) dispose(); + fn(); + }; + const check = () => { + this.#expire(true); + if (this.#terminal) { + const error = this.#terminal; + finish(() => reject(error)); + } + }; + + for (const changed of expiry.changed) disposes.push(changed.subscribe(check)); + operation.then( + (value) => finish(() => resolve(value)), + (error: unknown) => finish(() => reject(error)), + ); + check(); + }); + } + + #evict() { + const frames = this.#state.frames.peek(); + if (frames.length > 0) { + // Unread content is going away either way. If the budget had already given up + // on this group that is the more specific reason, so ask it first; otherwise + // the reader simply lagged behind the cache. + this.#expire(true); + if (!this.#terminal && !this.#ended) { + this.#terminal = new Lagged(); + if (this.#closed.peek() === undefined) this.#closed.set(this.#terminal); + } + } + this.#state.offset += frames.length; + this.#state.cacheBytes = 0; + this.#state.frames.set([]); + } + + #watchClosed() { + if (this.#watchingClosed) return; + this.#watchingClosed = true; + void this.#runClosed(); + } + + async #runClosed() { + for (;;) { + if (this.#terminal || this.#ended) return; + const closed = this.#state.closed.peek(); + if (closed !== undefined) { + this.#closed.set(closed); + return; + } + if (this.#expire()) return; + await this.#changed(); + } + } + + async #changed(): Promise { + if (!this.#expiry) { + await Signal.race(this.#state.frames, this.#state.closed); + return; + } + await Signal.race(this.#state.frames, this.#state.closed, ...this.#expiry.changed); } #readBufferedFrame(): { sequence: number; frame: Frame } | undefined { @@ -264,12 +417,16 @@ export class Consumer { /** True once no further frames can be read: the group has closed and every buffered frame is read. */ get done(): boolean { - return this.#state.frames.peek().length === 0 && this.#state.closed.peek() !== undefined; + return ( + this.#terminal !== undefined || + this.#ended || + (this.#state.frames.peek().length === 0 && this.#state.closed.peek() !== undefined) + ); } /** True once the group has been closed, regardless of whether buffered frames remain unread. Synchronous complement to the {@link closed} promise. */ get isClosed(): boolean { - return this.#state.closed.peek() !== undefined; + return this.#terminal !== undefined || this.#ended || this.#state.closed.peek() !== undefined; } /** True if frames were evicted from the front of this group before being read. */ @@ -285,12 +442,14 @@ export class Consumer { * end-of-group: check {@link done} to tell "no frame buffered yet" from "finished". */ tryReadFrame(): Frame | undefined { + if (this.#terminal || this.#ended) return undefined; const read = this.#readBufferedFrame(); return read?.frame; } /** Like {@link tryReadFrame} but also reports the frame's sequence number within the group. */ tryReadFrameSequence(): ({ sequence: number } & Frame) | undefined { + if (this.#terminal || this.#ended) return undefined; const read = this.#readBufferedFrame(); if (!read) return undefined; return { sequence: read.sequence, payload: read.frame.payload, timestamp: read.frame.timestamp }; @@ -299,9 +458,11 @@ export class Consumer { /** Resolves once {@link readFrame} would not block. */ async readable(): Promise { for (;;) { + if (this.#terminal || this.#ended) return; if (this.#state.frames.peek().length > 0) return; if (this.#state.closed.peek() !== undefined) return; - await Signal.race(this.#state.frames, this.#state.closed); + if (this.#expire()) return; + await this.#changed(); } } @@ -311,6 +472,8 @@ export class Consumer { */ async readFrame(): Promise { for (;;) { + if (this.#terminal) throw this.#terminal; + if (this.#ended) return; if (this.#state.offset > 0) throw new Lagged(); const read = this.#readBufferedFrame(); @@ -320,7 +483,10 @@ export class Consumer { if (closed instanceof Error) throw closed; if (closed !== undefined) return; - await Signal.race(this.#state.frames, this.#state.closed); + // Nothing buffered and the group is still open: this wait is the stall the + // drift budget bounds, and the only place it applies. + if (this.#expire()) continue; + await this.#changed(); } } @@ -330,6 +496,8 @@ export class Consumer { */ async readFrameSequence(): Promise<({ sequence: number } & Frame) | undefined> { for (;;) { + if (this.#terminal) throw this.#terminal; + if (this.#ended) return; if (this.#state.offset > 0) throw new Lagged(); const read = this.#readBufferedFrame(); @@ -339,7 +507,10 @@ export class Consumer { if (closed instanceof Error) throw closed; if (closed !== undefined) return; - await Signal.race(this.#state.frames, this.#state.closed); + // Nothing buffered and the group is still open: this wait is the stall the + // drift budget bounds, and the only place it applies. + if (this.#expire()) continue; + await this.#changed(); } } diff --git a/js/net/src/ietf/publisher.test.ts b/js/net/src/ietf/publisher.test.ts index 78892273387..402fcdf2c2e 100644 --- a/js/net/src/ietf/publisher.test.ts +++ b/js/net/src/ietf/publisher.test.ts @@ -1,12 +1,15 @@ import { expect, test } from "bun:test"; +import { Producer as GroupProducer } from "../group.ts"; import { createMockTransportPair } from "../mock.ts"; import { Producer as OriginProducer } from "../origin.ts"; import * as Path from "../path.ts"; import { Stream } from "../stream.ts"; +import { Timestamp } from "../time.ts"; import { NativeSession, type Session } from "./adapter.ts"; import { PublishNamespace } from "./publish_namespace.ts"; import { Publisher } from "./publisher.ts"; import { RequestError, RequestOk } from "./request.ts"; +import { Subscribe } from "./subscribe.ts"; import { SubscribeNamespace } from "./subscribe_namespace.ts"; import { ALPN, Version } from "./version.ts"; @@ -97,6 +100,82 @@ function publisher( return { pub: new Publisher(transport, inner, origin.consume(), requiresSolicitation), origin }; } +// The header is part of the group's lifetime too. If it blocks on flow control, advancing +// the live edge must reset the stream without waiting for that write to finish. +test("a blocked group header is reset when the group expires", async () => { + const pair = createMockTransportPair(ALPN.DRAFT_19); + + let started!: () => void; + const headerStarted = new Promise((resolve) => { + started = resolve; + }); + let release!: () => void; + const blocked = new Promise((resolve) => { + release = resolve; + }); + let reset!: () => void; + const streamReset = new Promise((resolve) => { + reset = resolve; + }); + const closed = new Promise(() => {}); + const writable = { + getWriter: () => ({ + closed, + write: async () => { + started(); + await blocked; + }, + close: async () => {}, + abort: async () => { + reset(); + }, + }), + abort: async () => {}, + } as unknown as WritableStream; + pair.server.createUnidirectionalStream = async () => writable; + + const { pub, origin } = publisher(pair.server); + const broadcast = origin.publish(Path.from("test")); + const track = broadcast.createTrack("video"); + const client = await Stream.open(pair.client, { version: VERSION }); + const server = await Stream.accept(pair.server, VERSION); + if (!server) throw new Error("publisher never accepted the subscribe stream"); + + try { + void pub.runSubscribe( + new Subscribe({ + requestId: 0n, + trackNamespace: Path.from("test"), + trackName: "video", + subscriberPriority: 0, + }), + server, + ); + + const old = new GroupProducer(0); + old.writeFrame({ payload: new TextEncoder().encode("old"), timestamp: Timestamp.fromMillis(0) }); + old.close(); + track.writeGroup(old); + await headerStarted; + + const edge = new GroupProducer(1); + edge.writeFrame({ payload: new TextEncoder().encode("edge"), timestamp: Timestamp.fromMillis(10_000) }); + edge.close(); + track.writeGroup(edge); + + const resetBeforeRelease = await Promise.race([ + streamReset.then(() => true), + new Promise((resolve) => setTimeout(() => resolve(false), 500)), + ]); + expect(resetBeforeRelease).toBe(true); + } finally { + release(); + client.close(); + broadcast.close(); + origin.close(); + } +}); + /** * Every advertisement waits a round trip for the peer's reply. A broadcast published in * that window has to survive it: the loop is not watching the signal while it waits, so diff --git a/js/net/src/ietf/publisher.ts b/js/net/src/ietf/publisher.ts index 14f43c5f6da..1fc7ca06778 100644 --- a/js/net/src/ietf/publisher.ts +++ b/js/net/src/ietf/publisher.ts @@ -2,11 +2,13 @@ import { type Dispose, type Getter, Signal } from "@moq/signals"; import type * as broadcast from "../broadcast.ts"; import { error, reason } from "../error.ts"; import type * as group from "../group.ts"; +import { hooks } from "../internal.ts"; import type { Consumer as OriginConsumer } from "../origin.ts"; import * as Path from "../path.ts"; import { type Stream, Writer } from "../stream.ts"; import type { Timescale } from "../time.ts"; import { withTimeout } from "../util/timeout.ts"; +import * as Varint from "../varint.ts"; import type { Session } from "./adapter.ts"; import { Frame, Group as GroupMessage } from "./object.ts"; import { fromWire } from "./priority.ts"; @@ -139,7 +141,14 @@ export class Publisher { return; } - const track = broadcast.subscribe(msg.trackName, { priority: fromWire(msg.subscriberPriority) }); + const track = broadcast.subscribe(msg.trackName, { + priority: fromWire(msg.subscriberPriority), + // moq-transport has no subscriber latency parameter. Keep everything the + // producer retained and let the receiving subscriber enforce its own budget. + // Keep the sentinel encodable if this demand crosses a Lite hop before the + // producer's retention bound is known. + latencyMax: Varint.MAX_U53, + }); try { // Declaring the timescale is what opts the track into timestamps; every object @@ -251,15 +260,15 @@ export class Publisher { }, }); - await header.encode(stream, this.#session.version); - try { + await hooks.guardGroup(group, header.encode(stream, this.#session.version)); + for (;;) { const frame = await Promise.race([group.readFrame(), stream.closed]); if (!frame) break; const obj = new Frame({ payload: frame.payload, timestamp: frame.timestamp }); - await obj.encode(stream, header.flags, timescale, this.#session.version); + await hooks.guardGroup(group, obj.encode(stream, header.flags, timescale, this.#session.version)); } stream.close(); diff --git a/js/net/src/integration.test.ts b/js/net/src/integration.test.ts index fa247e46030..0833e0c61f1 100644 --- a/js/net/src/integration.test.ts +++ b/js/net/src/integration.test.ts @@ -176,6 +176,7 @@ test("integration: lite applies initial and updated group bounds", async () => { const INITIAL_START_GROUP = 1; const INITIAL_END_GROUP = 2; const UPDATED_GROUP = 4; + const REPLAY_LATENCY_MS = 5000; const PENDING_ASSERT_MS = 20; const UPDATE_TIMEOUT_MS = 1000; @@ -191,9 +192,11 @@ test("integration: lite applies initial and updated group bounds", async () => { for (let sequence = 0; sequence < GROUP_COUNT; sequence++) producer.appendGroup().close(); const remote = client.consume(Path.from("test")); - const subscriber = remote - .track("video") - .subscribe({ startGroup: INITIAL_START_GROUP, endGroup: INITIAL_END_GROUP }); + const subscriber = remote.track("video").subscribe({ + latencyMax: REPLAY_LATENCY_MS, + startGroup: INITIAL_START_GROUP, + endGroup: INITIAL_END_GROUP, + }); try { expect((await subscriber.nextGroup())?.sequence).toBe(INITIAL_START_GROUP); expect((await subscriber.nextGroup())?.sequence).toBe(INITIAL_END_GROUP); @@ -201,7 +204,11 @@ test("integration: lite applies initial and updated group bounds", async () => { const pending = subscriber.nextGroup(); expect(await Promise.race([pending, sleep(PENDING_ASSERT_MS).then(() => "pending")])).toBe("pending"); - subscriber.update({ startGroup: UPDATED_GROUP, endGroup: UPDATED_GROUP }); + subscriber.update({ + latencyMax: REPLAY_LATENCY_MS, + startGroup: UPDATED_GROUP, + endGroup: UPDATED_GROUP, + }); expect((await withTimeout(pending, UPDATE_TIMEOUT_MS, "updated group bound timed out"))?.sequence).toBe( UPDATED_GROUP, ); diff --git a/js/net/src/internal.ts b/js/net/src/internal.ts index cad5a2a59a9..67eef1b2984 100644 --- a/js/net/src/internal.ts +++ b/js/net/src/internal.ts @@ -5,8 +5,9 @@ * * @module */ -import type { Dispose } from "@moq/signals"; -import type { Consumer as GroupConsumer } from "./group.ts"; +import type { Dispose, Getter } from "@moq/signals"; +import type { Consumer as GroupConsumer, Position } from "./group.ts"; +import type { Timestamp } from "./time.ts"; import type { Producer, Request, Subscriber } from "./track.ts"; /** @@ -38,6 +39,19 @@ export const hooks: { tryRecvGroup: (subscriber: Subscriber) => Recv; /** Wake once a subscriber's group cursor may read differently; assigned by `track.ts`. */ groupChanged: (subscriber: Subscriber, fn: () => void) => Dispose; + /** Disable subscription drift filtering for a one-shot FETCH scan. */ + ignoreLatency: (subscriber: Subscriber) => void; + /** Return a group's first timestamp, retained even after its first frame is read. */ + groupTimestamp: (group: GroupConsumer) => Timestamp | undefined; + /** Keep applying a subscription's drift policy after it hands a group out. */ + expireGroup: ( + group: GroupConsumer, + expiry: { expired: (at: Position) => boolean; changed: readonly Getter[] }, + ) => void; + /** Stop an in-flight group operation if the handed-out group expires. */ + guardGroup: (group: GroupConsumer, operation: Promise) => Promise; + /** Make an evicted mirror terminal while its track timeline still contains it. */ + evictGroup: (group: GroupConsumer) => void; } = { makeRequest: () => { throw new Error("track.ts not loaded"); @@ -48,4 +62,19 @@ export const hooks: { groupChanged: () => { throw new Error("track.ts not loaded"); }, + ignoreLatency: () => { + throw new Error("track.ts not loaded"); + }, + groupTimestamp: () => { + throw new Error("group.ts not loaded"); + }, + expireGroup: () => { + throw new Error("group.ts not loaded"); + }, + guardGroup: () => { + throw new Error("group.ts not loaded"); + }, + evictGroup: () => { + throw new Error("group.ts not loaded"); + }, }; diff --git a/js/net/src/lite/publisher.test.ts b/js/net/src/lite/publisher.test.ts index 0dacfa730a9..0efd4f24c49 100644 --- a/js/net/src/lite/publisher.test.ts +++ b/js/net/src/lite/publisher.test.ts @@ -4,6 +4,7 @@ import { createMockTransportPair } from "../mock.ts"; import { Producer as OriginProducer } from "../origin.ts"; import * as Path from "../path.ts"; import { Reader, Stream, Writer } from "../stream.ts"; +import { Timestamp } from "../time.ts"; import { Subscriber as TrackSubscriber } from "../track.ts"; import { Fetch } from "./fetch.ts"; import { Group as GroupMessage } from "./group.ts"; @@ -13,6 +14,17 @@ import { Publisher } from "./publisher.ts"; import { decodeSubscribeResponse, Subscribe, SubscribeUpdate } from "./subscribe.ts"; import { ALPN_05, ALPN_06_WIP, Version } from "./version.ts"; +// Scheduling tests intentionally stall groups, so keep latency enforcement out of their scope. +const TEST_LATENCY_MAX_MS = 30_000; + +function replaySubscribe(props: ConstructorParameters[0]) { + return new Subscribe({ ...props, latencyMax: TEST_LATENCY_MAX_MS }); +} + +function replayUpdate(props: ConstructorParameters[0]) { + return new SubscribeUpdate({ ...props, latencyMax: TEST_LATENCY_MAX_MS }); +} + // Delivers `sequences` in the given order, finishes the track, and returns the // SUBSCRIBE_END boundary the publisher put on the wire. async function subscribeEnd(sequences: number[]): Promise { @@ -90,7 +102,13 @@ async function groupSendOrders(options: { priority: number; sequences: number[]; const server = await Stream.accept(pair.server); if (!server) throw new Error("publisher never accepted the subscribe stream"); - const msg = new Subscribe({ id: 0n, broadcast: Path.from("test"), track: "video", priority, ordered }); + const msg = replaySubscribe({ + id: 0n, + broadcast: Path.from("test"), + track: "video", + priority, + ordered, + }); void publisher.runSubscribe(msg, server); // The peer end of each group stream, which arrives as the publisher opens it. @@ -99,7 +117,7 @@ async function groupSendOrders(options: { priority: number; sequences: number[]; try { for (const [index, group] of groups.entries()) { if (index === 1 && update !== undefined) { - await new SubscribeUpdate({ priority: update, ordered }).encode(client.writer, Version.DRAFT_05); + await replayUpdate({ priority: update, ordered }).encode(client.writer, Version.DRAFT_05); // Wait for the publisher to apply it, rather than assuming it beat the next group. while (track.subscription.peek()?.priority !== update) await track.subscription.changed(); } @@ -182,7 +200,12 @@ test("lite draft-05: a subscribe update re-ranks a group already on the wire", a const server = await Stream.accept(pair.server); if (!server) throw new Error("publisher never accepted the subscribe stream"); - const msg = new Subscribe({ id: 0n, broadcast: Path.from("test"), track: "video", priority: 1 }); + const msg = replaySubscribe({ + id: 0n, + broadcast: Path.from("test"), + track: "video", + priority: 1, + }); void publisher.runSubscribe(msg, server); // Leave the group open, so its stream is still being served when the update lands. @@ -199,7 +222,7 @@ test("lite draft-05: a subscribe update re-ranks a group already on the wire", a expect(stream.sendOrder).toBe(sendOrder({ priority: 1 })); try { - await new SubscribeUpdate({ priority: 9 }).encode(client.writer, Version.DRAFT_05); + await replayUpdate({ priority: 9 }).encode(client.writer, Version.DRAFT_05); while (track.subscription.peek()?.priority !== 9) await track.subscription.changed(); // The publisher re-ranks from that same signal, so wait on the send order itself rather @@ -241,7 +264,12 @@ test("lite draft-05: a subscribe update during the stream open still ranks the g const server = await Stream.accept(pair.server); if (!server) throw new Error("publisher never accepted the subscribe stream"); - const msg = new Subscribe({ id: 0n, broadcast: Path.from("test"), track: "video", priority: 1 }); + const msg = replaySubscribe({ + id: 0n, + broadcast: Path.from("test"), + track: "video", + priority: 1, + }); void publisher.runSubscribe(msg, server); const group = new GroupProducer(4); @@ -250,7 +278,7 @@ test("lite draft-05: a subscribe update during the stream open still ranks the g try { // The publisher is now parked inside the open, having already read priority 1. - await new SubscribeUpdate({ priority: 9 }).encode(client.writer, Version.DRAFT_05); + await replayUpdate({ priority: 9 }).encode(client.writer, Version.DRAFT_05); while (track.subscription.peek()?.priority !== 9) await track.subscription.changed(); release(); @@ -285,7 +313,12 @@ test("lite draft-05: many concurrent groups share one subscription listener", as const server = await Stream.accept(pair.server); if (!server) throw new Error("publisher never accepted the subscribe stream"); - const msg = new Subscribe({ id: 0n, broadcast: Path.from("test"), track: "video", priority: 1 }); + const msg = replaySubscribe({ + id: 0n, + broadcast: Path.from("test"), + track: "video", + priority: 1, + }); void publisher.runSubscribe(msg, server); // Leave every group open, so all of their streams are in flight at once. @@ -302,7 +335,7 @@ test("lite draft-05: many concurrent groups share one subscription listener", as expect(pair.server.sendStreams.uni.length).toBe(count); - await new SubscribeUpdate({ priority: 9 }).encode(client.writer, Version.DRAFT_05); + await replayUpdate({ priority: 9 }).encode(client.writer, Version.DRAFT_05); while (track.subscription.peek()?.priority !== 9) await track.subscription.changed(); // Newest-first, so the last group opened is at position 0 and the first is at the back. @@ -436,7 +469,7 @@ async function servedSubscription( const gate = gateWrites(accepted.value.writable, options.gated ?? false); const server = new Stream({ readable: accepted.value.readable, writable: gate.writable }); - const msg = new Subscribe({ + const msg = replaySubscribe({ id: 0n, broadcast: Path.from("test"), track: "video", @@ -555,7 +588,7 @@ test("lite draft-05: a group popped before a cap update is still served", async sub.serve(1); await sub.parked; - await new SubscribeUpdate({ priority: 0, endGroup: 0 }).encode(sub.client.writer, Version.DRAFT_05); + await replayUpdate({ priority: 0, endGroup: 0 }).encode(sub.client.writer, Version.DRAFT_05); await flush(); // The full update is visible, but the parked serving loop still owns its local cursor. expect(ranges).not.toHaveBeenCalled(); @@ -582,7 +615,7 @@ test("lite draft-06: a queued floor update applies before the next group pop", a await sub.parked; sub.serve(1); - await new SubscribeUpdate({ priority: 0, startGroup: 2 }).encode(sub.client.writer, Version.DRAFT_06); + await replayUpdate({ priority: 0, startGroup: 2 }).encode(sub.client.writer, Version.DRAFT_06); sub.serve(2); await flush(); expect(ranges).toHaveBeenCalledTimes(1); @@ -615,10 +648,7 @@ test("lite draft-06: a queued frame floor applies before the next group pop", as await sub.parked; sub.serve(1); - await new SubscribeUpdate({ priority: 0, startGroup: 1, startFrame: 2 }).encode( - sub.client.writer, - Version.DRAFT_06, - ); + await replayUpdate({ priority: 0, startGroup: 1, startFrame: 2 }).encode(sub.client.writer, Version.DRAFT_06); await flush(); expect(ranges).toHaveBeenCalledTimes(1); expect(ranges).toHaveBeenLastCalledWith(0); @@ -650,10 +680,7 @@ test("lite draft-06: a queued frame update applies before the next group pop", a sub.serve(0); await sub.parked; sub.serve(1); - await new SubscribeUpdate({ priority: 0, endGroup: 1, endFrame: 0 }).encode( - sub.client.writer, - Version.DRAFT_06, - ); + await replayUpdate({ priority: 0, endGroup: 1, endFrame: 0 }).encode(sub.client.writer, Version.DRAFT_06); await flush(); sub.release(); @@ -679,10 +706,7 @@ test("lite draft-06: a popped group keeps its frame bounds across a queued updat try { sub.serve(0); await sub.parked; - await new SubscribeUpdate({ priority: 0, endGroup: 0, endFrame: 2 }).encode( - sub.client.writer, - Version.DRAFT_06, - ); + await replayUpdate({ priority: 0, endGroup: 0, endFrame: 2 }).encode(sub.client.writer, Version.DRAFT_06); await flush(); sub.release(); @@ -712,14 +736,8 @@ test("lite draft-06: a burst of updates coalesces before the next group pop", as try { // Two updates land back to back, the second superseding the first. - await new SubscribeUpdate({ priority: 0, endGroup: 1, endFrame: 1 }).encode( - sub.client.writer, - Version.DRAFT_06, - ); - await new SubscribeUpdate({ priority: 0, endGroup: 1, endFrame: 0 }).encode( - sub.client.writer, - Version.DRAFT_06, - ); + await replayUpdate({ priority: 0, endGroup: 1, endFrame: 1 }).encode(sub.client.writer, Version.DRAFT_06); + await replayUpdate({ priority: 0, endGroup: 1, endFrame: 0 }).encode(sub.client.writer, Version.DRAFT_06); await flush(); sub.release(); @@ -756,7 +774,7 @@ test("lite draft-06: a newer update wins before a buffered group backlog drains" this: TrackSubscriber, endGroup, ) { - second ??= new SubscribeUpdate({ priority: 0, endGroup: 1 }).encode(sub.client.writer, Version.DRAFT_06); + second ??= replayUpdate({ priority: 0, endGroup: 1 }).encode(sub.client.writer, Version.DRAFT_06); return endAt.call(this, endGroup); }); @@ -769,7 +787,7 @@ test("lite draft-06: a newer update wins before a buffered group backlog drains" // The first update wakes the serving loop. Applying it starts the second update, // which caps the subscription before group 2. - await new SubscribeUpdate({ priority: 0, endGroup: 2 }).encode(sub.client.writer, Version.DRAFT_06); + await replayUpdate({ priority: 0, endGroup: 2 }).encode(sub.client.writer, Version.DRAFT_06); await flush(); sub.release(); @@ -793,16 +811,13 @@ test("lite draft-06: scheduling updates apply while SUBSCRIBE_START is blocked", sub.serve(0); await sub.parked; - await new SubscribeUpdate({ priority: 9, ordered: true, endGroup: 5 }).encode( - sub.client.writer, - Version.DRAFT_06, - ); + await replayUpdate({ priority: 9, ordered: true, endGroup: 5 }).encode(sub.client.writer, Version.DRAFT_06); await flush(); expect(sub.track.subscription.peek()).toEqual({ priority: 9, ordered: true, - latencyMax: 0, + latencyMax: TEST_LATENCY_MAX_MS, startGroup: undefined, endGroup: 5, }); @@ -875,7 +890,7 @@ test("lite draft-05: teardown unwinds with an undelivered update queued", async // The update decodes into the slot behind the parked loop, which never takes it // because the write it is parked on fails. - await new SubscribeUpdate({ priority: 0, endGroup: 5 }).encode(sub.client.writer, Version.DRAFT_05); + await replayUpdate({ priority: 0, endGroup: 5 }).encode(sub.client.writer, Version.DRAFT_05); await flush(); sub.release(new Error("write failed")); @@ -1144,6 +1159,78 @@ test("lite draft-05: group streams do not ask the transport to wait for a slot", close(); }); +// The header is part of the group's lifetime too. If it blocks on flow control, advancing +// the live edge must reset the stream without waiting for that write to finish. +test("lite draft-05: a blocked group header is reset when the group expires", async () => { + const pair = createMockTransportPair(ALPN_05); + + let started!: () => void; + const headerStarted = new Promise((resolve) => { + started = resolve; + }); + let release!: () => void; + const blocked = new Promise((resolve) => { + release = resolve; + }); + let reset!: () => void; + const streamReset = new Promise((resolve) => { + reset = resolve; + }); + const closed = new Promise(() => {}); + const writable = { + getWriter: () => ({ + closed, + write: async () => { + started(); + await blocked; + }, + close: async () => {}, + abort: async () => { + reset(); + }, + }), + abort: async () => {}, + } as unknown as WritableStream; + pair.server.createUnidirectionalStream = async () => writable; + + const origin = new OriginProducer(); + const publisher = new Publisher(pair.server, Version.DRAFT_05, randomOrigin(), origin.consume()); + const broadcast = origin.publish(Path.from("test")); + const track = broadcast.createTrack("video"); + const client = await Stream.open(pair.client); + const server = await Stream.accept(pair.server); + if (!server) throw new Error("publisher never accepted the subscribe stream"); + + try { + void publisher.runSubscribe( + new Subscribe({ id: 0n, broadcast: Path.from("test"), track: "video", priority: 0 }), + server, + ); + + const old = new GroupProducer(0); + old.writeFrame({ payload: new TextEncoder().encode("old"), timestamp: Timestamp.fromMillis(0) }); + old.close(); + track.writeGroup(old); + await headerStarted; + + const edge = new GroupProducer(1); + edge.writeFrame({ payload: new TextEncoder().encode("edge"), timestamp: Timestamp.fromMillis(1000) }); + edge.close(); + track.writeGroup(edge); + + const resetBeforeRelease = await Promise.race([ + streamReset.then(() => true), + new Promise((resolve) => setTimeout(() => resolve(false), 500)), + ]); + expect(resetBeforeRelease).toBe(true); + } finally { + release(); + publisher.close(); + client.close(); + broadcast.close(); + } +}); + test("lite draft-05: a group waiting for a stream slot is dropped when the subscriber leaves", async () => { const { client, track, freeSlot, outcome, close } = await saturatedGroup(); diff --git a/js/net/src/lite/publisher.ts b/js/net/src/lite/publisher.ts index a6670b4424e..80e7f36dd33 100644 --- a/js/net/src/lite/publisher.ts +++ b/js/net/src/lite/publisher.ts @@ -886,8 +886,13 @@ export class Publisher { // follows it too rather than keeping a stale rank until it finishes. priority.add(stream, group.sequence); - await stream.u53(0); // stream type - await msg.encode(stream, this.version); + await hooks.guardGroup( + group, + (async () => { + await stream.u53(0); // stream type + await msg.encode(stream, this.version); + })(), + ); // Lite05+ prefixes every frame with a zigzag-delta timestamp at the track's // advertised timescale; older drafts omit it. @@ -917,12 +922,12 @@ export class Publisher { if (timestamps) { // Convert each frame to the track's advertised timescale. const ts = BigInt(Math.round(frame.timestamp.as(timescale))); - await stream.u62(zigzag(ts - prevTs)); + await hooks.guardGroup(group, stream.u62(zigzag(ts - prevTs))); prevTs = ts; } - await stream.u53(frame.payload.byteLength); - await stream.write(frame.payload); + await hooks.guardGroup(group, stream.u53(frame.payload.byteLength)); + await hooks.guardGroup(group, stream.write(frame.payload)); } stream.close(); diff --git a/js/net/src/track.test.ts b/js/net/src/track.test.ts index f80d5976ef0..e90aa74617f 100644 --- a/js/net/src/track.test.ts +++ b/js/net/src/track.test.ts @@ -1,11 +1,31 @@ -import { expect, test } from "bun:test"; -import { Producer as GroupProducer } from "./group.ts"; +import { expect, setSystemTime, test } from "bun:test"; +import { Producer as GroupProducer, Lagged } from "./group.ts"; +import { hooks } from "./internal.ts"; import { Timestamp } from "./time.ts"; import { Producer as TrackProducer } from "./track.ts"; const enc = new TextEncoder(); const dec = new TextDecoder(); +/** Let every pending microtask and timer callback run, so a parked read gets a turn. */ +function settle(): Promise { + return new Promise((resolve) => setTimeout(resolve, 0)); +} + +function mockMonotonicTime(initial: number) { + let now = initial; + const real = performance.now.bind(performance); + performance.now = () => now; + return { + set: (value: number) => { + now = value; + }, + restore: () => { + performance.now = real; + }, + }; +} + test("used reflects subscriber demand and unused resolves when the last one leaves", async () => { const producer = new TrackProducer("test"); @@ -189,7 +209,7 @@ test("nextGroup skips late arrivals", async () => { test("nextGroup returns buffered groups in sequence", async () => { const producer = new TrackProducer("test"); - const track = producer.subscribe(); + const track = producer.subscribe({ latencyMax: 5000 }); producer.writeGroup(new GroupProducer(3)); producer.writeGroup(new GroupProducer(5)); @@ -198,9 +218,378 @@ test("nextGroup returns buffered groups in sequence", async () => { expect((await track.nextGroup())?.sequence).toBe(5); }); +test("latency budget skips a buffered timeline in every group read", async () => { + const producer = new TrackProducer("test").accept({ latencyMax: 5000 }); + const arrival = producer.subscribe(); + const ordered = producer.subscribe(); + const frames = producer.subscribe(); + + for (const timestamp of [0, 1000, 2000]) { + producer.writeFrame({ payload: enc.encode(`${timestamp}`), timestamp: Timestamp.fromMillis(timestamp) }); + } + + expect((await arrival.recvGroup())?.sequence).toBe(2); + expect((await ordered.nextGroup())?.sequence).toBe(2); + expect((await frames.readFrameSequence())?.group).toBe(2); +}); + +test("zero latency takes the latest group when ages are equal", async () => { + const clock = mockMonotonicTime(10_000); + try { + const producer = new TrackProducer("test").accept({ latencyMax: 5000 }); + const track = producer.subscribe(); + producer.writeString("old"); + producer.writeString("new"); + + expect((await track.recvGroup())?.sequence).toBe(1); + } finally { + clock.restore(); + } +}); + +test("latency budget admits groups within its presentation-time window", async () => { + const producer = new TrackProducer("test").accept({ latencyMax: 5000 }); + const track = producer.subscribe({ latencyMax: 1500 }); + + for (const timestamp of [0, 1000, 2000]) { + producer.writeFrame({ payload: enc.encode(`${timestamp}`), timestamp: Timestamp.fromMillis(timestamp) }); + } + + expect((await track.recvGroup())?.sequence).toBe(1); + expect((await track.recvGroup())?.sequence).toBe(2); +}); + +test("wall-clock age expires a group stalled before its first frame", async () => { + const clock = mockMonotonicTime(10_000); + try { + const producer = new TrackProducer("test").accept({ latencyMax: 5000 }); + const track = producer.subscribe(); + producer.appendGroup(); // seq 0 has no timestamp + + clock.set(11_000); + producer.writeFrame({ payload: enc.encode("edge"), timestamp: Timestamp.fromMillis(1000) }); + producer.close(); + + expect((await track.recvGroup())?.sequence).toBe(1); + expect(track.recvGroup()).resolves.toBeUndefined(); + } finally { + clock.restore(); + } +}); + +test("real time reads a live stream without truncating it", async () => { + // 2s GOPs produced one at a time and read as they arrive, at the default (zero) + // budget. Taking the live edge must not shorten the group the reader is already on, + // so every frame of every group arrives and each group *ends* at its boundary. + // + // The reader is always a little behind the edge (that is what reading live means), + // and it is parked at its group's end when the next one opens, because a group's + // close and the next group's first frame are separate events. + const producer = new TrackProducer("test").accept({ latencyMax: 60_000 }); + const track = producer.subscribe(); + + let open = producer.appendGroup(); + open.writeFrame({ payload: enc.encode("key"), timestamp: Timestamp.fromMillis(0) }); + open.writeFrame({ payload: enc.encode("tail"), timestamp: Timestamp.fromMillis(1900) }); + + let reading = await track.recvGroup(); + const read: Array<[number, number]> = []; + + for (let n = 1; n < 5; n++) { + if (!reading) throw new Error("missing live group"); + const sequence = reading.sequence; + + let frames = 0; + while (reading.tryReadFrame()) frames++; + read.push([sequence, frames]); + + // Parked at the end of the current group, with no close yet. + const end = reading.readFrame(); + + // The next keyframe opens its group. The verdict is taken in this window, before + // the previous group's close lands: give the parked read a real turn to run. + const next = producer.appendGroup(); + next.writeFrame({ payload: enc.encode("key"), timestamp: Timestamp.fromMillis(n * 2000) }); + await settle(); + open.close(); + next.writeFrame({ payload: enc.encode("tail"), timestamp: Timestamp.fromMillis(n * 2000 + 1900) }); + + await expect(end).resolves.toBeUndefined(); + + reading = await track.recvGroup(); + open = next; + } + + expect(read).toEqual([ + [0, 2], + [1, 2], + [2, 2], + [3, 2], + ]); +}); + +test("a budget is measured from the reader's position", async () => { + // A 2s GOP with a 1s budget: the reader has drained to 1900ms when the next group + // opens at 2000ms, so it is 100ms behind the live edge and well inside what it asked + // for. A straggling frame of the old group must still reach it. Measuring from the + // group's first frame instead makes the drift 2000ms, so a budget shorter than one + // GOP would drop the tail of every GOP. + const producer = new TrackProducer("test").accept({ latencyMax: 60_000 }); + const track = producer.subscribe({ latencyMax: 1000 }); + + const open = producer.appendGroup(); + open.writeFrame({ payload: enc.encode("key"), timestamp: Timestamp.fromMillis(0) }); + open.writeFrame({ payload: enc.encode("tail"), timestamp: Timestamp.fromMillis(1900) }); + + const reading = await track.recvGroup(); + if (!reading) throw new Error("missing group"); + expect(reading.tryReadFrame()).toBeDefined(); + expect(reading.tryReadFrame()).toBeDefined(); + + // Parked at 1900ms, then the next GOP opens 100ms ahead of it. + const late = reading.readFrame(); + const next = producer.appendGroup(); + next.writeFrame({ payload: enc.encode("key"), timestamp: Timestamp.fromMillis(2000) }); + await settle(); + + // A straggler from the old group, still inside the budget. + open.writeFrame({ payload: enc.encode("late"), timestamp: Timestamp.fromMillis(1950) }); + const frame = await late; + expect(frame?.timestamp.asMillis()).toBe(1950); +}); + +test("a handed-out group still expires while its first frame is stalled", async () => { + const clock = mockMonotonicTime(10_000); + try { + const producer = new TrackProducer("test").accept({ latencyMax: 5000 }); + const track = producer.subscribe(); + producer.appendGroup(); + + const stalled = await track.recvGroup(); + expect(stalled?.sequence).toBe(0); + if (!stalled) throw new Error("missing stalled group"); + const pending = stalled.readFrame(); + const closed = stalled.closed; + + clock.set(11_000); + producer.writeFrame({ payload: enc.encode("edge"), timestamp: Timestamp.fromMillis(1000) }); + + // It ends rather than fails: the reader took every frame the group ever had + // (none), so nothing was truncated. What it was waiting for was the producer, + // and a group abandoned where its reader stands looks like one that ended there. + await expect(pending).resolves.toBeUndefined(); + expect(await closed).toBeNull(); + } finally { + clock.restore(); + } +}); + +test("a handed-out frame cancels its in-flight operation when it expires", async () => { + const producer = new TrackProducer("test").accept({ latencyMax: 5000 }); + const track = producer.subscribe(); + producer.writeString("old"); + + const group = await track.recvGroup(); + if (!group) throw new Error("missing group"); + expect(await group.readString()).toBe("old"); + + let release!: () => void; + const operation = new Promise((resolve) => { + release = resolve; + }); + const guarded = hooks.guardGroup(group, operation); + producer.writeString("new"); + + await expect(guarded).rejects.toThrow("latency budget"); + release(); +}); + +test("a drained group finishes cleanly after the live edge advances", async () => { + const producer = new TrackProducer("test").accept({ latencyMax: 5000 }); + const track = producer.subscribe(); + producer.writeString("old"); + + const group = await track.recvGroup(); + if (!group) throw new Error("missing group"); + expect(await group.readString()).toBe("old"); + + producer.writeString("new"); + + expect(await group.readFrame()).toBeUndefined(); + expect(group.done).toBe(true); +}); + +test("retention eviction preserves expiry for a handed-out group", async () => { + const clock = mockMonotonicTime(10_000); + try { + const producer = new TrackProducer("test").accept({ latencyMax: 100 }); + const track = producer.subscribe({ latencyMax: 100 }); + const source = producer.appendGroup(); + source.writeString("first"); + source.writeString("tail"); + source.close(); + + const group = await track.recvGroup(); + if (!group) throw new Error("missing group"); + expect(new TextDecoder().decode((await group.readFrame())?.payload)).toBe("first"); + + clock.set(10_200); + producer.appendGroup(); + + await expect(group.readFrame()).rejects.toThrow("latency budget"); + } finally { + clock.restore(); + } +}); + +test("retention pruning aborts a held mirror without a new live edge", async () => { + const clock = mockMonotonicTime(10_000); + try { + const producer = new TrackProducer("test").accept({ latencyMax: 100 }); + const track = producer.subscribe({ latencyMax: 100 }); + const source = producer.appendGroup(); + source.writeString("first"); + source.writeString("tail"); + source.close(); + + const group = await track.recvGroup(); + if (!group) throw new Error("missing group"); + expect(new TextDecoder().decode((await group.readFrame())?.payload)).toBe("first"); + + clock.set(10_200); + producer.subscribe({ latencyMax: 100 }); + + await expect(group.readFrame()).rejects.toBeInstanceOf(Lagged); + } finally { + clock.restore(); + } +}); + +test("retention pruning preserves clean EOF for a drained mirror", async () => { + const clock = mockMonotonicTime(10_000); + try { + const producer = new TrackProducer("test").accept({ latencyMax: 100 }); + const track = producer.subscribe({ latencyMax: 100 }); + const source = producer.appendGroup(); + source.writeString("only"); + source.close(); + + const group = await track.recvGroup(); + if (!group) throw new Error("missing group"); + expect(await group.readString()).toBe("only"); + expect(await group.readFrame()).toBeUndefined(); + + clock.set(10_200); + producer.subscribe({ latencyMax: 100 }); + + expect(await group.readFrame()).toBeUndefined(); + expect(await group.closed).toBeNull(); + } finally { + clock.restore(); + } +}); + +test("system clock changes do not affect wall-clock latency", async () => { + const clock = mockMonotonicTime(10_000); + setSystemTime(new Date(10_000)); + try { + const producer = new TrackProducer("test").accept({ latencyMax: 100 }); + const track = producer.subscribe({ latencyMax: 100 }); + producer.writeString("old"); + + setSystemTime(new Date(20_000)); + producer.writeString("new"); + + expect((await track.recvGroup())?.sequence).toBe(0); + expect((await track.recvGroup())?.sequence).toBe(1); + } finally { + setSystemTime(); + clock.restore(); + } +}); + +test("frame readiness cancels the losing latency waiter", async () => { + const producer = new TrackProducer("test").accept({ latencyMax: 5000 }); + const track = producer.subscribe({ latencyMax: 5000 }); + const source = producer.appendGroup(); + const group = await track.recvGroup(); + if (!group) throw new Error("missing group"); + + for (let i = 0; i < 110; i++) { + const pending = group.readFrame(); + source.writeString(`${i}`); + expect(new TextDecoder().decode((await pending)?.payload)).toBe(`${i}`); + } +}); + +test("latency budget retains a consumed live-edge anchor", async () => { + const producer = new TrackProducer("test").accept({ latencyMax: 5000 }); + const track = producer.subscribe(); + + const edge = new GroupProducer(2); + edge.writeFrame({ payload: enc.encode("edge"), timestamp: Timestamp.fromMillis(2000) }); + edge.close(); + producer.writeGroup(edge); + expect((await track.recvGroup())?.sequence).toBe(2); + + const late = new GroupProducer(1); + late.writeFrame({ payload: enc.encode("late"), timestamp: Timestamp.fromMillis(0) }); + late.close(); + producer.writeGroup(late); + producer.close(); + + expect(track.recvGroup()).resolves.toBeUndefined(); +}); + +test("an aborted live-edge anchor does not make older content stale", async () => { + const producer = new TrackProducer("test").accept({ latencyMax: 5000 }); + const track = producer.subscribe(); + + const edge = new GroupProducer(2); + edge.writeFrame({ payload: enc.encode("edge"), timestamp: Timestamp.fromMillis(2000) }); + edge.close(new Error("aborted")); + producer.writeGroup(edge); + + const older = new GroupProducer(1); + older.writeFrame({ payload: enc.encode("older"), timestamp: Timestamp.fromMillis(0) }); + older.close(); + producer.writeGroup(older); + + expect((await track.recvGroup())?.sequence).toBe(1); + track.close(); +}); + +test("endAt caps the live edge used by the latency budget", async () => { + const producer = new TrackProducer("test").accept({ latencyMax: 5000 }); + const track = producer.subscribe(); + track.endAt(1); + + for (const timestamp of [0, 1000, 2000]) { + producer.writeFrame({ payload: enc.encode(`${timestamp}`), timestamp: Timestamp.fromMillis(timestamp) }); + } + + expect((await track.recvGroup())?.sequence).toBe(1); + track.endAt(undefined); + expect((await track.recvGroup())?.sequence).toBe(2); +}); + +test("endAt does not cap frame-level reads", async () => { + const producer = new TrackProducer("test").accept({ latencyMax: 5000 }); + const track = producer.subscribe({ latencyMax: 5000 }); + track.endAt(0); + + producer.writeFrame({ payload: enc.encode("zero"), timestamp: Timestamp.fromMillis(0) }); + producer.writeFrame({ payload: enc.encode("one"), timestamp: Timestamp.fromMillis(1) }); + producer.close(); + + expect((await track.readFrameSequence())?.group).toBe(0); + expect((await track.readFrameSequence())?.group).toBe(1); + expect(await track.readFrameSequence()).toBeUndefined(); +}); + test("local cursor bounds can skip, pause, and release buffered groups", async () => { const producer = new TrackProducer("test"); - const track = producer.subscribe(); + const track = producer.subscribe({ latencyMax: 5000 }); for (let sequence = 0; sequence < 5; sequence++) producer.writeGroup(new GroupProducer(sequence)); @@ -223,7 +612,7 @@ test("local cursor bounds can skip, pause, and release buffered groups", async ( // deliver it; a sequence cursor would skip it permanently. test("recvGroup serves a late arrival after a newer group", async () => { const producer = new TrackProducer("test"); - const track = producer.subscribe(); + const track = producer.subscribe({ latencyMax: 5000 }); producer.writeGroup(new GroupProducer(2)); expect((await track.recvGroup())?.sequence).toBe(2); @@ -242,7 +631,7 @@ test("recvGroup serves a late arrival after a newer group", async () => { // held, not dropped, and a raised cap re-offers them, even after a clean close. test("endAt parks recvGroup beyond the cap and a raised cap re-offers", async () => { const producer = new TrackProducer("test"); - const track = producer.subscribe(); + const track = producer.subscribe({ latencyMax: 5000 }); for (let sequence = 0; sequence < 3; sequence++) producer.writeGroup(new GroupProducer(sequence)); @@ -268,7 +657,7 @@ test("endAt parks recvGroup beyond the cap and a raised cap re-offers", async () // a relay can ingest a burst micro-reordered (newest first). test("recvGroup serves in-range groups that arrive behind a capped one", async () => { const producer = new TrackProducer("test"); - const track = producer.subscribe(); + const track = producer.subscribe({ latencyMax: 5000 }); track.endAt(1); @@ -373,7 +762,7 @@ test("closing the subscriber releases a recvGroup parked while the producer is l test("recvGroup after nextGroup still returns late arrivals", async () => { const producer = new TrackProducer("test"); - const track = producer.subscribe(); + const track = producer.subscribe({ latencyMax: 5000 }); producer.writeGroup(new GroupProducer(5)); @@ -399,7 +788,7 @@ test("nextGroup returns undefined when track closes", async () => { // the data (mirrors the Rust subscriber). Only a drained closed track reports finished. test("a closed track still delivers a group parked above the cap once the cap is raised", async () => { const producer = new TrackProducer("test"); - const track = producer.subscribe(); + const track = producer.subscribe({ latencyMax: 5000 }); for (let sequence = 0; sequence < 3; sequence++) { const group = new GroupProducer(sequence); diff --git a/js/net/src/track.ts b/js/net/src/track.ts index 7632a360142..29d9cf46fc6 100644 --- a/js/net/src/track.ts +++ b/js/net/src/track.ts @@ -5,7 +5,13 @@ */ import { type Dispose, type GetPromise, type Getter, Once, Signal } from "@moq/signals"; import type { Datagram } from "./datagram.ts"; -import { type Frame, type Consumer as GroupConsumer, Producer as GroupProducer, Lagged } from "./group.ts"; +import { + type Frame, + type Consumer as GroupConsumer, + Producer as GroupProducer, + Lagged, + type Position, +} from "./group.ts"; import { hooks, type Recv } from "./internal.ts"; import { Timescale, type Timestamp } from "./time.ts"; @@ -234,6 +240,13 @@ export class Consumer { // wiring, unexported so it never appears in the published type declarations. class TrackState { groups = new Signal([]); + // Every group still in the producer's replay cache, including groups this + // subscriber already consumed, paired with its source queue time. Drift anchors + // have the same lifetime as content. + timeline = new Map(); + // First timestamps mutate group state rather than track state, so held groups + // watch this revision as well as arrivals when enforcing latency after handoff. + timelineChanged = new Signal(0); /** Best-effort datagram channel, parallel to {@link groups}; an age-evicted send buffer per subscriber. */ datagrams = new Signal([]); latest?: number; @@ -449,6 +462,8 @@ export class Producer { #mirror(entry: CachedGroup, sink: TrackState): void { const dst = entry.group.mirror(); entry.mirrors.set(sink, dst); + sink.timeline.set(dst.sequence, { group: dst, time: entry.time }); + void dst.readable().then(() => sink.timelineChanged.update((revision) => revision + 1)); sink.latest = Math.max(sink.latest ?? 0, dst.sequence); sink.groups.mutate((groups) => { groups.push(dst); @@ -459,10 +474,12 @@ export class Producer { // Drop a cached group's mirror from every sink so no consumer can pin it. #evict(entry: CachedGroup): void { for (const [sink, mirror] of entry.mirrors) { + hooks.evictGroup(mirror); sink.groups.mutate((groups) => { const i = groups.indexOf(mirror); if (i >= 0) groups.splice(i, 1); }); + if (sink.timeline.get(mirror.sequence)?.group === mirror) sink.timeline.delete(mirror.sequence); mirror.close(); } entry.mirrors.clear(); @@ -471,11 +488,11 @@ export class Producer { // Evict cached groups that are closed and older than the cache window. #prune(): void { const latencyMaxMs = this.#state.info.peek()?.latencyMax ?? DEFAULT_LATENCY_MAX_MS; - const cutoff = Date.now() - latencyMaxMs; + const cutoff = performance.now() - latencyMaxMs; const retained: CachedGroup[] = []; for (const entry of this.#cache) { - if (entry.time > cutoff || entry.group.closed.peek() === undefined) { + if (entry.time >= cutoff || entry.group.closed.peek() === undefined) { retained.push(entry); continue; } @@ -486,10 +503,12 @@ export class Producer { // Retain a source group and fan it out to every live sink. #publish(group: GroupProducer): void { - const entry: CachedGroup = { group, time: Date.now(), mirrors: new Map() }; + const entry: CachedGroup = { group, time: performance.now(), mirrors: new Map() }; this.#cache.push(entry); - this.#prune(); for (const sink of this.#sinks) this.#mirror(entry, sink); + // Give held mirrors the new live edge before pruning their timeline entry, + // so their latency guard can preserve a terminal expiry verdict. + this.#prune(); } /** Append a new group with the next sequence number. */ @@ -643,6 +662,86 @@ export class Subscriber { #state: TrackState; #nextSequence = 0; #cursor = new Signal<{ start: number; end?: number }>({ start: 0 }); + #enforceLatency = true; + + #drift(): { + budget: number; + wall?: { sequence: number; time: number }; + presentation?: { sequence: number; timestamp: Timestamp }; + } { + const { end } = this.#cursor.peek(); + let wall: { sequence: number; time: number } | undefined; + let presentation: { sequence: number; timestamp: Timestamp } | undefined; + for (const { group, time } of this.#state.timeline.values()) { + if (end !== undefined && group.sequence > end) continue; + if (group.closed.peek() instanceof Error) continue; + if (!wall || group.sequence > wall.sequence) wall = { sequence: group.sequence, time }; + const timestamp = hooks.groupTimestamp(group); + if (timestamp !== undefined && (!presentation || group.sequence > presentation.sequence)) { + presentation = { sequence: group.sequence, timestamp }; + } + } + + const requested = this.#state.update.peek()?.latencyMax ?? 0; + const retained = this.#state.info.peek()?.latencyMax; + return { + budget: this.#enforceLatency + ? retained === undefined + ? requested + : Math.min(requested, retained) + : Number.POSITIVE_INFINITY, + wall, + presentation, + }; + } + + // `at` is where a handed-out group's reader stands. A group nobody has started + // reading sits at its own start, which is what selection measures; one already + // handed out sits wherever its reader got to, so a reader keeping pace is not + // convicted by how long ago its group opened. Measuring from the group's first + // frame instead makes a GOP one GOP-duration behind by construction. + #isStale( + group: GroupConsumer, + drift: { + budget: number; + wall?: { sequence: number; time: number }; + presentation?: { sequence: number; timestamp: Timestamp }; + }, + at?: Position, + ): boolean { + const candidate = this.#state.timeline.get(group.sequence); + if (candidate?.group !== group) return false; + + const time = at?.activity ?? candidate.time; + const wallStale = + drift.wall !== undefined && + drift.wall.sequence > group.sequence && + (drift.budget === 0 || drift.wall.time - time > drift.budget); + + const timestamp = at?.presentation ?? hooks.groupTimestamp(group); + const presentationStale = + drift.presentation !== undefined && + drift.presentation.sequence > group.sequence && + timestamp !== undefined && + drift.presentation.timestamp.asMillis() - timestamp.asMillis() > drift.budget; + + return wallStale || presentationStale; + } + + #guard(group: GroupConsumer): GroupConsumer { + if (!this.#enforceLatency) return group; + hooks.expireGroup(group, { + expired: (at) => this.#isStale(group, this.#drift(), at), + changed: [ + this.#state.groups, + this.#state.timelineChanged, + this.#state.update, + this.#cursor, + this.#state.closed, + ], + }); + return group; + } private constructor(name: string, state: TrackState) { this.name = name; @@ -653,6 +752,9 @@ export class Subscriber { makeSubscriber = (name, state) => new Subscriber(name, state); hooks.tryRecvGroup = (subscriber) => subscriber.#tryRecvGroup(); hooks.groupChanged = (subscriber, fn) => subscriber.#groupChanged(fn); + hooks.ignoreLatency = (subscriber) => { + subscriber.#enforceLatency = false; + }; } /** @@ -716,6 +818,7 @@ export class Subscriber { for (const group of groups) group.close(abort); groups.length = 0; }); + this.#state.timeline.clear(); } /** @@ -729,6 +832,10 @@ export class Subscriber { * Honors the floor set by {@link startAt} and the cap set by {@link endAt}: a group * beyond the cap stays buffered (not dropped) and is offered once the cap rises, even * after a clean close, without blocking in-range groups that arrive behind it. + * A group whose presentation time or wall-clock arrival is further behind the live edge + * than this subscriber's `latencyMax` is skipped. The default of zero takes the live edge. + * The budget remains attached after return, so a pending frame read rejects if a stalled + * group becomes stale while newer data advances. */ async recvGroup(): Promise { for (;;) { @@ -753,15 +860,22 @@ export class Subscriber { const groups = this.#state.groups.peek(); const { start, end } = this.#cursor.peek(); while (groups.length > 0 && groups[0].sequence < start) groups.shift()?.close(); + const drift = this.#drift(); - // The buffer is sequence-sorted, so an in-range group that arrives behind a - // beyond-cap one sorts in front of it and is never blocked by it. - const group = groups[0]; - if (group && (end === undefined || group.sequence <= end)) { + for (;;) { + // The buffer is sequence-sorted, so an in-range group that arrives behind a + // beyond-cap one sorts in front of it and is never blocked by it. + const group = groups[0]; + if (!group || (end !== undefined && group.sequence > end)) break; groups.shift(); - return { kind: "group", group }; + if (this.#isStale(group, drift)) { + group.close(); + continue; + } + return { kind: "group", group: this.#guard(group) }; } + const group = groups[0]; const closed = this.#state.closed.peek(); if (closed instanceof Error) return { kind: "error", error: closed }; if (closed === undefined) return { kind: "idle" }; @@ -818,6 +932,7 @@ export class Subscriber { * * Late arrivals (sequence at or below the last returned) are silently skipped. * Use {@link recvGroup} to see every group in arrival order instead. + * The subscription's `latencyMax` also skips groups that drift behind the live edge. */ async nextGroup(): Promise { for (;;) { @@ -825,12 +940,18 @@ export class Subscriber { const cursor = this.#cursor.peek(); const start = Math.max(cursor.start, this.#nextSequence); while (groups.length > 0 && groups[0].sequence < start) groups.shift()?.close(); + const drift = this.#drift(); - const group = groups[0]; - if (group && (cursor.end === undefined || group.sequence <= cursor.end)) { + let group = groups[0]; + while (group && (cursor.end === undefined || group.sequence <= cursor.end)) { groups.shift(); this.#nextSequence = group.sequence + 1; - return group; + if (this.#isStale(group, drift)) { + group.close(); + group = groups[0]; + continue; + } + return this.#guard(group); } const closed = this.#state.closed.peek(); @@ -856,15 +977,28 @@ export class Subscriber { /** * Reads the next frame along with its group and frame sequence numbers. * Treat the returned frame bytes as read-only; they are shared with other consumers. + * Groups outside the subscription's `latencyMax` budget are discarded before reading. */ async readFrameSequence(): Promise<({ group: number; frame: number } & Frame) | undefined> { for (;;) { const groups = this.#state.groups.peek(); const { start } = this.#cursor.peek(); while (groups.length > 0 && groups[0].sequence < start) groups.shift()?.close(); + const drift = this.#drift(); + for (let i = 0; i < groups.length; ) { + const group = groups[i]; + if (!this.#isStale(group, drift)) { + i++; + continue; + } + groups.splice(i, 1); + group.close(); + } + + let readable = groups.length; // Drain older groups first, dropping each once empty. - while (groups.length > 1) { + while (readable > 1) { if (groups[0].skipped) { // The reader fell behind this group's eviction window. Drop it and // signal the gap; the next read resyncs from the following group. @@ -881,12 +1015,17 @@ export class Subscriber { }; } groups.shift()?.close(); + readable--; } - if (groups.length === 0) { + if (readable === 0) { const closed = this.#state.closed.peek(); if (closed instanceof Error) throw closed; - if (closed !== undefined) return undefined; + if (closed !== undefined && groups.length === 0) return undefined; + if (closed !== undefined) { + await Signal.race(this.#cursor); + continue; + } await Signal.race(this.#state.groups, this.#cursor, this.#state.closed); continue; } diff --git a/js/watch/src/audio/decoder.ts b/js/watch/src/audio/decoder.ts index 24be6dd3283..e3b2afb8e25 100644 --- a/js/watch/src/audio/decoder.ts +++ b/js/watch/src/audio/decoder.ts @@ -5,6 +5,7 @@ import type * as Moq from "@moq/net"; import { Time } from "@moq/net"; import { Effect, type Getter, getter, type Inputs, type Readonlys, readonlys, Signal } from "@moq/signals"; import { base64ToBytes } from "../base64"; +import { subscribeMedia } from "../media"; import type { Sync } from "../sync"; import { type AudioBuffer, createAudioBuffer } from "./buffer"; @@ -272,8 +273,12 @@ export class Decoder { const active = broadcast.relativeBroadcast(effect, config.broadcast); if (!active) return; - const sub = active.track(track).subscribe({ priority: Catalog.PRIORITY.audio }); - effect.cleanup(() => sub.close()); + const sub = subscribeMedia(effect, { + broadcast: active, + track, + priority: Catalog.PRIORITY.audio, + latency: this.#consumerLatency, + }); if (config.container.kind === "cmaf") { this.#runCmafDecoder(effect, sub, config); diff --git a/js/watch/src/media.test.ts b/js/watch/src/media.test.ts new file mode 100644 index 00000000000..d43af724fc7 --- /dev/null +++ b/js/watch/src/media.test.ts @@ -0,0 +1,40 @@ +import { expect, test } from "bun:test"; +import type * as Moq from "@moq/net"; +import { Time } from "@moq/net"; +import { Effect, Signal } from "@moq/signals"; +import { subscribeMedia } from "./media"; + +const flush = () => new Promise((resolve) => setTimeout(resolve, 0)); + +test("media latency is present on the initial subscription and later updates", async () => { + let initial: Moq.Track.Subscription | undefined; + const updates: Moq.Track.Subscription[] = []; + const subscriber = { + close: () => undefined, + update: (subscription: Moq.Track.Subscription) => updates.push(subscription), + } as unknown as Moq.Track.Subscriber; + const broadcast = { + track: () => ({ + subscribe: (subscription: Moq.Track.Subscription) => { + initial = subscription; + return subscriber; + }, + }), + } as unknown as Moq.Broadcast.Consumer; + const latency = new Signal(Time.Milli(250)); + const effect = new Effect(); + + subscribeMedia(effect, { + broadcast, + track: "media", + priority: 7, + latency, + }); + expect(initial).toEqual({ priority: 7, latencyMax: 250 }); + + latency.set(Time.Milli(500)); + await flush(); + expect(updates.at(-1)).toEqual({ priority: 7, latencyMax: 500 }); + + effect.close(); +}); diff --git a/js/watch/src/media.ts b/js/watch/src/media.ts new file mode 100644 index 00000000000..95df9afdf42 --- /dev/null +++ b/js/watch/src/media.ts @@ -0,0 +1,28 @@ +import type * as Moq from "@moq/net"; +import type { Time } from "@moq/net"; +import type { Effect, Getter } from "@moq/signals"; + +/** + * Open a media subscription with its latency ceiling on the initial request and every update. + * + * @internal + */ +export function subscribeMedia( + effect: Effect, + props: { + broadcast: Moq.Broadcast.Consumer; + track: string; + priority: number; + latency: Getter; + }, +): Moq.Track.Subscriber { + const subscription = () => ({ priority: props.priority, latencyMax: props.latency.peek() }); + const subscriber = props.broadcast.track(props.track).subscribe(subscription()); + effect.cleanup(() => subscriber.close()); + + effect.run((inner) => { + subscriber.update({ priority: props.priority, latencyMax: inner.get(props.latency) }); + }); + + return subscriber; +} diff --git a/js/watch/src/text/renderer.ts b/js/watch/src/text/renderer.ts index 663f2f4f043..02e71bbedb7 100644 --- a/js/watch/src/text/renderer.ts +++ b/js/watch/src/text/renderer.ts @@ -7,6 +7,7 @@ import { CaptionsRenderer, parseText, VTTCue, type VTTRegion } from "media-capti // attributes and CSS variables it sets); without them the overlay renders nothing visible. import captionsCss from "media-captions/styles/captions.css?inline"; import regionsCss from "media-captions/styles/regions.css?inline"; +import { subscribeMedia } from "../media"; import type { Sync } from "../sync"; import type { Source } from "./source"; @@ -245,8 +246,12 @@ export class Renderer { // does not), so a track switch or reconnect doesn't leak an observer. effect.cleanup(() => renderer.destroy()); - const sub = active.track(track).subscribe({ priority: Catalog.PRIORITY.text }); - effect.cleanup(() => sub.close()); + const sub = subscribeMedia(effect, { + broadcast: active, + track, + priority: Catalog.PRIORITY.text, + latency: this.sync.out.maxBuffer, + }); const store: CueStore = { cues: [], regions: new Map(), clears: [] }; const commit = () => renderer.changeTrack({ cues: [...store.cues], regions: [...store.regions.values()] }); diff --git a/js/watch/src/video/decoder.ts b/js/watch/src/video/decoder.ts index 03b68272cfd..e3353341599 100644 --- a/js/watch/src/video/decoder.ts +++ b/js/watch/src/video/decoder.ts @@ -14,6 +14,7 @@ import { Signal, } from "@moq/signals"; import { base64ToBytes } from "../base64"; +import { subscribeMedia } from "../media"; import type { Sync } from "../sync"; import { @@ -296,8 +297,12 @@ class DecoderTrack { } #run(effect: Effect): void { - const sub = this.broadcast.track(this.track).subscribe({ priority: Catalog.PRIORITY.video }); - effect.cleanup(() => sub.close()); + const sub = subscribeMedia(effect, { + broadcast: this.broadcast, + track: this.track, + priority: Catalog.PRIORITY.video, + latency: this.sync.out.maxBuffer, + }); const decoder = new VideoDecoder({ output: async (frame: VideoFrame) => { @@ -365,7 +370,7 @@ class DecoderTrack { // Create consumer that reorders groups/frames up to the provided latency. const consumer = new Container.Consumer(sub, { format, - latency: this.sync.out.buffer, + latency: this.sync.out.maxBuffer, }); effect.cleanup(() => consumer.close()); @@ -441,7 +446,7 @@ class DecoderTrack { const consumer = new Container.Consumer(sub, { format: new Container.Cmaf.Format(init), - latency: this.sync.out.buffer, + latency: this.sync.out.maxBuffer, }); effect.cleanup(() => consumer.close());