From 574c546ea81cf03d6ae35010ea33949e183aae86 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 18 Aug 2026 13:32:34 -0700 Subject: [PATCH 1/5] feat(js/net): enforce the subscriber latency budget The JS mirror of the moq-net work in the parent PR: js/net applies the same drift budget as it reads, and js/watch requests the playback latency ceiling from its first subscription. Drift is measured against both a presentation-time and a wall-clock live edge, from the reader's own position rather than the group's first frame, so a reader keeping pace is not convicted by how long ago its group opened. A group with frames in hand always drains; only a read that would wait is judged, which is also what keeps the policy off the read path. A drained group the budget gives up on ends rather than fails, since nothing was lost; the latency error is reserved for a caller still holding content. Co-Authored-By: Claude Opus 5 --- js/hang/src/container/consumer.test.ts | 56 ++-- js/json/src/snapshot/compression.test.ts | 5 +- js/json/src/snapshot/snapshot.test.ts | 14 +- js/net/src/broadcast.test.ts | 6 +- js/net/src/broadcast.ts | 1 + js/net/src/group.ts | 185 ++++++++++- js/net/src/ietf/publisher.test.ts | 79 +++++ js/net/src/ietf/publisher.ts | 17 +- js/net/src/integration.test.ts | 15 +- js/net/src/internal.ts | 33 +- js/net/src/lite/publisher.test.ts | 165 ++++++--- js/net/src/lite/publisher.ts | 15 +- js/net/src/track.test.ts | 407 ++++++++++++++++++++++- js/net/src/track.ts | 171 +++++++++- js/watch/src/audio/decoder.ts | 9 +- js/watch/src/media.test.ts | 40 +++ js/watch/src/media.ts | 28 ++ js/watch/src/text/renderer.ts | 9 +- js/watch/src/video/decoder.ts | 13 +- 19 files changed, 1142 insertions(+), 126 deletions(-) create mode 100644 js/watch/src/media.test.ts create mode 100644 js/watch/src/media.ts diff --git a/js/hang/src/container/consumer.test.ts b/js/hang/src/container/consumer.test.ts index a5f246a8f7e..f021870c4b3 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({ maxAge: 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..563ad3831f6 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({ maxAge: 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({ maxAge: 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..6b5515c5f7b 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({ maxAge: 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({ maxAge: 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({ maxAge: 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({ maxAge: 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({ maxAge: REPLAY_LATENCY }))).toEqual([256, 1]); }); diff --git a/js/net/src/broadcast.test.ts b/js/net/src/broadcast.test.ts index 92497621503..9a17c6d8ce5 100644 --- a/js/net/src/broadcast.test.ts +++ b/js/net/src/broadcast.test.ts @@ -234,8 +234,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({ maxAge: 5000 }); + const b = broadcast.track("video").subscribe({ maxAge: 5000 }); producer.writeString("hello"); producer.writeString("world"); @@ -264,7 +264,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({ maxAge: 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 01b22f7b434..0712446eccb 100644 --- a/js/net/src/broadcast.ts +++ b/js/net/src/broadcast.ts @@ -114,6 +114,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 d8292868ddc..54a57e625e3 100644 --- a/js/net/src/ietf/publisher.test.ts +++ b/js/net/src/ietf/publisher.test.ts @@ -1,14 +1,17 @@ import { expect, test } from "bun:test"; +import { Producer as GroupProducer } from "../group.ts"; import { type Origin, OriginSchema } from "../hop.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 type * as Cluster from "./cluster.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"; @@ -111,6 +114,82 @@ function publisher( }; } +// 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 e4e1580d9ed..a7b5cf3a3f5 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 * as Cluster from "./cluster.ts"; import { Frame, Group as GroupMessage } from "./object.ts"; @@ -154,7 +156,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. + maxAge: Varint.MAX_U53, + }); try { // Declaring the timescale is what opts the track into timestamps; every object @@ -266,15 +275,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 f3580a76375..4cb36f2b012 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({ + maxAge: 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({ + maxAge: 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 059527d0c0b..37aa1781b0b 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"; /** @@ -56,6 +57,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"); @@ -66,4 +80,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 b6635361021..1d41de49a87 100644 --- a/js/net/src/lite/publisher.test.ts +++ b/js/net/src/lite/publisher.test.ts @@ -5,6 +5,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"; @@ -14,6 +15,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, maxAge: TEST_LATENCY_MAX_MS }); +} + +function replayUpdate(props: ConstructorParameters[0]) { + return new SubscribeUpdate({ ...props, maxAge: 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 { @@ -91,7 +103,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. @@ -100,7 +118,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(); } @@ -183,7 +201,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. @@ -200,7 +223,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 @@ -242,7 +265,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); @@ -251,7 +279,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(); @@ -286,7 +314,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. @@ -303,7 +336,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. @@ -437,7 +470,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", @@ -556,7 +589,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(); @@ -583,7 +616,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); @@ -616,10 +649,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); @@ -651,10 +681,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(); @@ -680,10 +707,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(); @@ -713,14 +737,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(); @@ -757,7 +775,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); }); @@ -770,7 +788,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(); @@ -794,16 +812,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, - maxAge: 0, + maxAge: TEST_LATENCY_MAX_MS, startGroup: undefined, endGroup: 5, }); @@ -876,7 +891,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")); @@ -1145,6 +1160,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 12ccd753ac0..6a3272b0221 100644 --- a/js/net/src/lite/publisher.ts +++ b/js/net/src/lite/publisher.ts @@ -887,8 +887,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. @@ -918,12 +923,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 630a1678cd9..dd91f603902 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({ maxAge: 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({ maxAge: 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({ maxAge: 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({ maxAge: 5000 }); + const track = producer.subscribe({ maxAge: 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({ maxAge: 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({ maxAge: 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({ maxAge: 60_000 }); + const track = producer.subscribe({ maxAge: 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({ maxAge: 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({ maxAge: 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({ maxAge: 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({ maxAge: 100 }); + const track = producer.subscribe({ maxAge: 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({ maxAge: 100 }); + const track = producer.subscribe({ maxAge: 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({ maxAge: 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({ maxAge: 100 }); + const track = producer.subscribe({ maxAge: 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({ maxAge: 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({ maxAge: 100 }); + const track = producer.subscribe({ maxAge: 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({ maxAge: 5000 }); + const track = producer.subscribe({ maxAge: 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({ maxAge: 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({ maxAge: 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({ maxAge: 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({ maxAge: 5000 }); + const track = producer.subscribe({ maxAge: 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({ maxAge: 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({ maxAge: 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({ maxAge: 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({ maxAge: 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({ maxAge: 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({ maxAge: 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 fee44923178..43b99340885 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, type TrackRequestOptions, type TrackSequence, type TrackSequences } from "./internal.ts"; import { Timescale, type Timestamp } from "./time.ts"; @@ -237,6 +243,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; @@ -468,6 +481,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); @@ -478,10 +493,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(); @@ -490,11 +507,11 @@ export class Producer { // Evict cached groups that are closed and older than the cache window. #prune(): void { const maxAgeMs = this.#state.info.peek()?.maxAge ?? DEFAULT_MAX_AGE_MS; - const cutoff = Date.now() - maxAgeMs; + const cutoff = performance.now() - maxAgeMs; 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; } @@ -505,10 +522,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. */ @@ -666,6 +685,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()?.maxAge ?? 0; + const retained = this.#state.info.peek()?.maxAge; + 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; @@ -676,6 +775,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; + }; } /** @@ -739,6 +841,7 @@ export class Subscriber { for (const group of groups) group.close(abort); groups.length = 0; }); + this.#state.timeline.clear(); } /** @@ -752,6 +855,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 `maxAge` 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 (;;) { @@ -776,15 +883,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" }; @@ -841,6 +955,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 `maxAge` also skips groups that drift behind the live edge. */ async nextGroup(): Promise { for (;;) { @@ -848,12 +963,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(); @@ -879,15 +1000,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 `maxAge` 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. @@ -904,12 +1038,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..96fec974498 --- /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, maxAge: 250 }); + + latency.set(Time.Milli(500)); + await flush(); + expect(updates.at(-1)).toEqual({ priority: 7, maxAge: 500 }); + + effect.close(); +}); diff --git a/js/watch/src/media.ts b/js/watch/src/media.ts new file mode 100644 index 00000000000..f600b1962eb --- /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, maxAge: props.latency.peek() }); + const subscriber = props.broadcast.track(props.track).subscribe(subscription()); + effect.cleanup(() => subscriber.close()); + + effect.run((inner) => { + subscriber.update({ priority: props.priority, maxAge: 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()); From abc9bc54ea2d862d98d7aa69181d3125959ad048 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 18 Aug 2026 16:28:38 -0700 Subject: [PATCH 2/5] test(hang): name the replay-window helper after what it asks for Matches the moq-mux rename in the parent PR: `subscribeAll` said nothing about what "all" meant and read like a subscribe-to-every-track operation. It is a replay window. Co-Authored-By: Claude Opus 5 --- js/hang/src/container/consumer.test.ts | 48 ++++++++++++++------------ 1 file changed, 25 insertions(+), 23 deletions(-) diff --git a/js/hang/src/container/consumer.test.ts b/js/hang/src/container/consumer.test.ts index f021870c4b3..2c2fe885552 100644 --- a/js/hang/src/container/consumer.test.ts +++ b/js/hang/src/container/consumer.test.ts @@ -37,7 +37,9 @@ function settle(ms = 20): Promise { // 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 { +// These tests write every group up front and only then read, so they ask for history +// rather than the live edge. +function replay(track: Track.Producer): Track.Subscriber { return track.subscribe({ maxAge: 30_000 }); } @@ -189,7 +191,7 @@ async function drainFrames( test("Consumer delivers frames from a single group", async () => { const track = new Track.Producer("test"); - const consumer = new Consumer(subscribeAll(track), { format: new LegacyFormat(), latency: 500 as Time.Milli }); + const consumer = new Consumer(replay(track), { format: new LegacyFormat(), latency: 500 as Time.Milli }); writeGroupWithLegacyFrames(track, 0, [0 as Time.Micro, 33_000 as Time.Micro]); track.close(); @@ -203,7 +205,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(subscribeAll(track), { format: new LegacyFormat(), latency: 500 as Time.Milli }); + const consumer = new Consumer(replay(track), { format: new LegacyFormat(), latency: 500 as Time.Milli }); writeGroupWithLegacyFrames(track, 0, [0 as Time.Micro, 33_000 as Time.Micro]); track.close(); @@ -227,7 +229,7 @@ test("Consumer index spans MoQ frames for keyframe detection", async () => { }; const track = new Track.Producer("test"); - const consumer = new Consumer(subscribeAll(track), { format: multiFormat, latency: 500 as Time.Milli }); + const consumer = new Consumer(replay(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 @@ -255,7 +257,7 @@ test("Consumer keeps frames decoded before an error (truncated GoP)", async () = }; const track = new Track.Producer("test"); - const consumer = new Consumer(subscribeAll(track), { format: truncatingFormat, latency: 500 as Time.Milli }); + const consumer = new Consumer(replay(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); @@ -282,7 +284,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(subscribeAll(track), { format: new LegacyFormat(), latency: 500 as Time.Milli }); + const consumer = new Consumer(replay(track), { format: new LegacyFormat(), latency: 500 as Time.Milli }); const promise = consumer.next(); consumer.close(); @@ -293,7 +295,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(subscribeAll(track), { format: new LegacyFormat(), latency: 500 as Time.Milli }); + const consumer = new Consumer(replay(track), { format: new LegacyFormat(), latency: 500 as Time.Milli }); // First call blocks waiting for data void consumer.next(); @@ -306,7 +308,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(subscribeAll(track), { format: new LegacyFormat(), latency: 0 as Time.Milli }); + const consumer = new Consumer(replay(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]); @@ -325,7 +327,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(subscribeAll(track), { format: new LegacyFormat(), latency: 500 as Time.Milli }); + const consumer = new Consumer(replay(track), { format: new LegacyFormat(), latency: 500 as Time.Milli }); writeGroupWithLegacyFrames(track, 2, [60_000 as Time.Micro]); writeGroupWithLegacyFrames(track, 0, [0 as Time.Micro]); @@ -344,7 +346,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(subscribeAll(track), { format: new LegacyFormat(), latency: 500 as Time.Milli }); + const consumer = new Consumer(replay(track), { format: new LegacyFormat(), latency: 500 as Time.Milli }); // Group.Producer 5 arrives first (sets active = 5) writeGroupWithLegacyFrames(track, 5, [0 as Time.Micro]); @@ -369,7 +371,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(subscribeAll(track), { format: new LegacyFormat(), latency: 500 as Time.Milli }); + const consumer = new Consumer(replay(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]); @@ -400,7 +402,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(subscribeAll(track), { format: new LegacyFormat(), latency: 500 as Time.Milli }); + const consumer = new Consumer(replay(track), { format: new LegacyFormat(), latency: 500 as Time.Milli }); expect(consumer.buffered.peek()).toEqual([]); @@ -422,7 +424,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(subscribeAll(track), { format: new LegacyFormat(), latency: 100 as Time.Milli }); + const consumer = new Consumer(replay(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]); @@ -452,7 +454,7 @@ test("Consumer handles empty decode result without deadlock", async () => { }; const track = new Track.Producer("test"); - const consumer = new Consumer(subscribeAll(track), { format: emptyThenValid, latency: 500 as Time.Milli }); + const consumer = new Consumer(replay(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 @@ -475,7 +477,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(subscribeAll(track), { + const consumer = new Consumer(replay(track), { format: new CmafFormat(TEST_INIT), latency: 500 as Time.Milli, }); @@ -548,7 +550,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(subscribeAll(track), { format: durationFormat, latency: 10_000 as Time.Milli }); + const consumer = new Consumer(replay(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); @@ -585,7 +587,7 @@ test("Consumer does not duration-skip when the gap is not covered", async () => }; const track = new Track.Producer("test"); - const consumer = new Consumer(subscribeAll(track), { format: shortFormat, latency: 10_000 as Time.Milli }); + const consumer = new Consumer(replay(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. @@ -618,7 +620,7 @@ 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(subscribeAll(track), { + const consumer = new Consumer(replay(track), { format: new CmafFormat(TEST_INIT), latency: 500 as Time.Milli, }); @@ -677,7 +679,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(subscribeAll(track), { + const consumer = new Consumer(replay(track), { format: new CmafFormat(TEST_INIT), latency: 10_000 as Time.Milli, }); @@ -751,7 +753,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(subscribeAll(track), { + const consumer = new Consumer(replay(track), { format: new CmafFormat(TEST_INIT), latency: 10_000 as Time.Milli, }); @@ -799,7 +801,7 @@ 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(subscribeAll(track), { + const consumer = new Consumer(replay(track), { format: new CmafFormat(TEST_INIT), latency: 100 as Time.Milli, }); @@ -852,7 +854,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(subscribeAll(track), { format: new LegacyFormat(), latency: 100 as Time.Milli }); + const consumer = new Consumer(replay(track), { format: new LegacyFormat(), latency: 100 as Time.Milli }); writeGroupWithLegacyFrames(track, 0, [0 as Time.Micro, 33_000 as Time.Micro]); await settle(); @@ -871,7 +873,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(subscribeAll(track), { + const consumer = new Consumer(replay(track), { format: new CmafFormat(TEST_INIT), latency: 10_000 as Time.Milli, }); From 283d299bcdb58fd38d9850834d21a925d2b28320 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 18 Aug 2026 21:50:11 -0700 Subject: [PATCH 3/5] fix(js/net): don't serve legacy lite peers at the live edge Mirrors the moq-net fix in the parent PR. Drafts 01 and 02 have no latency field in SUBSCRIBE, so it decodes as `0`, which this branch would otherwise act on: the serving side discards every group but the live edge for a subscriber that never declined the backlog. Those two are the most preferred negotiated versions, so it is the ordinary wire. `carriesLatency` is the one place that answers whether a decoded zero means "real time" or "not stated". Co-Authored-By: Claude Opus 5 --- js/net/src/lite/publisher.test.ts | 24 +++++++++++++++++++----- js/net/src/lite/publisher.ts | 18 +++++++++++++++--- js/net/src/lite/version.ts | 11 +++++++++++ 3 files changed, 45 insertions(+), 8 deletions(-) diff --git a/js/net/src/lite/publisher.test.ts b/js/net/src/lite/publisher.test.ts index 1d41de49a87..c6883fa1abe 100644 --- a/js/net/src/lite/publisher.test.ts +++ b/js/net/src/lite/publisher.test.ts @@ -13,17 +13,17 @@ import { sendOrder } from "./priority.ts"; import { Probe as ProbeMessage } from "./probe.ts"; import { Publisher } from "./publisher.ts"; import { decodeSubscribeResponse, Subscribe, SubscribeUpdate } from "./subscribe.ts"; -import { ALPN_05, ALPN_06_WIP, Version } from "./version.ts"; +import { ALPN_05, ALPN_06_WIP, carriesMaxAge, Version } from "./version.ts"; // Scheduling tests intentionally stall groups, so keep latency enforcement out of their scope. -const TEST_LATENCY_MAX_MS = 30_000; +const TEST_MAX_AGE_MS = 30_000; function replaySubscribe(props: ConstructorParameters[0]) { - return new Subscribe({ ...props, maxAge: TEST_LATENCY_MAX_MS }); + return new Subscribe({ ...props, maxAge: TEST_MAX_AGE_MS }); } function replayUpdate(props: ConstructorParameters[0]) { - return new SubscribeUpdate({ ...props, maxAge: TEST_LATENCY_MAX_MS }); + return new SubscribeUpdate({ ...props, maxAge: TEST_MAX_AGE_MS }); } // Delivers `sequences` in the given order, finishes the track, and returns the @@ -818,7 +818,7 @@ test("lite draft-06: scheduling updates apply while SUBSCRIBE_START is blocked", expect(sub.track.subscription.peek()).toEqual({ priority: 9, ordered: true, - maxAge: TEST_LATENCY_MAX_MS, + maxAge: TEST_MAX_AGE_MS, startGroup: undefined, endGroup: 5, }); @@ -1297,3 +1297,17 @@ test("runProbe rounds a fractional smoothedRtt instead of killing the stream", a await probing; } }); + +test("a version without the latency field serves a non-dropping budget", () => { + // Drafts 01/02 have no latency field, so a SUBSCRIBE from one decodes as 0. + // Serving that as a real-time budget would hold every legacy peer to the live edge + // and discard backlog it never declined, so those versions get a non-dropping + // window and leave enforcement to the receiver. They are the two most-preferred + // negotiated versions, so this is the common wire, not an edge case. + for (const version of [Version.DRAFT_01, Version.DRAFT_02]) { + expect(carriesMaxAge(version)).toBe(false); + } + + // A version that does carry it is taken at its word, zero included. + expect(carriesMaxAge(Version.DRAFT_05)).toBe(true); +}); diff --git a/js/net/src/lite/publisher.ts b/js/net/src/lite/publisher.ts index 6a3272b0221..a9f46bc95b3 100644 --- a/js/net/src/lite/publisher.ts +++ b/js/net/src/lite/publisher.ts @@ -25,7 +25,7 @@ import { SubscribeUpdate, } from "./subscribe.ts"; import { TrackInfo as TrackInfoMessage, type Track as TrackMessage } from "./track.ts"; -import { hasAnnounceId, hasAnnounceOk, hasDatagrams, hasProbeRtt, Version } from "./version.ts"; +import { carriesMaxAge, hasAnnounceId, hasAnnounceOk, hasDatagrams, hasProbeRtt, Version } from "./version.ts"; const PROBE_INTERVAL = 100; // ms const PROBE_MAX_AGE = 10_000; // ms @@ -261,6 +261,18 @@ function waitForSubscription(controls: SubscriptionControls, subscriber: track.S }); } +/** + * The budget to serve a peer with, given what its wire could tell us. + * + * A version without the field decodes as `0`, which is indistinguishable from a peer + * genuinely asking for the live edge. Serving that as real time would discard backlog + * a legacy subscriber never declined, so fall back to a window wide enough not to drop + * and leave enforcement to the receiver, as the IETF path does for the same reason. + */ +function servingMaxAge(version: Version, requested: number | undefined): number { + return carriesMaxAge(version) ? (requested ?? 0) : Number.MAX_SAFE_INTEGER; +} + /** * Handles publishing broadcasts and managing their lifecycle. * @@ -454,7 +466,7 @@ export class Publisher { const track = broadcast.subscribe(msg.track, { priority: msg.priority, ordered: msg.ordered, - maxAge: msg.maxAge, + maxAge: servingMaxAge(this.version, msg.maxAge), startGroup: msg.startGroup, endGroup: msg.endGroup, }); @@ -511,7 +523,7 @@ export class Publisher { track.update({ priority: update.priority, ordered: update.ordered, - maxAge: update.maxAge, + maxAge: servingMaxAge(this.version, update.maxAge), startGroup: update.startGroup, endGroup: update.endGroup, }); diff --git a/js/net/src/lite/version.ts b/js/net/src/lite/version.ts index 4ec196374bc..8dc97a1abde 100644 --- a/js/net/src/lite/version.ts +++ b/js/net/src/lite/version.ts @@ -46,6 +46,17 @@ export function hasSetupStream(version: Version): boolean { } } +/** + * Whether this version's SUBSCRIBE carries the subscriber's maximum-age preference. + * + * Drafts 01 and 02 have no field for it, so a decoded `0` there means "not stated", + * not "real time". A caller that acts on the budget has to tell the two apart or it + * will hold every legacy peer to the live edge. + */ +export function carriesMaxAge(version: Version): boolean { + return version !== Version.DRAFT_01 && version !== Version.DRAFT_02; +} + /// Whether the session may deliver groups over unreliable QUIC datagrams (lite-05 §6.4). /// A datagram carries one single-frame group's `subscribe | sequence | timestamp | payload` and is /// routed over the existing subscription. Added in lite-05; older versions never send/accept them. From ff7219415ee92b561b4d714299b31b75c093b254 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sat, 22 Aug 2026 13:09:19 -0700 Subject: [PATCH 4/5] fix(js/net): preserve latency enforcement invariants Co-Authored-By: GPT-5.6 Sol --- js/net/src/group.test.ts | 9 ++ js/net/src/group.ts | 183 ++++++++++++++++++------------ js/net/src/ietf/publisher.ts | 14 ++- js/net/src/internal.ts | 29 ++++- js/net/src/lite/publisher.test.ts | 28 ++--- js/net/src/lite/publisher.ts | 21 ++-- js/net/src/lite/version.ts | 11 -- js/net/src/track.test.ts | 52 +++++++++ js/net/src/track.ts | 24 ++-- 9 files changed, 244 insertions(+), 127 deletions(-) diff --git a/js/net/src/group.test.ts b/js/net/src/group.test.ts index 88a1633106c..d4860ae2fbf 100644 --- a/js/net/src/group.test.ts +++ b/js/net/src/group.test.ts @@ -146,6 +146,15 @@ test("done distinguishes a finished group from one that is merely empty", () => expect(consumer.done).toBe(true); }); +test("a previously obtained closed handle peeks source closure synchronously", () => { + const { producer, consumer } = pair(0); + const closed = consumer.closed; + + producer.close(); + + expect(closed.peek()).toBeNull(); +}); + test("readable resolves once a frame is buffered", async () => { const { producer, consumer } = pair(0); // No frame yet: readable() must stay pending for an empty, open group. diff --git a/js/net/src/group.ts b/js/net/src/group.ts index f53810f0e8c..c61a770abfa 100644 --- a/js/net/src/group.ts +++ b/js/net/src/group.ts @@ -4,7 +4,7 @@ * @module */ import { type Dispose, type GetPromise, type Getter, Once, Signal } from "@moq/signals"; -import { hooks } from "./internal.ts"; +import { type GroupPosition, hooks, type ReadGroupFrame } from "./internal.ts"; import { Timestamp } from "./time.ts"; /** Maximum bytes of frames cached in a group before old frames are evicted from the front. */ @@ -29,15 +29,10 @@ 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; +/** A frame paired with its arrival clock for wall-clock drift measurement. */ +interface BufferedFrame { + frame: Frame; + activity: number; } /** Immutable group metadata. */ @@ -60,7 +55,7 @@ export class Lagged extends Error { /** Reactive backing state shared by the group producer and one consumer. */ class GroupState { readonly sequence: number; - frames = new Signal([]); + frames = new Signal([]); closed = new Once(); total = new Signal(0); // The total number of frames in the group thus far @@ -81,20 +76,20 @@ class GroupState { } } -function appendFrame(state: GroupState, frame: Frame) { +function appendFrame(state: GroupState, frame: Frame, activity: number) { if (state.closed.peek() !== undefined) throw new Error("group is closed"); state.timestamp ??= frame.timestamp; state.latest = frame.timestamp; - state.activity = performance.now(); + state.activity = activity; state.cacheBytes += frame.payload.byteLength; state.frames.mutate((frames) => { - frames.push(frame); + frames.push({ frame, activity }); while (frames.length > MAX_GROUP_FRAMES || state.cacheBytes > MAX_GROUP_CACHE_BYTES) { const evicted = frames.shift(); if (!evicted) break; - state.cacheBytes -= evicted.payload.byteLength; + state.cacheBytes -= evicted.frame.payload.byteLength; state.offset++; } }); @@ -150,7 +145,7 @@ export class Producer { 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); + for (const { frame, activity } of this.#state.frames.peek()) appendFrame(dst, frame, activity); dst.offset = this.#state.offset; const closed = this.#state.closed.peek(); @@ -201,12 +196,13 @@ export class Producer { /** Writes a frame to the group. */ writeFrame(frame: Frame) { - appendFrame(this.#state, frame); + const activity = performance.now(); + appendFrame(this.#state, frame, activity); if (this.#mirrors) { for (const mirror of this.#mirrors) { if (mirror.closed.peek() !== undefined) this.#mirrors.delete(mirror); - else appendFrame(mirror, frame); + else appendFrame(mirror, frame, activity); } } } @@ -247,6 +243,66 @@ export class Producer { let makeConsumer: (state: GroupState) => Consumer; +// A consumer can finish from its own expiry verdict or from the shared group state. Keep +// one stable public handle while letting peek() observe either source synchronously, before +// signal subscribers run in the next microtask. +class CombinedClosed implements GetPromise { + #preferred: Once; + #source: Once; + #value = new Once(); + #dispose?: Dispose; + + constructor(preferred: Once, source: Once) { + this.#preferred = preferred; + this.#source = source; + if (this.#sync()) return; + + const dispose = [preferred.changed(() => this.#sync()), source.changed(() => this.#sync())]; + this.#dispose = () => { + for (const close of dispose) close(); + }; + } + + #sync(): boolean { + if (this.#value.peek() !== undefined) return true; + const preferred = this.#preferred.peek(); + const source = this.#source.peek(); + const value = preferred !== undefined ? preferred : source; + if (value === undefined) return false; + + this.#value.set(value); + this.#dispose?.(); + this.#dispose = undefined; + return true; + } + + peek(): Error | null | undefined { + this.#sync(); + return this.#value.peek(); + } + + changed(): Promise; + changed(fn: (value: Error | null | undefined) => void): Dispose; + changed(fn?: (value: Error | null | undefined) => void): Promise | Dispose { + this.#sync(); + return fn ? this.#value.changed(fn) : this.#value.changed(); + } + + subscribe(fn: (value: Error | null | undefined) => void): Dispose { + this.#sync(); + return this.#value.subscribe(fn); + } + + // biome-ignore lint/suspicious/noThenProperty: CombinedClosed is intentionally awaitable. + then( + onFulfilled?: ((value: Error | null) => R1 | PromiseLike) | null, + onRejected?: ((reason: unknown) => R2 | PromiseLike) | null, + ): PromiseLike { + this.#sync(); + return this.#value.then(onFulfilled, onRejected); + } +} + /** * The read side of an ordered stream of frames within a track. * @@ -260,15 +316,15 @@ export class Consumer { readonly sequence: number; #state: GroupState; - #expiry?: { expired: (at: Position) => boolean; changed: readonly Getter[] }; + #expiry?: { expired: (at: GroupPosition) => 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; + #verdict = new Once(); + #closed?: CombinedClosed; private constructor(state: GroupState) { this.#state = state; @@ -280,7 +336,7 @@ export class Consumer { * Peek it synchronously (`undefined` while open), observe it reactively, or `await` it. */ get closed(): GetPromise { - this.#watchClosed(); + this.#closed ??= new CombinedClosed(this.#verdict, this.#state.closed); return this.#closed; } @@ -290,7 +346,8 @@ export class Consumer { hooks.expireGroup = (group, expiry) => { group.#expiry = expiry; }; - hooks.guardGroup = (group, operation) => group.#guard(operation); + hooks.guardGroup = (group, operation, at) => group.#guard(operation, at); + hooks.readGroupFrame = (group) => group.#readFramePosition(); hooks.evictGroup = (group) => { group.#evict(); }; @@ -301,10 +358,11 @@ export class Consumer { // 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 { + #position(): GroupPosition { + const next = this.#state.frames.peek()[0]; return { - presentation: this.#state.frames.peek()[0]?.timestamp ?? this.#state.latest, - activity: this.#state.activity, + presentation: next?.frame.timestamp ?? this.#state.latest, + activity: next?.activity ?? this.#state.activity, }; } @@ -316,22 +374,22 @@ export class Consumer { // `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 { + #expire(unread = false, at = this.#position()): 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 (!this.#expiry?.expired(at)) 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); + if (this.#verdict.peek() === undefined) this.#verdict.set(this.#terminal ?? null); return true; } - #guard(operation: Promise): Promise { - if (this.#expire(true)) return Promise.reject(this.#terminal); + #guard(operation: Promise, at = this.#position()): Promise { + if (this.#expire(true, at)) return Promise.reject(this.#terminal); if (this.#terminal) return Promise.reject(this.#terminal); const expiry = this.#expiry; if (!expiry) return operation; @@ -346,7 +404,7 @@ export class Consumer { fn(); }; const check = () => { - this.#expire(true); + this.#expire(true, at); if (this.#terminal) { const error = this.#terminal; finish(() => reject(error)); @@ -371,7 +429,7 @@ export class Consumer { this.#expire(true); if (!this.#terminal && !this.#ended) { this.#terminal = new Lagged(); - if (this.#closed.peek() === undefined) this.#closed.set(this.#terminal); + if (this.#verdict.peek() === undefined) this.#verdict.set(this.#terminal); } } this.#state.offset += frames.length; @@ -379,25 +437,6 @@ export class Consumer { 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); @@ -406,13 +445,17 @@ export class Consumer { await Signal.race(this.#state.frames, this.#state.closed, ...this.#expiry.changed); } - #readBufferedFrame(): { sequence: number; frame: Frame } | undefined { + #readBufferedFrame(): ReadGroupFrame | undefined { const frames = this.#state.frames.peek(); - const frame = frames.shift(); - if (!frame) return undefined; + const buffered = frames.shift(); + if (!buffered) return undefined; - this.#state.cacheBytes -= frame.payload.byteLength; - return { sequence: this.#state.total.peek() - frames.length - 1, frame }; + this.#state.cacheBytes -= buffered.frame.payload.byteLength; + return { + sequence: this.#state.total.peek() - frames.length - 1, + frame: buffered.frame, + position: { presentation: buffered.frame.timestamp, activity: buffered.activity }, + }; } /** True once no further frames can be read: the group has closed and every buffered frame is read. */ @@ -471,13 +514,17 @@ export class Consumer { * Treat the returned frame bytes as read-only; they are shared with other consumers. */ async readFrame(): Promise { + return (await this.#readFramePosition())?.frame; + } + + async #readFramePosition(): Promise { for (;;) { if (this.#terminal) throw this.#terminal; if (this.#ended) return; if (this.#state.offset > 0) throw new Lagged(); const read = this.#readBufferedFrame(); - if (read) return read.frame; + if (read) return read; const closed = this.#state.closed.peek(); if (closed instanceof Error) throw closed; @@ -495,23 +542,9 @@ export class Consumer { * Treat the returned frame bytes as read-only; they are shared with other consumers. */ 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(); - if (read) return { sequence: read.sequence, payload: read.frame.payload, timestamp: read.frame.timestamp }; - - const closed = this.#state.closed.peek(); - if (closed instanceof Error) throw closed; - if (closed !== undefined) return; - - // 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(); - } + const read = await this.#readFramePosition(); + if (!read) return undefined; + return { sequence: read.sequence, payload: read.frame.payload, timestamp: read.frame.timestamp }; } /** Reads the next frame and decodes its payload as a UTF-8 string. */ diff --git a/js/net/src/ietf/publisher.ts b/js/net/src/ietf/publisher.ts index a7b5cf3a3f5..f1eaa60e515 100644 --- a/js/net/src/ietf/publisher.ts +++ b/js/net/src/ietf/publisher.ts @@ -279,11 +279,15 @@ export class Publisher { 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 hooks.guardGroup(group, obj.encode(stream, header.flags, timescale, this.#session.version)); + const read = await Promise.race([hooks.readGroupFrame(group), stream.closed]); + if (!read) break; + + const obj = new Frame({ payload: read.frame.payload, timestamp: read.frame.timestamp }); + await hooks.guardGroup( + group, + obj.encode(stream, header.flags, timescale, this.#session.version), + read.position, + ); } stream.close(); diff --git a/js/net/src/internal.ts b/js/net/src/internal.ts index 37aa1781b0b..dab5be078e5 100644 --- a/js/net/src/internal.ts +++ b/js/net/src/internal.ts @@ -6,7 +6,7 @@ * @module */ import type { Dispose, Getter } from "@moq/signals"; -import type { Consumer as GroupConsumer, Position } from "./group.ts"; +import type { Frame, Consumer as GroupConsumer } from "./group.ts"; import type { Timestamp } from "./time.ts"; import type { Producer, Request, Subscriber } from "./track.ts"; @@ -26,6 +26,24 @@ export type Recv = /** The track aborted. */ | { kind: "error"; error: Error }; +/** Where a group cursor sits while measuring drift against the live edge. */ +export interface GroupPosition { + /** Presentation timestamp of the next or in-flight frame. */ + presentation?: Timestamp; + /** Monotonic arrival time of the next or in-flight frame. */ + activity?: number; +} + +/** A package-internal frame read paired with its guarded cursor position. */ +export interface ReadGroupFrame { + /** Frame sequence within the group. */ + sequence: number; + /** Frame returned to the publisher. */ + frame: Frame; + /** Cursor position held while the frame is in flight. */ + position: GroupPosition; +} + /** The next group or datagram sequence shared by dynamic producers of one broadcast track. */ export interface TrackSequence { next: number; @@ -64,10 +82,12 @@ export const hooks: { /** Keep applying a subscription's drift policy after it hands a group out. */ expireGroup: ( group: GroupConsumer, - expiry: { expired: (at: Position) => boolean; changed: readonly Getter[] }, + expiry: { expired: (at: GroupPosition) => boolean; changed: readonly Getter[] }, ) => void; /** Stop an in-flight group operation if the handed-out group expires. */ - guardGroup: (group: GroupConsumer, operation: Promise) => Promise; + guardGroup: (group: GroupConsumer, operation: Promise, at?: GroupPosition) => Promise; + /** Read a frame with the cursor position needed to guard its wire write. */ + readGroupFrame: (group: GroupConsumer) => Promise; /** Make an evicted mirror terminal while its track timeline still contains it. */ evictGroup: (group: GroupConsumer) => void; } = { @@ -92,6 +112,9 @@ export const hooks: { guardGroup: () => { throw new Error("group.ts not loaded"); }, + readGroupFrame: () => { + 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 c6883fa1abe..3affef50896 100644 --- a/js/net/src/lite/publisher.test.ts +++ b/js/net/src/lite/publisher.test.ts @@ -6,14 +6,14 @@ 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 { DEFAULT_MAX_AGE_MS, Subscriber as TrackSubscriber } from "../track.ts"; import { Fetch } from "./fetch.ts"; import { Group as GroupMessage } from "./group.ts"; import { sendOrder } from "./priority.ts"; import { Probe as ProbeMessage } from "./probe.ts"; import { Publisher } from "./publisher.ts"; import { decodeSubscribeResponse, Subscribe, SubscribeUpdate } from "./subscribe.ts"; -import { ALPN_05, ALPN_06_WIP, carriesMaxAge, Version } from "./version.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_MAX_AGE_MS = 30_000; @@ -444,6 +444,7 @@ async function servedSubscription( endGroup?: number; endFrame?: number; gated?: boolean; + maxAge?: number; // Frame payloads written into every served group. Frame bounds need draft-06. frames?: string[]; version?: Version; @@ -456,7 +457,7 @@ async function servedSubscription( const publisher = new Publisher(pair.server, version, randomOrigin(), origin.consume()); const broadcast = origin.publish(Path.from("test")); - const track = broadcast.createTrack("video"); + const track = broadcast.createTrack("video", { maxAge: options.maxAge }); const client = await Stream.open(pair.client); @@ -818,7 +819,7 @@ test("lite draft-06: scheduling updates apply while SUBSCRIBE_START is blocked", expect(sub.track.subscription.peek()).toEqual({ priority: 9, ordered: true, - maxAge: TEST_MAX_AGE_MS, + maxAge: DEFAULT_MAX_AGE_MS, startGroup: undefined, endGroup: 5, }); @@ -1298,16 +1299,15 @@ test("runProbe rounds a fractional smoothedRtt instead of killing the stream", a } }); -test("a version without the latency field serves a non-dropping budget", () => { - // Drafts 01/02 have no latency field, so a SUBSCRIBE from one decodes as 0. - // Serving that as a real-time budget would hold every legacy peer to the live edge - // and discard backlog it never declined, so those versions get a non-dropping - // window and leave enforcement to the receiver. They are the two most-preferred - // negotiated versions, so this is the common wire, not an edge case. +test("a version without the latency field serves a non-dropping budget", async () => { for (const version of [Version.DRAFT_01, Version.DRAFT_02]) { - expect(carriesMaxAge(version)).toBe(false); + const sub = await servedSubscription({ version, maxAge: Number.MAX_SAFE_INTEGER }); + try { + // These drafts decode the absent field as zero. The publisher must not turn + // that into a live-edge request the peer never made. + expect(sub.track.subscription.peek()?.maxAge).toBe(Number.MAX_SAFE_INTEGER); + } finally { + await sub.close(); + } } - - // A version that does carry it is taken at its word, zero included. - expect(carriesMaxAge(Version.DRAFT_05)).toBe(true); }); diff --git a/js/net/src/lite/publisher.ts b/js/net/src/lite/publisher.ts index a9f46bc95b3..fd0c4ddae37 100644 --- a/js/net/src/lite/publisher.ts +++ b/js/net/src/lite/publisher.ts @@ -25,7 +25,7 @@ import { SubscribeUpdate, } from "./subscribe.ts"; import { TrackInfo as TrackInfoMessage, type Track as TrackMessage } from "./track.ts"; -import { carriesMaxAge, hasAnnounceId, hasAnnounceOk, hasDatagrams, hasProbeRtt, Version } from "./version.ts"; +import { hasAnnounceId, hasAnnounceOk, hasDatagrams, hasProbeRtt, Version } from "./version.ts"; const PROBE_INTERVAL = 100; // ms const PROBE_MAX_AGE = 10_000; // ms @@ -270,7 +270,8 @@ function waitForSubscription(controls: SubscriptionControls, subscriber: track.S * and leave enforcement to the receiver, as the IETF path does for the same reason. */ function servingMaxAge(version: Version, requested: number | undefined): number { - return carriesMaxAge(version) ? (requested ?? 0) : Number.MAX_SAFE_INTEGER; + const carriesMaxAge = version !== Version.DRAFT_01 && version !== Version.DRAFT_02; + return carriesMaxAge ? (requested ?? 0) : Number.MAX_SAFE_INTEGER; } /** @@ -916,8 +917,8 @@ export class Publisher { let reached = startFrame === 0; for (;;) { - const frame = await Promise.race([group.readFrameSequence(), stream.closed]); - if (!frame) { + const read = await Promise.race([hooks.readGroupFrame(group), stream.closed]); + if (!read) { // The group ended before the frame the subscriber asked to start // at, so this publisher can't serve the range at all. FINning here // would claim an empty group under that index; reset so it reads @@ -928,19 +929,19 @@ export class Publisher { // Frames below the requested start were excluded, and the receiver // numbers what it gets from `startFrame`. - if (frame.sequence < startFrame) continue; - if (endFrame !== undefined && frame.sequence > endFrame) break; + if (read.sequence < startFrame) continue; + if (endFrame !== undefined && read.sequence > endFrame) break; reached = true; if (timestamps) { // Convert each frame to the track's advertised timescale. - const ts = BigInt(Math.round(frame.timestamp.as(timescale))); - await hooks.guardGroup(group, stream.u62(zigzag(ts - prevTs))); + const ts = BigInt(Math.round(read.frame.timestamp.as(timescale))); + await hooks.guardGroup(group, stream.u62(zigzag(ts - prevTs)), read.position); prevTs = ts; } - await hooks.guardGroup(group, stream.u53(frame.payload.byteLength)); - await hooks.guardGroup(group, stream.write(frame.payload)); + await hooks.guardGroup(group, stream.u53(read.frame.payload.byteLength), read.position); + await hooks.guardGroup(group, stream.write(read.frame.payload), read.position); } stream.close(); diff --git a/js/net/src/lite/version.ts b/js/net/src/lite/version.ts index 8dc97a1abde..4ec196374bc 100644 --- a/js/net/src/lite/version.ts +++ b/js/net/src/lite/version.ts @@ -46,17 +46,6 @@ export function hasSetupStream(version: Version): boolean { } } -/** - * Whether this version's SUBSCRIBE carries the subscriber's maximum-age preference. - * - * Drafts 01 and 02 have no field for it, so a decoded `0` there means "not stated", - * not "real time". A caller that acts on the budget has to tell the two apart or it - * will hold every legacy peer to the live edge. - */ -export function carriesMaxAge(version: Version): boolean { - return version !== Version.DRAFT_01 && version !== Version.DRAFT_02; -} - /// Whether the session may deliver groups over unreliable QUIC datagrams (lite-05 §6.4). /// A datagram carries one single-frame group's `subscribe | sequence | timestamp | payload` and is /// routed over the existing subscription. Added in lite-05; older versions never send/accept them. diff --git a/js/net/src/track.test.ts b/js/net/src/track.test.ts index dd91f603902..f48240de0e4 100644 --- a/js/net/src/track.test.ts +++ b/js/net/src/track.test.ts @@ -189,6 +189,17 @@ test("multiple subscriber options aggregate like Rust", async () => { expect(await none).toBeUndefined(); }); +test("the producer aggregate is clamped without changing subscriber options", async () => { + const producer = new TrackProducer("test"); + const track = producer.subscribe({ maxAge: 10_000 }); + const clamped = producer.subscription.changed(); + + producer.accept({ maxAge: 2_000 }); + + expect((await clamped)?.maxAge).toBe(2_000); + expect(track.subscription.peek()?.maxAge).toBe(10_000); +}); + test("nextGroup skips late arrivals", async () => { const producer = new TrackProducer("test"); const track = producer.subscribe(); @@ -384,6 +395,24 @@ test("a handed-out group still expires while its first frame is stalled", async } }); +test("committing track info wakes a group newly outside the retention window", async () => { + const producer = new TrackProducer("test"); + const track = producer.subscribe({ maxAge: 10_000 }); + const source = producer.appendGroup(); + source.writeFrame({ payload: enc.encode("old"), timestamp: Timestamp.fromMillis(0) }); + + const group = await track.recvGroup(); + if (!group) throw new Error("missing group"); + expect((await group.readFrame())?.timestamp.asMillis()).toBe(0); + const waiting = group.readFrame(); + + producer.writeFrame({ payload: enc.encode("edge"), timestamp: Timestamp.fromMillis(1_000) }); + await settle(); + producer.accept({ maxAge: 100 }); + + await expect(waiting).resolves.toBeUndefined(); +}); + test("a handed-out frame cancels its in-flight operation when it expires", async () => { const producer = new TrackProducer("test").accept({ maxAge: 5000 }); const track = producer.subscribe(); @@ -404,6 +433,29 @@ test("a handed-out frame cancels its in-flight operation when it expires", async release(); }); +test("a guarded write keeps the position of the frame removed from the buffer", async () => { + const producer = new TrackProducer("test").accept({ maxAge: 100 }); + const track = producer.subscribe({ maxAge: 100 }); + const source = producer.appendGroup(); + source.writeFrame({ payload: enc.encode("old"), timestamp: Timestamp.fromMillis(0) }); + source.writeFrame({ payload: enc.encode("future"), timestamp: Timestamp.fromMillis(10_000) }); + + const group = await track.recvGroup(); + if (!group) throw new Error("missing group"); + const read = await hooks.readGroupFrame(group); + if (!read) throw new Error("missing frame"); + + let release!: () => void; + const operation = new Promise((resolve) => { + release = resolve; + }); + const guarded = hooks.guardGroup(group, operation, read.position); + + producer.writeFrame({ payload: enc.encode("edge"), timestamp: Timestamp.fromMillis(1_000) }); + 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({ maxAge: 5000 }); const track = producer.subscribe(); diff --git a/js/net/src/track.ts b/js/net/src/track.ts index 43b99340885..9d5f8a20130 100644 --- a/js/net/src/track.ts +++ b/js/net/src/track.ts @@ -5,14 +5,15 @@ */ 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, type TrackRequestOptions, type TrackSequence, type TrackSequences } from "./internal.ts"; + type GroupPosition, + hooks, + type Recv, + type TrackRequestOptions, + type TrackSequence, + type TrackSequences, +} from "./internal.ts"; import { Timescale, type Timestamp } from "./time.ts"; export type { Datagram } from "./datagram.ts"; @@ -389,6 +390,7 @@ export class Producer { this.#state.info.set(resolved); // Propagate to any sink handed out before accept (the on-demand path). for (const sink of this.#sinks) sink.info.set(resolved); + this.#updateSubscription(); return this; } @@ -472,7 +474,10 @@ export class Producer { // Recompute from every live sink because an update or close can narrow as well as widen // the aggregate. The wire layer observes this signal and emits SUBSCRIBE_UPDATE. #updateSubscription(): void { - this.#state.update.set(combineSubscriptions(this.#sinks)); + const combined = combineSubscriptions(this.#sinks); + const retained = this.#state.info.peek()?.maxAge; + if (combined && retained !== undefined) combined.maxAge = Math.min(combined.maxAge ?? 0, retained); + this.#state.update.set(combined); } // Mirror a cached source group into a sink. The mirror fills synchronously as the @@ -730,7 +735,7 @@ export class Subscriber { wall?: { sequence: number; time: number }; presentation?: { sequence: number; timestamp: Timestamp }; }, - at?: Position, + at?: GroupPosition, ): boolean { const candidate = this.#state.timeline.get(group.sequence); if (candidate?.group !== group) return false; @@ -759,6 +764,7 @@ export class Subscriber { this.#state.groups, this.#state.timelineChanged, this.#state.update, + this.#state.info, this.#cursor, this.#state.closed, ], From 07f6a0365eb3869b15a9584a14714096dfcd5ede Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sat, 22 Aug 2026 13:26:11 -0700 Subject: [PATCH 5/5] fix(js/net): defer clean closure until delivery Co-Authored-By: GPT-5.6 Sol --- js/net/src/group.ts | 58 +++++++++++++++++++++++++++++------- js/net/src/ietf/publisher.ts | 16 ++++++---- js/net/src/internal.ts | 2 ++ js/net/src/lite/publisher.ts | 32 +++++++++++--------- js/net/src/track.test.ts | 30 +++++++++++++++++++ 5 files changed, 107 insertions(+), 31 deletions(-) diff --git a/js/net/src/group.ts b/js/net/src/group.ts index c61a770abfa..8c32066ecae 100644 --- a/js/net/src/group.ts +++ b/js/net/src/group.ts @@ -249,12 +249,14 @@ let makeConsumer: (state: GroupState) => Consumer; class CombinedClosed implements GetPromise { #preferred: Once; #source: Once; + #sourceCleanReady: () => boolean; #value = new Once(); #dispose?: Dispose; - constructor(preferred: Once, source: Once) { + constructor(preferred: Once, source: Once, sourceCleanReady: () => boolean) { this.#preferred = preferred; this.#source = source; + this.#sourceCleanReady = sourceCleanReady; if (this.#sync()) return; const dispose = [preferred.changed(() => this.#sync()), source.changed(() => this.#sync())]; @@ -267,7 +269,12 @@ class CombinedClosed implements GetPromise { if (this.#value.peek() !== undefined) return true; const preferred = this.#preferred.peek(); const source = this.#source.peek(); - const value = preferred !== undefined ? preferred : source; + const value = + preferred !== undefined + ? preferred + : source instanceof Error || this.#sourceCleanReady() + ? source + : undefined; if (value === undefined) return false; this.#value.set(value); @@ -276,6 +283,10 @@ class CombinedClosed implements GetPromise { return true; } + refresh() { + this.#sync(); + } + peek(): Error | null | undefined { this.#sync(); return this.#value.peek(); @@ -325,6 +336,7 @@ export class Consumer { #terminal?: Error; #verdict = new Once(); #closed?: CombinedClosed; + #pendingFrames = 0; private constructor(state: GroupState) { this.#state = state; @@ -332,11 +344,16 @@ export class Consumer { } /** - * Settles once the group closes: `null` on a clean close, or the abort {@link Error}. + * Settles when this consumer reaches a terminal state: `null` after a clean close has no + * unread or in-flight frames, or the terminal {@link Error}. * Peek it synchronously (`undefined` while open), observe it reactively, or `await` it. */ get closed(): GetPromise { - this.#closed ??= new CombinedClosed(this.#verdict, this.#state.closed); + this.#closed ??= new CombinedClosed( + this.#verdict, + this.#state.closed, + () => this.#state.frames.peek().length === 0 && this.#pendingFrames === 0, + ); return this.#closed; } @@ -347,7 +364,7 @@ export class Consumer { group.#expiry = expiry; }; hooks.guardGroup = (group, operation, at) => group.#guard(operation, at); - hooks.readGroupFrame = (group) => group.#readFramePosition(); + hooks.readGroupFrame = (group) => group.#readFramePosition(true); hooks.evictGroup = (group) => { group.#evict(); }; @@ -445,16 +462,24 @@ export class Consumer { await Signal.race(this.#state.frames, this.#state.closed, ...this.#expiry.changed); } - #readBufferedFrame(): ReadGroupFrame | undefined { + #readBufferedFrame(pending = false): ReadGroupFrame | undefined { const frames = this.#state.frames.peek(); const buffered = frames.shift(); if (!buffered) return undefined; this.#state.cacheBytes -= buffered.frame.payload.byteLength; + if (pending) this.#pendingFrames++; + let completed = false; return { sequence: this.#state.total.peek() - frames.length - 1, frame: buffered.frame, position: { presentation: buffered.frame.timestamp, activity: buffered.activity }, + complete: () => { + if (completed) return; + completed = true; + if (pending) this.#pendingFrames--; + this.#closed?.refresh(); + }, }; } @@ -487,6 +512,7 @@ export class Consumer { tryReadFrame(): Frame | undefined { if (this.#terminal || this.#ended) return undefined; const read = this.#readBufferedFrame(); + read?.complete(); return read?.frame; } @@ -495,6 +521,7 @@ export class Consumer { if (this.#terminal || this.#ended) return undefined; const read = this.#readBufferedFrame(); if (!read) return undefined; + read.complete(); return { sequence: read.sequence, payload: read.frame.payload, timestamp: read.frame.timestamp }; } @@ -503,7 +530,10 @@ export class Consumer { for (;;) { if (this.#terminal || this.#ended) return; if (this.#state.frames.peek().length > 0) return; - if (this.#state.closed.peek() !== undefined) return; + if (this.#state.closed.peek() !== undefined) { + this.#closed?.refresh(); + return; + } if (this.#expire()) return; await this.#changed(); } @@ -517,18 +547,24 @@ export class Consumer { return (await this.#readFramePosition())?.frame; } - async #readFramePosition(): Promise { + async #readFramePosition(pending = false): Promise { for (;;) { if (this.#terminal) throw this.#terminal; if (this.#ended) return; if (this.#state.offset > 0) throw new Lagged(); - const read = this.#readBufferedFrame(); - if (read) return read; + const read = this.#readBufferedFrame(pending); + if (read) { + if (!pending) read.complete(); + return read; + } const closed = this.#state.closed.peek(); if (closed instanceof Error) throw closed; - if (closed !== undefined) return; + if (closed !== undefined) { + this.#closed?.refresh(); + return; + } // Nothing buffered and the group is still open: this wait is the stall the // drift budget bounds, and the only place it applies. diff --git a/js/net/src/ietf/publisher.ts b/js/net/src/ietf/publisher.ts index f1eaa60e515..54ab68b095e 100644 --- a/js/net/src/ietf/publisher.ts +++ b/js/net/src/ietf/publisher.ts @@ -282,12 +282,16 @@ export class Publisher { const read = await Promise.race([hooks.readGroupFrame(group), stream.closed]); if (!read) break; - const obj = new Frame({ payload: read.frame.payload, timestamp: read.frame.timestamp }); - await hooks.guardGroup( - group, - obj.encode(stream, header.flags, timescale, this.#session.version), - read.position, - ); + try { + const obj = new Frame({ payload: read.frame.payload, timestamp: read.frame.timestamp }); + await hooks.guardGroup( + group, + obj.encode(stream, header.flags, timescale, this.#session.version), + read.position, + ); + } finally { + read.complete(); + } } stream.close(); diff --git a/js/net/src/internal.ts b/js/net/src/internal.ts index dab5be078e5..2a98d17c30a 100644 --- a/js/net/src/internal.ts +++ b/js/net/src/internal.ts @@ -42,6 +42,8 @@ export interface ReadGroupFrame { frame: Frame; /** Cursor position held while the frame is in flight. */ position: GroupPosition; + /** Mark the frame delivered or deliberately skipped by the wire publisher. */ + complete(): void; } /** The next group or datagram sequence shared by dynamic producers of one broadcast track. */ diff --git a/js/net/src/lite/publisher.ts b/js/net/src/lite/publisher.ts index fd0c4ddae37..7338202891b 100644 --- a/js/net/src/lite/publisher.ts +++ b/js/net/src/lite/publisher.ts @@ -927,21 +927,25 @@ export class Publisher { break; } - // Frames below the requested start were excluded, and the receiver - // numbers what it gets from `startFrame`. - if (read.sequence < startFrame) continue; - if (endFrame !== undefined && read.sequence > endFrame) break; - reached = true; - - if (timestamps) { - // Convert each frame to the track's advertised timescale. - const ts = BigInt(Math.round(read.frame.timestamp.as(timescale))); - await hooks.guardGroup(group, stream.u62(zigzag(ts - prevTs)), read.position); - prevTs = ts; - } + try { + // Frames below the requested start were excluded, and the receiver + // numbers what it gets from `startFrame`. + if (read.sequence < startFrame) continue; + if (endFrame !== undefined && read.sequence > endFrame) break; + reached = true; + + if (timestamps) { + // Convert each frame to the track's advertised timescale. + const ts = BigInt(Math.round(read.frame.timestamp.as(timescale))); + await hooks.guardGroup(group, stream.u62(zigzag(ts - prevTs)), read.position); + prevTs = ts; + } - await hooks.guardGroup(group, stream.u53(read.frame.payload.byteLength), read.position); - await hooks.guardGroup(group, stream.write(read.frame.payload), read.position); + await hooks.guardGroup(group, stream.u53(read.frame.payload.byteLength), read.position); + await hooks.guardGroup(group, stream.write(read.frame.payload), read.position); + } finally { + read.complete(); + } } stream.close(); diff --git a/js/net/src/track.test.ts b/js/net/src/track.test.ts index f48240de0e4..c0c97c4a8a9 100644 --- a/js/net/src/track.test.ts +++ b/js/net/src/track.test.ts @@ -453,6 +453,36 @@ test("a guarded write keeps the position of the frame removed from the buffer", producer.writeFrame({ payload: enc.encode("edge"), timestamp: Timestamp.fromMillis(1_000) }); await expect(guarded).rejects.toThrow("latency budget"); + read.complete(); + release(); +}); + +test("clean source closure stays provisional while a frame write can expire", async () => { + const producer = new TrackProducer("test").accept({ maxAge: 100 }); + const track = producer.subscribe({ maxAge: 100 }); + const source = producer.appendGroup(); + source.writeFrame({ payload: enc.encode("old"), timestamp: Timestamp.fromMillis(0) }); + source.close(); + + const group = await track.recvGroup(); + if (!group) throw new Error("missing group"); + const closed = group.closed; + expect(closed.peek()).toBeUndefined(); + + const read = await hooks.readGroupFrame(group); + if (!read) throw new Error("missing frame"); + let release!: () => void; + const operation = new Promise((resolve) => { + release = resolve; + }); + const guarded = hooks.guardGroup(group, operation, read.position); + + const edge = producer.appendGroup(); + edge.writeFrame({ payload: enc.encode("edge"), timestamp: Timestamp.fromMillis(1_000) }); + await expect(guarded).rejects.toThrow("latency budget"); + expect(await closed).toBeInstanceOf(Error); + + read.complete(); release(); });