From d751b63cd2e9ea27b1b6a59028cfa2c438f6efe9 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 16 Nov 2026 15:40:56 -0800 Subject: [PATCH 01/23] chore(quest): claim quest/m2/audio-playout/browser-audio-hole-skip.md Quest-Claim: 8da1f2e4c072eec9 From 77fb537ce83cf908b850b4765e3b4067e4beb2de Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 16 Nov 2026 17:50:46 -0800 Subject: [PATCH 02/23] fix(watch): audio keeps a hole a late burst fills within the stretch Browser audio's container consumer ended a missing group as soon as the shared clock reached the group past it. The ring still plays audio trailing the clock within its stretch bound, so a late burst's hole that fills a moment later was thrown away. The consumer now reads the clock less that bound, and the replay harness gives its consumer the same clock the decoder does. Co-Authored-By: Claude Opus 5.5 --- doc/concept/audio-jitter.md | 9 +++-- js/hang/src/container/consumer.ts | 11 +++-- js/watch/src/audio/decoder.ts | 3 +- js/watch/src/audio/playhead.ts | 22 ++++++++++ js/watch/src/audio/replay.test.ts | 17 ++++++++ js/watch/src/audio/replay.ts | 6 ++- .../audio-playout/browser-audio-hole-skip.md | 40 ------------------- quest/m2/delay-hole-wait.md | 9 ++++- 8 files changed, 66 insertions(+), 51 deletions(-) create mode 100644 js/watch/src/audio/playhead.ts delete mode 100644 quest/m2/audio-playout/browser-audio-hole-skip.md diff --git a/doc/concept/audio-jitter.md b/doc/concept/audio-jitter.md index 21f79ac572a..24c54d623dc 100644 --- a/doc/concept/audio-jitter.md +++ b/doc/concept/audio-jitter.md @@ -49,9 +49,12 @@ group is observed when the stall clears. A missing group, one that has delivered no frame, is waited for only the playout delay plus any lookahead, since past that it would play late: a reordered backlog's holes waited out to the whole budget would delay the frames behind them, which the estimator would measure as -jitter. The browser player waits less still, only until its clock reaches the -group past the hole: a viewer resuming behind a replayed backlog, which arrives -newest first, would otherwise hold the live audio for the backlog's oldest group. A caller that estimates keeps the budget past the target, which is why +jitter. The browser player waits less still, only until the group past the hole +trails its clock by the stretch threshold, past which the ring would skip the +hole's audio anyway: a viewer resuming behind a replayed backlog, which arrives +newest first, would otherwise hold the live audio for the backlog's oldest group, +while a late burst that fills a hole a moment after the group past it lands +still plays it. A caller that estimates keeps the budget past the target, which is why `moq play` waits on a stalled audio group for the delay plus the estimate's 2 s ceiling. The observation is also only as honest as the caller is prompt: `read()` is timed when it resolves, so a player drains it diff --git a/js/hang/src/container/consumer.ts b/js/hang/src/container/consumer.ts index 4734cd33836..d51a8825367 100644 --- a/js/hang/src/container/consumer.ts +++ b/js/hang/src/container/consumer.ts @@ -82,16 +82,19 @@ export interface ConsumerProps { predecessor?: Consumer; /** * The playout clock this reader feeds, such as the player's `Sync` (default: none). A missing - * group whose successor starts at or before the media time it presents now could only arrive - * too late to play, so it is skipped then rather than waited for: a reader resuming behind the - * live edge moves on once the clock passes the hole, not a whole {@link ConsumerProps.wait} later. + * group whose successor starts at or before the oldest media the clock still plays could only + * arrive too late to play, so it is skipped then rather than waited for: a reader resuming behind + * the live edge moves on once the clock passes the hole, not a whole {@link ConsumerProps.wait} later. */ playhead?: Playhead; } /** A playout clock, which a {@link Consumer} reads to tell when a missing group could no longer play. */ export interface Playhead { - /** The media time presenting now, or undefined while nothing presents. */ + /** + * The oldest media time the player still plays, or undefined while nothing presents: the media + * presenting now, less however far a player that catches up late media lets it trail. + */ now(): Duration | undefined; /** Changes whenever {@link Playhead.now} jumps rather than advancing with the wall clock: a re-anchor, a new delay, or a pause. */ readonly anchor: Getter; diff --git a/js/watch/src/audio/decoder.ts b/js/watch/src/audio/decoder.ts index 00bc3ce885f..9d4c44d096e 100644 --- a/js/watch/src/audio/decoder.ts +++ b/js/watch/src/audio/decoder.ts @@ -31,6 +31,7 @@ import { import { Handover } from "./handover"; import { bound, maxDelay, ringHold, target } from "./latency"; import { Order } from "./order"; +import { playable } from "./playhead"; // A blob: URL, or a hosted file when assets() is set; see vite-plugin-worklet. import RenderWorklet from "./render-worklet.ts?worklet"; import type { Source } from "./source"; @@ -925,7 +926,7 @@ export class Decoder { wait: this.sync.out.maxDelay, warmup: Duration.millis(config.warmup ?? 0).min(DELAY_MAX), predecessor: continues ? outgoing.consumer : undefined, - playhead: this.sync, + playhead: playable(this.sync), }); effect.cleanup(() => consumer.close()); this.#phase.set({ ...phase, consumer: { path, codec: config.codec, consumer } }); diff --git a/js/watch/src/audio/playhead.ts b/js/watch/src/audio/playhead.ts new file mode 100644 index 00000000000..578578786df --- /dev/null +++ b/js/watch/src/audio/playhead.ts @@ -0,0 +1,22 @@ +import type * as Container from "@moq/hang/container"; +import { Derived } from "@moq/signals"; +import type { Sync } from "../sync"; +import { bound } from "./latency"; + +/** + * The oldest media the ring still plays, which the audio consumer reads as its clock: the shared + * clock less the ring's {@link bound}. The ring stretches audio trailing the clock within the bound + * back onto it, so a missing group can still play until the group past it trails the clock by more + * than that. A late burst often fills a hole a moment after the group past it lands. + * + * @internal Exported for the replay harness. + */ +export function playable(sync: Sync): Container.Playhead { + const trail = new Derived([sync.out.delay, sync.out.maxDelay, sync.in.stretch], (delay, maxDelay, stretch) => + bound({ delay, maxDelay, stretch }), + ); + return { + now: () => sync.now()?.saturatingSub(trail.peek()), + anchor: new Derived([sync.anchor, trail], (anchor, trail) => ({ anchor, trail })), + }; +} diff --git a/js/watch/src/audio/replay.test.ts b/js/watch/src/audio/replay.test.ts index 0297cdb37da..b40a259bd26 100644 --- a/js/watch/src/audio/replay.test.ts +++ b/js/watch/src/audio/replay.test.ts @@ -197,6 +197,23 @@ describe("replay against the shared clock", () => { const flushed = paced(60, (i) => 30 + (4 - (i % 5)) * 20); const fixed = { rate: RATE, config: CONFIG, delay: Duration.millis(40), duration: observed(60) }; + // A late burst lands out of order: the group before lands a moment after the one past it, which the + // clock already passed. The ring still plays audio trailing the clock within the stretch, so the + // consumer waits for that group rather than skipping a hole the burst fills; with the stretch off, + // the ring would skip it anyway. + it("keeps a hole a late burst fills once the clock passed the group past it", async () => { + // Groups 250 to 259 are held and released together at 5230 ms, 250 a millisecond after the rest. + const held = (i: number) => (i >= 250 && i < 260 ? 5230 - i * 20 + (i === 250 ? 1 : 0) : 30); + const trace = paced(10, held).sort((a, b) => a.at - b.at); + const options = { rate: RATE, config: CONFIG, delay: Duration.millis(100), duration: observed(10) }; + + // The consumer warns on every group it skips. + await lag(trace, options, 0); + expect(warn).not.toHaveBeenCalled(); + await lag(trace, { ...options, stretch: 0 }, 0); + expect(warn).toHaveBeenCalled(); + }); + it("underruns a fixed target short of the spread with the stretch off, rather than trailing the clock", async () => { const { lags, median, underruns, accelerated } = await lag(flushed, { ...fixed, stretch: 0 }, 30_000); expect(underruns).toBeGreaterThanOrEqual(flushed.length / 5); diff --git a/js/watch/src/audio/replay.ts b/js/watch/src/audio/replay.ts index 29a02c9dfcc..fcc98ceac75 100644 --- a/js/watch/src/audio/replay.ts +++ b/js/watch/src/audio/replay.ts @@ -2,8 +2,8 @@ * Replay a recorded arrival trace through the player's consumer and ring on a simulated clock. * * Every frame is written into its group at the instant the trace says it arrived, and the player's - * real `Container.Consumer` decides what to deliver, wait for, and skip, at the hole wait and max delay - * the decoder sets. Delivered frames go into the real ring, which carries on through a gap the way the decoder's + * real `Container.Consumer` decides what to deliver, wait for, and skip, at the hole wait, max delay, and + * clock the decoder gives it. Delivered frames go into the real ring, which carries on through a gap the way the decoder's * does: a gap restarts only the codec. One render quantum is read every quantum's worth of that same * clock, which is what the AudioWorklet does. A real {@link Sync} resolves the delay from the playout target the decoder * registers, measured by that same consumer from the recorded catalog config, and the ring and the @@ -26,6 +26,7 @@ import { type Delay, STRETCH, Sync } from "../sync"; import { Backpressure } from "./buffer"; import { frameDuration } from "./config"; import { maxDelay as audioMaxDelay, bound, ringHold, target } from "./latency"; +import { playable } from "./playhead"; import { AudioRingBuffer } from "./ring-buffer"; /** An AudioWorklet render quantum, in frames. */ @@ -258,6 +259,7 @@ export async function* replay(trace: Arrival[], options: Options): AsyncGenerato format: new Container.Legacy.Format("audio"), delay: new Derived([sync.out.delay, maxDelay], (min, max) => ({ min, max })), wait: sync.out.maxDelay, + playhead: playable(sync), }, ); diff --git a/quest/m2/audio-playout/browser-audio-hole-skip.md b/quest/m2/audio-playout/browser-audio-hole-skip.md deleted file mode 100644 index 075ac73b448..00000000000 --- a/quest/m2/audio-playout/browser-audio-hole-skip.md +++ /dev/null @@ -1,40 +0,0 @@ -# [M] Browser audio keeps a hole a late burst still fills - -## Goal - -`@moq/watch`'s audio no longer skips a missing group that lands a moment -after the group past it: the Chromium `bursty` and `congestion` rows of -`just test audio-quality` grade no worse than before -[moq-dev/moq#8799](https://github.com/moq-dev/moq/pull/8799) gave the audio -consumer the player's clock, while the Firefox `after resume` window that PR -fixed stays audible. - -## Plan - -Native evidence, from the PR that gave the Rust consumer the same clock -(`just test audio-quality --runtimes native --codecs opus --duration 40 ---seed 7`): ending an audio hole once the clock reaches the group past it -took `bursty` from 3 to 155 underruns a minute. A burst's groups land late -together, so the group past a hole is already due when the missing one lands -a moment later in the same burst. Ending it at the clock plus the 200 ms -stretch held `bursty` level but left `congestion` worse than the native -estimate wait (A/V lag p95 808 to 946 ms against 288 to 631 ms over three -runs each). `moq play` gives the clock to video only for that reason. - -`js/watch/src/audio/decoder.ts` passes `playhead: this.sync` with a -`wait` of `sync.out.maxDelay`, so the browser has the rule that measured -worst natively. First measure: the Chromium `bursty` and `congestion` rows -with and without that `playhead`, a few runs each, since `congestion` is -noisy. - -If the browser regressed, recommended: audio waits a hole out for its -playout estimate from the arrival of the group past it, as native audio does -(`rs/moq-audio/src/decode/consumer.rs`, `set_wait(self.delay())`), instead of -the playhead. That still ends the resume hole within one playout delay. -Confirm with #8799's repro, `taskset -c 4-5 nix develop --command just test -media --media-engines firefox --media-cases rename,pause`. Video keeps the -playhead. - -## Related - -- [A hole is waited for by the subscription's delay](/quest/m2/delay-hole-wait.md) - removes the separate wait this would keep for browser audio, so the two settle the same rule diff --git a/quest/m2/delay-hole-wait.md b/quest/m2/delay-hole-wait.md index b93b764d5b9..42bc551e62d 100644 --- a/quest/m2/delay-hole-wait.md +++ b/quest/m2/delay-hole-wait.md @@ -51,6 +51,14 @@ Facts found by the audit: lag p95 of 808 to 946 ms against 288 to 631 ms. The estimate wait gives every hole the estimate from the arrival of the group past it, which a late burst needs. +- Browser audio ends a hole once the group past it trails the clock by the + ring's stretch bound, the furthest the ring plays late audio + ([moq-dev/moq#8982](https://github.com/moq-dev/moq/pull/8982)): the + variant that lost natively on `congestion`. In the browser it graded no + worse than the bare clock or the wait alone on the Chromium `bursty` and + `congestion` rows, and the replays show the bare clock skipping holes a + burst fills 1 ms later. The estimate wait alone (no clock) left the Firefox + resume window silent longer (9 to 41 samples against 6 to 12). For the PR, settle the home of native audio's live estimate first. Two ways: @@ -79,4 +87,3 @@ loses `ConsumerProps.wait`. Wire: none. ## Related - [Native audio playout is a library](/quest/m3/audio-playout-library.md) - moves the placement this wait feeds into moq-audio -- [Browser audio keeps a hole a late burst still fills](/quest/m2/audio-playout/browser-audio-hole-skip.md) - measures whether the browser's audio playhead over-skips, which decides the rule this quest applies to both languages From 263119cc519504349eed10183aa45a8785f35066 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 16 Nov 2026 19:01:24 -0800 Subject: [PATCH 03/23] fix(watch): count the output latency the ring renders ahead by in audio's hole clock Review: the ring renders the output latency ahead of the shared clock, so the oldest media it still plays is the clock plus that, less the bound. Co-Authored-By: Claude Opus 5.5 --- js/watch/src/audio/decoder.ts | 8 +++++- js/watch/src/audio/playhead.test.ts | 42 +++++++++++++++++++++++++++++ js/watch/src/audio/playhead.ts | 26 +++++++++++------- 3 files changed, 66 insertions(+), 10 deletions(-) create mode 100644 js/watch/src/audio/playhead.test.ts diff --git a/js/watch/src/audio/decoder.ts b/js/watch/src/audio/decoder.ts index 9d4c44d096e..12204375632 100644 --- a/js/watch/src/audio/decoder.ts +++ b/js/watch/src/audio/decoder.ts @@ -192,6 +192,8 @@ export class Decoder { // Audio ring bridging the main thread and the worklet. #ring = new Signal(undefined); + // How far ahead of the clock the ring renders, so what it renders sounds when due. + #output: Getter; // The context, worklet, and ring are keyed on this alone. It outlives a rendition's absence, so // the queued tail plays out and a return with the same shape reuses the graph. @@ -285,6 +287,10 @@ export class Decoder { complete, }; }); + this.#output = this.#signals.computed((effect) => { + const ring = effect.get(this.#ring); + return ring ? effect.get(ring.output) : undefined; + }); this.#track = this.sync.track({ target: playout, startup }); this.#signals.cleanup(() => this.#track.close()); this.#identity = this.#signals.computed((effect) => { @@ -926,7 +932,7 @@ export class Decoder { wait: this.sync.out.maxDelay, warmup: Duration.millis(config.warmup ?? 0).min(DELAY_MAX), predecessor: continues ? outgoing.consumer : undefined, - playhead: playable(this.sync), + playhead: playable(this.sync, this.#output), }); effect.cleanup(() => consumer.close()); this.#phase.set({ ...phase, consumer: { path, codec: config.codec, consumer } }); diff --git a/js/watch/src/audio/playhead.test.ts b/js/watch/src/audio/playhead.test.ts new file mode 100644 index 00000000000..c55e96ac400 --- /dev/null +++ b/js/watch/src/audio/playhead.test.ts @@ -0,0 +1,42 @@ +import { expect, it } from "bun:test"; +import { Duration } from "@moq/clock"; +import { Manual } from "@moq/clock/test"; +import { Signal } from "@moq/signals"; +import { Sync } from "../sync"; +import { playable } from "./playhead"; + +it("reads the clock the ring renders at, less the stretch it plays late audio within", async () => { + const clock = new Manual(); + const installed = clock.install(); + const sync = new Sync({ delay: Duration.millis(300), stretch: Duration.millis(200) }); + const span = new Signal<{ start: Duration; end: Duration } | null>(null); + const audio = sync.track({ target: new Signal(Duration.millis(300)), startup: span }); + const output = new Signal(Duration.millis(40)); + const playhead = playable(sync, output); + try { + await clock.advance(Duration.ZERO); + audio.received(Duration.ZERO); + span.set({ start: Duration.ZERO, end: Duration.millis(300) }); + await clock.advance(Duration.millis(1000)); + const now = sync.now(); + if (now === undefined) throw new Error("the clock never started"); + expect(playhead.now()).toEqual(now.add(Duration.millis(40)).saturatingSub(Duration.millis(200))); + + // The trail moving is a jump, which wakes a consumer waiting on a hole. + let jumped = false; + const dispose = playhead.anchor.subscribe(() => { + jumped = true; + }); + await clock.advance(Duration.ZERO); + jumped = false; + output.set(Duration.millis(60)); + await clock.advance(Duration.ZERO); + expect(jumped).toBe(true); + expect(playhead.now()).toEqual(now.add(Duration.millis(60)).saturatingSub(Duration.millis(200))); + dispose(); + } finally { + audio.close(); + sync.close(); + installed.close(); + } +}); diff --git a/js/watch/src/audio/playhead.ts b/js/watch/src/audio/playhead.ts index 578578786df..9d55398ef71 100644 --- a/js/watch/src/audio/playhead.ts +++ b/js/watch/src/audio/playhead.ts @@ -1,22 +1,30 @@ +import { Duration } from "@moq/clock"; import type * as Container from "@moq/hang/container"; -import { Derived } from "@moq/signals"; +import { Derived, type Getter, Signal } from "@moq/signals"; import type { Sync } from "../sync"; import { bound } from "./latency"; /** - * The oldest media the ring still plays, which the audio consumer reads as its clock: the shared - * clock less the ring's {@link bound}. The ring stretches audio trailing the clock within the bound - * back onto it, so a missing group can still play until the group past it trails the clock by more - * than that. A late burst often fills a hole a moment after the group past it lands. + * The oldest media the ring still plays, which the audio consumer reads as its clock. The ring renders + * `output` (none until known) ahead of the shared clock, so the sample it renders now sounds when the clock reaches it, + * and stretches audio trailing that within its {@link bound} back onto it. So a missing group can + * still play until the group past it trails the ring by more than the bound, as when a late burst + * fills the hole a moment after the group past it lands. * * @internal Exported for the replay harness. */ -export function playable(sync: Sync): Container.Playhead { - const trail = new Derived([sync.out.delay, sync.out.maxDelay, sync.in.stretch], (delay, maxDelay, stretch) => - bound({ delay, maxDelay, stretch }), +export function playable(sync: Sync, output: Getter = new Signal(undefined)): Container.Playhead { + const trail = new Derived( + [sync.out.delay, sync.out.maxDelay, sync.in.stretch, output], + (delay, maxDelay, stretch, output) => + bound({ delay, maxDelay, stretch }).asMicros() - (output?.asMicros() ?? 0), ); return { - now: () => sync.now()?.saturatingSub(trail.peek()), + now: () => { + const now = sync.now(); + if (now === undefined) return undefined; + return Duration.micros(Math.max(0, now.asMicros() - trail.peek())); + }, anchor: new Derived([sync.anchor, trail], (anchor, trail) => ({ anchor, trail })), }; } From 69a996837ba88ac8753cd2f9271e5dd637d3d41f Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 16 Nov 2026 19:07:59 -0800 Subject: [PATCH 04/23] fix(watch): apply the output latency to the signed clock position Review: before media zero's turn the clock reads zero while the ring already renders, so the output term applies before the clamp. Co-Authored-By: Claude Opus 5.5 --- js/watch/src/audio/playhead.test.ts | 23 +++++++++++++++++++++++ js/watch/src/audio/playhead.ts | 18 ++++++++++-------- 2 files changed, 33 insertions(+), 8 deletions(-) diff --git a/js/watch/src/audio/playhead.test.ts b/js/watch/src/audio/playhead.test.ts index c55e96ac400..c5e3edccbe3 100644 --- a/js/watch/src/audio/playhead.test.ts +++ b/js/watch/src/audio/playhead.test.ts @@ -40,3 +40,26 @@ it("reads the clock the ring renders at, less the stretch it plays late audio wi installed.close(); } }); + +it("applies the output latency before media zero's turn, when the ring already renders it", async () => { + const clock = new Manual(); + const installed = clock.install(); + const sync = new Sync({ delay: Duration.millis(300), lookahead: Duration.millis(1000), stretch: Duration.ZERO }); + const span = new Signal<{ start: Duration; end: Duration; lead?: Duration } | null>(null); + const audio = sync.track({ target: new Signal(Duration.millis(300)), startup: span }); + const playhead = playable(sync, new Signal(Duration.millis(120))); + try { + await clock.advance(Duration.ZERO); + audio.received(Duration.ZERO); + span.set({ start: Duration.ZERO, end: Duration.millis(180), lead: Duration.millis(120) }); + await clock.advance(Duration.millis(50)); + // 70 ms short of media zero's turn, which the clock reads as zero, the ring renders 50 ms. + expect(sync.now()).toEqual(Duration.ZERO); + expect(sync.position()).toBe(-70); + expect(playhead.now()).toEqual(Duration.millis(50)); + } finally { + audio.close(); + sync.close(); + installed.close(); + } +}); diff --git a/js/watch/src/audio/playhead.ts b/js/watch/src/audio/playhead.ts index 9d55398ef71..745bd6bd2e3 100644 --- a/js/watch/src/audio/playhead.ts +++ b/js/watch/src/audio/playhead.ts @@ -6,24 +6,26 @@ import { bound } from "./latency"; /** * The oldest media the ring still plays, which the audio consumer reads as its clock. The ring renders - * `output` (none until known) ahead of the shared clock, so the sample it renders now sounds when the clock reaches it, - * and stretches audio trailing that within its {@link bound} back onto it. So a missing group can - * still play until the group past it trails the ring by more than the bound, as when a late burst - * fills the hole a moment after the group past it lands. + * `output` (none until known) ahead of the shared clock, so what it renders now sounds when the clock + * reaches it, and stretches audio trailing that within its {@link bound} back onto it. So a missing + * group can still play until the group past it trails the ring by more than the bound, as when a late + * burst fills the hole a moment after the group past it lands. * * @internal Exported for the replay harness. */ export function playable(sync: Sync, output: Getter = new Signal(undefined)): Container.Playhead { + // How far the oldest playable media trails the clock, in ms; negative when the output leads by more. const trail = new Derived( [sync.out.delay, sync.out.maxDelay, sync.in.stretch, output], (delay, maxDelay, stretch, output) => - bound({ delay, maxDelay, stretch }).asMicros() - (output?.asMicros() ?? 0), + bound({ delay, maxDelay, stretch }).asMillis() - (output?.asMillis() ?? 0), ); return { now: () => { - const now = sync.now(); - if (now === undefined) return undefined; - return Duration.micros(Math.max(0, now.asMicros() - trail.peek())); + // The signed position, since before media zero's turn the ring may already render it. + const position = sync.position(); + if (position === undefined) return undefined; + return Duration.millis(Math.max(0, position - trail.peek())); }, anchor: new Derived([sync.anchor, trail], (anchor, trail) => ({ anchor, trail })), }; From 9a91d6bfa596015f3ae4af46f5fae09e384290a0 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 17 Nov 2026 20:00:46 -0800 Subject: [PATCH 05/23] chore(quest): claim quest/m2/audio-playout/browser-audio-hole-skip.md Quest-Claim: cff160f3d6cbe822 From 02eae7db476c739dd0026db2bebf1b5d17c454cc Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 17 Nov 2026 20:25:53 -0800 Subject: [PATCH 06/23] feat(net)!: an ordered track reports the groups it gives up on, as Rust's does Co-Authored-By: Claude Opus 5.5 --- js/json/src/snapshot/consumer.ts | 15 +- js/json/src/snapshot/snapshot.test.ts | 20 +- js/json/src/stream/codec.test.ts | 2 +- js/json/src/stream/stream.test.ts | 4 +- js/json/src/window/consumer.ts | 7 +- js/json/src/window/window.test.ts | 4 +- js/net/bench/drift.ts | 4 +- js/net/bench/frames.ts | 2 +- js/net/src/broadcast.test.ts | 7 +- js/net/src/connection/reload.test.ts | 13 +- js/net/src/consume.test.ts | 3 +- js/net/src/fill.test.ts | 51 ++--- js/net/src/ietf/join.test.ts | 39 ++-- js/net/src/ietf/range.test.ts | 33 ++-- js/net/src/ietf/subscriber.test.ts | 29 +-- js/net/src/integration.test.ts | 27 +-- js/net/src/lite/connection.test.ts | 27 +-- js/net/src/lite/copy_fill.test.ts | 9 +- js/net/src/lite/subscriber.test.ts | 5 +- js/net/src/ordered.test-util.ts | 20 ++ js/net/src/ordered.test.ts | 184 ++++++++++++++++++ js/net/src/resume.test.ts | 27 +-- js/net/src/retention.test.ts | 5 +- js/net/src/track.test.ts | 101 +++++----- js/net/src/track.ts | 258 +++++++++++++++++++++++--- js/net/src/untimed.test.ts | 7 +- js/publish/bench/audio-page.ts | 2 +- js/publish/src/announce.test.ts | 2 +- js/publish/src/audio/encoder.test.ts | 12 +- js/publish/src/broadcast.test.ts | 6 +- js/publish/src/catalog.test.ts | 6 +- js/publish/src/video/encoder.test.ts | 2 +- 32 files changed, 684 insertions(+), 249 deletions(-) create mode 100644 js/net/src/ordered.test-util.ts create mode 100644 js/net/src/ordered.test.ts diff --git a/js/json/src/snapshot/consumer.ts b/js/json/src/snapshot/consumer.ts index 52bc5054a9b..6ea2af08922 100644 --- a/js/json/src/snapshot/consumer.ts +++ b/js/json/src/snapshot/consumer.ts @@ -99,21 +99,26 @@ export class Consumer { // the sequence space). // Mirrors the Rust consumer. A newer group restarts from a full snapshot, so switching mid-group loses // nothing but stale state. - for (let group = this.#track.tryNextGroup(); group; group = this.#track.tryNextGroup()) { + for (let item = this.#track.tryNextGroup(); item; item = this.#track.tryNextGroup()) { + // A gap needs nothing: the next group restarts from its own snapshot. + if (item.kind === "gap") continue; this.#group?.close(); - this.#group = group; + this.#group = item.group; this.#framesRead = 0; } } if (!this.#group) { // Advance to the next group with a higher sequence number (skipping late arrivals). - const next = await this.#track.nextGroup(); + const item = await this.#track.nextGroup(); if (this.#closed) { - next?.close(); + item?.group?.close(); return undefined; } - if (!next) return undefined; + if (!item) return undefined; + // Each group starts from a full snapshot, so a gap needs nothing. + if (item.kind === "gap") continue; + const next = item.group; this.#group = next; // The next frame is the new group's snapshot, which also restarts the decoder's window. this.#framesRead = 0; diff --git a/js/json/src/snapshot/snapshot.test.ts b/js/json/src/snapshot/snapshot.test.ts index 6080e6c9bb6..9f0fa3c48fd 100644 --- a/js/json/src/snapshot/snapshot.test.ts +++ b/js/json/src/snapshot/snapshot.test.ts @@ -40,7 +40,7 @@ function reader(track: Track.Producer | Consumer): Consumer { async function structure(track: Track.Ordered): Promise { const counts: number[] = []; for (;;) { - const group = await track.nextGroup(); + const group = (await track.nextGroup())?.group; if (!group) break; let frames = 0; @@ -476,7 +476,7 @@ test("a refresh reuses the newest timestamp", async () => { const ordered = track.subscribe({ delay: { max: REPLAY_LATENCY } }).ordered(); const timestamps: (number | undefined)[] = []; - for (let group = await ordered.nextGroup(); group; group = await ordered.nextGroup()) { + for (let group = (await ordered.nextGroup())?.group; group; group = (await ordered.nextGroup())?.group) { const frame = await group.readFrame(); timestamps.push(frame?.timestamp?.asMillis()); while ((await group.readFrame()) !== undefined) {} @@ -506,7 +506,7 @@ test("a refresh after older updates waits for a later one", async () => { const ordered = track.subscribe({ delay: { max: REPLAY_LATENCY } }).ordered(); const restated: [number | undefined, unknown][] = []; - for (let group = await ordered.nextGroup(); group; group = await ordered.nextGroup()) { + for (let group = (await ordered.nextGroup())?.group; group; group = (await ordered.nextGroup())?.group) { const frame = await group.readFrame(); restated.push([frame?.timestamp?.asMillis(), frame && JSON.parse(new TextDecoder().decode(frame.payload))]); while ((await group.readFrame()) !== undefined) {} @@ -537,7 +537,7 @@ test("a scale-less refresh waits for an update past the open group's key", async const ordered = track.subscribe({ delay: { max: REPLAY_LATENCY } }).ordered(); const restated: [bigint, unknown][] = []; - for (let group = await ordered.nextGroup(); group; group = await ordered.nextGroup()) { + for (let group = (await ordered.nextGroup())?.group; group; group = (await ordered.nextGroup())?.group) { const frame = await group.readFrame(); restated.push([group.start, frame && JSON.parse(new TextDecoder().decode(frame.payload))]); while ((await group.readFrame()) !== undefined) {} @@ -679,9 +679,9 @@ test("a delta that would overflow the snapshot rolls a new one instead", async ( // Two groups, a self-contained snapshot each, rather than one whose frame 0 was evicted. const subscriber = track.subscribe({ delay: { max: REPLAY_LATENCY } }).ordered(); - expect((await subscriber.nextGroup())?.start).toBe(0n); - expect((await subscriber.nextGroup())?.start).toBe(1n); - expect(await subscriber.nextGroup()).toBeUndefined(); + expect(((await subscriber.nextGroup())?.group)?.start).toBe(0n); + expect(((await subscriber.nextGroup())?.group)?.start).toBe(1n); + expect((await subscriber.nextGroup())?.group).toBeUndefined(); // The newest value is readable with no earlier frame to apply it to. expect(await drain(track)).toEqual([{ v: "y".repeat(size) }]); @@ -744,7 +744,7 @@ test("a scale-less snapshot opens its group at its key, and a delta carries that }, Time.Timestamp.unscaled(9n)); producer.finish(); - const group = await track.subscribe().ordered().nextGroup(); + const group = (await track.subscribe().ordered().nextGroup())?.group; expect(group?.start).toBe(5n); expect((await group?.readFrame())?.timestamp).toEqual(Time.Timestamp.unscaled(5n)); expect((await group?.readFrame())?.timestamp).toEqual(Time.Timestamp.unscaled(5n)); @@ -762,7 +762,7 @@ test("a scale-less snapshot at a key not past the newest group is refused", asyn const ordered = track.subscribe({ delay: { max: REPLAY_LATENCY } }).ordered(); const sequences: bigint[] = []; - for (let group = await ordered.nextGroup(); group; group = await ordered.nextGroup()) sequences.push(group.start); + for (let group = (await ordered.nextGroup())?.group; group; group = (await ordered.nextGroup())?.group) sequences.push(group.start); expect(sequences).toEqual([5n, 8n]); expect(await drain(track)).toEqual([{ n: 1 }]); }); @@ -782,7 +782,7 @@ test("a capture timestamp is written on snapshots and deltas alike", async () => producer.update({ a: 2, b: "x".repeat(64) }, Time.Timestamp.fromMillis(2_000)); producer.finish(); - const group = await track.subscribe().ordered().nextGroup(); + const group = (await track.subscribe().ordered().nextGroup())?.group; expect((await group?.readFrame())?.timestamp?.as(Time.Timescale.MILLI)).toBe(1_000); expect((await group?.readFrame())?.timestamp?.as(Time.Timescale.MILLI)).toBe(2_000); }); diff --git a/js/json/src/stream/codec.test.ts b/js/json/src/stream/codec.test.ts index e1ab5b4bdc5..1fdc71a0081 100644 --- a/js/json/src/stream/codec.test.ts +++ b/js/json/src/stream/codec.test.ts @@ -78,7 +78,7 @@ test("a failed write on the very first record still ends the track", async () => // The consumer is handed the group that was already published, and reading it surfaces the // abort. Without ending the track that group stays open and empty, so this read hangs instead. - const group = await subscriber.nextGroup(); + const group = (await subscriber.nextGroup())?.group; expect(group).toBeDefined(); await expect(group?.readFrame()).rejects.toThrow(failure); }); diff --git a/js/json/src/stream/stream.test.ts b/js/json/src/stream/stream.test.ts index a7976113ca9..955a79d5edd 100644 --- a/js/json/src/stream/stream.test.ts +++ b/js/json/src/stream/stream.test.ts @@ -61,9 +61,9 @@ test("the whole log rides one group, never rolled", async () => { // A single group holds everything, and the consumer reads it all in order. const subscriber = track.subscribe().ordered(); - const group0 = await subscriber.nextGroup(); + const group0 = (await subscriber.nextGroup())?.group; expect(group0?.start).toBe(0n); - const group1 = await subscriber.nextGroup(); + const group1 = (await subscriber.nextGroup())?.group; expect(group1).toBeUndefined(); }); diff --git a/js/json/src/window/consumer.ts b/js/json/src/window/consumer.ts index 9f5232a91ed..7285de51280 100644 --- a/js/json/src/window/consumer.ts +++ b/js/json/src/window/consumer.ts @@ -67,8 +67,11 @@ export class Consumer { if (event && this.#at) return { value: event, at: this.#at }; if (!this.#group) { - this.#group = await this.#track.nextGroup(); - if (!this.#group) return undefined; + const item = await this.#track.nextGroup(); + if (!item) return undefined; + // The next group starts with a checkpoint that accounts for what the gap missed. + if (item.kind === "gap") continue; + this.#group = item.group; this.#codec = this.#decoder.group(); } diff --git a/js/json/src/window/window.test.ts b/js/json/src/window/window.test.ts index 0d7e9f480ea..f7364d0f25e 100644 --- a/js/json/src/window/window.test.ts +++ b/js/json/src/window/window.test.ts @@ -217,7 +217,7 @@ test("compressed round-trip across rolls", async () => { async function groups(track: Track.Producer): Promise<[number, number | undefined][]> { const ordered = track.subscribe({ delay: { max: Duration.millis(30_000) } }).ordered(); const out: [number, number | undefined][] = []; - for (let group = await ordered.nextGroup(); group; group = await ordered.nextGroup()) { + for (let group = (await ordered.nextGroup())?.group; group; group = (await ordered.nextGroup())?.group) { const first = await group.readFrame(); let frames = first ? 1 : 0; while ((await group.readFrame()) !== undefined) frames++; @@ -571,7 +571,7 @@ test("edits keep their timestamps, and a scale-less edit its group's key", async producer.finish(); // A scale-less header opens its group at its key, and an op carries that key. - const group = await track.subscribe().ordered().nextGroup(); + const group = (await track.subscribe().ordered().nextGroup())?.group; for (let i = 0; i < 2; i++) expect((await group?.readFrame())?.timestamp).toEqual(at); } }); diff --git a/js/net/bench/drift.ts b/js/net/bench/drift.ts index 639c21c5e89..b760dcc7719 100644 --- a/js/net/bench/drift.ts +++ b/js/net/bench/drift.ts @@ -75,13 +75,13 @@ export async function run(): Promise { const ordered = subscribers.map((sub) => sub.ordered()); for (let sequence = 0; sequence < retained; sequence++) for (const reader of ordered) { - const group = await reader.nextGroup(); + const group = (await reader.nextGroup())?.group; if (group?.start !== BigInt(sequence)) throw new Error("history missing"); await group.readFrame(); } sources.push(hooks.appendNext(track)); for (const reader of ordered) { - const group = await reader.nextGroup(); + const group = (await reader.nextGroup())?.group; if (!group) throw new Error("live group missing"); consumers.push(group); } diff --git a/js/net/bench/frames.ts b/js/net/bench/frames.ts index 9f6a6d0407a..97773915c13 100644 --- a/js/net/bench/frames.ts +++ b/js/net/bench/frames.ts @@ -108,7 +108,7 @@ const ietf: Protocol = { flags: IETF_FLAGS, }); const done = subscriber.handleGroup(header, new Reader(stream, undefined, IETF_VERSION)); - return { group: ordered.nextGroup(), done }; + return { group: ordered.nextGroup().then((item) => item?.group), done }; }; return { open, close: () => track.close() }; }, diff --git a/js/net/src/broadcast.test.ts b/js/net/src/broadcast.test.ts index ba986238ebe..fe1b88f607d 100644 --- a/js/net/src/broadcast.test.ts +++ b/js/net/src/broadcast.test.ts @@ -10,6 +10,7 @@ import { Timescale, Timestamp } from "./time.ts"; import type { Request as TrackRequest } from "./track.ts"; import { unwanted } from "./util/demand.ts"; import { wireOf } from "./wire.ts"; +import { nextGroup } from "./ordered.test-util.ts"; // The public API mints consumers internally (Producer.consume, the wire layers); tests act // as a wire layer by subclassing, the same way lite's ConsumeBroadcast does. @@ -430,7 +431,7 @@ test("subscribe serves a statically inserted track without a request", async () // The track already exists, so subscribe resolves immediately (no requested()). const sub1 = broadcast.track("track1").subscribe().ordered(); - expect((await sub1.nextGroup())?.start).toBe(0n); + expect((await nextGroup(sub1))?.start).toBe(0n); // No on-demand request was emitted for it. expect(await pendingRequest(broadcast)).toBeUndefined(); @@ -440,7 +441,7 @@ test("subscribe serves a statically inserted track without a request", async () const sub2 = broadcast.track("track2").subscribe().ordered(); hooks.appendNext(track2).finish(); - expect((await sub2.nextGroup())?.start).toBe(0n); + expect((await nextGroup(sub2))?.start).toBe(0n); }); test("two subscribers to one inserted track each get a full copy", async () => { @@ -573,7 +574,7 @@ test("a finished track is still served from its cache", async () => { .subscribe({ delay: { max: Duration.millis(5000) } }) .ordered(); expect(await late.readString()).toBe("last"); - expect(await late.nextGroup()).toBeUndefined(); + expect(await nextGroup(late)).toBeUndefined(); expect(await broadcast.track("track1").info()).toBeDefined(); expect(await pendingRequest(broadcast)).toBeUndefined(); }); diff --git a/js/net/src/connection/reload.test.ts b/js/net/src/connection/reload.test.ts index 748d12c37e7..afea6856654 100644 --- a/js/net/src/connection/reload.test.ts +++ b/js/net/src/connection/reload.test.ts @@ -24,6 +24,7 @@ import { type AcceptProps, accept as acceptSession } from "./index.ts"; import { Connection, resetShared } from "./pool.ts"; import { type Backoff, pumpAnnounced, Redirects, Reload, type ReloadProps } from "./reload.ts"; import type { Session } from "./session.ts"; +import { nextGroup } from "../ordered.test-util.ts"; function accept(transport: WebTransport, url: URL, props: Omit = {}) { return acceptSession({ transport, url, ...props }); @@ -825,7 +826,7 @@ for (const [name, teardown] of Object.entries(teardowns)) { try { hooks.appendNext(producer).writeFrame(textFrame("first", Timestamp.fromMillis(0))); - expect(await (await track.nextGroup())?.readString()).toBe("first"); + expect(await (await nextGroup(track))?.readString()).toBe("first"); if (teardown.goaway) { const stream = await Stream.open(first.quic, { version: Lite.Version.DRAFT_06 }); @@ -845,7 +846,7 @@ for (const [name, teardown] of Object.entries(teardowns)) { if (teardown.hide) win.dispatchEvent(new Event("pagehide")); if (teardown.drains) { - expect(await (await track.nextGroup())?.readString()).toBe("last"); + expect(await (await nextGroup(track))?.readString()).toBe("last"); await fin.hold?.reached; // Just short of the close deadline, the session still waits for the FIN. await clock.advance(Duration.millis(999)); @@ -917,7 +918,7 @@ for (const [name, drainEnd] of Object.entries(drainEnds)) { try { // The group stays open, so the old session's drain waits out its deadline. hooks.appendNext(producer).writeFrame(textFrame("live")); - expect(await (await track.nextGroup())?.readString()).toBe("live"); + expect(await (await nextGroup(track))?.readString()).toBe("live"); reload.url.set(new URL("https://example.com/b")); await waitUntil(() => dials.length === 2 && reload.status.peek() === "connected"); @@ -979,7 +980,7 @@ test("a retired GOAWAY predecessor still closes by its handover cap", async () = try { // The group stays open, so a graceful close of the predecessor would wait out its deadline. hooks.appendNext(producer).writeFrame(textFrame("live")); - expect(await (await track.nextGroup())?.readString()).toBe("live"); + expect(await (await nextGroup(track))?.readString()).toBe("live"); const stream = await Stream.open(first.quic, { version: Lite.Version.DRAFT_06 }); await stream.writer.u53(Lite.StreamId.Goaway); @@ -1052,7 +1053,7 @@ test("closing the loop keeps the tokens until the session drains", async () => { const track = remote.track("video").subscribe().ordered(); try { hooks.appendNext(producer).writeFrame(textFrame("first", Timestamp.fromMillis(0))); - expect(await (await track.nextGroup())?.readString()).toBe("first"); + expect(await (await nextGroup(track))?.readString()).toBe("first"); fin.hold?.enable(); const last = hooks.appendNext(producer); @@ -1062,7 +1063,7 @@ test("closing the loop keeps the tokens until the session drains", async () => { producer.close(); reload.close(); - expect(await (await track.nextGroup())?.readString()).toBe("last"); + expect(await (await nextGroup(track))?.readString()).toBe("last"); await fin.hold?.reached; await clock.advance(Duration.millis(999)); expect(fin.closed).toBe(false); diff --git a/js/net/src/consume.test.ts b/js/net/src/consume.test.ts index c1cf0a7a526..0e54afd4627 100644 --- a/js/net/src/consume.test.ts +++ b/js/net/src/consume.test.ts @@ -6,6 +6,7 @@ import { WireRoute } from "./hop.ts"; import * as Instance from "./instance.ts"; import { hooks } from "./internal.ts"; import * as Path from "./path.ts"; +import { nextGroup } from "./ordered.test-util.ts"; test("cache identity follows the serving announcement, preserving held tracks", async () => { const cache = new BroadcastCache(); @@ -33,7 +34,7 @@ test("cache identity follows the serving announcement, preserving held tracks", expect(shared?.closed).toBe(fresh.closed); // Cache replacement never transfers or closes the track an old handle is reading. hooks.appendNext(track).finish(); - expect((await ordered.nextGroup())?.start).toBe(0n); + expect((await nextGroup(ordered))?.start).toBe(0n); cache.withdraw(job, specific); expect(cache.get(job, cache.instance(job))).toBeUndefined(); for (const consumer of [held, same, fresh, shared]) consumer?.close(); diff --git a/js/net/src/fill.test.ts b/js/net/src/fill.test.ts index ae181a96bf5..8146664ff47 100644 --- a/js/net/src/fill.test.ts +++ b/js/net/src/fill.test.ts @@ -15,6 +15,7 @@ import * as Path from "./path.ts"; import { Timescale, Timestamp } from "./time.ts"; import type { FillGroups, Producer, Requests, Subscription } from "./track.ts"; import { wireOf } from "./wire.ts"; +import { nextGroup } from "./ordered.test-util.ts"; const enc = new TextEncoder(); const dec = new TextDecoder(); @@ -252,7 +253,7 @@ async function failedAnswerHoldsTheEnd(error: Error) { const reader = track.subscribe({ delay: { max: null } }); const ordered = reader.ordered(); for (const key of [0n, 2n]) hooks.receiveGroup(track, { start: key, offset: 0 }).finish(); - expect((await ordered.nextGroup())?.start).toBe(0n); + expect((await nextGroup(ordered))?.start).toBe(0n); const requests = track.requests(); const fetching = wireOf(broadcast).fetchGroup("video", 1n); const fill = await requestedGroups(requests); @@ -267,17 +268,17 @@ async function failedAnswerHoldsTheEnd(error: Error) { // A subscriber arriving after the failure is not handed the failed answer either. const late = track.subscribe({ delay: { max: null } }); const lateOrdered = late.ordered(); - expect((await lateOrdered.nextGroup())?.start).toBe(0n); - const lateNext = lateOrdered.nextGroup(); + expect((await nextGroup(lateOrdered))?.start).toBe(0n); + const lateNext = nextGroup(lateOrdered); expect(await Promise.race([lateNext.then(() => "moved"), yieldNow().then(() => "waiting")])).toBe("waiting"); // The failed answer is no verdict on group 1, so an ordered reader still waits for it rather // than moving on to group 2, and gets it once the feed delivers it. - const next = ordered.nextGroup(); + const next = nextGroup(ordered); expect(await Promise.race([next.then(() => "moved"), yieldNow().then(() => "waiting")])).toBe("waiting"); hooks.receiveGroup(track, { start: 1n, offset: 0 }).finish(); expect((await next)?.start).toBe(1n); - expect((await ordered.nextGroup())?.start).toBe(2n); + expect((await nextGroup(ordered))?.start).toBe(2n); expect((await lateNext)?.start).toBe(1n); reader.close(); @@ -376,7 +377,7 @@ test("fill: an answer withheld after a probe judged it is asked again", async () delay: { max: null }, }); const ordered = reader.ordered(); - const first = ordered.nextGroup(); + const first = nextGroup(ordered); const fill = await requestedGroups(requests); expect(fill && [fill.start, fill.end]).toEqual([0n, 4n]); if (fill?.kind !== "groups") throw new Error("no fill of groups"); @@ -385,13 +386,13 @@ test("fill: an answer withheld after a probe judged it is asked again", async () answer.writeFrame({ payload: enc.encode("fill 2"), timestamp: Timestamp.unscaled(answer.start) }); expect((await first)?.start).toBe(0n); // Waiting on group 1, the bounded window probes everything it names, group 2 held among it. - const second = ordered.nextGroup(); + const second = nextGroup(ordered); await yieldNow(); answer.abort(new Error("archive failed")); fill.accept(1n).finish(); expect((await second)?.start).toBe(1n); - const third = ordered.nextGroup(); + const third = nextGroup(ordered); const again = groupsOf(await Promise.race([requests.requestedFill(), yieldNow().then(() => undefined)])); expect(again && [again.start, again.end]).toEqual([2n, 3n]); if (again) serve(again, new Map([[2n, ["again"]]])); @@ -420,7 +421,7 @@ test("fill: a gap below a group that fails after a probe is asked", async () => await reader.start(); group.abort(new StreamError(StreamCode.Cancel)); await yieldNow(); - const next = ordered.nextGroup(); + const next = nextGroup(ordered); const fill = groupsOf(await Promise.race([requests.requestedFill(), yieldNow().then(() => undefined)])); expect(fill && [fill.start, fill.end]).toEqual([0n, 2n]); @@ -495,7 +496,7 @@ test("fill: a reader reaching back for history gets the misses filled in order", const ordered = reader.ordered(); const seen: [bigint, string[]][] = []; for (let i = 0; i < 4; i++) { - const group = await ordered.nextGroup(); + const group = await nextGroup(ordered); if (!group) break; seen.push([group.start, await frames(group)]); } @@ -709,7 +710,7 @@ test("fill: an ordered reader stops waiting on an unanswered fill once its budge delay: { max: Duration.millis(1000) }, order: "ascending", }); - const next = reader.ordered().nextGroup(); + const next = nextGroup(reader.ordered()); // The handler takes the fill for the missing groups and never answers. const fill = await requestedGroups(requests); expect([fill?.start, fill?.end]).toEqual([0n, 5n]); @@ -769,7 +770,7 @@ test("fill: a handler hears that a reader stopped wanting what it handed out pas delay: { max: Duration.millis(1000) }, order: "ascending", }); - const next = reader.ordered().nextGroup(); + const next = nextGroup(reader.ordered()); const fill = await requestedGroups(requests); if (fill?.kind !== "groups") throw new Error("no fill of groups"); expect(await fill.wantedChanged()).toBe(0n); @@ -995,10 +996,10 @@ test("fill: a filled group stays wanted only while a reader will still read it", const requests = track.requests(); // A live reader already passed every group below the edge. const live = track.subscribe({ ranges: [{ start: { relative: 0n } }], delay: { max: null } }); - expect((await live.ordered().nextGroup())?.start).toBe(5n); + expect((await nextGroup(live.ordered()))?.start).toBe(5n); const reader = track.subscribe(history); - const next = reader.ordered().nextGroup(); + const next = nextGroup(reader.ordered()); const fill = await requestedGroups(requests); if (fill?.kind !== "groups") throw new Error("no fill of groups"); expect(fill.wanted()).toBe(0n); @@ -1436,7 +1437,7 @@ test.each(["arrival", "sequence"])( ? () => reader.recvGroup() : (() => { const ordered = reader.ordered(); - return () => ordered.nextGroup(); + return () => nextGroup(ordered); })(); const got: [bigint, string[]][] = []; for (let group = await next(); group; group = await next()) got.push([group.start, await frames(group)]); @@ -1449,7 +1450,7 @@ test.each(["arrival", "sequence"])( // An open reader takes the whole copy that replaced the headless one in the cache. const open = track.subscribe(history); - const first = await open.ordered().nextGroup(); + const first = await nextGroup(open.ordered()); expect([first?.start, first && (await frames(first))]).toEqual([2n, ["c0", "c1", "c2", "c3", "c4"]]); open.close(); @@ -1471,7 +1472,7 @@ test("fill: a refused head gives its group up, and the bounded reader moves past const reader = track.subscribe(twoAndThree); const ordered = reader.ordered(); const got: bigint[] = []; - for (let group = await ordered.nextGroup(); group; group = await ordered.nextGroup()) got.push(group.start); + for (let group = await nextGroup(ordered); group; group = await nextGroup(ordered)) got.push(group.start); expect(got).toEqual([3n]); requests.close(); @@ -1498,7 +1499,7 @@ test.each([ const reader = track.subscribe(twoAndThree); const ordered = mode === "sequence" ? reader.ordered() : undefined; - const next = () => (ordered ? ordered.nextGroup() : reader.recvGroup()); + const next = () => (ordered ? nextGroup(ordered) : reader.recvGroup()); const got: bigint[] = []; for (let group = await next(); group; group = await next()) got.push(group.start); expect(got).toEqual([3n]); @@ -1512,7 +1513,7 @@ test("fill: a drop of a held group landing while its head is asked leaves the he const { broadcast, track } = headless(); const requests = track.requests(); const ordered = track.subscribe(twoAndThree).ordered(); - const first = ordered.nextGroup(); + const first = nextGroup(ordered); const fill = await requestedGroups(requests); if (!fill) throw new Error("no head asked"); expect([fill.start, fill.end]).toEqual([2n, 3n]); @@ -1545,7 +1546,7 @@ test("fill: with no handler, a bounded reader gives a headless group up while an expect(toStreamCode(fetched)).toBe(StreamCode.NotFound); const open = track.subscribe(history); - const first = await open.ordered().nextGroup(); + const first = await nextGroup(open.ordered()); expect([first?.start, first && (await frames(first))]).toEqual([2n, ["c3", "c4"]]); open.close(); @@ -1624,7 +1625,7 @@ test("fill: a time start no held group resolves is looked up, and the range star const reader = track.subscribe(fromTime(2n)); const ordered = reader.ordered(); const got: bigint[] = []; - for (let i = 0; i < 4; i++) got.push((await ordered.nextGroup())?.start ?? -1n); + for (let i = 0; i < 4; i++) got.push((await nextGroup(ordered))?.start ?? -1n); expect(got).toEqual([2n, 3n, 4n, 5n]); expect(times).toEqual([2n]); @@ -1656,7 +1657,7 @@ test("fill: a lookup answered below the eviction watermark starts the range ther const reader = track.subscribe(fromTime(2n)); const ordered = reader.ordered(); const got: bigint[] = []; - for (let i = 0; i < 4; i++) got.push((await ordered.nextGroup())?.start ?? -1n); + for (let i = 0; i < 4; i++) got.push((await nextGroup(ordered))?.start ?? -1n); expect(got).toEqual([2n, 3n, 4n, 5n]); expect(times).toEqual([2n]); @@ -1672,7 +1673,7 @@ test("fill: a lookup's answer is read at once, before its first frame: its key i const { broadcast, track } = timed(); const requests = track.requests(); const reader = track.subscribe(fromTime(2n)); - const next = reader.ordered().nextGroup(); + const next = nextGroup(reader.ordered()); // The handler answers with group 2 but writes no frame yet. const lookup = await requests.requestedFill(); if (lookup?.kind !== "lookup") throw new Error("no lookup"); @@ -1696,7 +1697,7 @@ test("fill: a lookup closed unanswered starts the range at its time, asking noth const reader = track.subscribe(fromTime(2n)); const ordered = reader.ordered(); const got: bigint[] = []; - for (let i = 0; i < 4; i++) got.push((await ordered.nextGroup())?.start ?? -1n); + for (let i = 0; i < 4; i++) got.push((await nextGroup(ordered))?.start ?? -1n); expect(got).toEqual([2n, 3n, 4n, 5n]); expect(times).toEqual([2n]); @@ -1711,7 +1712,7 @@ test("fill: a time start the held groups place asks no lookup", async () => { const times = lookups(requests, () => 0n); const reader = track.subscribe(fromTime(6n)); - expect((await reader.ordered().nextGroup())?.start).toBe(5n); + expect((await nextGroup(reader.ordered()))?.start).toBe(5n); expect(times).toEqual([]); reader.close(); diff --git a/js/net/src/ietf/join.test.ts b/js/net/src/ietf/join.test.ts index 0b87dc5a98e..ad016e320b2 100644 --- a/js/net/src/ietf/join.test.ts +++ b/js/net/src/ietf/join.test.ts @@ -23,6 +23,7 @@ import { NativeSession } from "./session.ts"; import { Subscribe, SubscribeOk } from "./subscribe.ts"; import { Subscriber } from "./subscriber.ts"; import { ALPN, type IetfVersion, Version, versionName } from "./version.ts"; +import { nextGroup } from "../ordered.test-util.ts"; const VERSIONS = [Version.DRAFT_18, Version.DRAFT_20, Version.DRAFT_22] as const; const VERSION = Version.DRAFT_18; @@ -196,7 +197,7 @@ test("a head that lands before its tail is continued by it", async () => { await subscriber.handleFetch(await head(fetch.requestId, ["h0", "h1"])); await subscriber.handleGroup(...liveStream(GROUP, 2, ["t2", "t3"])); - const group = await consumer.ordered().nextGroup(); + const group = await nextGroup(consumer.ordered()); expect(group?.start).toBe(GROUP); expect(await frames(group)).toEqual(["h0", "h1", "t2", "t3"]); }); @@ -209,7 +210,7 @@ test("a tail that lands before its head waits for it", async () => { await subscriber.handleFetch(await head(fetch.requestId, ["h0", "h1"])); await tail; - const group = await consumer.ordered().nextGroup(); + const group = await nextGroup(consumer.ordered()); expect(await frames(group)).toEqual(["h0", "h1", "t2"]); }); @@ -220,7 +221,7 @@ test("a catalog written once is readable from the head alone", async () => { // No live stream ever comes: the group was written before the subscription. await subscriber.handleFetch(await head(fetch.requestId, ['{"video":{}}'], 0n)); - const group = await consumer.ordered().nextGroup(); + const group = await nextGroup(consumer.ordered()); expect(group?.start).toBe(0n); expect(untext((await group?.readFrame())?.payload)).toBe('{"video":{}}'); }); @@ -234,7 +235,7 @@ test("an empty tail finishes a group the head already holds whole", async () => header.flags = flags(false); await subscriber.handleGroup(header, new Reader(undefined, new Uint8Array(), VERSION)); - const group = await consumer.ordered().nextGroup(); + const group = await nextGroup(consumer.ordered()); expect(await frames(group)).toEqual(["h0", "h1"]); expect(await group?.closed).toBeNull(); }); @@ -256,7 +257,7 @@ for (const outcome of ["a refused joining FETCH", "an empty joining FETCH"] as c await subscriber.handleGroup(...liveStream(GROUP, 2, ["t2"])); await subscriber.handleGroup(...liveStream(GROUP + 1n, 0, ["n0"])); - const group = await consumer.ordered().nextGroup(); + const group = await nextGroup(consumer.ordered()); expect(group?.start).toBe(GROUP + 1n); expect(await frames(group)).toEqual(["n0"]); }); @@ -271,7 +272,7 @@ test("a reader in sequence order with no delay budget skips headless groups", as await subscriber.handleGroup(...liveStream(GROUP + 1n, 1, ["m1"])); await subscriber.handleGroup(...liveStream(GROUP + 2n, 0, ["n0"])); - const group = await consumer.ordered().nextGroup(); + const group = await nextGroup(consumer.ordered()); expect(group?.start).toBe(GROUP + 2n); }); @@ -287,7 +288,7 @@ for (const version of VERSIONS) { // Largest is inclusive, including object 0: its following tail is no whole message. await subscriber.handleGroup(...liveStream(0n, Number(objectId) + 1, ["cut"], version)); await subscriber.handleGroup(...liveStream(1n, 0, ["whole"], version)); - const group = await consumer.ordered().nextGroup(); + const group = await nextGroup(consumer.ordered()); expect(group?.start).toBe(1n); expect(await frames(group)).toEqual(["whole"]); }); @@ -302,7 +303,7 @@ test("a tail parked on a refused joining FETCH is dropped", async () => { await tail; await subscriber.handleGroup(...liveStream(GROUP + 1n, 0, ["n0"])); - const group = await consumer.ordered().nextGroup(); + const group = await nextGroup(consumer.ordered()); expect(group?.start).toBe(GROUP + 1n); }); @@ -318,7 +319,7 @@ test("a joining FETCH has no deadline of its own", async () => { await subscriber.handleFetch(await head(fetch.requestId, ["h0", "h1"])); await tail; - const group = await consumer.ordered().nextGroup(); + const group = await nextGroup(consumer.ordered()); expect(group?.start).toBe(GROUP); expect(await frames(group)).toEqual(["h0", "h1", "t2"]); }); @@ -349,7 +350,7 @@ test("SUBSCRIPTION_ENDED cancels a head nothing claimed", async () => { const { subscriber, consumer, fetching, fetch, peer } = await join(); await accept(fetching); await subscriber.handleFetch(await head(fetch.requestId, ["h0", "h1"])); - const group = await consumer.ordered().nextGroup(); + const group = await nextGroup(consumer.ordered()); expect(group?.start).toBe(GROUP); // The group may run past the head upstream, so it must not read as whole. @@ -386,7 +387,7 @@ test("a whole group that precedes the head wins the sequence", async () => { await subscriber.handleGroup(...liveStream(GROUP, 0, ["w0", "w1", "w2"])); await subscriber.handleFetch(await head(fetch.requestId, ["h0", "h1"])); - const group = await consumer.ordered().nextGroup(); + const group = await nextGroup(consumer.ordered()); expect(await frames(group)).toEqual(["w0", "w1", "w2"]); }); @@ -397,7 +398,7 @@ test("a whole group for a headed sequence is refused, with its head", async () = await subscriber.handleFetch(await head(fetch.requestId, ["h0", "h1"])); await subscriber.handleGroup(...liveStream(GROUP, 0, ["w0"])); - const group = await consumer.ordered().nextGroup(); + const group = await nextGroup(consumer.ordered()); expect(group?.start).toBe(GROUP); expect(await group?.closed).toBeInstanceOf(Error); }); @@ -410,7 +411,7 @@ test("a head that does not meet its tail is refused", async () => { // Object 2 is missing. await subscriber.handleGroup(...liveStream(GROUP, 3, ["t3"])); - const group = await consumer.ordered().nextGroup(); + const group = await nextGroup(consumer.ordered()); expect(await group?.closed).toBeInstanceOf(Error); }); @@ -441,7 +442,7 @@ test("a head that spells Object ID Delta 1 is contiguous", async () => { await subscriber.handleFetch(await deltaHead(fetch.requestId, ["h0", "h1"], 1)); await subscriber.handleGroup(...liveStream(GROUP, 2, ["t2"])); - const group = await consumer.ordered().nextGroup(); + const group = await nextGroup(consumer.ordered()); expect(await frames(group)).toEqual(["h0", "h1", "t2"]); }); @@ -451,7 +452,7 @@ test("a head that repeats an Object ID is dropped", async () => { await subscriber.handleFetch(await deltaHead(fetch.requestId, ["h0", "h0"], 0)); - const group = await consumer.ordered().nextGroup(); + const group = await nextGroup(consumer.ordered()); expect(await group?.closed).toBeInstanceOf(Error); }); @@ -465,7 +466,7 @@ test("a tail that is only an End of Group finishes the head", async () => { // Object ID 2, an empty payload, then status End of Group. await subscriber.handleGroup(header, new Reader(undefined, new Uint8Array([2, 0, 3]), VERSION)); - const group = await consumer.ordered().nextGroup(); + const group = await nextGroup(consumer.ordered()); expect(await frames(group)).toEqual(["h0", "h1"]); expect(await group?.closed).toBeNull(); }); @@ -489,7 +490,7 @@ test("a joining FETCH spanning another group drops the head", async () => { }); await subscriber.handleFetch(new Reader(undefined, bytes, VERSION)); - const group = await consumer.ordered().nextGroup(); + const group = await nextGroup(consumer.ordered()); expect(await group?.closed).toBeInstanceOf(Error); }); @@ -515,7 +516,7 @@ for (const version of VERSIONS) { await subscriber.handleFetch(await head(subscribe.requestId, ["h0", "h1"], GROUP, version)); await tail; - const group = await consumer.ordered().nextGroup(); + const group = await nextGroup(consumer.ordered()); expect(group?.start).toBe(GROUP); expect(await frames(group)).toEqual(["h0", "h1", "t2"]); }); @@ -527,7 +528,7 @@ for (const version of VERSIONS) { await fill; await subscriber.handleGroup(...liveStream(GROUP, 2, ["t2"], version)); - const group = await consumer.ordered().nextGroup(); + const group = await nextGroup(consumer.ordered()); expect(await frames(group)).toEqual(["h0", "h1", "t2"]); }); diff --git a/js/net/src/ietf/range.test.ts b/js/net/src/ietf/range.test.ts index 849e860290c..b62e6be92bf 100644 --- a/js/net/src/ietf/range.test.ts +++ b/js/net/src/ietf/range.test.ts @@ -13,6 +13,7 @@ import { Subscribe, SubscribeOk } from "./subscribe.ts"; import { Subscriber } from "./subscriber.ts"; import { TrackStatusOk, TrackStatusRequest } from "./track.ts"; import { ALPN, type IetfVersion, Version } from "./version.ts"; +import { nextGroup } from "../ordered.test-util.ts"; const VERSIONS = [Version.DRAFT_18, Version.DRAFT_20, Version.DRAFT_22] as const; const ALPNS = { @@ -151,7 +152,7 @@ for (const version of VERSIONS) { const reader = fx.broadcast.track("video").subscribe(ranges(1n, 5n)); fx.readers.push(reader); const ordered = reader.ordered(); - const read = ordered.nextGroup(); + const read = nextGroup(ordered); await fx.status(); const { stream, request } = await fx.fetch(); await fx.answer(stream, 4n); @@ -162,17 +163,17 @@ for (const version of VERSIONS) { expect(await payloads(first)).toEqual(["1a", "", "1c"]); first.close(); for (const key of [3n, 4n]) { - const group = await ordered.nextGroup(); + const group = await nextGroup(ordered); expect(group?.start).toBe(key); if (!group) throw new Error("missing group"); expect(await payloads(group)).toEqual([`${key}a`, "", `${key}c`]); group.close(); } - expect(await ordered.nextGroup()).toBeUndefined(); + expect(await nextGroup(ordered)).toBeUndefined(); const overlapping = fx.broadcast.track("video").subscribe(ranges(0n, 5n)); fx.readers.push(overlapping); const overlap = overlapping.ordered(); - const missing = overlap.nextGroup(); + const missing = nextGroup(overlap); const backfill = await fx.fetch(); await fx.answer(backfill.stream, 0n); await fx.data(backfill.request.requestId, [0n]); @@ -180,14 +181,14 @@ for (const version of VERSIONS) { expect(zero?.start).toBe(0n); zero?.close(); for (const key of [1n, 3n, 4n]) { - const group = await overlap.nextGroup(); + const group = await nextGroup(overlap); expect(group?.start).toBe(key); group?.close(); } - expect(await overlap.nextGroup()).toBeUndefined(); + expect(await nextGroup(overlap)).toBeUndefined(); overlapping.close(); reader.update(ranges(5n, 6n)); - const more = ordered.nextGroup(); + const more = nextGroup(ordered); const second = await fx.fetch(); await fx.answer(second.stream, 5n); await fx.data(second.request.requestId, [5n]); @@ -257,7 +258,7 @@ for (const version of VERSIONS) { const fx = fixture(version); const reader = fx.broadcast.track("video").subscribe(ranges(1n, 2n)); fx.readers.push(reader); - const pending = reader.ordered().nextGroup(); + const pending = nextGroup(reader.ordered()); await fx.status(); const { stream, request } = await fx.fetch(); await fx.answer(stream, 1n); @@ -321,7 +322,7 @@ for (const version of VERSIONS) { const history = fx.broadcast.track("video").subscribe(ranges(1n, 3n)); fx.readers.push(history); const ordered = history.ordered(); - const first = ordered.nextGroup(); + const first = nextGroup(ordered); await fx.status(); const fetching = await fx.fetch(); await fx.answer(fetching.stream, 2n); @@ -340,12 +341,12 @@ for (const version of VERSIONS) { if (!group) throw new Error("missing history group"); expect(await payloads(group)).toEqual(["1a", "", "1c"]); group?.close(); - const second = await ordered.nextGroup(); + const second = await nextGroup(ordered); expect(second?.start).toBe(2n); if (!second) throw new Error("missing history group"); expect(await payloads(second)).toEqual(["2a", "", "2c"]); second?.close(); - expect(await ordered.nextGroup()).toBeUndefined(); + expect(await nextGroup(ordered)).toBeUndefined(); const cached = await fx.broadcast.track("video").fetchGroup(1n); expect(await payloads(cached)).toEqual(["1a", "", "1c"]); cached.close(); @@ -356,7 +357,7 @@ for (const version of VERSIONS) { const history = fx.broadcast.track("video").subscribe(ranges(1n, 3n)); fx.readers.push(history); const ordered = history.ordered(); - const first = ordered.nextGroup(); + const first = nextGroup(ordered); await fx.status(); const fetching = await fx.fetch(); await fx.answer(fetching.stream, 2n); @@ -374,11 +375,11 @@ for (const version of VERSIONS) { if (!group) throw new Error("missing history group"); expect(await payloads(group)).toEqual(["1a", "", "1c"]); group.close(); - const second = await ordered.nextGroup(); + const second = await nextGroup(ordered); if (!second) throw new Error("missing history group"); expect(await payloads(second)).toEqual(["2a", "", "2c"]); second.close(); - expect(await ordered.nextGroup()).toBeUndefined(); + expect(await nextGroup(ordered)).toBeUndefined(); }); test(`${version}: a relative end on an empty track subscribes for the first group`, async () => { @@ -390,7 +391,7 @@ for (const version of VERSIONS) { }); fx.readers.push(reader); const ordered = reader.ordered(); - const first = ordered.nextGroup(); + const first = nextGroup(ordered); await fx.status(null); const live = await fx.next(); expect(await live.reader.u53()).toBe(Subscribe.id); @@ -421,7 +422,7 @@ for (const version of VERSIONS) { if (!group) throw new Error("missing first group"); expect(await payloads(group)).toEqual(["0a"]); group.close(); - expect(await ordered.nextGroup()).toBeUndefined(); + expect(await nextGroup(ordered)).toBeUndefined(); }); test(`${version}: a nonexistent trailing object range preserves the group's payloads`, async () => { diff --git a/js/net/src/ietf/subscriber.test.ts b/js/net/src/ietf/subscriber.test.ts index 70a0ce233c7..c03e7697200 100644 --- a/js/net/src/ietf/subscriber.test.ts +++ b/js/net/src/ietf/subscriber.test.ts @@ -27,6 +27,7 @@ import { SubscribeNamespace, SubscribeNamespaceEntry, SubscribeNamespaceEntryDon import { Subscriber } from "./subscriber.ts"; import { TrackStatusOk, TrackStatusRequest } from "./track.ts"; import { ALPN, type IetfVersion, Version } from "./version.ts"; +import { nextGroup } from "../ordered.test-util.ts"; const VERSION = Version.DRAFT_18; @@ -808,7 +809,7 @@ test("a track without TIMESCALE arrives untimed, even if an object carries a Tim // Property 0x10 (Timestamp) = 5, with no units to read it in. await subscriber.handleGroup(stampedGroup(0n), new Reader(undefined, encodeStamped([0x10, 5]), VERSION)); - const group = await track.ordered().nextGroup(); + const group = await nextGroup(track.ordered()); const frame = await group?.readFrame(); expect(frame?.payload).toEqual(new Uint8Array([42])); // Its group's key, not the object's Timestamp. @@ -824,7 +825,7 @@ test("a received frame's time is its group's key in the track's TIMESCALE", asyn // neither is read. The second object carries no properties at all. const objects = new Uint8Array([...encodeStamped([0x08, 1, 0x08, 5]), ...encodeStamped([])]); await subscriber.handleGroup(stampedGroup(7n), new Reader(undefined, objects, VERSION)); - const group = await track.ordered().nextGroup(); + const group = await nextGroup(track.ordered()); for (let i = 0; i < 2; i++) { const frame = await group?.readFrame(); expect(frame?.payload).toEqual(new Uint8Array([42])); @@ -1144,7 +1145,7 @@ test("early group waits for SUBSCRIBE_OK priority before track acceptance", asyn expect((await track.info()).priority).toBe(127 - 37); expect(group.publisherPriority).toBe(37); const ordered = track.ordered(); - expect((await ordered.nextGroup())?.start).toBe(3n); + expect((await nextGroup(ordered))?.start).toBe(3n); const explicit = new GroupMessage({ trackAlias: ALIAS, groupId: 4n, @@ -1155,7 +1156,7 @@ test("early group waits for SUBSCRIBE_OK priority before track acceptance", asyn await subscriber.handleGroup(explicit, new Reader(undefined, encodeObjects([0]), VERSION)); expect(explicit.publisherPriority).toBe(9); expect((await track.info()).priority).toBe(127 - 37); - expect((await ordered.nextGroup())?.start).toBe(4n); + expect((await nextGroup(ordered))?.start).toBe(4n); ordered.close(); track.close(); }); @@ -1203,7 +1204,7 @@ test.each([Version.DRAFT_18, Version.DRAFT_20, Version.DRAFT_22])( const ordered = consumer.ordered(); try { for (const key of [1n, 2n]) { - const group = await ordered.nextGroup(); + const group = await nextGroup(ordered); expect(group?.start).toBe(key); if (!group) throw new Error("missing prefix group"); expect(await group.readString()).toBe("object 0"); @@ -1259,7 +1260,7 @@ test.each([Version.DRAFT_18, Version.DRAFT_20, Version.DRAFT_22])( new Reader(undefined, encodeObjects([0, 0]), version), ); // The reader waits on group 0, which only a FETCH can bring. - void ordered.nextGroup().catch(() => {}); + void nextGroup(ordered).catch(() => {}); fetch = await nextStream(pair.client, version); expect(await fetch.reader.u53()).toBe(Fetch.id); const { type } = await Fetch.decode(fetch.reader, version); @@ -1337,7 +1338,7 @@ test("a group served from partway through is dropped", async () => { new Reader(undefined, encodeObjects([0, 0]), VERSION), ); - const group = await track.ordered().nextGroup(); + const group = await nextGroup(track.ordered()); expect(group?.start).toBe(4n); track.close(); @@ -1357,7 +1358,7 @@ test("a clear FIRST_OBJECT at object 0 is the whole group", async () => { new Reader(undefined, encodeObjects([0, 0]), VERSION), ); - const group = await track.ordered().nextGroup(); + const group = await nextGroup(track.ordered()); expect(group?.start).toBe(3n); if (!group) return; expect(await group.readString()).toBe("object 0"); @@ -1382,7 +1383,7 @@ test("an END_OF_GROUP status on a marked stream finishes the group", async () => new Reader(undefined, objects, VERSION), ); - const group = await track.ordered().nextGroup(); + const group = await nextGroup(track.ordered()); expect(group?.start).toBe(3n); if (!group) return; for (let i = 0; i < 5; i++) { @@ -1448,7 +1449,7 @@ test("a clear FIRST_OBJECT past object 0 is dropped", async () => { new Reader(undefined, encodeObjects([0]), VERSION), ); - const group = await track.ordered().nextGroup(); + const group = await nextGroup(track.ordered()); expect(group?.start).toBe(4n); track.close(); @@ -1508,7 +1509,7 @@ test("a group that claims its first object must start at zero", async () => { const header = new GroupMessage({ trackAlias: ALIAS, groupId: 3n, subGroupId: 0n, publisherPriority: 0, flags }); await subscriber.handleGroup(header, new Reader(undefined, encodeObjects([5, 0, 0]), VERSION)); - const group = await track.ordered().nextGroup(); + const group = await nextGroup(track.ordered()); expect(group).toBeDefined(); if (!group) return; await expect(group.readFrameIndex()).rejects.toThrow(/object IDs must start at 0/); @@ -1626,7 +1627,7 @@ test("every object in a chunk reaches the reader before it wakes", async () => { }); const handled = subscriber.handleGroup(header, new Reader(readable, undefined, VERSION)); - const group = await track.ordered().nextGroup(); + const group = await nextGroup(track.ordered()); if (!group) throw new Error("no group"); expect(await group.readString()).toBe("object 0"); expect(group.frameCount).toBe(10); @@ -1686,7 +1687,7 @@ test("object extension limit accepts 64 KiB and stops one byte over before readi await subscriber.handleGroup(header, reader); if (size === 65536) { expect(stop.mock.calls).toEqual([]); - const group = await track.ordered().nextGroup(); + const group = await nextGroup(track.ordered()); expect(group?.frameCount).toBe(first ? 1 : 2); expect(await group?.readString()).toBe("*"); } else { @@ -1757,7 +1758,7 @@ for (const version of [Version.DRAFT_18, Version.DRAFT_20, Version.DRAFT_22]) { message, new Reader(undefined, new Uint8Array([0, 0, 0, 0, 1, 42, 0, 0, 3]), version), ); - const group = await track.ordered().nextGroup(); + const group = await nextGroup(track.ordered()); expect((await group?.readFrame())?.payload).toEqual(new Uint8Array()); expect((await group?.readFrame())?.payload).toEqual(new Uint8Array([42])); expect(await group?.readFrame()).toBeUndefined(); diff --git a/js/net/src/integration.test.ts b/js/net/src/integration.test.ts index 38d4000184e..0c64e5e075f 100644 --- a/js/net/src/integration.test.ts +++ b/js/net/src/integration.test.ts @@ -31,6 +31,7 @@ import type { Position, Producer as TrackProducer } from "./track.ts"; import { unwanted } from "./util/demand.ts"; import { withTimeout } from "./util/timeout.ts"; import { wireOf } from "./wire.ts"; +import { nextGroup } from "./ordered.test-util.ts"; function publish(origin: OriginProducer, path: Path.Valid) { const broadcastRoute = origin.route(path); @@ -354,11 +355,11 @@ test("integration: lite applies initial and updated group bounds", async () => { }) .ordered(); try { - expect((await subscriber.nextGroup())?.start).toBe(INITIAL_START_GROUP); - expect((await subscriber.nextGroup())?.start).toBe(INITIAL_END_GROUP - 1n); + expect((await nextGroup(subscriber))?.start).toBe(INITIAL_START_GROUP); + expect((await nextGroup(subscriber))?.start).toBe(INITIAL_END_GROUP - 1n); // A bounded read ends once its window is read, as in Rust. - expect(await subscriber.nextGroup()).toBeUndefined(); + expect(await nextGroup(subscriber)).toBeUndefined(); // Replacing the ranges reads on from the same reader, the update going upstream. subscriber.update({ @@ -367,15 +368,15 @@ test("integration: lite applies initial and updated group bounds", async () => { }); const updated = (pending: Promise) => withTimeout(pending, Duration.millis(UPDATE_TIMEOUT_MS), "updated group bound timed out"); - expect(((await updated(subscriber.nextGroup())) as { start: bigint } | undefined)?.start).toBe(UPDATED_GROUP); - expect(await updated(subscriber.nextGroup())).toBeUndefined(); + expect(((await updated(nextGroup(subscriber))) as { start: bigint } | undefined)?.start).toBe(UPDATED_GROUP); + expect(await updated(nextGroup(subscriber))).toBeUndefined(); // An open range parks at the live edge instead. subscriber.update({ delay: { max: Duration.millis(REPLAY_LATENCY_MS) }, ranges: [{ start: { time: GROUP_COUNT } }], }); - expect(await settlesWithin(subscriber.nextGroup(), clock, Duration.millis(PENDING_ASSERT_MS))).toBe(false); + expect(await settlesWithin(nextGroup(subscriber), clock, Duration.millis(PENDING_ASSERT_MS))).toBe(false); } finally { subscriber.close(); remote.close(); @@ -423,12 +424,12 @@ test("integration: lite refuses an empty requested range on open and on update", ranges: [{ start: { time: 1n }, end: { time: 1n } }], }) .ordered(); - expect((await live.nextGroup())?.start).toBe(1n); + expect((await nextGroup(live))?.start).toBe(1n); live.update({ delay: { max: Duration.millis(REPLAY_LATENCY_MS) }, ranges: [{ start: { time: 3n }, end: { time: 2n } }], }); - expect(await live.nextGroup()).toBeUndefined(); + expect(await nextGroup(live)).toBeUndefined(); expect( await withTimeout(Promise.resolve(live.closed), Duration.millis(TIMEOUT_MS), "empty update never settled"), ).toHaveProperty("message", "empty subscription range cannot be encoded"); @@ -470,9 +471,9 @@ test("integration: lite-07 serves sparse and relative ranges", async () => { .ordered(); // Covering the ranges ends the subscription upstream, and the read with its window. const got: bigint[] = []; - for (let i = 0; i < 4; i++) got.push((await reader.nextGroup())?.start ?? -1n); + for (let i = 0; i < 4; i++) got.push((await nextGroup(reader))?.start ?? -1n); expect(got).toEqual([1n, 2n, 7n, 8n]); - expect(await reader.nextGroup()).toBeUndefined(); + expect(await nextGroup(reader)).toBeUndefined(); reader.close(); } finally { remote.close(); @@ -562,7 +563,7 @@ test("integration: lite-07 joins a late relative start at the live edge", async "the update never reached the publisher", ); late = remote.track("video").subscribe(subscription).ordered(); - expect((await late.nextGroup())?.start).toBe(3n); + expect((await nextGroup(late))?.start).toBe(3n); } finally { late?.close(); first.close(); @@ -862,7 +863,7 @@ test("integration: a group reset carries the peer's code to the subscriber", asy const group = hooks.appendNext(producer); group.writeFrame(textFrame("frame")); - const consumer = await track.nextGroup(); + const consumer = await nextGroup(track); if (!consumer) throw new Error("expected a group"); expect(await consumer.readString()).toBe("frame"); @@ -902,7 +903,7 @@ test("integration: a locally raised group error reaches the peer as its own code const group = hooks.appendNext(producer); group.writeFrame(textFrame("frame")); - const consumer = await track.nextGroup(); + const consumer = await nextGroup(track); if (!consumer) throw new Error("expected a group"); expect(await consumer.readString()).toBe("frame"); diff --git a/js/net/src/lite/connection.test.ts b/js/net/src/lite/connection.test.ts index a8a17a49203..6e2a796dd57 100644 --- a/js/net/src/lite/connection.test.ts +++ b/js/net/src/lite/connection.test.ts @@ -42,6 +42,7 @@ import { Version, versionName, } from "./version.ts"; +import { nextGroup } from "../ordered.test-util.ts"; /** A transport whose `getStats` behaves as described, or is absent entirely. */ function transport(getStats?: () => Promise): WebTransport { @@ -370,7 +371,7 @@ for (const [alpn, version] of [ first.finish(); // A frame can arrive while its sender still yields on the write. Drain the setup group // before a zero-delay subscription supersedes its still-unfinished sender. - const received = await track.nextGroup(); + const received = await nextGroup(track); expect(await received?.readString()).toBe("first"); expect(await received?.readString()).toBeUndefined(); received?.close(); @@ -383,7 +384,7 @@ for (const [alpn, version] of [ producer.close(); const closing = server.close(); - expect(await (await track.nextGroup())?.readString()).toBe("last"); + expect(await (await nextGroup(track))?.readString()).toBe("last"); await fin.reached; await settle(); expect(closed).toBe(false); @@ -391,7 +392,7 @@ for (const [alpn, version] of [ fin.release(); await closing; expect(closed).toBe(true); - expect(await track.nextGroup()).toBeUndefined(); + expect(await nextGroup(track)).toBeUndefined(); } finally { fin.release(); track.close(); @@ -433,7 +434,7 @@ for (const [alpn, version] of [ const first = hooks.appendNext(producer); first.writeFrame(textFrame("first", Timestamp.fromMillis(Number(first.start)))); first.finish(); - const received = await track.nextGroup(); + const received = await nextGroup(track); expect(await received?.readString()).toBe("first"); expect(await received?.readString()).toBeUndefined(); received?.close(); @@ -442,14 +443,14 @@ for (const [alpn, version] of [ const last = hooks.appendNext(producer); last.writeFrame(textFrame("last", Timestamp.fromMillis(Number(last.start)))); last.finish(); - expect(await (await track.nextGroup())?.readString()).toBe("last"); + expect(await (await nextGroup(track))?.readString()).toBe("last"); await fin.reached; replies.enable(); producer.finish(); producer.close(); const closing = server.close(); - expect(await track.nextGroup()).toBeUndefined(); + expect(await nextGroup(track)).toBeUndefined(); await settle(); expect(closed).toBe(false); @@ -496,7 +497,7 @@ for (const [alpn, version] of [ const first = hooks.appendNext(producer); first.writeFrame(textFrame("first", Timestamp.fromMillis(Number(first.start)))); first.finish(); - expect(await (await track.nextGroup())?.readString()).toBe("first"); + expect(await (await nextGroup(track))?.readString()).toBe("first"); const frames = Array.from({ length: 32 }, (_, i) => `frame ${i}`); const last = hooks.appendNext(producer); @@ -506,10 +507,10 @@ for (const [alpn, version] of [ producer.close(); await server.close(); - const group = await track.nextGroup(); + const group = await nextGroup(track); for (const frame of frames) expect(await group?.readString()).toBe(frame); expect(await group?.readString()).toBeUndefined(); - expect(await track.nextGroup()).toBeUndefined(); + expect(await nextGroup(track)).toBeUndefined(); } finally { yielding.mockRestore(); track.close(); @@ -547,14 +548,14 @@ for (const [alpn, version] of [ const group = hooks.appendNext(producer); group.writeFrame(textFrame("only", Timestamp.fromMillis(Number(group.start)))); group.finish(); - expect(await (await track.nextGroup())?.readString()).toBe("only"); + expect(await (await nextGroup(track))?.readString()).toBe("only"); producer.finish(); producer.close(); await settle(); client.abort(); - expect(await track.nextGroup()).toBeUndefined(); + expect(await nextGroup(track)).toBeUndefined(); expect(await track.closed).toBeNull(); } finally { track.close(); @@ -591,12 +592,12 @@ for (const [alpn, version] of [ const group = hooks.appendNext(producer); group.writeFrame(textFrame("only", Timestamp.fromMillis(Number(group.start)))); group.finish(); - expect(await (await track.nextGroup())?.readString()).toBe("only"); + expect(await (await nextGroup(track))?.readString()).toBe("only"); producer.finish(); producer.close(); await server.close(); - expect(await track.nextGroup()).toBeUndefined(); + expect(await nextGroup(track)).toBeUndefined(); } finally { track.close(); remote.close(); diff --git a/js/net/src/lite/copy_fill.test.ts b/js/net/src/lite/copy_fill.test.ts index 2fcab947259..44c489a8e83 100644 --- a/js/net/src/lite/copy_fill.test.ts +++ b/js/net/src/lite/copy_fill.test.ts @@ -21,6 +21,7 @@ import { wireOf } from "../wire.ts"; import * as Lite from "./index.ts"; import { Publisher as LitePublisher } from "./publisher.ts"; import { Subscriber as LiteSubscriber } from "./subscriber.ts"; +import { nextGroup } from "../ordered.test-util.ts"; const enc = new TextEncoder(); const dec = new TextDecoder(); @@ -268,7 +269,7 @@ test("copy fill: a filled group stops downloading once every reader left or pass // A live reader keeps the copy up, and has read past group 0 before it lands. It never // reads again, so the copy it still buffers is all that is left of it. const reader = remote.track("video").subscribe({ ranges: [{ start: { relative: 0n } }] }); - expect((await reader.ordered().nextGroup())?.start).toBe(1n); + expect((await nextGroup(reader.ordered()))?.start).toBe(1n); const history = remote .track("video") .subscribe({ ...WIDE, ranges: [{ start: { time: 0n }, end: { time: 0n } }] }); @@ -335,7 +336,7 @@ test("copy fill: a filled group nobody holds any more stops downloading", async // A live reader keeps the copy up. It reads in order, so it lets go of what it passes. const reader = remote.track("video").subscribe({ ranges: [{ start: { relative: 0n } }] }); const live = reader.ordered(); - expect((await live.nextGroup())?.start).toBe(1n); + expect((await nextGroup(live))?.start).toBe(1n); const history = remote .track("video") .subscribe({ ...WIDE, ranges: [{ start: { time: 0n }, end: { time: 0n } }] }); @@ -353,7 +354,7 @@ test("copy fill: a filled group nobody holds any more stops downloading", async group?.close(); history.close(); write(track.createGroup(2n), 2n, "live"); - expect((await live.nextGroup())?.start).toBe(2n); + expect((await nextGroup(live))?.start).toBe(2n); await clock.drive( timeout( Duration.millis(2000), @@ -406,7 +407,7 @@ test("copy fill: a group reset to make room ends", async () => { const remote = wireOf(client).consume(Path.from("room")); try { const reader = remote.track("video").subscribe({ ranges: [{ start: { relative: 0n } }] }); - const live = await reader.ordered().nextGroup(); + const live = await nextGroup(reader.ordered()); expect(live?.start).toBe(2n); expect(dec.decode((await live?.readFrame())?.payload)).toBe("live 2"); expect(await live?.readFrame()).toBeUndefined(); diff --git a/js/net/src/lite/subscriber.test.ts b/js/net/src/lite/subscriber.test.ts index d04c0b1350f..cd79a957db0 100644 --- a/js/net/src/lite/subscriber.test.ts +++ b/js/net/src/lite/subscriber.test.ts @@ -63,6 +63,7 @@ import { import { Minted, Subscriber } from "./subscriber.ts"; import { Track, TrackInfo } from "./track.ts"; import { hasLengthFirst, Version, versionName } from "./version.ts"; +import { nextGroup } from "../ordered.test-util.ts"; test("closing the subscriber suppresses probe stream warnings", async () => { let readable!: ReadableStreamDefaultController; @@ -1812,7 +1813,7 @@ test("a grant that shrinks while the subscription sets up refuses it", async () const subscriber = new Subscriber(quic, Version.DRAFT_05, toHop(1n), undefined, undefined, undefined, grant); const track = subscriber.consume(Path.from("room/cam")).track("video").subscribe().ordered(); - const next = track.nextGroup().catch((err: unknown) => err); + const next = nextGroup(track).catch((err: unknown) => err); // Parked on TRACK_INFO when the grant shrinks, which ends the TRACK exchange too. await opened(0); @@ -2579,7 +2580,7 @@ test("a local unsubscribe owes no SUBSCRIBE_FINISH", async () => { await opened(0); await answerTrackInfo(streams[0], Version.DRAFT_07); await (await opened(1)).reading; - const next = ordered.nextGroup(); + const next = nextGroup(ordered); await subscriber.runGroup( new Group({ subscribe: 0n, key: 0n }), new Reader( diff --git a/js/net/src/ordered.test-util.ts b/js/net/src/ordered.test-util.ts new file mode 100644 index 00000000000..46838c2ba60 --- /dev/null +++ b/js/net/src/ordered.test-util.ts @@ -0,0 +1,20 @@ +// Group-only reads of an ordered track, for tests that check what it delivers rather than the +// gaps it reports. +import type * as Group from "./group.ts"; +import type * as Track from "./track.ts"; + +/** The next group `ordered` returns, past any gap it reports first. */ +export async function nextGroup(ordered: Track.Ordered): Promise { + for (;;) { + const item = await ordered.nextGroup(); + if (item?.kind !== "gap") return item?.group; + } +} + +/** The next group `ordered` holds now, past any gap, without waiting. */ +export function tryNextGroup(ordered: Track.Ordered): Group.Consumer | undefined { + for (;;) { + const item = ordered.tryNextGroup(); + if (item?.kind !== "gap") return item?.group; + } +} diff --git a/js/net/src/ordered.test.ts b/js/net/src/ordered.test.ts new file mode 100644 index 00000000000..04b2295712b --- /dev/null +++ b/js/net/src/ordered.test.ts @@ -0,0 +1,184 @@ +// What an ordered read returns: groups in key order, and a gap for every group it gives up on. +// Ports the Rust `track::Ordered` item tests, so both read the same. +import { expect, test } from "bun:test"; +import { Duration } from "@moq/clock"; +import { Manual } from "@moq/clock/test"; +import { StreamCode, StreamError } from "./error.ts"; +import { hooks } from "./internal.ts"; +import { textFrame } from "./mock.ts"; +import { Timestamp } from "./time.ts"; +import { type Ordered, Producer as TrackProducer } from "./track.ts"; + +// A session-fed copy owes holes; an in-process producer does not. +function receivedTrack() { + const producer = new TrackProducer("test").accept({ maxAge: null }); + hooks.receiveTrack(producer); + return producer; +} + +// A finished one-frame group, presenting at its key in milliseconds on a timed track. +function put(producer: TrackProducer, key: bigint, timed = true) { + const group = producer.createGroup(key); + group.writeFrame(textFrame("x", timed ? Timestamp.fromMillis(Number(key)) : Timestamp.unscaled(key))); + group.finish(); +} + +function drop(producer: TrackProducer, start: bigint, end: bigint) { + hooks.dropTrackGroups(producer, start, end, { error: new StreamError(StreamCode.DeliveryTimeout) }); +} + +const NAMES: Record = { + [StreamCode.DeliveryTimeout]: "delivery timeout", + [StreamCode.Old]: "old", + [StreamCode.NotFound]: "not found", +}; + +// What an ordered read returns until it would wait, as `group 2` or `gap 1..2 (old)`. +function items(ordered: Ordered): string[] { + const out: string[] = []; + for (;;) { + if (out.length > 20) throw new Error(`no end to the items: ${out.join(", ")}`); + const item = ordered.tryNextGroup(); + if (!item) return out; + if (item.kind === "group") { + out.push(`group ${item.group.start}`); + item.group.close(); + } else { + const code = item.error instanceof StreamError ? item.error.code : -1; + out.push(`gap ${item.start}..${item.end} (${NAMES[code] ?? item.error.message})`); + } + } +} + +function withClock(fn: (clock: Manual) => void) { + const clock = new Manual(); + const installed = clock.install(); + try { + fn(clock); + } finally { + installed.close(); + } +} + +test("an ordered read reports what it gives up, in key order, but no skip", () => { + const producer = new TrackProducer("test"); + const ordered = producer.subscribe({ delay: { max: null } }).ordered(); + put(producer, 0n); + put(producer, 3n); + drop(producer, 1n, 3n); + producer.skipGroups(4n, 6n); + put(producer, 6n); + expect(items(ordered)).toEqual(["group 0", "gap 1..3 (delivery timeout)", "group 3", "group 6"]); + + // A group handed out and then dropped is never reported again. + const cut = producer.createGroup(7n); + const read = ordered.tryNextGroup(); + expect(read?.group?.start).toBe(7n); + drop(producer, 7n, 8n); + cut.abort(new StreamError(StreamCode.Cancel)); + expect(items(ordered)).toEqual([]); +}); + +test("a key a local track never produced is no gap", () => { + const producer = new TrackProducer("test"); + const ordered = producer.subscribe({ delay: { max: Duration.secs(1) } }).ordered(); + put(producer, 0n); + put(producer, 2n); + expect(items(ordered)).toEqual(["group 0", "group 2"]); +}); + +test("a gap waits behind what is owed below it, and goes out before the end", () => + withClock(() => { + const producer = receivedTrack(); + const ordered = producer.subscribe({ delay: { max: null } }).ordered(); + put(producer, 0n, false); + put(producer, 2n, false); + drop(producer, 4n, 5n); + expect(items(ordered)).toEqual(["group 0"]); + put(producer, 1n, false); + expect(items(ordered)).toEqual(["group 1", "group 2"]); + put(producer, 3n, false); + expect(items(ordered)).toEqual(["group 3", "gap 4..5 (delivery timeout)"]); + + const local = new TrackProducer("test"); + const read = local.subscribe({ delay: { max: null } }).ordered(); + put(local, 0n); + drop(local, 1n, 2n); + local.finish(); + expect(items(read)).toEqual(["group 0", "gap 1..2 (delivery timeout)"]); + expect(read.tryNextGroup()).toBeUndefined(); + })); + +test("a gap is returned once, even when a later drop names it again", () => + withClock((clock) => { + const producer = receivedTrack(); + const ordered = producer.subscribe({ delay: { max: Duration.millis(50) } }).ordered(); + put(producer, 0n, false); + put(producer, 2n, false); + expect(items(ordered)).toEqual(["group 0"]); + // The budget gives up on the group still owed, as stale. + clock.jump(Duration.millis(50)); + expect(items(ordered)).toEqual(["gap 1..2 (old)", "group 2"]); + drop(producer, 1n, 2n); + put(producer, 3n, false); + expect(items(ordered)).toEqual(["group 3"]); + })); + +test("a skip replaces a gap still waiting, and the rest of the drop stays one", () => + withClock(() => { + const producer = receivedTrack(); + const ordered = producer.subscribe({ delay: { max: null } }).ordered(); + put(producer, 0n, false); + put(producer, 2n, false); + drop(producer, 4n, 8n); + expect(items(ordered)).toEqual(["group 0"]); + producer.skipGroups(5n, 7n); + drop(producer, 1n, 2n); + expect(items(ordered)).toEqual(["gap 1..2 (delivery timeout)", "group 2"]); + put(producer, 3n, false); + expect(items(ordered)).toEqual(["group 3", "gap 4..5 (delivery timeout)", "gap 7..8 (delivery timeout)"]); + })); + +test("a cached group the seek passes as stale is a gap", () => + withClock((clock) => { + const producer = receivedTrack(); + put(producer, 0n, false); + put(producer, 1n, false); + clock.jump(Duration.millis(100)); + put(producer, 2n, false); + const ordered = producer.subscribe({ delay: { max: Duration.millis(50) } }).ordered(); + expect(items(ordered)).toEqual(["gap 0..1 (old)", "group 1", "group 2"]); + })); + +test("a late arrival is a gap, told once", () => { + const producer = new TrackProducer("test"); + const ordered = producer.subscribe({ delay: { max: null } }).ordered(); + put(producer, 0n); + put(producer, 5n); + expect(items(ordered)).toEqual(["group 0", "group 5"]); + put(producer, 3n); + expect(items(ordered)).toEqual(["gap 3..4 (old)"]); + put(producer, 6n); + expect(items(ordered)).toEqual(["group 6"]); +}); + +test("a gap is clipped to the reader's range", () => { + const producer = new TrackProducer("test"); + const ordered = producer + .subscribe({ delay: { max: null } }) + .ordered() + .withRange({ start: { included: 2n }, end: { excluded: 4n } }); + drop(producer, 0n, 6n); + put(producer, 5n); + expect(items(ordered)).toEqual(["gap 2..4 (delivery timeout)"]); +}); + +test("the frame helpers read past a gap", async () => { + const producer = new TrackProducer("test"); + const ordered = producer.subscribe({ delay: { max: null } }).ordered(); + put(producer, 0n); + drop(producer, 1n, 2n); + put(producer, 2n); + expect((await ordered.readFrame())?.group).toBe(0n); + expect((await ordered.readFrame())?.group).toBe(2n); +}); diff --git a/js/net/src/resume.test.ts b/js/net/src/resume.test.ts index 5f27cc6ce0f..c7666428b26 100644 --- a/js/net/src/resume.test.ts +++ b/js/net/src/resume.test.ts @@ -19,6 +19,7 @@ import { Timestamp } from "./time.ts"; import type * as track from "./track.ts"; import { unwanted } from "./util/demand.ts"; import { overrideBroadcastWire, wireOf } from "./wire.ts"; +import { nextGroup, tryNextGroup } from "./ordered.test-util.ts"; const INFO: track.Info = { compression: "none", timescale: null, maxAge: null, priority: 0, refresh: null }; @@ -1851,15 +1852,15 @@ test("an ordered reader takes a replaced copy's buffered group before the new co .subscribe({ delay: { max: Duration.millis(10_000) } }) .ordered(); ta.write(0n); - expect((await ordered.nextGroup())?.start).toBe(0n); + expect((await nextGroup(ordered))?.start).toBe(0n); // The old copy holds group 1 unread; the new one only has group 2. ta.write(1n); tb.write(2n); front.serve(b.consume()); await settle(); - expect((await ordered.nextGroup())?.start).toBe(1n); - expect((await ordered.nextGroup())?.start).toBe(2n); + expect((await nextGroup(ordered))?.start).toBe(1n); + expect((await nextGroup(ordered))?.start).toBe(2n); ordered.close(); front.consumer.close(); @@ -1882,7 +1883,7 @@ test("a routed read right after an update picks its group under the new preferen await settle(); // The copy learns of the update a microtask later; the read must not pick under its old budget. ordered.update({ delay: { max: Duration.ZERO } }); - expect(ordered.tryNextGroup()?.start).toBe(1n); + expect(tryNextGroup(ordered)?.start).toBe(1n); } finally { ordered.close(); front.consumer.close(); @@ -1908,13 +1909,13 @@ for (const resolution of ["arrival", "drop", "other copy", "budget"] as const) { .ordered(); try { ta.write(4n); - expect((await ordered.nextGroup())?.start).toBe(4n); + expect((await nextGroup(ordered))?.start).toBe(4n); ta.write(6n); tb.write(7n); hooks.startTrack(tb.producer, { start: 7n, requested: 4n }); front.serve(b.consume()); await settle(); - const held = ordered.nextGroup(); + const held = nextGroup(ordered); expect(await isPending(held)).toBe(true); if (resolution === "arrival") ta.write(5n); if (resolution === "other copy") { @@ -1926,7 +1927,7 @@ for (const resolution of ["arrival", "drop", "other copy", "budget"] as const) { if (resolution === "budget") await clock.advance(Duration.millis(1000)); const expected = resolution === "arrival" || resolution === "other copy" ? [5n, 6n, 7n] : [6n, 7n]; expect((await held)?.start).toBe(expected[0]); - for (const key of expected.slice(1)) expect((await ordered.nextGroup())?.start).toBe(key); + for (const key of expected.slice(1)) expect((await nextGroup(ordered))?.start).toBe(key); } finally { ordered.close(); front.consumer.close(); @@ -2578,7 +2579,7 @@ test.each([true, false])( const sub = front.consumer.track("seq").subscribe(); const view = ordered ? sub.ordered() : undefined; const next = async () => { - const group = await (view ? view.nextGroup() : sub.recvGroup()); + const group = await (view ? nextGroup(view) : sub.recvGroup()); group?.close(); return group?.start; }; @@ -2620,7 +2621,7 @@ test.each([ front.serve(a.consume()); const sub = front.consumer.track("seq").subscribe(); const view = ordered ? sub.ordered() : undefined; - const next = () => (view ? view.nextGroup() : sub.recvGroup()); + const next = () => (view ? nextGroup(view) : sub.recvGroup()); ta.write(0n); (await next())?.close(); front.serve(b.consume()); @@ -2663,7 +2664,7 @@ test.each([true, false])( front.serve(a.consume()); const sub = front.consumer.track("seq").subscribe(); const view = ordered ? sub.ordered() : undefined; - const next = () => (view ? view.nextGroup() : sub.recvGroup()); + const next = () => (view ? nextGroup(view) : sub.recvGroup()); ta.write(0n); (await next())?.close(); front.serve(b.consume()); @@ -3167,7 +3168,7 @@ test.each([true, false])( front.serve(a.consume()); const sub = front.consumer.track("seq").subscribe({ delay: { max: Duration.millis(3_600_000) } }); const view = ordered ? sub.ordered() : undefined; - const next = () => (view ? view.nextGroup() : sub.recvGroup()); + const next = () => (view ? nextGroup(view) : sub.recvGroup()); ta.write(0n); (await next())?.close(); front.serve(b.consume()); @@ -3209,7 +3210,7 @@ test.each([true, false])("a replaced copy backs a group before its first arrival front.serve(a.consume()); const sub = front.consumer.track("seq").subscribe({ delay: { max: Duration.millis(3_600_000) } }); const view = ordered ? sub.ordered() : undefined; - const next = () => (view ? view.nextGroup() : sub.recvGroup()); + const next = () => (view ? nextGroup(view) : sub.recvGroup()); ta.write(0n); (await next())?.close(); front.serve(b.consume()); @@ -3531,7 +3532,7 @@ test.each([ const inOrder = ordered ? sub.ordered() : undefined; const read = () => { const keys: bigint[] = []; - const next = () => (inOrder ? inOrder.tryNextGroup() : sub.tryRecvGroup()); + const next = () => (inOrder ? tryNextGroup(inOrder) : sub.tryRecvGroup()); for (let group = next(); group; group = next()) { keys.push(group.start); group.close(); diff --git a/js/net/src/retention.test.ts b/js/net/src/retention.test.ts index 7f43534d31a..db8cd1adbe1 100644 --- a/js/net/src/retention.test.ts +++ b/js/net/src/retention.test.ts @@ -10,6 +10,7 @@ import { Producer as OriginProducer } from "./origin.ts"; import * as Path from "./path.ts"; import { Timescale, Timestamp } from "./time.ts"; import { wireOf } from "./wire.ts"; +import { nextGroup } from "./ordered.test-util.ts"; // A subscription races its track's `closed` once per frame. These count the listeners left on // every Once that is still pending, so a per-frame leak shows up as a slope in frames. @@ -119,7 +120,7 @@ for (const [name, alpn] of [ const group = hooks.appendNext(producer); group.writeFrame(frame(0)); - const consumer = await track.nextGroup(); + const consumer = await nextGroup(track); if (!consumer) throw new Error("no group"); await readFrames(consumer, 1); @@ -142,7 +143,7 @@ for (const [name, alpn] of [ const group = hooks.appendNext(producer); group.writeFrame(frame(offset + i)); group.finish(); - const consumer = await track.nextGroup(); + const consumer = await nextGroup(track); if (!consumer) throw new Error("no group"); await readFrames(consumer, 1); } diff --git a/js/net/src/track.test.ts b/js/net/src/track.test.ts index eb353b62b67..bd600229a43 100644 --- a/js/net/src/track.test.ts +++ b/js/net/src/track.test.ts @@ -13,6 +13,7 @@ import { Timescale, Timestamp } from "./time.ts"; import { authoredInfo, Subscription, Producer as TrackProducer } from "./track.ts"; import { unwanted } from "./util/demand.ts"; import { LIVE, rangesStart } from "./window.ts"; +import { nextGroup, tryNextGroup } from "./ordered.test-util.ts"; const enc = new TextEncoder(); const dec = new TextDecoder(); @@ -96,7 +97,7 @@ function appendFrozen(producer: TrackProducer, text = "x"): bigint { function drainOrdered(reader: import("./track.ts").Ordered) { const keys: bigint[] = []; - for (let group = reader.tryNextGroup(); group; group = reader.tryNextGroup()) { + for (let group = tryNextGroup(reader); group; group = tryNextGroup(reader)) { keys.push(group.start); group.close(); } @@ -132,7 +133,7 @@ test("an ordered owed hole wakes exactly at its wall budget", async () => { expect(drainOrdered(reader)).toEqual([0n]); putGroup(producer, 2n); let resolved = false; - const pending = reader.nextGroup().then((group) => { + const pending = nextGroup(reader).then((group) => { resolved = true; return group; }); @@ -191,7 +192,7 @@ test("an ordered owed hole follows media time and a lower successor", async () = edge.writeFrame(textFrame("edge", Timestamp.fromMillis(4000))); expect(drainOrdered(reader)).toEqual([]); let resolved = false; - const pending = reader.nextGroup().then((group) => { + const pending = nextGroup(reader).then((group) => { resolved = true; return group; }); @@ -203,7 +204,7 @@ test("an ordered owed hole follows media time and a lower successor", async () = expect(drainOrdered(reader)).toEqual([]); // Group 3 is still owed. edge.writeFrame(textFrame("within", Timestamp.fromMillis(4999))); expect(drainOrdered(reader)).toEqual([]); - const deadline = reader.nextGroup(); + const deadline = nextGroup(reader); edge.writeFrame(textFrame("deadline", Timestamp.fromMillis(5000))); await settle(); expect((await deadline)?.start).toBe(4n); @@ -228,7 +229,7 @@ test("an ordered owed hole wakes when its ledger gap folds", async () => { putGroup(producer, 3n); opener.abort(new StreamError(StreamCode.Cancel)); let resolved = false; - const pending = reader.nextGroup().then((group) => { + const pending = nextGroup(reader).then((group) => { resolved = true; return group; }); @@ -262,7 +263,7 @@ test("ordered owed holes follow zero, narrowed, unlimited, and publisher budgets putGroup(producer, 1n); expect(drainOrdered(reader)).toEqual([1n, 2n]); } else if (!maxDelay.isZero()) { - const pending = reader.nextGroup(); + const pending = nextGroup(reader); reader.update({ delay: { max: Duration.ZERO } }); expect((await pending)?.start).toBe(2n); } @@ -275,7 +276,7 @@ test("ordered owed holes follow zero, narrowed, unlimited, and publisher budgets putGroup(producer, 0n); putGroup(producer, 2n); expect(drainOrdered(reader)).toEqual([0n]); - const pending = reader.nextGroup(); + const pending = nextGroup(reader); await clock.advance(3_600_050); expect((await pending)?.start).toBe(2n); reader.close(); @@ -799,11 +800,11 @@ test("an ordered reader keeps a group between its ranges until the cursor passes }) .ordered(); for (const key of [0n, 1n]) producer.createGroup(key).finish(); - expect(track.tryNextGroup()?.start).toBe(0n); - expect(track.tryNextGroup()).toBeUndefined(); + expect(tryNextGroup(track)?.start).toBe(0n); + expect(tryNextGroup(track)).toBeUndefined(); track.update({ delay: { max: null }, ranges: [{ start: { time: 0n }, end: { time: 3n } }] }); - expect(track.tryNextGroup()?.start).toBe(1n); + expect(tryNextGroup(track)?.start).toBe(1n); track.close(); producer.finish(); producer.close(); @@ -1020,7 +1021,7 @@ test("a time start resolves on keys alone, before any group's first frame", () = for (let group = reader.tryRecvGroup(); group; group = reader.tryRecvGroup()) got.push(group.start); expect(got.sort()).toEqual([1000n, 2000n]); const inOrder: bigint[] = []; - for (let group = ordered.tryNextGroup(); group; group = ordered.tryNextGroup()) inOrder.push(group.start); + for (let group = tryNextGroup(ordered); group; group = tryNextGroup(ordered)) inOrder.push(group.start); expect(inOrder).toEqual([1000n, 2000n]); } }); @@ -1099,7 +1100,7 @@ test("nextGroup skips late arrivals", async () => { producer.createGroup(5n); - const first = await track.nextGroup(); + const first = await nextGroup(track); expect(first?.start).toBe(5n); // Late arrivals with sequence <= last returned are skipped. @@ -1107,7 +1108,7 @@ test("nextGroup skips late arrivals", async () => { producer.createGroup(4n); producer.createGroup(7n); - const next = await track.nextGroup(); + const next = await nextGroup(track); expect(next?.start).toBe(7n); }); @@ -1118,8 +1119,8 @@ test("nextGroup returns buffered groups in sequence", async () => { producer.createGroup(3n); producer.createGroup(5n); - expect((await track.nextGroup())?.start).toBe(3n); - expect((await track.nextGroup())?.start).toBe(5n); + expect((await nextGroup(track))?.start).toBe(3n); + expect((await nextGroup(track))?.start).toBe(5n); }); test.each([false, true])("a reordered tail keeps the group PTS drift verdict (B-frame: %s)", async (reordered) => { @@ -1199,13 +1200,13 @@ test("the latency budget skips a buffered timeline on either cursor", async () = } expect((await arrival.recvGroup())?.start).toBe(2000n); - expect((await ordered.nextGroup())?.start).toBe(2000n); + expect((await nextGroup(ordered))?.start).toBe(2000n); // The budget is the only gate: one that spans the backlog bursts it in order. const replay = producer.subscribe({ delay: { max: Duration.millis(30_000) } }).ordered(); - expect((await replay.nextGroup())?.start).toBe(0n); - expect((await replay.nextGroup())?.start).toBe(1000n); - expect((await replay.nextGroup())?.start).toBe(2000n); + expect((await nextGroup(replay))?.start).toBe(0n); + expect((await nextGroup(replay))?.start).toBe(1000n); + expect((await nextGroup(replay))?.start).toBe(2000n); }); // A frameless successor is not content, so the next started group bounds the group before @@ -1288,7 +1289,7 @@ for (const take of ["nextGroup", "tryNextGroup"] as const) { // The frame path enters group 0; a direct take then claims group 1. expect((await track.readFrame())?.group).toBe(0n); - expect((await track[take]())?.start).toBe(1n); + expect((await track[take]())?.group?.start).toBe(1n); // The frame path must not resume group 0 behind the cursor: it continues at 2. const next = await track.readFrame(); @@ -1440,19 +1441,19 @@ test("the ordered cursor sheds a stale backlog", async () => { // The whole backlog is already buffered, so no read ever blocks on it: without the // budget here the cursor would replay four seconds of history at 1x and stay behind. const live = producer.subscribe().ordered(); - expect((await live.nextGroup())?.start).toBe(3000n); + expect((await nextGroup(live))?.start).toBe(3000n); // Only what is provably too old goes. Group 0 reaches 1s, a full 2s behind the 3s // edge; group 1000 reaches 2s and could still present inside a 1.5s budget. const bounded = producer.subscribe({ delay: { max: Duration.millis(1500) } }).ordered(); - expect((await bounded.nextGroup())?.start).toBe(1000n); - expect((await bounded.nextGroup())?.start).toBe(2000n); - expect((await bounded.nextGroup())?.start).toBe(3000n); + expect((await nextGroup(bounded))?.start).toBe(1000n); + expect((await nextGroup(bounded))?.start).toBe(2000n); + expect((await nextGroup(bounded))?.start).toBe(3000n); // A budget spanning the history still bursts it in full, gap-free. const replay = producer.subscribe({ delay: { max: Duration.millis(30_000) } }).ordered(); for (const key of [0n, 1000n, 2000n, 3000n]) { - expect((await replay.nextGroup())?.start).toBe(key); + expect((await nextGroup(replay))?.start).toBe(key); } }); @@ -2208,7 +2209,7 @@ test.each(["arrival", "ordered"] as const)("subscription bounds stay reader-loca ranges: [{ start: { time: 1n }, end: { time: 2n } }], }); const ordered = order === "ordered" ? subscriber.ordered() : undefined; - const read = () => (ordered ? ordered.nextGroup() : subscriber.recvGroup()); + const read = () => (ordered ? nextGroup(ordered) : subscriber.recvGroup()); try { for (let key = 0n; key < 5n; key++) producer.createGroup(key); expect((await everything.recvGroup())?.start).toBe(0n); @@ -2368,10 +2369,10 @@ test("local cursor bounds can skip, pause, and release buffered groups", async ( for (let key = 0n; key < 5n; key++) producer.createGroup(key); track.withRange({ start: { included: 1n }, end: { excluded: 3n } }); - expect((await track.nextGroup())?.start).toBe(1n); - expect((await track.nextGroup())?.start).toBe(2n); + expect((await nextGroup(track))?.start).toBe(1n); + expect((await nextGroup(track))?.start).toBe(2n); - const pending = track.nextGroup(); + const pending = nextGroup(track); expect(await Promise.race([pending, Promise.resolve("pending")])).toBe("pending"); track.withRange({ start: { included: 4n }, end: { excluded: 5n } }); @@ -2535,7 +2536,7 @@ test("the ordered and arrival cursors are independent", async () => { const arrival = producer.subscribe({ delay: { max: Duration.millis(5000) } }); producer.createGroup(5n); - expect((await ordered.nextGroup())?.start).toBe(5n); + expect((await nextGroup(ordered))?.start).toBe(5n); // A late seq 3 is skipped by the ordered cursor, which has already passed it, but the // arrival cursor has both buffered and still delivers each exactly once. @@ -2565,8 +2566,8 @@ test("the first group read commits the cursor and refuses the other order", asyn const ordered = inert.ordered(); expect(inert.recvGroup()).rejects.toThrow("sequence order"); expect(() => inert.ordered()).toThrow("sequence order"); - expect((await ordered.nextGroup())?.start).toBe(3n); - expect((await ordered.nextGroup())?.start).toBe(5n); + expect((await nextGroup(ordered))?.start).toBe(3n); + expect((await nextGroup(ordered))?.start).toBe(5n); }); // Datagrams are a separate cursor on either handle, so reading them must not commit @@ -2576,7 +2577,7 @@ test("nextGroup returns undefined when track closes", async () => { const track = producer.subscribe().ordered(); producer.finish(); producer.close(); - expect(await track.nextGroup()).toBeUndefined(); + expect(await nextGroup(track)).toBeUndefined(); }); // A clean close ends a pending ordered read without erasing beyond-cap frames. @@ -2591,23 +2592,23 @@ test("a closed track still delivers a group parked above the cap once the cap is } track.withRange({ end: { excluded: 2n } }); - expect((await track.nextGroup())?.start).toBe(0n); - expect((await track.nextGroup())?.start).toBe(1n); + expect((await nextGroup(track))?.start).toBe(0n); + expect((await nextGroup(track))?.start).toBe(1n); // Group 2 parks while open; a clean close completes the current range. - const parked = track.nextGroup(); + const parked = nextGroup(track); producer.finish(); producer.close(); expect(await parked).toBeUndefined(); // Raising the cap after close releases the buffered group, frames intact. track.withRange({ end: { excluded: 3n } }); - const released = await track.nextGroup(); + const released = await nextGroup(track); expect(released?.start).toBe(2n); expect(await released?.readString()).toBe("frame-2"); // Drained and closed: now it's finished. - expect(await track.nextGroup()).toBeUndefined(); + expect(await nextGroup(track)).toBeUndefined(); }); // 0 is the only encoding for "nothing produced"; an abort declares no boundary at all. @@ -3027,7 +3028,7 @@ for (const ordered of [false, true]) { const producer = new TrackProducer("test"); const subscriber = producer.subscribe({ delay: { max: Duration.millis(60_000) } }); const track = ordered ? subscriber.ordered() : subscriber; - const receive = () => ("nextGroup" in track ? track.nextGroup() : track.recvGroup()); + const receive = () => ("nextGroup" in track ? nextGroup(track) : track.recvGroup()); try { producer.finishAt({ group: 3n, frame: 0 }); const waiting = receive(); @@ -3217,7 +3218,7 @@ test("an abort keeps finished groups for a slow reader, then reports it", async const boom = new Error("boom"); producer.abort(boom); - for (const next of [() => arrival.recvGroup(), () => ordered.nextGroup()]) { + for (const next of [() => arrival.recvGroup(), () => nextGroup(ordered)]) { for (let i = 0; i < 2; i++) { const group = await next(); expect(group?.start).toBe(BigInt(i)); @@ -3240,7 +3241,7 @@ test("an abort after the declared end settles ends clean", async () => { producer.finishAt({ group: 2n, frame: 0 }); producer.abort(new Error("boom")); - for (const next of [() => arrival.recvGroup(), () => ordered.nextGroup()]) { + for (const next of [() => arrival.recvGroup(), () => nextGroup(ordered)]) { expect((await next())?.start).toBe(0n); expect((await next())?.start).toBe(1n); expect(await next()).toBeUndefined(); @@ -3360,7 +3361,7 @@ test("an abort leaves a group already taken readable, then reports the abort", a const arrival = producer.subscribe({ delay: { max: Duration.millis(10_000) } }); const ordered = producer.subscribe({ delay: { max: Duration.millis(10_000) } }).ordered(); hooks.appendNext(producer).writeFrame(textFrame("held")); - const held = [await arrival.recvGroup(), await ordered.nextGroup()]; + const held = [await arrival.recvGroup(), await nextGroup(ordered)]; const boom = new Error("boom"); producer.abort(boom); @@ -4968,7 +4969,7 @@ for (const refresh of [undefined, 0]) { const subscriber = producer.subscribe(); const ordered = subscriber.ordered(); const group = hooks.appendNext(producer); - const consumer = await ordered.nextGroup(); + const consumer = await nextGroup(ordered); if (!consumer) throw new Error("missing group"); for (let index = 0; index < 40; index++) group.writeFrame({ payload: new Uint8Array(1024 * 1024), timestamp: Timestamp.unscaled(group.start) }); @@ -4990,7 +4991,7 @@ test("reading a shed frame head requests refresh", async () => { const subscriber = producer.subscribe(); const ordered = subscriber.ordered(); const group = hooks.appendNext(producer); - const consumer = await ordered.nextGroup(); + const consumer = await nextGroup(ordered); if (!consumer) throw new Error("missing group"); const MiB = 1024 * 1024; const frame = group.createFrame({ size: 40 * MiB, timestamp: Timestamp.unscaled(group.start) }); @@ -5025,9 +5026,9 @@ test("a failed track keeps its history", async () => { await expect(arrival.recvGroup()).rejects.toBe(failed); const ordered = producer.subscribe(replay).ordered(); - expect((await ordered.nextGroup())?.start).toBe(0n); - expect((await ordered.nextGroup())?.start).toBe(1n); - await expect(ordered.nextGroup()).rejects.toBe(failed); + expect((await nextGroup(ordered))?.start).toBe(0n); + expect((await nextGroup(ordered))?.start).toBe(1n); + await expect(nextGroup(ordered)).rejects.toBe(failed); // The nonblocking reads end the same way. const polled = producer.subscribe(replay); @@ -5035,9 +5036,9 @@ test("a failed track keeps its history", async () => { expect(polled.tryRecvGroup()?.start).toBe(1n); expect(() => polled.tryRecvGroup()).toThrow(failed); const polledOrdered = producer.subscribe(replay).ordered(); - expect(polledOrdered.tryNextGroup()?.start).toBe(0n); - expect(polledOrdered.tryNextGroup()?.start).toBe(1n); - expect(() => polledOrdered.tryNextGroup()).toThrow(failed); + expect(tryNextGroup(polledOrdered)?.start).toBe(0n); + expect(tryNextGroup(polledOrdered)?.start).toBe(1n); + expect(() => tryNextGroup(polledOrdered)).toThrow(failed); }); // `fail` ends where `finish` would, after the highest group written, so a late group below it is diff --git a/js/net/src/track.ts b/js/net/src/track.ts index 1c5ea22ddb9..1fd95628a10 100644 --- a/js/net/src/track.ts +++ b/js/net/src/track.ts @@ -83,6 +83,19 @@ function taken(read: () => Recv, ended: () => undefined): GroupConsumer | undefi } } +/** What an {@link Ordered} read returns next. Mirrors the Rust `track::Item`. */ +export type Item = + /** A group, with a higher key than any group or gap returned before. */ + | { kind: "group"; group: GroupConsumer } + /** + * Groups `[start, end)` this reader gave up on, which it will not return, with what a read of + * them would have ended with. `group` is absent, so `item?.group` reads a group or nothing. + */ + | { kind: "gap"; start: bigint; end: bigint; error: Error; group?: never }; + +// What an ordered read found: an item, or the same idle, end, and error as a group read. +type ItemRecv = Item | { kind: "idle" } | { kind: "done" } | { kind: "error"; error: Error }; + // The unset priority, the midpoint of the signed range: moq-lite carries it as 128 and // moq-transport as 127, one urgency on both. const DEFAULT_PRIORITY = 0; @@ -972,6 +985,8 @@ let mayLand: (producer: Producer, land: Land) => boolean; // static block. let resubscribe: (producer: Producer) => void; let owedRuns: (producer: Producer, start: bigint, end: bigint) => Iterable; +// Whether a wire subscription feeds the producer, so it owes every group it has not accounted for. +let wireFed: (producer: Producer) => boolean; let owedGroup: (producer: Producer, start: bigint, end: bigint) => { key: bigint; folds?: Instant } | undefined; let fillEdge: (producer: Producer) => bigint | undefined; let sourceStart: (producer: Producer) => bigint | "pending" | undefined; @@ -1065,8 +1080,8 @@ let fillsOf: (producer: Producer) => FillState; // assigned in the class's static block. let makeOrdered: (subscriber: Subscriber) => Ordered; let ordered_: { - nextGroup(subscriber: Subscriber): Promise; - tryNextGroup(subscriber: Subscriber): Recv; + nextItem(subscriber: Subscriber): Promise; + tryItem(subscriber: Subscriber): ItemRecv; ended(subscriber: Subscriber): undefined; readFrame(subscriber: Subscriber): Promise<({ group: bigint; frame: number } & Frame) | undefined>; readString(subscriber: Subscriber): Promise; @@ -1482,6 +1497,7 @@ export class Producer { } }; mayLand = (producer, land) => producer.#landable(land) !== undefined; + wireFed = (producer) => producer.#wire !== undefined; owedRuns = (producer, start, end) => { if (!producer.#wire) return []; const feed = producer.#feedStart(); @@ -2611,6 +2627,21 @@ type Drift = { end?: bigint; }; +// An ordered read's state, mirroring the Rust `Ordered`: a group read and held back because a gap +// below it goes first, the gaps found and not returned yet (sorted and disjoint), and one past +// the highest key returned, as a group or the end of a gap. +type Items = { held?: GroupConsumer; gaps: DropRun[]; at: bigint }; + +// A group that landed after an ordered read passed its key. +function late(): Hole { + return { error: new StreamError(StreamCode.Old, { message: "group landed after the read passed it" }) }; +} + +// A group missing its head that no fill could serve. +function headless(): Hole { + return { error: new StreamError(StreamCode.NotFound, { message: "group head never served" }) }; +} + // The successor a handed-out group was last judged by, so the group stays judgeable once the // cache evicts both. Each reader keeps its own, so the memory is bounded by the groups held. type Superseded = { successor?: Successor }; @@ -2754,6 +2785,8 @@ export class Subscriber { coverage?: Coverage; }; #reported = new Runs(sameReport); + // What an ordered read owes before its next group; unset before its first read. See #tryItem. + #items?: Items; // The group the frame-level helpers are currently draining, acquired through the // key cursor so frame reads and {@link Ordered.nextGroup} share one floor. #frameGroup?: GroupConsumer; @@ -4109,8 +4142,8 @@ export class Subscriber { // The key cursor lives here (it shares the buffer and the drift anchor with // the arrival cursor); `Ordered` is the handle that reaches it. ordered_ = { - nextGroup: (subscriber) => subscriber.#nextGroup(), - tryNextGroup: (subscriber) => subscriber.#tryNextGroup(), + nextItem: (subscriber) => subscriber.#nextItem(), + tryItem: (subscriber) => subscriber.#tryItem(), ended: (subscriber) => subscriber.#ended(), readFrame: (subscriber) => subscriber.#readFrame(), readString: (subscriber) => subscriber.#readString(), @@ -4774,12 +4807,13 @@ export class Subscriber { } // The key cursor behind {@link Ordered}, which owns the only public door to it. - async #nextGroup(): Promise { + async #nextItem(): Promise { for (;;) { - const recv = this.#tryNextGroup(); + const recv = this.#tryItem(); switch (recv.kind) { case "group": - return recv.group; + case "gap": + return recv; case "done": return this.#ended(); case "error": @@ -4789,6 +4823,158 @@ export class Subscriber { } } + // The next group in key order, past any gap, for the frame helpers. + async #nextGroup(): Promise { + for (;;) { + const item = await this.#nextItem(); + if (!item || item.kind === "group") return item?.group; + } + } + + // The synchronous half of #nextItem: the next group, or a gap the read gave up on below it, + // as the Rust `Ordered::poll_item` merges them. Every gap goes out before the end. + #tryItem(): ItemRecv { + let items = this.#items; + if (!items) { + items = this.#items = { gaps: [], at: 0n }; + // The drop record starts before the first read, so the cursor keeps what it gives up. + this.#findGaps(items); + } + const read = this.#readHeld(items); + this.#findGaps(items); + switch (read.kind) { + case "group": { + const key = read.group.start; + const lowest = this.#lowestGap(items); + // The gap lies wholly below it, or around it: the part below goes first. + if (lowest && lowest.span.start < key) { + // What lies above the group, or above the run when it ends before it, waits. + const resume = lowest.span.end <= key ? lowest.span.end : key + 1n; + const below = { start: lowest.span.start, end: min(lowest.span.end, key) }; + items.held = read.group; + return this.#takeGap(items, lowest.index, below, resume); + } + // A group handed out is no gap, even one a drop also named, as a cut group is. + if (lowest && lowest.span.start === key) this.#cutGap(items, lowest.index, key, key + 1n); + items.at = max(items.at, key + 1n); + return read; + } + case "done": + case "error": { + const lowest = this.#lowestGap(items); + if (lowest) return this.#takeGap(items, lowest.index, lowest.span, lowest.span.end); + return read; + } + case "drop": + // Only a read with dispositions reports a drop, which this one finds through the record. + throw new Error("an ordered read took a drop"); + default: { + // What the read still owes lies above the gap, so the gap goes first. + const lowest = this.#lowestGap(items); + if (!lowest) return { kind: "idle" }; + const owed = this.nextInRange(items.at); + const ready = lowest.span.start <= items.at || owed === undefined || owed >= lowest.span.start; + return ready ? this.#takeGap(items, lowest.index, lowest.span, lowest.span.end) : { kind: "idle" }; + } + } + } + + // The group held behind a gap, while the bounds still cover it, else the cursor's next. A group + // read is settled, so no later cut or drop of it is a gap. + #readHeld(items: Items): Recv { + const held = items.held; + if (held) { + items.held = undefined; + if (this.#covered(held.start, held.start + 1n).length > 0) return { kind: "group", group: held }; + // The bounds moved off it. With nothing they cover above, it waits for them to widen again; + // otherwise the read passes it. + if (this.#covered(held.start, UNBOUNDED).length === 0) { + items.held = held; + return { kind: "idle" }; + } + held.close(); + } + const read = this.#tryNextGroup(); + if (read.kind === "group") this.#settled(read.group.start, read.group.start + 1n); + return read; + } + + // The parts of `[start, end)` this reader's ranges and bounds cover now. + #covered(start: bigint, end: bigint): Run[] { + const cursor = this.#cursor.peek(); + const from = max(start, cursor.start); + const to = cursor.end === undefined ? end : min(end, cursor.end); + if (from >= to) return []; + if (this.#resume) return this.#resume.runs(from, to) ?? [{ start: from, end: to }]; + return this.#window.runs(from, to); + } + + // Take every run the record gave up into the gaps waiting, in whatever order they come. A drop + // replaces what it overlaps, and a skip was never a group, so it removes them. + #findGaps(items: Items): void { + for (let dropped = this.#tryDrop(); dropped; dropped = this.#tryDrop()) { + items.gaps = dropped.skip + ? removeRun(items.gaps, dropped.start, dropped.end) + : insertDrop(items.gaps, dropped.start, dropped.end, { error: dropped.error }); + } + } + + // The lowest gap waiting that the bounds cover, as its index and the first part of it they cover, + // since they may have moved since it was found. A gap they exclude waits, in case they widen. + #lowestGap(items: Items): { index: number; span: Run } | undefined { + for (let index = 0; index < items.gaps.length; index++) { + const gap = items.gaps[index]; + const [span] = this.#covered(gap.start, gap.end); + if (span) return { index, span }; + } + return undefined; + } + + // Take `given` from the gap at `index` as an item, which the read has now moved past. What lies + // below `given`, which the bounds leave out, and from `resume` on stay gaps. + #takeGap(items: Items, index: number, given: Run, resume: bigint): Item { + const error = this.#cutGap(items, index, given.start, resume); + items.at = max(items.at, given.end); + // Told once: no later drop of these keys is a gap again. + this.#settled(given.start, given.end); + return { kind: "gap", start: given.start, end: given.end, error }; + } + + // Remove `[from, resume)` from the gap at `index`, returning its error. + #cutGap(items: Items, index: number, from: bigint, resume: bigint): Error { + const gap = items.gaps[index]; + const kept: DropRun[] = []; + if (gap.start < from) kept.push({ ...gap, end: from }); + if (gap.end > resume) kept.push({ ...gap, start: resume }); + items.gaps.splice(index, 1, ...kept); + return gap.error; + } + + // Record `[start, end)` as settled: handed out, or told as a gap. + #settled(start: bigint, end: bigint): void { + this.#reported.set(start, end, { start, end, kind: "settled" }); + } + + // The key cursor passes `[start, end)` to hand out the group at `end`. On a wire-fed copy each + // key there no group or drop accounts for was owed and given up, whether the budget convicted + // it or the tail's grace folded it, so it is stale. Below the first group passed is where the + // read joined, which is no gap. + #passOwed(start: bigint, end: bigint, drift: Drift): void { + const producer = this.#state.producer; + if (start >= end || this.#nextKey === 0n || !this.#dropsSeen || !producer || !wireFed(producer)) return; + const drops = this.#state.drops; + for (const run of this.#window.runs(start, end)) { + for (const owed of runGaps(drops.overlapping(run.start, run.end), run.start, run.end)) { + this.#giveUp(owed, staleHole(drift.budget)); + } + } + } + + // Keep a run the key cursor gave up, once the drop record started, so a read reports it. + #giveUp(run: Run, hole: Hole): void { + if (this.#dropsSeen) this.#pending = insertDrop(this.#pending, run.start, run.end, hole); + } + // A missing group the subscription still owes holds sequence order until it lands, // is accounted for, or the same drift budget as a buffered group gives up on it. #waitOwed(start: bigint, end: bigint, drift: Drift): boolean { @@ -4850,7 +5036,13 @@ export class Subscriber { const groups = this.#state.groups.peek(); const cursor = this.#cursor.peek(); let start = max(cursor.start, this.#nextKey); - while (groups.length > 0 && groups[0].start < start) groups.shift()?.close(); + // A group landing after the read passed its key is old: the read never goes back. + for (let group = groups[0]; group && group.start < start; group = groups[0]) { + groups.shift(); + group.close(); + // The record tells nothing twice, so a key already handed out or given up stays told. + this.#giveUp({ start: group.start, end: group.start + 1n }, late()); + } // One anchor for the whole pass, so walking a backlog off stays linear. const drift = this.#drift(); @@ -4866,6 +5058,7 @@ export class Subscriber { // Every frame this group could still hold is past the budget, so keep // scanning: one pass walks a whole backlog off rather than replaying it. if (this.#staleAt(group.start, drift)) { + this.#giveUp({ start: group.start, end: group.start + 1n }, staleHole(drift.budget)); const passed = this.#nextKey; this.#pass(groups, index); // The cursor passed what lies below it, which a fill no longer owes this reader. @@ -4886,6 +5079,7 @@ export class Subscriber { return { kind: "idle" }; } // Given up: past it, as past any group no fill can serve. + this.#giveUp({ start: group.start, end: group.start + 1n }, headless()); const passed = this.#nextKey; this.#pass(groups, index); this.#stoppedReading(passed, this.#nextKey); @@ -4894,6 +5088,7 @@ export class Subscriber { group.close(); continue; } + this.#passOwed(start, group.start, drift); this.#pass(groups, index); this.#handOut(group.start, true); return { kind: "group", group: this.#guard(group) }; @@ -5031,7 +5226,8 @@ export class Subscriber { * Created by {@link Subscriber.ordered}, which takes the subscription over: the two * cursors draw from one buffer, so a track is read one way or the other and never both. * Every group this returns has a higher key than the last, so a late arrival is - * skipped rather than delivered out of turn. + * reported as a gap rather than delivered out of turn, as is every group the read gives up on + * (see {@link Ordered.nextGroup}). * * `delay.max` applies as this cursor reads, exactly as it does on the arrival cursor: a * group is skipped once its reach, where its immediate successor begins, is that far @@ -5115,29 +5311,41 @@ export class Ordered { } /** - * Return the next group with a strictly-greater sequence number than the last returned. + * The next group with a higher key than any returned before, or a gap this reader gave up on + * below the next group, as the Rust `next_group` returns. Mirrors its `Item`. * - * Late arrivals (key at or below the last returned) are silently skipped, as is a - * group whose every frame is further behind the live edge than `delay.max` (the default - * subscription's zero keeps only what nothing newer has superseded). Honors the bounds set by - * {@link withRange}. Like {@link Subscriber.recvGroup}, a read whose ranges all end - * finishes once nothing in them is left to deliver. Later reads return `undefined` - * immediately too; widening the ranges with {@link update} reads on above the last key returned. + * A gap is every group the publisher or a relay dropped, the transport evicted, `delay.max` + * aged out (the default subscription's zero keeps only what nothing newer has superseded), a + * fill could not find, or that landed after the read passed its key. It carries the keys it + * spans and is returned once, after any group the read still owes below it and before the + * next group above it, or when the track ends. Keys the publisher declared skipped were never + * groups, so they are no gap, and nor is a key a local track never produced. Honors the bounds + * set by {@link withRange}. Like {@link Subscriber.recvGroup}, a read whose ranges all end + * finishes once nothing in them is left to deliver. Later reads return `undefined` immediately + * too; widening the ranges with {@link update} reads on above the last key returned. */ - nextGroup(): Promise { - return ordered_.nextGroup(this.#subscriber); + nextGroup(): Promise { + return ordered_.nextItem(this.#subscriber); } /** - * Take the next group as {@link nextGroup} would, without waiting: `undefined` when nothing - * is deliverable right now, which is not by itself the end of the track. Mirrors the Rust + * Take the next item as {@link nextGroup} would, without waiting: `undefined` when nothing + * is ready right now, which is not by itself the end of the track. Mirrors the Rust * `poll_next_group`. */ - tryNextGroup(): GroupConsumer | undefined { - return taken( - () => ordered_.tryNextGroup(this.#subscriber), - () => ordered_.ended(this.#subscriber), - ); + tryNextGroup(): Item | undefined { + const recv = ordered_.tryItem(this.#subscriber); + switch (recv.kind) { + case "group": + case "gap": + return recv; + case "error": + throw recv.error; + case "done": + return ordered_.ended(this.#subscriber); + default: + return undefined; + } } /** diff --git a/js/net/src/untimed.test.ts b/js/net/src/untimed.test.ts index f3722e5b715..fceaa3315a3 100644 --- a/js/net/src/untimed.test.ts +++ b/js/net/src/untimed.test.ts @@ -12,6 +12,7 @@ import { Producer as OriginProducer } from "./origin.ts"; import * as Path from "./path.ts"; import { Timescale, Timestamp } from "./time.ts"; import { wireOf } from "./wire.ts"; +import { nextGroup } from "./ordered.test-util.ts"; const url = new URL("https://localhost:4443/test"); @@ -72,7 +73,7 @@ async function roundTrip(wire: Wire, timescale: Timescale | undefined, timestamp const remote = wireOf(client).consume(Path.from("test")); const subscriber = remote.track("video").subscribe(); const info = await subscriber.info(); - const group = await subscriber.ordered().nextGroup(); + const group = await nextGroup(subscriber.ordered()); const frames = []; for (let frame = await group?.readFrame(); frame; frame = await group?.readFrame()) frames.push(frame); @@ -92,7 +93,7 @@ async function republish(input: BroadcastConsumer): Promise { void (async () => { try { const groups = subscription.ordered(); - for (let group = await groups.nextGroup(); group; group = await groups.nextGroup()) { + for (let group = await nextGroup(groups); group; group = await nextGroup(groups)) { // The same group, so a scale-less frame's key still names it. const out = video.createGroup(group.start); for (let frame = await group.readFrame(); frame; frame = await group.readFrame()) out.writeFrame(frame); @@ -152,7 +153,7 @@ test("a forwarded untimed track stays untimed", async () => { const remote = wireOf(subscriber).consume(Path.from("test")); const track = remote.track("video").subscribe(); expect((await track.info()).timescale).toBeNull(); - const frame = await (await track.ordered().nextGroup())?.readFrame(); + const frame = await (await nextGroup(track.ordered()))?.readFrame(); expect(frame?.payload).toEqual(new Uint8Array([7])); expect(frame?.timestamp).toEqual(Timestamp.unscaled(0n)); diff --git a/js/publish/bench/audio-page.ts b/js/publish/bench/audio-page.ts index cf7e9a64d6d..fa2ea13f1ac 100644 --- a/js/publish/bench/audio-page.ts +++ b/js/publish/bench/audio-page.ts @@ -132,7 +132,7 @@ async function measure(tracks: number, seconds: number, onDemand: boolean) { const catchup = performance.now() - joining; for (const subscriber of subscribers) { const reader = subscriber.ordered(); - const group = await reader.nextGroup(); + const group = (await reader.nextGroup())?.group; const frame = await group?.readFrame(); if (!frame) throw new Error("missing retained audio"); const timestamp = Moq.Varint.decode(frame.payload)[0]; diff --git a/js/publish/src/announce.test.ts b/js/publish/src/announce.test.ts index 8c663f512db..f415f894d80 100644 --- a/js/publish/src/announce.test.ts +++ b/js/publish/src/announce.test.ts @@ -96,7 +96,7 @@ test("a subscriber arriving at announce time sees every rendition in its first c const net = env.broadcast.net.peek(); if (!net) throw new Error("expected a network producer once connected"); const subscriber = net.track(Broadcast.CATALOG_TRACK).subscribe({ delay: { max: null } }); - const group = await subscriber.ordered().nextGroup(); + const group = (await subscriber.ordered().nextGroup())?.group; // Reaching back over every group, the oldest is also the newest: nothing was published before it. expect(group?.start).toBe((await subscriber.largest())?.group); const catalog = (await group?.readJson()) as Catalog.Root; diff --git a/js/publish/src/audio/encoder.test.ts b/js/publish/src/audio/encoder.test.ts index b7e160c5f87..0ffd9fd7f69 100644 --- a/js/publish/src/audio/encoder.test.ts +++ b/js/publish/src/audio/encoder.test.ts @@ -1360,7 +1360,7 @@ test.each([undefined, "off", "all"] as const)( expect(encoder.out.active.peek()).toBe(true); await push(3); - const group = await late.ordered().nextGroup(); + const group = (await late.ordered().nextGroup())?.group; if (!group) throw new Error("expected a group"); const frame = await group.readFrame(); if (!frame) throw new Error("expected a frame"); @@ -1482,7 +1482,7 @@ test("default audio replays the last second after three seconds without a subscr // The subscription's one second reaches back from the newest frame, 152, to 102. const reader = late.ordered(); for (let index = 102; index < 153; index++) { - const group = await reader.nextGroup(); + const group = (await reader.nextGroup())?.group; if (!group) throw new Error("expected buffered group"); const frame = await group.readFrame(); if (!frame) throw new Error("expected buffered frame"); @@ -1540,7 +1540,7 @@ for (const [name, subscription] of [ expect(encoder.out.stats.peek().frames).toBe(7 - FakeAudioEncoder.LAG); await feed.push({ timestamp: Duration.micros(150 * 20_000), channels: [new Float32Array(960)] }); await feed.drain(); - const group = await late.ordered().nextGroup(); + const group = (await late.ordered().nextGroup())?.group; const frame = await group?.readFrame(); if (!frame) throw new Error("expected a replayed frame"); expect(Moq.Varint.decode(frame.payload)[0]).toBe(143 * 20_000); @@ -1759,7 +1759,7 @@ test.each([false, true])("audio retained before a disable is encoded on demand ( expect(encoder.out.stats.peek().frames).toBe(4); const reader = late.ordered(); for (let index = 0; index < 4; index++) { - const group = await reader.nextGroup(); + const group = (await reader.nextGroup())?.group; const frame = await group?.readFrame(); if (!frame) throw new Error("expected retained frame"); expect(Moq.Varint.decode(frame.payload)[0]).toBe(index * 20_000); @@ -1822,7 +1822,7 @@ test("audio retained across a disable and re-enable is served before the break", const reader = late.ordered(); const read: [number, number][] = []; while (read.length < 6) { - const group = await reader.nextGroup(); + const group = (await reader.nextGroup())?.group; const frame = await group?.readFrame(); if (!frame) throw new Error("expected a frame"); const [timestamp, payload] = Moq.Varint.decode(frame.payload); @@ -1889,7 +1889,7 @@ test("a capture gap inside replayed audio keeps every frame on both sides of it" const reader = late.ordered(); const read: [number, number][] = []; while (read.length < 7) { - const group = await reader.nextGroup(); + const group = (await reader.nextGroup())?.group; const frame = await group?.readFrame(); if (!frame) throw new Error("expected a frame"); const [timestamp, payload] = Moq.Varint.decode(frame.payload); diff --git a/js/publish/src/broadcast.test.ts b/js/publish/src/broadcast.test.ts index 277e2e3e33c..815874146e0 100644 --- a/js/publish/src/broadcast.test.ts +++ b/js/publish/src/broadcast.test.ts @@ -381,7 +381,7 @@ test("serves no catalog until announced, so the first snapshot is the one at ann if (!net) throw new Error("expected a network producer once connected"); const subscriber = net.track(Broadcast.CATALOG_TRACK).subscribe({ delay: { max: null } }); - const group = await subscriber.ordered().nextGroup(); + const group = (await subscriber.ordered().nextGroup())?.group; // Reaching back over every group, the oldest is also the newest: nothing was published before it. expect(group?.start).toBe((await subscriber.largest())?.group); const catalog = (await group?.readJson()) as Catalog.Root; @@ -409,7 +409,7 @@ test("a re-announce continues the catalog's group sequence", async () => { if (!net) throw new Error("expected a network producer once connected"); const announced = broadcast.in.origin.peek()?.follow(broadcast.in.name.peek()); const first = net.track(Broadcast.CATALOG_TRACK).subscribe().ordered(); - const start = (await first.nextGroup())?.start; + const start = ((await first.nextGroup())?.group)?.start; if (start === undefined) throw new Error("expected the first catalog"); const instance = announced?.active.peek()?.instance; expect(instance).toBeDefined(); @@ -426,7 +426,7 @@ test("a re-announce continues the catalog's group sequence", async () => { // is past the first. expect(announced?.active.peek()?.instance).toBe(instance); expect(broadcast.net.peek()).toBe(net); - const group = await first.nextGroup(); + const group = (await first.nextGroup())?.group; expect(group?.start).toBeGreaterThan(start); const catalog = (await group?.readJson()) as Catalog.Root; expect(Object.keys(catalog.audio?.renditions ?? {})).toEqual(["audio"]); diff --git a/js/publish/src/catalog.test.ts b/js/publish/src/catalog.test.ts index 994bd5663b9..d8524060e76 100644 --- a/js/publish/src/catalog.test.ts +++ b/js/publish/src/catalog.test.ts @@ -89,7 +89,7 @@ test("catalog producer publishes every update as a snapshot group", async () => catalog.serve(track, effect); const subscriber = track.subscribe().ordered(); - const first = await subscriber.nextGroup(); + const first = (await subscriber.nextGroup())?.group; if (!first) throw new Error("expected the first snapshot"); expect(await first?.readJson()).toEqual({ sync: { clock: expect.anything() }, video: { renditions: {} } }); expect(first?.done).toBe(true); @@ -98,7 +98,7 @@ test("catalog producer publishes every update as a snapshot group", async () => c.scte35 = { splices: [] }; }); - const second = await subscriber.nextGroup(); + const second = (await subscriber.nextGroup())?.group; // Each snapshot opens a group at its timestamp, past the previous one. expect(second?.start).toBeGreaterThan(first.start); expect(await second?.readJson()).toEqual({ @@ -160,7 +160,7 @@ test("catalog producer omits the clock when the page's wall clock is unset", asy const track = new Track.Producer("catalog.json").accept({ timescale: Time.Timescale.MILLI }); catalog.serve(track, effect); const subscriber = track.subscribe().ordered(); - const group = await subscriber.nextGroup(); + const group = (await subscriber.nextGroup())?.group; expect(await group?.readJson()).toEqual({ video: { renditions: {} } }); effect.close(); } finally { diff --git a/js/publish/src/video/encoder.test.ts b/js/publish/src/video/encoder.test.ts index ae12d852d21..14ac2a6b654 100644 --- a/js/publish/src/video/encoder.test.ts +++ b/js/publish/src/video/encoder.test.ts @@ -1553,7 +1553,7 @@ test.each(["off", "all"] as const)( const groups: bigint[] = []; const firsts: number[] = []; for (let i = 0; i < (onDemand ? 1 : 2); i++) { - const group = await ordered.nextGroup(); + const group = (await ordered.nextGroup())?.group; if (!group) throw new Error("expected a group"); groups.push(group.start); const frame = await group.readFrame(); From 3b38c9a27e6719132b305e83aa4df746eae96377 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 17 Nov 2026 20:53:17 -0800 Subject: [PATCH 07/23] feat(watch,hang): browser audio takes its holes from the ordered reader Co-Authored-By: Claude Opus 5.5 --- .../src/container/consumer.ordered.test.ts | 121 ++++++++++ js/hang/src/container/consumer.ts | 227 +++++++++++++----- js/watch/src/audio/buffer.ts | 9 + js/watch/src/audio/decoder.test.ts | 32 ++- js/watch/src/audio/decoder.ts | 69 ++++-- js/watch/src/audio/playhead.test.ts | 66 ----- js/watch/src/audio/playhead.ts | 34 --- js/watch/src/audio/replay.test.ts | 52 ++-- js/watch/src/audio/replay.ts | 65 ++--- test/audio-quality/clients/js/replay.ts | 1 - 10 files changed, 397 insertions(+), 279 deletions(-) create mode 100644 js/hang/src/container/consumer.ordered.test.ts delete mode 100644 js/watch/src/audio/playhead.test.ts delete mode 100644 js/watch/src/audio/playhead.ts diff --git a/js/hang/src/container/consumer.ordered.test.ts b/js/hang/src/container/consumer.ordered.test.ts new file mode 100644 index 00000000000..f86e49d4901 --- /dev/null +++ b/js/hang/src/container/consumer.ordered.test.ts @@ -0,0 +1,121 @@ +// A consumer reading an ordered reader: the reader decides every hole, and the arrival subscription +// only feeds the estimate. +import { expect, test } from "bun:test"; +import { Duration } from "@moq/clock"; +import { Manual } from "@moq/clock/test"; +import { Time, Track } from "@moq/net"; +import { Consumer, type Read } from "./consumer.ts"; +import { encodeFrame, Format } from "./legacy.ts"; + +const flush = () => new Promise((resolve) => setImmediate(resolve)); + +// An audio track whose missing groups an unserved fill owes, as a session's feed would, read by a +// consumer whose ordered reader waits `wait` for a hole and whose arrival subscription reaches 2 s. +function setup(wait: number) { + const clock = new Manual(); + const installed = clock.install(); + const track = new Track.Producer("audio"); + const requests = track.requests(); + const ordered = track.subscribe({ delay: { min: Duration.ZERO, max: Duration.millis(wait) } }).ordered(); + const consumer = new Consumer(track.subscribe({ delay: { max: Duration.secs(2) } }), { + format: new Format("audio"), + delay: { min: Duration.ZERO, max: Duration.secs(2) }, + ordered, + }); + const reads: Read[] = []; + const reading = (async () => { + for (;;) { + const read = await consumer.next(); + if (!read) return; + reads.push(read); + } + })(); + // One finished group holding a 20 ms frame at `ms`. + const write = (sequence: bigint, ms: number) => { + const group = track.createGroup(sequence); + group.writeFrame({ + payload: encodeFrame(new Uint8Array([1]), Duration.millis(ms)), + timestamp: Time.Timestamp.fromMillis(ms), + }); + group.finish(); + }; + return { + clock, + consumer, + reads, + write, + // What was read, as `frame 20` or `gap 20+20`, in ms. + read: () => + reads.map((read) => + read.kind === "gap" + ? `gap ${read.timestamp.asMillis()}+${read.duration.asMillis()}` + : read.kind === "frame" + ? `frame ${read.frame.timestamp.asMillis()}` + : `end ${read.end.asMillis()}`, + ), + async close() { + consumer.close(); + requests.close(); + track.finish(); + track.close(); + await reading; + installed.close(); + }, + }; +} + +test("a hole is waited for as long as the ordered reader waits, then read as a gap", async () => { + const t = setup(100); + try { + t.write(0n, 0); + t.write(2n, 40); + await flush(); + expect(t.read()).toEqual(["frame 0"]); + // The consumer keeps no wait of its own: the reader's budget alone holds the group past the hole. + await t.clock.advance(Duration.millis(99)); + expect(t.read()).toEqual(["frame 0"]); + await t.clock.advance(Duration.millis(1)); + await flush(); + expect(t.read()).toEqual(["frame 0", "gap 0+40", "frame 40"]); + } finally { + await t.close(); + } +}); + +test("a group that lands within the reader's wait fills its hole", async () => { + const t = setup(100); + try { + t.write(0n, 0); + t.write(2n, 40); + await t.clock.advance(Duration.millis(50)); + t.write(1n, 20); + await flush(); + expect(t.read()).toEqual(["frame 0", "frame 20", "frame 40"]); + } finally { + await t.close(); + } +}); + +test("the estimate observes late groups the ordered reader gave up on", async () => { + // The spread after 5 s of groups 20 ms apart, every tenth landing `late` ms past its turn. + const spread = async (late: number) => { + const t = setup(50); + try { + const arrivals = Array.from({ length: 250 }, (_, i) => ({ i, at: i * 20 + (i % 10 === 5 ? late : 0) })); + arrivals.sort((a, b) => a.at - b.at); + let at = 0; + for (const arrival of arrivals) { + await t.clock.advance(Duration.millis(arrival.at - at)); + at = arrival.at; + t.write(BigInt(arrival.i), arrival.i * 20); + } + await flush(); + // The reader passed each late group long before it landed, so it plays as a gap. + if (late > 0) expect(t.read()).not.toContain("frame 100"); + return t.consumer.spread.peek(); + } finally { + await t.close(); + } + }; + expect((await spread(300)).gt(await spread(0))).toBe(true); +}); diff --git a/js/hang/src/container/consumer.ts b/js/hang/src/container/consumer.ts index ea361469e86..0b2f794c265 100644 --- a/js/hang/src/container/consumer.ts +++ b/js/hang/src/container/consumer.ts @@ -74,6 +74,14 @@ export interface ConsumerProps { * switch neither lowers nor raises {@link Consumer.spread} on its own. */ predecessor?: Consumer; + /** + * Read the media in key order from this reader of the same track instead of `track`'s arrival + * order, so it decides every hole: a missing group is a hole once the reader reports it as a gap, + * and never waited for here. Its `delay.max` is then how long a hole is waited for, so size it to + * what the player can still play late. `track` only feeds the arrival estimate, read frame by frame + * as it lands, so give it a `delay.max` reaching as far as lateness can move the estimate. + */ + ordered?: Moq.Track.Ordered; /** * The playout clock this reader feeds, such as the player's `Sync` (default: none). A missing * group whose successor starts at or before the oldest media the clock still plays could only @@ -129,6 +137,7 @@ interface Group { // and the groups past it, kept on insert so a hole reads it without scanning the backlog. late: Instant; frames: ReceivedFrame[]; // decode order + gap?: boolean; // An ordered reader gave up on groups just below this one. costs: number[]; // What each of frames holds against the max buffer empty: boolean; // no wire frame was published; empty groups mean nothing media: boolean; // a decodable (non-marker) frame was buffered @@ -197,6 +206,10 @@ function maxMicros(delay: Moq.Track.Delay): number { */ export class Consumer { #track: Moq.Track.Subscriber; + // The reader that decides every hole, when one does; `#track` then only feeds the estimate. + #ordered?: Moq.Track.Ordered; + // The ordered reader gave up on groups since the last one it returned. + #gap = false; #format: Format; #delay: Getter; #playhead?: Playhead; @@ -287,6 +300,7 @@ export class Consumer { /** Start consuming the given track, decoding frames with `props.format`. */ constructor(track: Moq.Track.Subscriber, props: ConsumerProps) { this.#track = track; + this.#ordered = props.ordered; this.#format = props.format; this.#delay = getter(props.delay ?? {}); this.#playhead = props.playhead; @@ -301,14 +315,21 @@ export class Consumer { // later raise the largest past it. The start says only once the info or a first group shows the // subscription established. Off the delivery path: a range capped below the largest never // reports one, which reports no backlog rather than stalling delivery. - this.#signals.spawn(async () => { - await race([this.#track.info().catch(() => undefined), this.#tuned]); - await this.#track.start(); - this.#joined = (await this.#track.largest())?.group; - }); - this.#signals.spawn(this.#run.bind(this)); + const ordered = this.#ordered; + if (ordered) { + this.#signals.spawn(this.#runOrdered.bind(this, ordered)); + this.#signals.spawn(this.#observe.bind(this)); + } else { + this.#signals.spawn(async () => { + await race([this.#track.info().catch(() => undefined), this.#tuned]); + await this.#track.start(); + this.#joined = (await this.#track.largest())?.group; + }); + this.#signals.spawn(this.#run.bind(this)); + } this.#signals.cleanup(() => { this.#track.close(); + this.#ordered?.close(); for (const group of this.#groups) { group.consumer.close(); } @@ -362,37 +383,41 @@ export class Consumer { consumer.close(); continue; } - const group: Group = { - consumer, - // When the group landed, not when it was pulled: a full max buffer delays pulls. - late: consumer.arrived, - frames: [], - costs: [], - empty: true, - media: false, - index: 0, - charged: 0, - }; - this.#charge(group, GROUP_COST); - - // Insert into #groups based on the group sequence number (ascending). - // This is used to cancel old groups. - let index = this.#groups.findIndex((other) => other.consumer.start > consumer.start); - if (index === -1) index = this.#groups.length; - // Each group is late from the earliest arrival among it and the groups past it. A drained - // backlog comes in sequence order, not arrival order, so an arrival can lower those below it. - const next = this.#groups.at(index); - if (next?.late.lt(group.late)) group.late = next.late; - for (let i = index - 1; i >= 0 && this.#groups[i].late.gt(group.late); i--) - this.#groups[i].late = group.late; - this.#groups.splice(index, 0, group); - // Group overhead alone can fill the max buffer, past which next() moves on from a stalled head. - if (this.#full()) { - this.#notify?.(); - this.#notify = undefined; - } + this.#add(consumer); + } + if (!this.#signals.abort.aborted) { + this.#delivered = true; + this.#settle(); + } + this.#finish(null); + } catch (err) { + this.#finish(err instanceof Error ? err : new Error(String(err))); + } + } + + // Read groups in key order from `ordered`, noting each gap it reports on the group after it. + async #runOrdered(ordered: Moq.Track.Ordered) { + try { + for (;;) { + // As #run: past the max buffer, later groups wait in the transport's cache. + while (this.#full() && this.#groups.length >= 2 && !this.#signals.abort.aborted) await this.#park(); + if (this.#signals.abort.aborted) break; - this.#signals.spawn(this.#watch.bind(this, group)); + const item = await ordered.nextGroup(); + if (!item) break; + if (item.kind === "gap") { + this.#gap = true; + continue; + } + // Delivery starts at the first group: the reader already skipped what is too stale to + // play, and waited for the groups below it that its feed owed. + if (this.#active === undefined) { + this.#tuned.set(true); + this.#active = item.group.start; + this.#starting = false; + } + this.#add(item.group, this.#gap); + this.#gap = false; } if (!this.#signals.abort.aborted) { this.#delivered = true; @@ -404,6 +429,103 @@ export class Consumer { } } + // Buffer a group in sequence order and watch it for frames. + #add(consumer: Moq.Group.Consumer, gap = false): void { + const group: Group = { + consumer, + // When the group landed, not when it was pulled: a full max buffer delays pulls. + late: consumer.arrived, + frames: [], + costs: [], + gap, + empty: true, + media: false, + index: 0, + charged: 0, + }; + this.#charge(group, GROUP_COST); + + // Insert into #groups based on the group sequence number (ascending). + // This is used to cancel old groups. + let index = this.#groups.findIndex((other) => other.consumer.start > consumer.start); + if (index === -1) index = this.#groups.length; + // Each group is late from the earliest arrival among it and the groups past it. A drained + // backlog comes in sequence order, not arrival order, so an arrival can lower those below it. + const next = this.#groups.at(index); + if (next?.late.lt(group.late)) group.late = next.late; + for (let i = index - 1; i >= 0 && this.#groups[i].late.gt(group.late); i--) this.#groups[i].late = group.late; + this.#groups.splice(index, 0, group); + // Group overhead alone can fill the max buffer, past which next() moves on from a stalled head. + if (this.#full()) { + this.#notify?.(); + this.#notify = undefined; + } + + this.#signals.spawn(this.#watch.bind(this, group)); + } + + // Feed the arrival estimate from every frame of `#track` as it lands, while an ordered reader + // delivers: late media that reader gives up on must still move the estimate, or it could never rise. + async #observe() { + try { + for (;;) { + const group = await this.#track.recvGroup(); + if (!group || this.#signals.abort.aborted) return; + this.#signals.spawn(this.#observeGroup.bind(this, group)); + } + } catch { + // The ordered reader reports how the track ended. + } + } + + async #observeGroup(group: Moq.Group.Consumer) { + let media = false; + try { + for (;;) { + const wire = await group.readFrame(); + if (!wire || this.#signals.abort.aborted) return; + // A payload that fails to decode is the ordered read's to raise. + let decoded: Frame[]; + try { + decoded = this.#format.decode(wire.payload, wire.timestamp); + } catch { + return; + } + const arrived = (wire.arrived ?? now()).since(Instant.ZERO).asMillis(); + if (this.#format.kind === "data" && decoded.length === 0) this.#declare(group.start); + for (const sample of decoded) { + const marker = this.#format.end?.(sample) !== undefined; + this.#note(group.start, marker, media, sample.timestamp, arrived); + if (!marker) media = true; + } + } + } catch { + // A group cut short has no more frames to observe. + } finally { + group.close(); + } + } + + // Observe one decoded sample of group `sequence` for the arrival estimate: media is observed, + // and a marker ahead of any media (`media` false) declares an end. + #note(sequence: bigint, marker: boolean, media: boolean, timestamp: Duration, arrived: number): void { + // Observed before any gap handling or age budget: a target derived from what survives the + // budget would only ever confirm the budget it was cut to. + if (!marker) { + if (this.#mediaSequence === undefined || sequence > this.#mediaSequence) this.#mediaSequence = sequence; + if (this.#declared !== undefined && sequence > this.#declared) { + this.#jitter.end(); + this.#declared = undefined; + } + this.#jitter.observe(arrived, timestamp.asMillis()); + const spread = this.#jitter.measured; + if (spread !== this.#spread.peek().asMillis()) this.#spread.set(Duration.millis(spread)); + } else if (!media) { + // Only a marker ahead of any media declares an end; one after it is a frame's endpoint. + this.#declare(sequence); + } + } + // Watch `group` for wire frames and its end, waking the reader. Only #look decodes, and the // watcher runs it at once rather than leave it to the next read, so buffered ranges, arrival times // and the age budget keep up while the reader is busy. Completion, faults and the pressure skip are @@ -484,9 +606,8 @@ export class Consumer { return start; } - // Note an end the publisher declared in `group`, which a later group's first frame resumes from. - #declare(group: Group): void { - const sequence = group.consumer.start; + // Note an end the publisher declared in group `sequence`, which a later group's first frame resumes from. + #declare(sequence: bigint): void { if (this.#mediaSequence !== undefined && sequence < this.#mediaSequence) return; if (this.#declared === undefined || sequence > this.#declared) this.#declared = sequence; } @@ -515,7 +636,7 @@ export class Consumer { return; } group.bare = decoded.length === 0; - if (group.bare) this.#declare(group); + if (group.bare && !this.#ordered) this.#declare(group.consumer.start); } // Decoded payloads are views of the wire payload, which stays allocated until the last of them is @@ -523,23 +644,8 @@ export class Consumer { let views = 0; for (const sample of decoded) { const marker = this.#format.end?.(sample) !== undefined; - - // Observed here, before any gap handling or age budget: a target derived from - // what survives the budget would only ever confirm the budget it was cut to. - if (!marker) { - if (this.#mediaSequence === undefined || group.consumer.start > this.#mediaSequence) - this.#mediaSequence = group.consumer.start; - if (this.#declared !== undefined && group.consumer.start > this.#declared) { - this.#jitter.end(); - this.#declared = undefined; - } - this.#jitter.observe(arrived, sample.timestamp.asMillis()); - const spread = this.#jitter.measured; - if (spread !== this.#spread.peek().asMillis()) this.#spread.set(Duration.millis(spread)); - } else if (!group.media) { - // Only a marker ahead of any media declares an end; one after it is a frame's endpoint. - this.#declare(group); - } + // Observed here, as it comes off the transport, unless #observe sees every arrival instead. + if (!this.#ordered) this.#note(group.consumer.start, marker, group.media, sample.timestamp, arrived); const frame: ReceivedFrame = { arrival, payload: sample.payload, @@ -857,6 +963,7 @@ export class Consumer { this.#error = error; this.#finish(error); this.#track.close(error); + this.#ordered?.close(error); this.#notify?.(); this.#notify = undefined; // Nothing more is read, so stop the group watchers and release their groups rather than let a @@ -947,7 +1054,10 @@ export class Consumer { const excluded = next === undefined || next >= head.consumer.start; // The groups past the hole already fill the max buffer, so it can hold none of what would arrive into it. const full = this.#full(); + // An ordered reader returns a group only once it resolved every key below it. + const decided = this.#ordered !== undefined; if ( + decided || startup || empty || contiguous || @@ -958,7 +1068,8 @@ export class Consumer { full || ended !== undefined ) { - if (!contiguous && !empty) { + // What an ordered reader gives up it reports as a gap; a key it skips without one was never a group. + if (!contiguous && !empty && (!decided || head.gap)) { this.#lost = true; if (!startup) { console.warn( diff --git a/js/watch/src/audio/buffer.ts b/js/watch/src/audio/buffer.ts index 7b3663b69d1..59d657e8200 100644 --- a/js/watch/src/audio/buffer.ts +++ b/js/watch/src/audio/buffer.ts @@ -6,6 +6,15 @@ import type { Clock, Data, End, Init, Latency, Playing, Reading, Received, Reset // The stretch's 30 ms processing window, in microseconds. @internal export const WINDOW = 30_000; +/** + * How long an ordered reader waits for a missing group before giving it up as a gap: what the ring + * holds of the delay, plus how far the ring lets audio trail the clock before skipping it, never less + * than one stretch window. A group landing any later could no longer play. + */ +export function holeWait(held: Duration, bound: Duration): Duration { + return held.add(bound.max(Duration.micros(WINDOW))); +} + // The least move, in milliseconds, of how far the worklet renders ahead of what sounds that is reported. const LEAD_STEP = 5; diff --git a/js/watch/src/audio/decoder.test.ts b/js/watch/src/audio/decoder.test.ts index 74f92a69bb8..68b028c1aba 100644 --- a/js/watch/src/audio/decoder.test.ts +++ b/js/watch/src/audio/decoder.test.ts @@ -1596,14 +1596,18 @@ async function livePlayback(burst: number) { let frame = 0; let sequence = 0n; let held: number[] = []; + let owed: Moq.Track.Requests | undefined; const ring = () => worklets.findLast((worklet) => worklet.ring && insert.mock.contexts.includes(worklet.ring)); return { sync, error: decoder.out.error, // Lose one whole group without changing the following media timestamps or arrival cadence. + // An open fill nobody serves stands in for a session's feed, which owes the group until the + // reader gives up on it. async hole() { if (held.length) throw new Error("a hole needs an empty delivery burst"); + owed ??= track.requests(); sequence++; frame++; await clock.advance(FRAME); @@ -1682,8 +1686,8 @@ it("a missing live group re-primes without clearing decoded PCM or resetting Syn const buffered = ring?.length; await playback.hole(); expect(ring?.length).toBe(buffered); - // A missing group is waited on for the subscription's max delay, as late audio could still - // arrive inside it, and skipped once the frames past it span that much. + // A missing group is waited on for what the ring holds, as late audio could still play inside + // it, and the ordered reader then reports the gap the decoder re-primes on. await playback.run(4000); expect(prime).toHaveBeenCalledTimes(1); expect(reset).not.toHaveBeenCalled(); @@ -2053,26 +2057,29 @@ it.each([false, true])("releases shared startup across a hole in queued audio (C }); // Audio may trail the clock by the stretch, or a buffered player's whole lookahead when that is longer, -// and a zero stretch turns the time stretch off in either mode. The stretch sizes nothing else: the -// subscription reaches the estimator's 2 s ceiling past the delay whatever it is. +// and a zero stretch turns the time stretch off in either mode. The subscription reaches the +// estimator's 2 s ceiling past the delay whatever the stretch is, while the ordered reader that +// delivers the audio waits a hole out for as long as the ring could still play it: the delay it holds +// plus that bound, never less than one stretch window. for (const buffered of [false, true]) { it(`bounds ${buffered ? "buffered" : "live"} audio's lag by the stretch alone`, async () => { - // The max delay each subscribe and update asked the publisher for, in order. - const asked: (Duration | null | undefined)[] = []; + // The max delay each subscription last asked for, in the order they opened. + const asked = new Map(); const subscribe = Moq.Track.Consumer.prototype.subscribe; const update = Moq.Track.Subscriber.prototype.update; const subscribes = spyOn(Moq.Track.Consumer.prototype, "subscribe").mockImplementation(function ( this: Moq.Track.Consumer, ...args: Parameters ) { - asked.push(args[0]?.delay?.max); - return subscribe.apply(this, args); + const subscriber = subscribe.apply(this, args); + asked.set(subscriber, args[0]?.delay?.max); + return subscriber; }); const updates = spyOn(Moq.Track.Subscriber.prototype, "update").mockImplementation(function ( this: Moq.Track.Subscriber, ...args: Parameters ) { - asked.push(args[0]?.delay?.max); + asked.set(this, args[0]?.delay?.max); return update.apply(this, args); }); const playback = await play(Duration.millis(100), buffered); @@ -2080,15 +2087,16 @@ for (const buffered of [false, true]) { await playback.play(12); const bound = () => worklets.at(-1)?.terms?.bound; expect(bound()).toBe(buffered ? 1000 : 200); - const reach = Duration.millis(2100); - expect(asked.at(-1)).toEqual(reach); + const budgets = (hole: number) => [Duration.millis(2100), Duration.millis(hole)]; + expect([...asked.values()].slice(-2)).toEqual(budgets(buffered ? 1100 : 300)); playback.stretch.set(Duration.millis(1500)); await microtasks(); expect(bound()).toBe(1500); + expect([...asked.values()].slice(-2)).toEqual(budgets(1600)); playback.stretch.set(Duration.ZERO); await microtasks(); expect(bound()).toBe(0); - expect(asked.at(-1)).toEqual(reach); + expect([...asked.values()].slice(-2)).toEqual(budgets(130)); } finally { subscribes.mockRestore(); updates.mockRestore(); diff --git a/js/watch/src/audio/decoder.ts b/js/watch/src/audio/decoder.ts index 4112a4c5783..374f47e5269 100644 --- a/js/watch/src/audio/decoder.ts +++ b/js/watch/src/audio/decoder.ts @@ -19,7 +19,7 @@ import { base64ToBytes } from "../base64"; import { arrivedAt, type Counter, type Key, type Received, Tally } from "../feedback"; import { type Failure, failureMoved, nextMedia, subscribeMedia } from "../media"; import { DELAY_MAX, type Sync, type Track } from "../sync"; -import { AudioBuffer } from "./buffer"; +import { AudioBuffer, holeWait } from "./buffer"; import { type DecoderConfig, decoderDescription, @@ -31,7 +31,6 @@ import { import { Handover } from "./handover"; import { bound, maxDelay, ringHold, target } from "./latency"; import { Order } from "./order"; -import { playable } from "./playhead"; // A blob: URL, or a hosted file when assets() is set; see vite-plugin-worklet. import RenderWorklet from "./render-worklet.ts?worklet"; import type { Source } from "./source"; @@ -136,7 +135,14 @@ const EMPTY: Stats = { }; // What a decode attempt reads, and where its counts go. -type Attempt = { config: DecoderConfig; failure: Signal; path: Moq.Path.Valid; key: Key }; +type Attempt = { + config: DecoderConfig; + failure: Signal; + path: Moq.Path.Valid; + key: Key; + // The same track read in key order, which decides every hole. + ordered: Moq.Track.Ordered; +}; // The newest container consumer, the path it reads, and its codec, whose estimate a replacement // continues. @@ -191,8 +197,6 @@ export class Decoder { // Audio ring bridging the main thread and the worklet. #ring = new Signal(undefined); - // How far ahead of the clock the ring renders, so what it renders sounds when due. - #output: Getter; // The context, worklet, and ring are keyed on this alone. It outlives a rendition's absence, so // the queued tail plays out and a return with the same shape reuses the graph. @@ -212,6 +216,9 @@ export class Decoder { // The subscription's min delay: the playout delay plus the warmup, where the publisher starts a // live join. #subscribeMinDelay = new Signal(Duration.ZERO); + // The ordered reader's max delay, how long it waits for a missing group before reporting a gap: + // as long as the ring could still play it, plus the warmup the subscription adds. + #readMaxDelay = new Signal(Duration.ZERO); // The container consumer's delay: the playout delay to start at and the shared budget. Its warmup // reaches the start further back, to the media the decoder primes on. #delay = new Signal({}); @@ -286,10 +293,6 @@ export class Decoder { complete, }; }); - this.#output = this.#signals.computed((effect) => { - const ring = effect.get(this.#ring); - return ring ? effect.get(ring.lead) : undefined; - }); this.#track = this.sync.track({ target: playout, startup }); this.#signals.cleanup(() => this.#track.close()); this.#identity = this.#signals.computed((effect) => { @@ -367,20 +370,25 @@ export class Decoder { // The subscription reaches the estimator's 2 s ceiling past the delay, whatever the stretch, since a // group the relay expires is never observed: a subscription cut to the target would leave the - // estimate rising one bucket at a time. The container - // consumer drops aged media at the same max delay, since it observes each frame before applying - // it, and carves out the warmup the subscription adds once it has warmed, as Rust's does. It waits - // on a missing group only for the delay, its min: past that the group would play late, and a - // reordered backlog's holes waited out to the max would read as jitter to the estimator. - // See doc/concept/audio-jitter.md. + // estimate rising one bucket at a time. The container consumer reads it only to observe every + // arrival, and drops aged media at the same max delay. + // + // The ordered reader delivering the audio decides each hole, giving up on a missing group once the + // ring could no longer play it: past what the ring holds of the delay and the stretch bound it still + // plays late audio within, which follow the delay, the stretch, and the output latency. Both carry + // the warmup, so the start reaches the media the decoder primes on. See doc/concept/audio-jitter.md. #runSubscribeMaxDelay(effect: Effect): void { const budget = this.#budget(effect); const delay = budget.delay; const max = maxDelay(budget); const warmup = Duration.millis(effect.get(this.source.out.config)?.warmup ?? 0).min(DELAY_MAX); + const ring = effect.get(this.#ring); + if (ring) effect.get(ring.output); + const held = ring ? ring.held(delay) : delay; this.#delay.set({ min: delay, max }); this.#subscribeMinDelay.set(delay.add(warmup)); this.#subscribeMaxDelay.set(max.add(warmup)); + this.#readMaxDelay.set(holeWait(held, bound(budget)).add(warmup)); } // The shared delay and max delay, and the stretch threshold the ring skips past. @@ -654,14 +662,22 @@ export class Decoder { priority: Catalog.PRIORITY.audio, delay: new Derived([this.#subscribeMinDelay, this.#subscribeMaxDelay], (min, max) => ({ min, max })), }); - if (!sub) { + // A second subscription to the same track, read in key order, delivers the audio; `sub` + // only feeds the arrival estimate. Both share one upstream request, at the wider budget. + const read = subscribeMedia(run, { + broadcast: active, + track: Catalog.track(track, identity), + priority: Catalog.PRIORITY.audio, + delay: new Derived([this.#subscribeMinDelay, this.#readMaxDelay], (min, max) => ({ min, max })), + }); + if (!sub || !read) { this.#retire(); return; } // A config the probe accepted can still fail to parse (a malformed init segment or Opus // header). Report it like a decode failure, which also retires the outgoing estimate. - const props: Attempt = { config, failure, path: active.path, key: rendition }; + const props: Attempt = { config, failure, path: active.path, key: rendition, ordered: read.ordered() }; spawnFatal(run, failure, async () => { if (config.container.kind === "cmaf") await this.#runCmafDecoder(run, sub, props); else this.#runLegacyDecoder(run, sub, props); @@ -669,7 +685,7 @@ export class Decoder { }); } - #runLegacyDecoder(effect: Effect, sub: Moq.Track.Subscriber, { config, failure, path, key }: Attempt): void { + #runLegacyDecoder(effect: Effect, sub: Moq.Track.Subscriber, { config, failure, path, key, ordered }: Attempt): void { const preSkip = config.codec === "opus" && config.description ? Util.Opus.preSkip(Util.Hex.toBytes(config.description)) : 0; this.#terminal.clear( @@ -682,7 +698,7 @@ export class Decoder { config.container.kind === "loc" ? new Container.Loc.Format("audio") : new Container.Legacy.Format(config); // Create consumer with slightly less latency than the render worklet to avoid underflowing. // TODO include JITTER_UNDERHEAD - const { consumer, read } = this.#consume(effect, sub, format, { config, path }); + const { consumer, read } = this.#consume(effect, sub, format, { config, path, ordered }); spawnFatal(effect, failure, async () => { const loaded = await Util.Libav.polyfill(hosted.url); @@ -752,7 +768,7 @@ export class Decoder { async #runCmafDecoder( effect: Effect, sub: Moq.Track.Subscriber, - { config, failure, path, key }: Attempt, + { config, failure, path, key, ordered }: Attempt, ): Promise { if (config.container.kind !== "cmaf") return; // just to help typescript @@ -776,7 +792,7 @@ export class Decoder { config.description ? Util.Hex.toBytes(config.description) : init.description, ); - const { consumer, read } = this.#consume(effect, sub, new Cmaf.Format(init), { config, path }); + const { consumer, read } = this.#consume(effect, sub, new Cmaf.Format(init), { config, path, ordered }); spawnFatal(effect, failure, async () => { const loaded = await Util.Libav.polyfill(hosted.url); @@ -935,14 +951,15 @@ export class Decoder { })); } - // Reorders groups and frames up to the shared max delay. A rename is not a cold start: the path's - // arrivals are what they were, so the estimate continues from whatever read it before. Another - // path's arrivals have nothing to do with what this one learned. + // Reads `ordered` in key order, playing each gap it reports as the hole, and observes every arrival + // on `sub`. A rename is not a cold start: the path's arrivals are what they were, so the estimate + // continues from whatever read it before. Another path's arrivals have nothing to do with what + // this one learned. #consume( effect: Effect, sub: Moq.Track.Subscriber, format: Container.Format, - { config, path }: { config: DecoderConfig; path: Moq.Path.Valid }, + { config, path, ordered }: { config: DecoderConfig; path: Moq.Path.Valid; ordered: Moq.Track.Ordered }, ): { consumer: Container.Consumer; read: Signal } { const phase = this.#phase.peek(); if (phase.kind !== "running") throw new Error("audio: a consumer opened outside a running rendition"); @@ -953,7 +970,7 @@ export class Decoder { delay: this.#delay, warmup: Duration.millis(config.warmup ?? 0).min(DELAY_MAX), predecessor: continues ? outgoing.consumer : undefined, - playhead: playable(this.sync, this.#output), + ordered, }); effect.cleanup(() => consumer.close()); this.#phase.set({ ...phase, consumer: { path, codec: config.codec, consumer } }); diff --git a/js/watch/src/audio/playhead.test.ts b/js/watch/src/audio/playhead.test.ts deleted file mode 100644 index 4a3f1048e18..00000000000 --- a/js/watch/src/audio/playhead.test.ts +++ /dev/null @@ -1,66 +0,0 @@ -import { expect, it } from "bun:test"; -import { Duration } from "@moq/clock"; -import { Manual } from "@moq/clock/test"; -import { Signal } from "@moq/signals"; -import { Sync } from "../sync"; -import { playable } from "./playhead"; - -it("reads the clock the ring renders at, less the stretch it plays late audio within", async () => { - const clock = new Manual(); - const installed = clock.install(); - const sync = new Sync({ delay: Duration.millis(300), stretch: Duration.millis(200) }); - const span = new Signal<{ start: Duration; end: Duration } | null>(null); - const audio = sync.track({ target: new Signal(Duration.millis(300)), startup: span }); - const output = new Signal(Duration.millis(40)); - const playhead = playable(sync, output); - try { - await clock.advance(Duration.ZERO); - audio.received(Duration.ZERO); - span.set({ start: Duration.ZERO, end: Duration.millis(300) }); - await clock.advance(Duration.millis(1000)); - const now = sync.now(); - if (now === undefined) throw new Error("the clock never started"); - expect(playhead.now()).toEqual(now.add(Duration.millis(40)).saturatingSub(Duration.millis(200))); - - // The trail moving is a jump, which wakes a consumer waiting on a hole. - let jumped = false; - const dispose = playhead.anchor.subscribe(() => { - jumped = true; - }); - await clock.advance(Duration.ZERO); - jumped = false; - output.set(Duration.millis(60)); - await clock.advance(Duration.ZERO); - expect(jumped).toBe(true); - expect(playhead.now()).toEqual(now.add(Duration.millis(60)).saturatingSub(Duration.millis(200))); - dispose(); - } finally { - audio.close(); - sync.close(); - installed.close(); - } -}); - -it("applies the output latency before media zero's turn, when the ring already renders it", async () => { - const clock = new Manual(); - const installed = clock.install(); - const sync = new Sync({ delay: Duration.millis(300), lookahead: Duration.millis(1000), stretch: Duration.ZERO }); - const span = new Signal<{ start: Duration; end: Duration; lead?: Duration } | null>(null); - const audio = sync.track({ target: new Signal(Duration.millis(300)), startup: span }); - const playhead = playable(sync, new Signal(Duration.millis(120))); - try { - await clock.advance(Duration.ZERO); - audio.received(Duration.ZERO); - span.set({ start: Duration.ZERO, end: Duration.millis(180), lead: Duration.millis(120) }); - await clock.advance(Duration.millis(50)); - // 70 ms short of media zero's turn, which the clock reads as zero, the ring renders 50 ms, and - // plays audio trailing it by its 30 ms window even with the stretch off. - expect(sync.now()).toEqual(Duration.ZERO); - expect(sync.position()).toBe(-70); - expect(playhead.now()).toEqual(Duration.millis(20)); - } finally { - audio.close(); - sync.close(); - installed.close(); - } -}); diff --git a/js/watch/src/audio/playhead.ts b/js/watch/src/audio/playhead.ts deleted file mode 100644 index 900233d0fe8..00000000000 --- a/js/watch/src/audio/playhead.ts +++ /dev/null @@ -1,34 +0,0 @@ -import { Duration } from "@moq/clock"; -import type * as Container from "@moq/hang/container"; -import { Derived, type Getter, Signal } from "@moq/signals"; -import type { Sync } from "../sync"; -import { WINDOW } from "./buffer"; -import { bound } from "./latency"; - -/** - * The oldest media the ring still plays, which the audio consumer reads as its clock. The ring renders - * `output` (none until known) ahead of the shared clock, so what it renders now sounds when the clock - * reaches it, and stretches audio trailing that within its {@link bound} back onto it, at least one stretch window. So a missing - * group can still play until the group past it trails the ring by more than the bound, as when a late - * burst fills the hole a moment after the group past it lands. - * - * @internal Exported for the replay harness. - */ -export function playable(sync: Sync, output: Getter = new Signal(undefined)): Container.Playhead { - // How far the oldest playable media trails the clock, in ms; negative when the output leads by more. - const trail = new Derived( - [sync.out.delay, sync.out.maxDelay, sync.in.stretch, output], - (delay, maxDelay, stretch, output) => - // The ring skips only past its bound, never less than one stretch window, even with the stretch off. - Math.max(bound({ delay, maxDelay, stretch }).asMillis(), WINDOW / 1000) - (output?.asMillis() ?? 0), - ); - return { - now: () => { - // The signed position, since before media zero's turn the ring may already render it. - const position = sync.position(); - if (position === undefined) return undefined; - return Duration.millis(Math.max(0, position - trail.peek())); - }, - anchor: new Derived([sync.anchor, trail], (anchor, trail) => ({ anchor, trail })), - }; -} diff --git a/js/watch/src/audio/replay.test.ts b/js/watch/src/audio/replay.test.ts index b40a259bd26..6d9b6d3096f 100644 --- a/js/watch/src/audio/replay.test.ts +++ b/js/watch/src/audio/replay.test.ts @@ -1,8 +1,7 @@ import { afterEach, beforeEach, describe, expect, it, type Mock, spyOn } from "bun:test"; import { Duration } from "@moq/clock"; import type * as Catalog from "@moq/hang/catalog"; -import { Track } from "@moq/net"; -import { type Arrival, answering, type Options, QUANTUM, type Quantum, replay } from "./replay"; +import { type Arrival, type Options, QUANTUM, type Quantum, replay } from "./replay"; const RATE = 48000; const CONFIG = { codec: "opus", sampleRate: RATE, numberOfChannels: 1 } as Catalog.AudioConfig; @@ -71,9 +70,10 @@ describe("replay", () => { }); it("counts each run-dry the way the player's stats do", async () => { - // One frame 200 ms late against a 100 ms target: the ring runs dry once and re-stalls to refill, - // which counts the short quantum it ran dry in and the stall after it. - const trace = paced(10, (i) => (i === 250 ? 230 : 30)).sort((a, b) => a.at - b.at); + // Ten frames held and released together, the first 200 ms late against a 100 ms target: the ring + // runs dry once and re-stalls to refill, which counts the short quantum it ran dry in and the + // stall after it. + const trace = paced(10, (i) => (i >= 250 && i < 260 ? 30 + (260 - i) * 20 : 30)).sort((a, b) => a.at - b.at); const counted = async (arrivals: Arrival[]) => { let last = 0; for await (const { underruns } of replay(arrivals, { @@ -90,19 +90,17 @@ describe("replay", () => { expect(await counted(trace)).toBeLessThanOrEqual(2); }); - it("holds newer groups behind a missing one until the max delay gives up on it", async () => { + it("holds newer groups behind a missing one until the ring could no longer play it", async () => { const trace = paced(10, () => 30).filter((arrival) => arrival.group !== 250); - // The consumer delivers in group order, so the ring runs dry for longer than the missing frame - // while the groups behind it wait. Writing arrivals straight into the ring plays straight through. - const frame = Math.ceil((20 / 1000) * (RATE / QUANTUM)); - expect( - await underruns(trace, { - rate: RATE, - config: CONFIG, - delay: Duration.millis(100), - duration: observed(10), - }), - ).toBeGreaterThan(frame); + // The consumer delivers in group order, so the ring runs dry while the groups behind the missing + // one wait, and the ordered reader gives up on it as the ring's stretch bound passes it. + const run = await underruns(trace, { + rate: RATE, + config: CONFIG, + delay: Duration.millis(100), + duration: observed(10), + }); + expect(run).toBeGreaterThan(0); expect(warn).toHaveBeenCalled(); }); @@ -449,23 +447,3 @@ describe("buffered replay against the shared clock", () => { expect(warn).not.toHaveBeenCalled(); }); }); - -describe("answering", () => { - it("names the publisher's largest group first, then each newer group, and delegates the rest", async () => { - const track = new Track.Producer("audio"); - const subscriber = answering(track.subscribe(), 5n); - try { - // A group at or below the answer is no news: the track's own largest is older than it. - track.createGroup(3n); - expect(await subscriber.largest()).toEqual({ group: 5n, frame: 0 }); - const next = subscriber.largest(); - track.createGroup(5n); - track.createGroup(9n); - expect((await next)?.group).toBe(9n); - expect(subscriber.name).toBe("audio"); - } finally { - subscriber.close(); - track.close(); - } - }); -}); diff --git a/js/watch/src/audio/replay.ts b/js/watch/src/audio/replay.ts index c059501b774..51be9e7b6a0 100644 --- a/js/watch/src/audio/replay.ts +++ b/js/watch/src/audio/replay.ts @@ -2,8 +2,8 @@ * Replay a recorded arrival trace through the player's consumer and ring on a simulated clock. * * Every frame is written into its group at the instant the trace says it arrived, and the player's - * real `Container.Consumer` decides what to deliver, wait for, and skip, at the hole wait, max delay, and - * clock the decoder gives it. Delivered frames go into the real ring, which carries on through a gap the way the decoder's + * real `Container.Consumer` decides what to deliver and skip, at the max delay the decoder gives it, + * reading the ordered reader that decides each hole at the budget the decoder gives that. Delivered frames go into the real ring, which carries on through a gap the way the decoder's * does: a gap restarts only the codec. One render quantum is read every quantum's worth of that same * clock, which is what the AudioWorklet does. A real {@link Sync} resolves the delay from the playout target the decoder * registers, measured by that same consumer from the recorded catalog config, and the ring and the @@ -23,10 +23,9 @@ import * as Container from "@moq/hang/container"; import { type Group, Time, Track } from "@moq/net"; import { Derived, Effect, Signal } from "@moq/signals"; import { type Delay, STRETCH, Sync } from "../sync"; -import { Backpressure } from "./buffer"; +import { Backpressure, holeWait } from "./buffer"; import { frameDuration } from "./config"; import { maxDelay as audioMaxDelay, bound, ringHold, target } from "./latency"; -import { playable } from "./playhead"; import { AudioRingBuffer } from "./ring-buffer"; /** An AudioWorklet render quantum, in frames. */ @@ -66,12 +65,6 @@ export interface Options { lookahead?: number; /** The configured stretch, in ms, as the element takes it (default: the element's). */ stretch?: number; - /** - * The publisher's largest group as the subscription began, which the consumer learns as a wire - * subscriber learns it from the publisher's answer. Omitted, the replay's track names its own: the - * first group to land. - */ - largest?: number; /** The rendition as the catalog described it: its advertised jitter, delay, and codec. */ config: Catalog.AudioConfig; /** @@ -184,33 +177,6 @@ const micros = (ms: number) => Math.round(ms * 1000); */ const settle = () => new Promise((resolve) => setImmediate(resolve)); -/** - * `track` answering `largest` the way a wire subscriber does once the publisher has answered: first - * the publisher's largest group as the subscription began, then each newer group as it lands. - * Everything else is the local subscriber's. - */ -export function answering(track: Track.Subscriber, largest: bigint): Track.Subscriber { - let answered = false; - return new Proxy(track, { - get(target, prop) { - if (prop !== "largest") { - const value = Reflect.get(target, prop, target); - return typeof value === "function" ? value.bind(target) : value; - } - return async () => { - if (!answered) { - answered = true; - return { group: largest, frame: 0 }; - } - for (;;) { - const next = await target.largest(); - if (!next || next.group > largest) return next; - } - }; - }, - }); -} - /** * Play `trace` in simulated real time, yielding every render quantum from the first arrival to the * end of the observation. @@ -252,15 +218,16 @@ export async function* replay(trace: Arrival[], options: Options): AsyncGenerato const maxDelay = new Derived([sync.out.delay, sync.out.maxDelay], (delay, max) => audioMaxDelay({ delay, maxDelay: max }), ); + // Fills nobody serves stand in for the recorder's feed: the ordered reader waits for a missing + // group as it would for a session's, until the group lands or its budget gives up on it. + const requests = track.requests(); const subscriber = track.subscribe({ delay: { max: WIRE_MAX_DELAY } }); - const consumer = new Container.Consumer( - options.largest === undefined ? subscriber : answering(subscriber, BigInt(options.largest)), - { - format: new Container.Legacy.Format("audio"), - delay: new Derived([sync.out.delay, maxDelay], (min, max) => ({ min, max })), - playhead: playable(sync), - }, - ); + const ordered = track.subscribe({ delay: { min: sync.out.delay.peek() } }).ordered(); + const consumer = new Container.Consumer(subscriber, { + format: new Container.Legacy.Format("audio"), + delay: new Derived([sync.out.delay, maxDelay], (min, max) => ({ min, max })), + ordered, + }); // Match the decoder: a codec constant until a delivered packet states its own duration. const signals = new Effect(); @@ -287,6 +254,14 @@ export async function* replay(trace: Arrival[], options: Options): AsyncGenerato : undefined; const audio = sync.track({ target: playout, startup }); signals.cleanup(() => audio.close()); + // The ordered reader waits a hole out as the decoder's does. A replay's ring holds the whole delay: + // it has no output. + signals.run((effect) => { + const delay = effect.get(sync.out.delay); + const max = holeWait(delay, bound({ delay, maxDelay: effect.get(sync.out.maxDelay), stretch })); + ordered.update({ delay: { min: delay, max } }); + }); + signals.cleanup(() => requests.close()); await settle(); let delay = sync.out.delay.peek(); diff --git a/test/audio-quality/clients/js/replay.ts b/test/audio-quality/clients/js/replay.ts index 6cb92752b6c..f0f20b0e1c7 100644 --- a/test/audio-quality/clients/js/replay.ts +++ b/test/audio-quality/clients/js/replay.ts @@ -141,7 +141,6 @@ for (const { row, trace } of rows) { rate, delay: "auto", config: trace.config as unknown as Catalog.AudioConfig, - largest: trace.largest, duration: trace.duration, }); let last: Reading | undefined; From 0f8006da24f21755155144e2e85e673eb62f18d4 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 17 Nov 2026 20:53:21 -0800 Subject: [PATCH 08/23] feat(net): a local track's ordered read reports a fill-owed group it gives up on Co-Authored-By: Claude Opus 5.5 --- js/net/src/ordered.test.ts | 18 ++++++++++++++++++ js/net/src/track.ts | 20 ++++++++++++-------- 2 files changed, 30 insertions(+), 8 deletions(-) diff --git a/js/net/src/ordered.test.ts b/js/net/src/ordered.test.ts index 04b2295712b..f5e27969541 100644 --- a/js/net/src/ordered.test.ts +++ b/js/net/src/ordered.test.ts @@ -182,3 +182,21 @@ test("the frame helpers read past a gap", async () => { expect((await ordered.readFrame())?.group).toBe(0n); expect((await ordered.readFrame())?.group).toBe(2n); }); + +test("a local track waits for what it asked a fill for, and reports a gap once the budget gives up", () => + withClock((clock) => { + const producer = new TrackProducer("test"); + const requests = producer.requests(); + const ordered = producer.subscribe({ delay: { max: Duration.millis(50) } }).ordered(); + put(producer, 0n); + put(producer, 2n); + expect(items(ordered)).toEqual(["group 0"]); + // Group 1 lands late, within the budget, as a group does. + put(producer, 1n); + expect(items(ordered)).toEqual(["group 1", "group 2"]); + put(producer, 4n); + expect(items(ordered)).toEqual([]); + clock.jump(Duration.millis(50)); + expect(items(ordered)).toEqual(["gap 3..4 (old)", "group 4"]); + requests.close(); + })); diff --git a/js/net/src/track.ts b/js/net/src/track.ts index 1fd95628a10..9ae775fea82 100644 --- a/js/net/src/track.ts +++ b/js/net/src/track.ts @@ -4955,17 +4955,21 @@ export class Subscriber { this.#reported.set(start, end, { start, end, kind: "settled" }); } - // The key cursor passes `[start, end)` to hand out the group at `end`. On a wire-fed copy each - // key there no group or drop accounts for was owed and given up, whether the budget convicted - // it or the tail's grace folded it, so it is stale. Below the first group passed is where the - // read joined, which is no gap. + // The key cursor passes `[start, end)` to hand out the group at `end`. Each key there that the + // track owed and no group or drop accounts for was given up, whether the budget convicted it or + // the tail's grace folded it, so it is stale. A wire-fed copy owes every key; a local track only + // what this reader asked a fill for. Below the first group passed is where the read joined, + // which is no gap. #passOwed(start: bigint, end: bigint, drift: Drift): void { const producer = this.#state.producer; - if (start >= end || this.#nextKey === 0n || !this.#dropsSeen || !producer || !wireFed(producer)) return; + if (start >= end || this.#nextKey === 0n || !this.#dropsSeen || !producer) return; + const owed = wireFed(producer) + ? this.#window.runs(start, end) + : [...intersect(this.#asked, start, end), ...intersect(this.#givenUp, start, end)]; const drops = this.#state.drops; - for (const run of this.#window.runs(start, end)) { - for (const owed of runGaps(drops.overlapping(run.start, run.end), run.start, run.end)) { - this.#giveUp(owed, staleHole(drift.budget)); + for (const run of owed) { + for (const passed of runGaps(drops.overlapping(run.start, run.end), run.start, run.end)) { + this.#giveUp(passed, staleHole(drift.budget)); } } } From 032efc45358c780469f008cc37c6b295ce78f349 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 17 Nov 2026 20:57:19 -0800 Subject: [PATCH 09/23] docs(audio-jitter): the browser leaves an audio hole to the ordered reader; lint and API reports Co-Authored-By: Claude Opus 5.5 --- doc/concept/audio-jitter.md | 21 +++++++++++++-------- js/hang/api/container.api.md | 1 + js/json/src/snapshot/snapshot.test.ts | 7 ++++--- js/net/api/index.api.md | 14 ++++++++++++-- js/net/src/broadcast.test.ts | 2 +- js/net/src/connection/reload.test.ts | 2 +- js/net/src/consume.test.ts | 2 +- js/net/src/fill.test.ts | 2 +- js/net/src/ietf/join.test.ts | 2 +- js/net/src/ietf/range.test.ts | 2 +- js/net/src/ietf/subscriber.test.ts | 2 +- js/net/src/integration.test.ts | 2 +- js/net/src/lite/connection.test.ts | 2 +- js/net/src/lite/copy_fill.test.ts | 2 +- js/net/src/lite/subscriber.test.ts | 2 +- js/net/src/resume.test.ts | 2 +- js/net/src/retention.test.ts | 2 +- js/net/src/track.test.ts | 2 +- js/net/src/untimed.test.ts | 2 +- js/publish/src/broadcast.test.ts | 2 +- js/watch/src/audio/decoder.test.ts | 1 + js/watch/src/audio/decoder.ts | 6 +++++- 22 files changed, 52 insertions(+), 30 deletions(-) diff --git a/doc/concept/audio-jitter.md b/doc/concept/audio-jitter.md index 3df5573d331..3de4119f1fb 100644 --- a/doc/concept/audio-jitter.md +++ b/doc/concept/audio-jitter.md @@ -49,12 +49,18 @@ group is observed when the stall clears. A missing group, one that has delivered no frame, is waited for only the playout delay, the subscription's `delay.min`, since past that it would play late: a reordered backlog's holes waited out to the whole budget would delay the frames behind them, which the estimator would measure as -jitter. The browser player waits less still, only until the group past the hole -trails its clock by the stretch threshold, past which the ring would skip the -hole's audio anyway: a viewer resuming behind a replayed backlog, which arrives -newest first, would otherwise hold the live audio for the backlog's oldest group, -while a late burst that fills a hole a moment after the group past it lands -still plays it. A caller that estimates keeps the budget past the target, which is why +jitter. The browser player leaves the hole to the transport: it reads its audio +through an ordered track reader whose own `delay.max` is what the ring holds of +the delay plus the stretch threshold, past which the ring would skip the hole's +audio anyway, and plays each gap that reader reports as the hole. The reader +gives up on a missing group by the same two clocks as any stale group: once the +newest frame is that far past where the group after it starts, or that group +arrived that long ago. A late burst that fills a hole a moment after the group +past it lands still plays it, and a viewer resuming behind a replayed backlog +does not hold the live audio for the backlog's oldest group. That reader's +budget is its own: a second subscription to the same track, read in arrival +order, observes every frame, so the late groups the reader gives up on are +still measured. A caller that estimates keeps the budget past the target, which is why `moq play` waits on a stalled audio group for the delay plus the estimate's 2 s ceiling. The observation is also only as honest as the caller is prompt: `read()` is timed when it resolves, so a player drains it @@ -69,8 +75,7 @@ the target: the estimate creeps up one bucket at a time while the frames it should have measured go unplayed. Both implementations subscribe with the delay plus the estimate's own 2 s ceiling, whatever the player's `stretch` setting: `moq play` through its age budget, and the browser through the audio -subscription alone, since its container consumer observes each frame before -applying the local budget. So any lateness the estimator can measure is +subscription it observes arrivals on, beside the narrower ordered one it plays. So any lateness the estimator can measure is observed at once. A buffered browser player keeps its subscription at least the delay plus its lookahead. Browser video keeps the shared budget, because a longer one fetches whole stale diff --git a/js/hang/api/container.api.md b/js/hang/api/container.api.md index 6438d36ea00..88108b5dabc 100644 --- a/js/hang/api/container.api.md +++ b/js/hang/api/container.api.md @@ -26,6 +26,7 @@ export class Consumer { export interface ConsumerProps { delay?: Signals.GetterInit; format: Format; + ordered?: Net.Track.Ordered; playhead?: Playhead; predecessor?: Consumer; warmup?: Net.Clock.Duration; diff --git a/js/json/src/snapshot/snapshot.test.ts b/js/json/src/snapshot/snapshot.test.ts index 9f0fa3c48fd..036d62592ac 100644 --- a/js/json/src/snapshot/snapshot.test.ts +++ b/js/json/src/snapshot/snapshot.test.ts @@ -679,8 +679,8 @@ test("a delta that would overflow the snapshot rolls a new one instead", async ( // Two groups, a self-contained snapshot each, rather than one whose frame 0 was evicted. const subscriber = track.subscribe({ delay: { max: REPLAY_LATENCY } }).ordered(); - expect(((await subscriber.nextGroup())?.group)?.start).toBe(0n); - expect(((await subscriber.nextGroup())?.group)?.start).toBe(1n); + expect((await subscriber.nextGroup())?.group?.start).toBe(0n); + expect((await subscriber.nextGroup())?.group?.start).toBe(1n); expect((await subscriber.nextGroup())?.group).toBeUndefined(); // The newest value is readable with no earlier frame to apply it to. @@ -762,7 +762,8 @@ test("a scale-less snapshot at a key not past the newest group is refused", asyn const ordered = track.subscribe({ delay: { max: REPLAY_LATENCY } }).ordered(); const sequences: bigint[] = []; - for (let group = (await ordered.nextGroup())?.group; group; group = (await ordered.nextGroup())?.group) sequences.push(group.start); + for (let group = (await ordered.nextGroup())?.group; group; group = (await ordered.nextGroup())?.group) + sequences.push(group.start); expect(sequences).toEqual([5n, 8n]); expect(await drain(track)).toEqual([{ n: 1 }]); }); diff --git a/js/net/api/index.api.md b/js/net/api/index.api.md index e50fdcd271e..7dafb5fc62f 100644 --- a/js/net/api/index.api.md +++ b/js/net/api/index.api.md @@ -748,6 +748,16 @@ export namespace Track { export interface InfoOptions { signal?: AbortSignal; } + export type Item = { + group: Group.Consumer; + kind: "group"; + } | { + end: bigint; + error: Error; + group?: never; + kind: "gap"; + start: bigint; + }; export type Order = "ascending" | "descending"; export class Ordered { close(abort?: Error): void; @@ -757,7 +767,7 @@ export namespace Track { isSkipped(start: bigint, end: bigint): boolean; largest(): Promise; readonly name: string; - nextGroup(): Promise; + nextGroup(): Promise; readFrame(): Promise<{ frame: number; group: bigint; @@ -765,7 +775,7 @@ export namespace Track { readJson(): Promise; readString(): Promise; get subscription(): Signals.Getter; - tryNextGroup(): Group.Consumer | undefined; + tryNextGroup(): Track.Item | undefined; update(options: Track.Subscription): void; withRange(groups: Track.Groups): this; } diff --git a/js/net/src/broadcast.test.ts b/js/net/src/broadcast.test.ts index fe1b88f607d..0e5eb31cae8 100644 --- a/js/net/src/broadcast.test.ts +++ b/js/net/src/broadcast.test.ts @@ -6,11 +6,11 @@ import * as cache from "./cache.ts"; import { NotFound, StreamCode, TooFarBehind, toStreamCode } from "./error.ts"; import { hooks } from "./internal.ts"; import { textFrame } from "./mock.ts"; +import { nextGroup } from "./ordered.test-util.ts"; import { Timescale, Timestamp } from "./time.ts"; import type { Request as TrackRequest } from "./track.ts"; import { unwanted } from "./util/demand.ts"; import { wireOf } from "./wire.ts"; -import { nextGroup } from "./ordered.test-util.ts"; // The public API mints consumers internally (Producer.consume, the wire layers); tests act // as a wire layer by subclassing, the same way lite's ConsumeBroadcast does. diff --git a/js/net/src/connection/reload.test.ts b/js/net/src/connection/reload.test.ts index afea6856654..c8391c6d79a 100644 --- a/js/net/src/connection/reload.test.ts +++ b/js/net/src/connection/reload.test.ts @@ -14,6 +14,7 @@ import { ALPN as IetfALPN } from "../ietf/version.ts"; import { hooks } from "../internal.ts"; import * as Lite from "../lite/index.ts"; import { createMockTransportPair, type MockTransport, manual, textFrame, waitFor } from "../mock.ts"; +import { nextGroup } from "../ordered.test-util.ts"; import { Producer as OriginProducer } from "../origin.ts"; import * as Path from "../path.ts"; import { Stream } from "../stream.ts"; @@ -24,7 +25,6 @@ import { type AcceptProps, accept as acceptSession } from "./index.ts"; import { Connection, resetShared } from "./pool.ts"; import { type Backoff, pumpAnnounced, Redirects, Reload, type ReloadProps } from "./reload.ts"; import type { Session } from "./session.ts"; -import { nextGroup } from "../ordered.test-util.ts"; function accept(transport: WebTransport, url: URL, props: Omit = {}) { return acceptSession({ transport, url, ...props }); diff --git a/js/net/src/consume.test.ts b/js/net/src/consume.test.ts index 0e54afd4627..5661526a030 100644 --- a/js/net/src/consume.test.ts +++ b/js/net/src/consume.test.ts @@ -5,8 +5,8 @@ import { StreamCode, StreamError } from "./error.ts"; import { WireRoute } from "./hop.ts"; import * as Instance from "./instance.ts"; import { hooks } from "./internal.ts"; -import * as Path from "./path.ts"; import { nextGroup } from "./ordered.test-util.ts"; +import * as Path from "./path.ts"; test("cache identity follows the serving announcement, preserving held tracks", async () => { const cache = new BroadcastCache(); diff --git a/js/net/src/fill.test.ts b/js/net/src/fill.test.ts index 8146664ff47..5d508910381 100644 --- a/js/net/src/fill.test.ts +++ b/js/net/src/fill.test.ts @@ -10,12 +10,12 @@ import type { Consumer as GroupConsumer } from "./group.ts"; import { hooks, staleHole } from "./internal.ts"; import * as Lite from "./lite/index.ts"; import { createMockTransportPair, groupsOf, requestedGroups } from "./mock.ts"; +import { nextGroup } from "./ordered.test-util.ts"; import { Producer as OriginProducer } from "./origin.ts"; import * as Path from "./path.ts"; import { Timescale, Timestamp } from "./time.ts"; import type { FillGroups, Producer, Requests, Subscription } from "./track.ts"; import { wireOf } from "./wire.ts"; -import { nextGroup } from "./ordered.test-util.ts"; const enc = new TextEncoder(); const dec = new TextDecoder(); diff --git a/js/net/src/ietf/join.test.ts b/js/net/src/ietf/join.test.ts index ad016e320b2..98f6f10ddaa 100644 --- a/js/net/src/ietf/join.test.ts +++ b/js/net/src/ietf/join.test.ts @@ -6,6 +6,7 @@ import { StreamCode } from "../error.ts"; import { hooks } from "../internal.ts"; import { GRACE } from "../ledger.ts"; import { createMockTransportPair, manual, settlesWithin, textFrame } from "../mock.ts"; +import { nextGroup } from "../ordered.test-util.ts"; import { Producer as OriginProducer } from "../origin.ts"; import * as Path from "../path.ts"; import { Reader, Stream, Writer } from "../stream.ts"; @@ -23,7 +24,6 @@ import { NativeSession } from "./session.ts"; import { Subscribe, SubscribeOk } from "./subscribe.ts"; import { Subscriber } from "./subscriber.ts"; import { ALPN, type IetfVersion, Version, versionName } from "./version.ts"; -import { nextGroup } from "../ordered.test-util.ts"; const VERSIONS = [Version.DRAFT_18, Version.DRAFT_20, Version.DRAFT_22] as const; const VERSION = Version.DRAFT_18; diff --git a/js/net/src/ietf/range.test.ts b/js/net/src/ietf/range.test.ts index b62e6be92bf..b2939ad2065 100644 --- a/js/net/src/ietf/range.test.ts +++ b/js/net/src/ietf/range.test.ts @@ -2,6 +2,7 @@ import { expect, onTestFinished, test } from "bun:test"; import { StreamCode, StreamError } from "../error.ts"; import { hooks } from "../internal.ts"; import { createMockTransportPair } from "../mock.ts"; +import { nextGroup } from "../ordered.test-util.ts"; import * as Path from "../path.ts"; import { Reader, Stream, Writer } from "../stream.ts"; import { type Subscription, Producer as TrackProducer } from "../track.ts"; @@ -13,7 +14,6 @@ import { Subscribe, SubscribeOk } from "./subscribe.ts"; import { Subscriber } from "./subscriber.ts"; import { TrackStatusOk, TrackStatusRequest } from "./track.ts"; import { ALPN, type IetfVersion, Version } from "./version.ts"; -import { nextGroup } from "../ordered.test-util.ts"; const VERSIONS = [Version.DRAFT_18, Version.DRAFT_20, Version.DRAFT_22] as const; const ALPNS = { diff --git a/js/net/src/ietf/subscriber.test.ts b/js/net/src/ietf/subscriber.test.ts index c03e7697200..5f990d4a342 100644 --- a/js/net/src/ietf/subscriber.test.ts +++ b/js/net/src/ietf/subscriber.test.ts @@ -7,6 +7,7 @@ import { ProtocolViolation, StreamCode, Stream as StreamError } from "../error.t import { type Hop, toHop, UNKNOWN_HOP } from "../hop.ts"; import { hooks } from "../internal.ts"; import { createMockTransportPair, manual, settlesWithin } from "../mock.ts"; +import { nextGroup } from "../ordered.test-util.ts"; import * as Path from "../path.ts"; import { Reader, Stream } from "../stream.ts"; import { Tail } from "../tail.ts"; @@ -27,7 +28,6 @@ import { SubscribeNamespace, SubscribeNamespaceEntry, SubscribeNamespaceEntryDon import { Subscriber } from "./subscriber.ts"; import { TrackStatusOk, TrackStatusRequest } from "./track.ts"; import { ALPN, type IetfVersion, Version } from "./version.ts"; -import { nextGroup } from "../ordered.test-util.ts"; const VERSION = Version.DRAFT_18; diff --git a/js/net/src/integration.test.ts b/js/net/src/integration.test.ts index 0c64e5e075f..ccbba2d4d50 100644 --- a/js/net/src/integration.test.ts +++ b/js/net/src/integration.test.ts @@ -22,6 +22,7 @@ import { hooks } from "./internal.ts"; import * as Lite from "./lite/index.ts"; import { Publisher as LitePublisher } from "./lite/publisher.ts"; import { createMockTransportPair, manual, settlesWithin, textFrame, waitFor } from "./mock.ts"; +import { nextGroup } from "./ordered.test-util.ts"; import type { Consumer as OriginConsumer } from "./origin.ts"; import { Producer as OriginProducer } from "./origin.ts"; import * as Path from "./path.ts"; @@ -31,7 +32,6 @@ import type { Position, Producer as TrackProducer } from "./track.ts"; import { unwanted } from "./util/demand.ts"; import { withTimeout } from "./util/timeout.ts"; import { wireOf } from "./wire.ts"; -import { nextGroup } from "./ordered.test-util.ts"; function publish(origin: OriginProducer, path: Path.Valid) { const broadcastRoute = origin.route(path); diff --git a/js/net/src/lite/connection.test.ts b/js/net/src/lite/connection.test.ts index 6e2a796dd57..49f41b573e5 100644 --- a/js/net/src/lite/connection.test.ts +++ b/js/net/src/lite/connection.test.ts @@ -8,6 +8,7 @@ import { inspect } from "../connection/stats.ts"; import { SessionCode, SessionError } from "../error.ts"; import { hooks } from "../internal.ts"; import { createMockTransportPair, type MockTransport, manual, settlesWithin, textFrame } from "../mock.ts"; +import { nextGroup } from "../ordered.test-util.ts"; import { Producer } from "../origin.ts"; import * as Path from "../path.ts"; import { acceptBudget, Readers, Stream, Writer } from "../stream.ts"; @@ -42,7 +43,6 @@ import { Version, versionName, } from "./version.ts"; -import { nextGroup } from "../ordered.test-util.ts"; /** A transport whose `getStats` behaves as described, or is absent entirely. */ function transport(getStats?: () => Promise): WebTransport { diff --git a/js/net/src/lite/copy_fill.test.ts b/js/net/src/lite/copy_fill.test.ts index 44c489a8e83..eeb105956d1 100644 --- a/js/net/src/lite/copy_fill.test.ts +++ b/js/net/src/lite/copy_fill.test.ts @@ -13,6 +13,7 @@ import type { Consumer as GroupConsumer } from "../group.ts"; import { hooks } from "../internal.ts"; import { createMockTransportPair, requestedGroups } from "../mock.ts"; import { lines } from "../open.ts"; +import { nextGroup } from "../ordered.test-util.ts"; import { Producer as OriginProducer } from "../origin.ts"; import * as Path from "../path.ts"; import { Timescale, Timestamp } from "../time.ts"; @@ -21,7 +22,6 @@ import { wireOf } from "../wire.ts"; import * as Lite from "./index.ts"; import { Publisher as LitePublisher } from "./publisher.ts"; import { Subscriber as LiteSubscriber } from "./subscriber.ts"; -import { nextGroup } from "../ordered.test-util.ts"; const enc = new TextEncoder(); const dec = new TextDecoder(); diff --git a/js/net/src/lite/subscriber.test.ts b/js/net/src/lite/subscriber.test.ts index cd79a957db0..d6101335220 100644 --- a/js/net/src/lite/subscriber.test.ts +++ b/js/net/src/lite/subscriber.test.ts @@ -25,6 +25,7 @@ import { type Hop, isAnonymous, MAX_HOPS, toHop, UNKNOWN_HOP, WireRoute } from " import * as Instance from "../instance.ts"; import { hooks } from "../internal.ts"; import { GRACE } from "../ledger.ts"; +import { nextGroup } from "../ordered.test-util.ts"; import * as Path from "../path.ts"; import { Reader, Writer } from "../stream.ts"; import { Timescale } from "../time.ts"; @@ -63,7 +64,6 @@ import { import { Minted, Subscriber } from "./subscriber.ts"; import { Track, TrackInfo } from "./track.ts"; import { hasLengthFirst, Version, versionName } from "./version.ts"; -import { nextGroup } from "../ordered.test-util.ts"; test("closing the subscriber suppresses probe stream warnings", async () => { let readable!: ReadableStreamDefaultController; diff --git a/js/net/src/resume.test.ts b/js/net/src/resume.test.ts index c7666428b26..03fdab08ef5 100644 --- a/js/net/src/resume.test.ts +++ b/js/net/src/resume.test.ts @@ -12,6 +12,7 @@ import { Version as IetfVersion } from "./ietf/version.ts"; import * as Instance from "./instance.ts"; import { hooks, staleHole } from "./internal.ts"; import type { Lister } from "./listing.ts"; +import { nextGroup, tryNextGroup } from "./ordered.test-util.ts"; import { Producer } from "./origin.ts"; import * as Path from "./path.ts"; import { Front, routeFailed } from "./resume.ts"; @@ -19,7 +20,6 @@ import { Timestamp } from "./time.ts"; import type * as track from "./track.ts"; import { unwanted } from "./util/demand.ts"; import { overrideBroadcastWire, wireOf } from "./wire.ts"; -import { nextGroup, tryNextGroup } from "./ordered.test-util.ts"; const INFO: track.Info = { compression: "none", timescale: null, maxAge: null, priority: 0, refresh: null }; diff --git a/js/net/src/retention.test.ts b/js/net/src/retention.test.ts index db8cd1adbe1..a54367f5c7b 100644 --- a/js/net/src/retention.test.ts +++ b/js/net/src/retention.test.ts @@ -6,11 +6,11 @@ import * as Ietf from "./ietf/index.ts"; import { hooks } from "./internal.ts"; import * as Lite from "./lite/index.ts"; import { createMockTransportPair } from "./mock.ts"; +import { nextGroup } from "./ordered.test-util.ts"; import { Producer as OriginProducer } from "./origin.ts"; import * as Path from "./path.ts"; import { Timescale, Timestamp } from "./time.ts"; import { wireOf } from "./wire.ts"; -import { nextGroup } from "./ordered.test-util.ts"; // A subscription races its track's `closed` once per frame. These count the listeners left on // every Once that is still pending, so a per-frame leak shows up as a slope in frames. diff --git a/js/net/src/track.test.ts b/js/net/src/track.test.ts index bd600229a43..a153edf3234 100644 --- a/js/net/src/track.test.ts +++ b/js/net/src/track.test.ts @@ -8,12 +8,12 @@ import type { Consumer as GroupConsumer, Producer as GroupProducer } from "./gro import { Version as IetfVersion } from "./ietf/version.ts"; import { hooks, skipHole, staleHole } from "./internal.ts"; import { textFrame } from "./mock.ts"; +import { nextGroup, tryNextGroup } from "./ordered.test-util.ts"; import { rescale, rescaleIn } from "./rescale.ts"; import { Timescale, Timestamp } from "./time.ts"; import { authoredInfo, Subscription, Producer as TrackProducer } from "./track.ts"; import { unwanted } from "./util/demand.ts"; import { LIVE, rangesStart } from "./window.ts"; -import { nextGroup, tryNextGroup } from "./ordered.test-util.ts"; const enc = new TextEncoder(); const dec = new TextDecoder(); diff --git a/js/net/src/untimed.test.ts b/js/net/src/untimed.test.ts index fceaa3315a3..7ddf69bda02 100644 --- a/js/net/src/untimed.test.ts +++ b/js/net/src/untimed.test.ts @@ -8,11 +8,11 @@ import * as Ietf from "./ietf/index.ts"; import { hooks } from "./internal.ts"; import * as Lite from "./lite/index.ts"; import { createMockTransportPair } from "./mock.ts"; +import { nextGroup } from "./ordered.test-util.ts"; import { Producer as OriginProducer } from "./origin.ts"; import * as Path from "./path.ts"; import { Timescale, Timestamp } from "./time.ts"; import { wireOf } from "./wire.ts"; -import { nextGroup } from "./ordered.test-util.ts"; const url = new URL("https://localhost:4443/test"); diff --git a/js/publish/src/broadcast.test.ts b/js/publish/src/broadcast.test.ts index 815874146e0..0337efccac8 100644 --- a/js/publish/src/broadcast.test.ts +++ b/js/publish/src/broadcast.test.ts @@ -409,7 +409,7 @@ test("a re-announce continues the catalog's group sequence", async () => { if (!net) throw new Error("expected a network producer once connected"); const announced = broadcast.in.origin.peek()?.follow(broadcast.in.name.peek()); const first = net.track(Broadcast.CATALOG_TRACK).subscribe().ordered(); - const start = ((await first.nextGroup())?.group)?.start; + const start = (await first.nextGroup())?.group?.start; if (start === undefined) throw new Error("expected the first catalog"); const instance = announced?.active.peek()?.instance; expect(instance).toBeDefined(); diff --git a/js/watch/src/audio/decoder.test.ts b/js/watch/src/audio/decoder.test.ts index 68b028c1aba..353b9b88921 100644 --- a/js/watch/src/audio/decoder.test.ts +++ b/js/watch/src/audio/decoder.test.ts @@ -1664,6 +1664,7 @@ async function livePlayback(burst: number) { counts.inserted = insert.mock.calls.reduce((sum, [, data]) => sum + (data as Float32Array[])[0].length, 0); }, async close() { + owed?.close(); decoder.close(); source.close(); sync.close(); diff --git a/js/watch/src/audio/decoder.ts b/js/watch/src/audio/decoder.ts index 374f47e5269..30041a8cb2a 100644 --- a/js/watch/src/audio/decoder.ts +++ b/js/watch/src/audio/decoder.ts @@ -685,7 +685,11 @@ export class Decoder { }); } - #runLegacyDecoder(effect: Effect, sub: Moq.Track.Subscriber, { config, failure, path, key, ordered }: Attempt): void { + #runLegacyDecoder( + effect: Effect, + sub: Moq.Track.Subscriber, + { config, failure, path, key, ordered }: Attempt, + ): void { const preSkip = config.codec === "opus" && config.description ? Util.Opus.preSkip(Util.Hex.toBytes(config.description)) : 0; this.#terminal.clear( From 085868067ca02b188f1b0b4f79811e6e93debc72 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 17 Nov 2026 21:23:15 -0800 Subject: [PATCH 10/23] test(audio-quality): re-measure the replays reading audio through the ordered reader The interop range client and a publish test read past the gaps an ordered read now reports. Co-Authored-By: Claude Opus 5.5 --- js/publish/src/audio/encoder.test.ts | 8 +++++++- test/audio-quality/budgets.json | 24 ++++++++++++------------ test/interop/clients/js-native/ranges.ts | 5 ++++- 3 files changed, 23 insertions(+), 14 deletions(-) diff --git a/js/publish/src/audio/encoder.test.ts b/js/publish/src/audio/encoder.test.ts index 0ffd9fd7f69..909e379387e 100644 --- a/js/publish/src/audio/encoder.test.ts +++ b/js/publish/src/audio/encoder.test.ts @@ -1482,7 +1482,13 @@ test("default audio replays the last second after three seconds without a subscr // The subscription's one second reaches back from the newest frame, 152, to 102. const reader = late.ordered(); for (let index = 102; index < 153; index++) { - const group = (await reader.nextGroup())?.group; + let item = await reader.nextGroup(); + // The replay's older groups, past the subscription's second, read as gaps ahead of it. + while (item?.kind === "gap") { + expect(item.end).toBeLessThanOrEqual(BigInt(index * 20_000)); + item = await reader.nextGroup(); + } + const group = item?.group; if (!group) throw new Error("expected buffered group"); const frame = await group.readFrame(); if (!frame) throw new Error("expected buffered frame"); diff --git a/test/audio-quality/budgets.json b/test/audio-quality/budgets.json index 445d4a410fc..d3ab793c3d8 100644 --- a/test/audio-quality/budgets.json +++ b/test/audio-quality/budgets.json @@ -1,5 +1,5 @@ { - "note": "The browser rows are measured on the nightly runner (ubuntu-24.04-arm, headless Chromium, seed 7, 60 s a row), from the audio-quality-run artifacts of the seven scheduled Nightly runs on main from 2026-10-29 to 2026-11-04 (40885347517, 41065371094, 41204380716, 41313466339, 41483654426, 41656613559, 41852517544), the first after a fresh subscriber stopped receiving the relay's cached history. The six AAC rows other than congestion are measured the same way from the seven runs from 2026-11-05 to 2026-11-11 (42050683248, 42236107954, 42377867523, 42487375545, 42659882487, 42842827718, 43041909115), the first after the TS importer published each PES as one group; the first four predate the browser's time stretch, and the six rows keep the four provisional ceilings set below from 2026-11-09 and 2026-11-10. Each ceiling is the worst of its seven nights times 1.25, plus one runner hiccup, rounded up to two significant figures. The hiccup is sized from the single gaps the 2026-10-08 night put on otherwise clean rows, the fixed-250 control among them: 250 underruns/min, 700 gap ms/min, 3.3 skips/min, 280 dropped ms/min (both sized on the playhead's skip-ahead inference, and now applied to player_skips_per_min and trimmed_ms_per_min), 0.01 stalled, 0.015 silence, and one 20 ms bucket of target. Budgeted this way, every night passes when it is held out of its row's measurement except one, and that row's own ceiling includes it: the 2026-11-03 Opus bursty row raised its target to 300 ms 2.6 s in and held it for one 20 s half-life before settling at 180. Such startup holds, Opus near-zero's 100 ms on 2026-10-30 and 10-31 among them, are budgeted as measured. These ceilings record today's player as the runner hears it, not target audio quality. To re-measure, download the same artifact from the latest scheduled nightlies (`gh run download -n audio-quality-run`), which keep every run, and apply the same rule. On 2026-11-10 the inferred skip_aheads and discarded_ms keys were dropped, since they read a time stretch's catch-up as dropped audio, and every browser row gained player_skips_per_min, trimmed_ms_per_min, and av_lag_ms p50 and p95, by the same rule from the only two scheduled nights on main with today's browser player and its trim counter, 2026-11-09 and 2026-11-10 (42659882487, 42842827718). A lag is signed, so its ceiling is the worst night plus a quarter of its size plus one 20 ms bucket. These four keys are provisional until seven nights with the stretch model re-measure every row. The grade follows the model: audio rests on the shared clock, trails it through a stall, and catches up after. When a change moves a row, a steady-state lag (av_lag_ms p50) that rises, or audio the player trimmed, is a regression to fix rather than budget; a p95 lag that rises through a stall, or an underrun count that moves, is re-measured in. No ceiling is fixed at zero underruns or zero stalls; a replay row's is exactly what it measured. The replay rows are deterministic, so their ceilings are exactly what they measured, through the end of each recording, with no headroom: any regression fails them, and an improvement should be tightened in. They were last re-measured on 2026-10-22 using version 3 traces with encoded frame durations: AAC-LC uses its fixed 1024 samples, and relay-mic retains Opus packet TOC durations. relay-mic was re-recorded on 2026-11-03 from a real microphone, Chrome 156 on a MacBook Air publishing its built-in microphone through the public relay, recorded by headless Chromium on a Linux host (35 s, minimum RTT 2 ms), which raised its target ceiling from 60 to 80 ms and its silence from 0 to 0.001 as measured. The recording path itself has no added RTT. relay-mic-rtt40 is the 2026-11-03 Chrome row at 40 ms of added RTT on that laptop (180 s, minimum RTT 47 ms), kept as the baseline time stretch improves on; like every replay row, its player_underruns_per_min ceiling is what it measures, not a fixed zero. player_underruns_per_min, the player's own counter that its stats panel shows, is budgeted on the replay rows only; it counts the run-dry re-stalls the tap files as stalled time. On 2026-11-07, after the ordered read stopped delivering groups below its cursor (#8071) and took Rust's hole and age bounds (#8218), relay-bbb was re-measured at 16.1 player underruns/min, 0.025 stalled and 0.02 silence, and relay-mic-rtt40 at 8.2, its discarded audio at 70.9 ms/min and its target p95 at 320 ms rather than 780, since the stale backlog it never played no longer reaches the estimator; neither row lost audio the previous player heard. On 2026-11-08 the player began time-stretching live playback with NetEq's accelerate, deciding on the ring's depth right after each arrival and never expanding, and every replay row was re-measured with it, the browser rows left to the nightly runner. Each row's av_lag_ms, how far the playhead trails the shared clock video plays from, is what it measured: the ring rests one frame ahead of the newest arrival's playout, as the trim it replaces left it, so audio leads the clock by 19 to 23 ms at p50. Against the trim, the A/V lag p50 fell from 0.7, -17.5, -21.5, -18.2 and -15.6 ms to -22.4 on bursty-aac, -22.2 on local-aac, -22.7 on relay-bbb, -19 on relay-mic and -20.1 on relay-mic-rtt40, and its p95 fell on every row, most on relay-bbb (10.5 to -4.2) and relay-mic-rtt40 (-0.9 to -13.4). Underruns stayed where the trim had them, as the latency they would cost is not spent: player_underruns_per_min held at 4.4, 12.1, 16.1 and 6.1 and rose from 8.2 to 10.6 on relay-mic-rtt40, and relay-mic's tap now files 2 short quanta a minute, 2 ms of missing audio, where it filed none. What the stretch buys is the audio the trim dropped: discarded_ms_per_min fell from 87.8 to 0 on relay-bbb and from 127.5 to 100.6 on local-aac, whose remainder drops nothing: two receive stalls 14 and 15.3 s in leave audio 159 and 132 ms behind the clock, and the fast accelerate brings it back within half a second. player_skips_per_min and trimmed_ms_per_min, the ring's own count of re-anchors that dropped buffered audio and the media they dropped, are budgeted beside it, at 0 on every recorded row. relay-mic-stall, added 2026-11-10, is relay-mic with nothing arriving from 15 s to 16.5 s and the held frames then trickling in at twice real time until 18 s; today's player trims 2152.5 ms/min of it and its target p95 rises to 1540 ms. Once durations became whole nanoseconds, relay-bbb's delay, 200 ms plus one 1024-sample AAC frame, rounds up by a fraction of a sample, so its ring holds one more sample (23 µs) and its A/V lag p50 measures -22.6 rather than -22.7. Neither replay calibration changed the browser or native ceilings. bursty-aac is the 2026-10-18 AAC bursty isolated capture, recorded with the observer subscribed at the decoder's 2 s budget, so it holds every group the player saw. The native rows are provisional: measured on a loaded developer host (x86_64 Linux, the private PulseAudio null sink, seed 7, 60 s a row) on 2026-10-17, three runs of every row from the debug build nightly uses plus three more of the AAC rows from a release build, which played alike. Each ceiling is the worst clean run times 1.25, plus one native hiccup sized from the unimpaired Opus row's worst run (20 underruns/min, 50 gap ms/min, 2.2 skips/min, 110 discarded ms/min, 0.01 stalled, 0.005 silence, one 20 ms bucket of target), rounded up to two significant figures. On 2026-11-10, after native playback began reporting its A/V lag (#8361), the native rows' player_skips_per_min, trimmed_ms_per_min, and av_lag_ms p50 and p95, and every key of the native and browser congestion rows, were measured by the same rules from three runs of each on a loaded developer host (x86_64 Linux, the debug build, seed 7, 60 s a row), with no void; native audio rests 9 to 95 ms behind its clock at p50. These are provisional until the stretch model's nightly re-measure, which also moves the browser congestion rows onto the runner. On the 2026-10-17 host the null sink's clock ran about 150 ppm slow against the monotonic clock, read within 5 ms at p95 per sample, and its output latency sat between 14 and 28 ms. Five of the 36 AAC rows (none of the 18 Opus rows) voided on the clock: the device stopped pulling for about two seconds mid-row, sometimes after a backend error and a stream restart, which is a native playback defect rather than noise, and the ceilings exclude those runs. Re-measure from the nightly runner's artifacts once it has a week of native rows. On 2026-11-11 every player began following one stretch rule on the shared clock: it slows down below its target, speeds up above it, and skips only past its bound, which in the browser is the subscription's max delay. Every replay row was re-measured with it, the browser and native rows left to the nightly runner. Audio now rests on the clock rather than one frame ahead of it, so the A/V lag p50 rose from about -20 ms to 0.4 ms on relay-bbb, 1.1 on relay-mic, 1.2 on relay-mic-rtt40 and 1.8 on local-aac. Its p95 rose on every row, since audio that falls behind is now caught up by speeding up rather than trimmed: the shared clock steps forward as its reference converges through a tune-in backlog, and again when a target falls, and audio follows at the accelerate's pace, which on the replay's constant tone is one 2.5 ms period a window, slower than on speech. bursty-aac rests 5 ms behind its clock, so its p50 of 10.4 ms is mostly its catch-ups, and relay-mic-stall's p50 of 66.1 ms is the catch-up after its target falls from 1540 to 80 ms, which outlasts half the row. In exchange nothing is trimmed: relay-mic-stall's trimmed_ms_per_min fell from 2152.5 to 0, its skips from 6.1 to 0, and its underruns from 24.2 to 0 a minute, and player_underruns_per_min fell from 12.1 to 4 on local-aac, 16.1 to 0 on relay-bbb, 6.1 to 0 on relay-mic, 10.6 to 2.7 on relay-mic-rtt40 and 6.1 to 4 on relay-mic-stall, holding at 4.4 on bursty-aac. The tap now files 3.3 to 6.1 short quanta a minute on the AAC rows, under 0.3 ms of missing audio, where it filed none. To deliver the audio a stall delays, the container consumer now waits and skips at the subscription's max delay, as native already does, rather than at the delay plus lookahead. relay-mic-rtt40's join backlog arrives reordered, so the consumer now waits on its holes and the estimator observes the frames that fill them, up to 775 ms late, and its target p95 returns from 320 to 780 ms, held for one half-life after the join. Later on 2026-11-11 audio began skipping as far as the shared clock's reference moves earlier, once those moves add up to one stretch window and only as far as it holds audio past its target, rather than speeding through them, and every replay row was re-measured. The tune-in backlog's jumps now land before the graded window, so the A/V lag p95 fell from 453.1 to 2.1 ms on relay-bbb (its p50 from 0.4 to -1.3), 743.7 to 1.9 on relay-mic-rtt40, whose p50 fell from 1.2 to 0.4 and its tap's missing audio rose from 0.6 to 0.9 ms a minute, since a jump past what is decoded skips the rest once it lands,, 335.5 to 39.2 on local-aac and 88.6 to 0.3 on relay-mic, and the p50 from 66.1 to 25.3 on relay-mic-stall, with nothing trimmed in any graded window. The tap's underruns fell from 6.1 to 2 a minute on local-aac and 6.1 to 0 on relay-bbb; local-aac's silence rose from 0.001 to 0.002. Later on 2026-11-11 the container consumer began waiting on a missing group only for the delay plus the lookahead, while still delivering groups that arrived until they age past the max delay, and every replay row was re-measured. relay-mic-rtt40's target p95 fell from 780 back to 320 ms, since the holes in its reordered join backlog no longer delay the frames behind them; its tap's missing audio rose from 0.9 to 1.1 ms a minute and its A/V lag p50 and p95 from 0.4 and 1.9 to 0.7 and 2.4 ms. bursty-aac's silence rose from 0.007 to 0.009 and its A/V lag p95 fell from 162.1 to 156.3 ms, and relay-bbb's lag p50 and p95 moved from -1.3 and 2.1 to -1.2 and 2.2 ms. relay-mic-stall did not move. Also on 2026-11-11 the stretch became a player setting, 2 s by default, and the audio subscription's max delay became the delay plus it rather than the 2 s constant, so the container consumer delivers a late group that much longer before it ages out, and every replay row was re-measured: only relay-mic moved, its A/V lag p50 and p95 from 0.3 to 1.6 ms, under the 2.5 ms pitch period the stretch can move it by. Holding the constant max delay with the new bound reproduces the old values exactly. On 2026-11-12 the replays stopped playing a constant and began playing a seeded speech-like signal (syllables gliding a 90 to 220 Hz fundamental, with pauses held above the silence classifier), since the stretch's pitch search found only its shortest period in a constant, and the browser ring stopped zero-filling a hole of up to a millisecond and two samples between frames, as native stopped writing silence for one: the recorded AAC timestamps land up to 2.5 samples either side of a 1024-sample boundary, and on speech the 2-sample holes this filled ended 119.1 quanta a minute short on bursty-aac. Every replay row was re-measured. The tap's underruns fell to 0 on bursty-aac (from 3.3) and local-aac (from 2), and relay-mic-rtt40's missing audio from 1.1 to 0.3 ms a minute while its player underruns rose from 2.7 to 3.1. The A/V lag p95 fell from 156.3 to 104.8 ms on bursty-aac, 39.2 to 15.1 on local-aac, 2.2 to 1.4 on relay-bbb and 501.8 to 484.9 on relay-mic-stall, whose p50 fell from 25.3 to 1.1, and rose from 1.6 to 3.4 on relay-mic and 2.4 to 3.5 on relay-mic-rtt40. Where audio rests moved within one speech pitch period, which is as close as one stretch seam can steer it: the p50 is 11 ms on bursty-aac (from 10.4), -4.2 on relay-bbb (from -1.2), 1.1 on relay-mic (from 1.6), 0.9 on relay-mic-rtt40 (from 0.7) and 1.7 on local-aac (from 1.8). On 2026-11-13 the stretch default fell from 2 s to 200 ms and audio trailing the clock past it began skipping onto the clock rather than back to the bound, as video skips, with the audio subscription still reaching 2 s past the delay; every replay row was re-measured. A target fall past 200 ms now costs one skip rather than seconds of catch-up, and so does a trail past it, and a rise past it pads silence until the clock arrives rather than slowing down: relay-mic-stall skips the 1.46 s it trails after the outage and its 1540 to 1020 and 1020 to 80 ms falls, and pads the 0.5 s its 60 to 1540 ms rise leaves it ahead, where it slowed down for 4 s, so it trims 4678.2 ms a minute where it trimmed none and its stalled share rose from 0.05 to 0.067 and silence from 0.049 to 0.085. The frames it holds through the outage then trickle in at twice real time, so its low buffer slows it to 154 ms behind the clock, where it had sat ahead of it: its A/V lag p95 fell from 484.9 to 118.6 ms and its p50 rose from 1.1 to 2.2. relay-mic-rtt40 skips its 320 to 80 ms fall, 0.3 skips and 83.3 trimmed ms a minute, its p95 from 3.5 to 2.9 ms. bursty-aac skips a 225 ms trail 6 s in, 1.1 skips and 312.7 trimmed ms a minute, its p95 from 102.7 to 49.2 ms and p50 from 11 to 10. relay-mic trims nothing, but its tune-in's skips land on the clock rather than at the bound, which moves where it rests within a pitch period: its p50 from 1.1 to 2.2 ms and p95 from 3.4 to 4.5. Trimming at a target fall or a trail past 200 ms is the rule, not a regression. Also on 2026-11-13, for the same change, the congestion rows' trimmed_ms_per_min ceilings were raised by the same rule from two runs of each on a loaded developer host (x86_64 Linux, the debug build, seed 7, 60 s a row): to 3800 on chromium AAC (worst 2740.3 ms/min), 3700 on chromium Opus (2697.2), 3900 on native AAC (2996.9) and 4600 on native Opus (3532.3), whose player_skips_per_min rose to 15 (9.8). The trim is the outage's audio skipped onto the clock rather than played seconds late: against main on the same host, chromium's A/V lag p95 fell from 1396.8 to 61.6 ms on AAC and 1424.8 to 64.3 on Opus, and native's from 1246.3 to 116.7 and 826.9 to 117.5. These four ceilings are provisional until the nightly re-measures the congestion rows. Also on 2026-11-13, the estimator began counting one outage, the intervals its stalled frames span and the empty ones before them, as one observation, and every replay row was re-measured on top of the snap: only relay-mic-stall moved. Its single stall no longer raises the target, so its target p95 fell from 1540 to 80 ms and the trail the outage leaves is skipped onto the clock at once rather than through the target's falls: 2 skips a minute where it took 6.1, 5122.3 trimmed ms a minute where it trimmed 4678.2, and its A/V lag p95 from 118.6 to 19.7 ms. With 80 ms of buffer rather than 1540, more of the outage plays as silence: its stalled share rose from 0.067 to 0.092 and silence from 0.085 to 0.092. On 2026-11-14 every player began following the clock by its lag alone: a continuous WSOLA time stretch for any content, at a rate proportional to the lag and capped at 10%, which leaves a lag within half a 10 ms hop alone, and slows down while the audio received ahead of the playhead is about to run out, replacing NetEq's buffer-level decision and pitch-period splices. Every replay row was re-measured. Audio now rests within half a hop of the clock rather than within a pitch period: the A/V lag p50 fell from 10 to 0.2 ms on bursty-aac, whose p95 fell from 49.2 to 0.2, from 1.7 to -1.3 on local-aac, 2.2 to 1.8 on relay-mic and 0.9 to 0.6 on relay-mic-rtt40, and moved from -2 to 2.7 on relay-bbb and 2.2 to 3.1 on relay-mic-stall, each within the half hop the rule leaves alone. The p95 rose from 3.6 to 6.2 ms on relay-bbb, 4.5 to 6.9 on relay-mic, 2.9 to 6.9 on relay-mic-rtt40 and 19.7 to 32.1 on relay-mic-stall, and fell from 15.1 to 14.3 on local-aac: a lag under a hop is corrected only once its pace adds up to one. player_underruns_per_min rose from 4.4 to 6.6 on bursty-aac and 4 to 8.1 on local-aac, whose recorded outages outlast what slowing down at 10% bridges, and fell from 3.1 to 1 on relay-mic-rtt40, whose tap's underruns fell from 0.7 to 0.3 a minute; bursty-aac's silence rose from 0.007 to 0.008. Nothing more is trimmed on any row. The browser and native rows were measured on a loaded developer host (x86_64 Linux, the debug build, seed 7, 60 s a row) against main the same day and left to the nightly runner: every browser row's A/V lag p50 now sits between 27 and 39 ms, where the fixed-250 control does on that host, where wide and bursty sat up to 58 ms behind, and every native row's within 15 ms of the clock. Also on 2026-11-14 the estimator stopped folding the intervals a subscription's join spans, those holding a frame due before its backlog finished arriving, and every replay row was re-measured: only relay-mic and relay-mic-stall moved. Their first frame arrives slower than the path after it, so their first interval folds nothing and the target leaves the prior 500 ms later, which moves where audio rests within the half hop the rule leaves alone: relay-mic's A/V lag p50 from 1.8 to -0.3 ms and p95 from 6.9 to 9, and relay-mic-stall's p50 from 3.1 to 1.7. relay-mic-rtt40 did not move: the browser consumer closes its join's stale groups below the cursor unread, so the estimator never sees when that backlog ended, and its target p95 held at 320 ms. Later on 2026-11-14 both container consumers began reporting when each group they close unread arrived, if it is at or below the publisher's largest group as the subscription began, which extends a join still open. On 2026-11-15 the traces gained that largest group (version 4), so the replay's consumer learns it as a wire subscriber does, and relay-mic-rtt40 was re-measured: its target p95 fell from 320 to 120 ms, underruns per minute rose from 0.3 to 0.7, player skips per minute fell from 0.3 to 0, trimmed ms per minute from 83 to 0, A/V lag p50 rose from 0.6 to 2.3 ms and p95 from 6.9 to 8.6, the trade of reporting the join's backlog. No other replay row moved.", + "note": "The browser rows are measured on the nightly runner (ubuntu-24.04-arm, headless Chromium, seed 7, 60 s a row), from the audio-quality-run artifacts of the seven scheduled Nightly runs on main from 2026-10-29 to 2026-11-04 (40885347517, 41065371094, 41204380716, 41313466339, 41483654426, 41656613559, 41852517544), the first after a fresh subscriber stopped receiving the relay's cached history. The six AAC rows other than congestion are measured the same way from the seven runs from 2026-11-05 to 2026-11-11 (42050683248, 42236107954, 42377867523, 42487375545, 42659882487, 42842827718, 43041909115), the first after the TS importer published each PES as one group; the first four predate the browser's time stretch, and the six rows keep the four provisional ceilings set below from 2026-11-09 and 2026-11-10. Each ceiling is the worst of its seven nights times 1.25, plus one runner hiccup, rounded up to two significant figures. The hiccup is sized from the single gaps the 2026-10-08 night put on otherwise clean rows, the fixed-250 control among them: 250 underruns/min, 700 gap ms/min, 3.3 skips/min, 280 dropped ms/min (both sized on the playhead's skip-ahead inference, and now applied to player_skips_per_min and trimmed_ms_per_min), 0.01 stalled, 0.015 silence, and one 20 ms bucket of target. Budgeted this way, every night passes when it is held out of its row's measurement except one, and that row's own ceiling includes it: the 2026-11-03 Opus bursty row raised its target to 300 ms 2.6 s in and held it for one 20 s half-life before settling at 180. Such startup holds, Opus near-zero's 100 ms on 2026-10-30 and 10-31 among them, are budgeted as measured. These ceilings record today's player as the runner hears it, not target audio quality. To re-measure, download the same artifact from the latest scheduled nightlies (`gh run download -n audio-quality-run`), which keep every run, and apply the same rule. On 2026-11-10 the inferred skip_aheads and discarded_ms keys were dropped, since they read a time stretch's catch-up as dropped audio, and every browser row gained player_skips_per_min, trimmed_ms_per_min, and av_lag_ms p50 and p95, by the same rule from the only two scheduled nights on main with today's browser player and its trim counter, 2026-11-09 and 2026-11-10 (42659882487, 42842827718). A lag is signed, so its ceiling is the worst night plus a quarter of its size plus one 20 ms bucket. These four keys are provisional until seven nights with the stretch model re-measure every row. The grade follows the model: audio rests on the shared clock, trails it through a stall, and catches up after. When a change moves a row, a steady-state lag (av_lag_ms p50) that rises, or audio the player trimmed, is a regression to fix rather than budget; a p95 lag that rises through a stall, or an underrun count that moves, is re-measured in. No ceiling is fixed at zero underruns or zero stalls; a replay row's is exactly what it measured. The replay rows are deterministic, so their ceilings are exactly what they measured, through the end of each recording, with no headroom: any regression fails them, and an improvement should be tightened in. They were last re-measured on 2026-10-22 using version 3 traces with encoded frame durations: AAC-LC uses its fixed 1024 samples, and relay-mic retains Opus packet TOC durations. relay-mic was re-recorded on 2026-11-03 from a real microphone, Chrome 156 on a MacBook Air publishing its built-in microphone through the public relay, recorded by headless Chromium on a Linux host (35 s, minimum RTT 2 ms), which raised its target ceiling from 60 to 80 ms and its silence from 0 to 0.001 as measured. The recording path itself has no added RTT. relay-mic-rtt40 is the 2026-11-03 Chrome row at 40 ms of added RTT on that laptop (180 s, minimum RTT 47 ms), kept as the baseline time stretch improves on; like every replay row, its player_underruns_per_min ceiling is what it measures, not a fixed zero. player_underruns_per_min, the player's own counter that its stats panel shows, is budgeted on the replay rows only; it counts the run-dry re-stalls the tap files as stalled time. On 2026-11-07, after the ordered read stopped delivering groups below its cursor (#8071) and took Rust's hole and age bounds (#8218), relay-bbb was re-measured at 16.1 player underruns/min, 0.025 stalled and 0.02 silence, and relay-mic-rtt40 at 8.2, its discarded audio at 70.9 ms/min and its target p95 at 320 ms rather than 780, since the stale backlog it never played no longer reaches the estimator; neither row lost audio the previous player heard. On 2026-11-08 the player began time-stretching live playback with NetEq's accelerate, deciding on the ring's depth right after each arrival and never expanding, and every replay row was re-measured with it, the browser rows left to the nightly runner. Each row's av_lag_ms, how far the playhead trails the shared clock video plays from, is what it measured: the ring rests one frame ahead of the newest arrival's playout, as the trim it replaces left it, so audio leads the clock by 19 to 23 ms at p50. Against the trim, the A/V lag p50 fell from 0.7, -17.5, -21.5, -18.2 and -15.6 ms to -22.4 on bursty-aac, -22.2 on local-aac, -22.7 on relay-bbb, -19 on relay-mic and -20.1 on relay-mic-rtt40, and its p95 fell on every row, most on relay-bbb (10.5 to -4.2) and relay-mic-rtt40 (-0.9 to -13.4). Underruns stayed where the trim had them, as the latency they would cost is not spent: player_underruns_per_min held at 4.4, 12.1, 16.1 and 6.1 and rose from 8.2 to 10.6 on relay-mic-rtt40, and relay-mic's tap now files 2 short quanta a minute, 2 ms of missing audio, where it filed none. What the stretch buys is the audio the trim dropped: discarded_ms_per_min fell from 87.8 to 0 on relay-bbb and from 127.5 to 100.6 on local-aac, whose remainder drops nothing: two receive stalls 14 and 15.3 s in leave audio 159 and 132 ms behind the clock, and the fast accelerate brings it back within half a second. player_skips_per_min and trimmed_ms_per_min, the ring's own count of re-anchors that dropped buffered audio and the media they dropped, are budgeted beside it, at 0 on every recorded row. relay-mic-stall, added 2026-11-10, is relay-mic with nothing arriving from 15 s to 16.5 s and the held frames then trickling in at twice real time until 18 s; today's player trims 2152.5 ms/min of it and its target p95 rises to 1540 ms. Once durations became whole nanoseconds, relay-bbb's delay, 200 ms plus one 1024-sample AAC frame, rounds up by a fraction of a sample, so its ring holds one more sample (23 µs) and its A/V lag p50 measures -22.6 rather than -22.7. Neither replay calibration changed the browser or native ceilings. bursty-aac is the 2026-10-18 AAC bursty isolated capture, recorded with the observer subscribed at the decoder's 2 s budget, so it holds every group the player saw. The native rows are provisional: measured on a loaded developer host (x86_64 Linux, the private PulseAudio null sink, seed 7, 60 s a row) on 2026-10-17, three runs of every row from the debug build nightly uses plus three more of the AAC rows from a release build, which played alike. Each ceiling is the worst clean run times 1.25, plus one native hiccup sized from the unimpaired Opus row's worst run (20 underruns/min, 50 gap ms/min, 2.2 skips/min, 110 discarded ms/min, 0.01 stalled, 0.005 silence, one 20 ms bucket of target), rounded up to two significant figures. On 2026-11-10, after native playback began reporting its A/V lag (#8361), the native rows' player_skips_per_min, trimmed_ms_per_min, and av_lag_ms p50 and p95, and every key of the native and browser congestion rows, were measured by the same rules from three runs of each on a loaded developer host (x86_64 Linux, the debug build, seed 7, 60 s a row), with no void; native audio rests 9 to 95 ms behind its clock at p50. These are provisional until the stretch model's nightly re-measure, which also moves the browser congestion rows onto the runner. On the 2026-10-17 host the null sink's clock ran about 150 ppm slow against the monotonic clock, read within 5 ms at p95 per sample, and its output latency sat between 14 and 28 ms. Five of the 36 AAC rows (none of the 18 Opus rows) voided on the clock: the device stopped pulling for about two seconds mid-row, sometimes after a backend error and a stream restart, which is a native playback defect rather than noise, and the ceilings exclude those runs. Re-measure from the nightly runner's artifacts once it has a week of native rows. On 2026-11-11 every player began following one stretch rule on the shared clock: it slows down below its target, speeds up above it, and skips only past its bound, which in the browser is the subscription's max delay. Every replay row was re-measured with it, the browser and native rows left to the nightly runner. Audio now rests on the clock rather than one frame ahead of it, so the A/V lag p50 rose from about -20 ms to 0.4 ms on relay-bbb, 1.1 on relay-mic, 1.2 on relay-mic-rtt40 and 1.8 on local-aac. Its p95 rose on every row, since audio that falls behind is now caught up by speeding up rather than trimmed: the shared clock steps forward as its reference converges through a tune-in backlog, and again when a target falls, and audio follows at the accelerate's pace, which on the replay's constant tone is one 2.5 ms period a window, slower than on speech. bursty-aac rests 5 ms behind its clock, so its p50 of 10.4 ms is mostly its catch-ups, and relay-mic-stall's p50 of 66.1 ms is the catch-up after its target falls from 1540 to 80 ms, which outlasts half the row. In exchange nothing is trimmed: relay-mic-stall's trimmed_ms_per_min fell from 2152.5 to 0, its skips from 6.1 to 0, and its underruns from 24.2 to 0 a minute, and player_underruns_per_min fell from 12.1 to 4 on local-aac, 16.1 to 0 on relay-bbb, 6.1 to 0 on relay-mic, 10.6 to 2.7 on relay-mic-rtt40 and 6.1 to 4 on relay-mic-stall, holding at 4.4 on bursty-aac. The tap now files 3.3 to 6.1 short quanta a minute on the AAC rows, under 0.3 ms of missing audio, where it filed none. To deliver the audio a stall delays, the container consumer now waits and skips at the subscription's max delay, as native already does, rather than at the delay plus lookahead. relay-mic-rtt40's join backlog arrives reordered, so the consumer now waits on its holes and the estimator observes the frames that fill them, up to 775 ms late, and its target p95 returns from 320 to 780 ms, held for one half-life after the join. Later on 2026-11-11 audio began skipping as far as the shared clock's reference moves earlier, once those moves add up to one stretch window and only as far as it holds audio past its target, rather than speeding through them, and every replay row was re-measured. The tune-in backlog's jumps now land before the graded window, so the A/V lag p95 fell from 453.1 to 2.1 ms on relay-bbb (its p50 from 0.4 to -1.3), 743.7 to 1.9 on relay-mic-rtt40, whose p50 fell from 1.2 to 0.4 and its tap's missing audio rose from 0.6 to 0.9 ms a minute, since a jump past what is decoded skips the rest once it lands,, 335.5 to 39.2 on local-aac and 88.6 to 0.3 on relay-mic, and the p50 from 66.1 to 25.3 on relay-mic-stall, with nothing trimmed in any graded window. The tap's underruns fell from 6.1 to 2 a minute on local-aac and 6.1 to 0 on relay-bbb; local-aac's silence rose from 0.001 to 0.002. Later on 2026-11-11 the container consumer began waiting on a missing group only for the delay plus the lookahead, while still delivering groups that arrived until they age past the max delay, and every replay row was re-measured. relay-mic-rtt40's target p95 fell from 780 back to 320 ms, since the holes in its reordered join backlog no longer delay the frames behind them; its tap's missing audio rose from 0.9 to 1.1 ms a minute and its A/V lag p50 and p95 from 0.4 and 1.9 to 0.7 and 2.4 ms. bursty-aac's silence rose from 0.007 to 0.009 and its A/V lag p95 fell from 162.1 to 156.3 ms, and relay-bbb's lag p50 and p95 moved from -1.3 and 2.1 to -1.2 and 2.2 ms. relay-mic-stall did not move. Also on 2026-11-11 the stretch became a player setting, 2 s by default, and the audio subscription's max delay became the delay plus it rather than the 2 s constant, so the container consumer delivers a late group that much longer before it ages out, and every replay row was re-measured: only relay-mic moved, its A/V lag p50 and p95 from 0.3 to 1.6 ms, under the 2.5 ms pitch period the stretch can move it by. Holding the constant max delay with the new bound reproduces the old values exactly. On 2026-11-12 the replays stopped playing a constant and began playing a seeded speech-like signal (syllables gliding a 90 to 220 Hz fundamental, with pauses held above the silence classifier), since the stretch's pitch search found only its shortest period in a constant, and the browser ring stopped zero-filling a hole of up to a millisecond and two samples between frames, as native stopped writing silence for one: the recorded AAC timestamps land up to 2.5 samples either side of a 1024-sample boundary, and on speech the 2-sample holes this filled ended 119.1 quanta a minute short on bursty-aac. Every replay row was re-measured. The tap's underruns fell to 0 on bursty-aac (from 3.3) and local-aac (from 2), and relay-mic-rtt40's missing audio from 1.1 to 0.3 ms a minute while its player underruns rose from 2.7 to 3.1. The A/V lag p95 fell from 156.3 to 104.8 ms on bursty-aac, 39.2 to 15.1 on local-aac, 2.2 to 1.4 on relay-bbb and 501.8 to 484.9 on relay-mic-stall, whose p50 fell from 25.3 to 1.1, and rose from 1.6 to 3.4 on relay-mic and 2.4 to 3.5 on relay-mic-rtt40. Where audio rests moved within one speech pitch period, which is as close as one stretch seam can steer it: the p50 is 11 ms on bursty-aac (from 10.4), -4.2 on relay-bbb (from -1.2), 1.1 on relay-mic (from 1.6), 0.9 on relay-mic-rtt40 (from 0.7) and 1.7 on local-aac (from 1.8). On 2026-11-13 the stretch default fell from 2 s to 200 ms and audio trailing the clock past it began skipping onto the clock rather than back to the bound, as video skips, with the audio subscription still reaching 2 s past the delay; every replay row was re-measured. A target fall past 200 ms now costs one skip rather than seconds of catch-up, and so does a trail past it, and a rise past it pads silence until the clock arrives rather than slowing down: relay-mic-stall skips the 1.46 s it trails after the outage and its 1540 to 1020 and 1020 to 80 ms falls, and pads the 0.5 s its 60 to 1540 ms rise leaves it ahead, where it slowed down for 4 s, so it trims 4678.2 ms a minute where it trimmed none and its stalled share rose from 0.05 to 0.067 and silence from 0.049 to 0.085. The frames it holds through the outage then trickle in at twice real time, so its low buffer slows it to 154 ms behind the clock, where it had sat ahead of it: its A/V lag p95 fell from 484.9 to 118.6 ms and its p50 rose from 1.1 to 2.2. relay-mic-rtt40 skips its 320 to 80 ms fall, 0.3 skips and 83.3 trimmed ms a minute, its p95 from 3.5 to 2.9 ms. bursty-aac skips a 225 ms trail 6 s in, 1.1 skips and 312.7 trimmed ms a minute, its p95 from 102.7 to 49.2 ms and p50 from 11 to 10. relay-mic trims nothing, but its tune-in's skips land on the clock rather than at the bound, which moves where it rests within a pitch period: its p50 from 1.1 to 2.2 ms and p95 from 3.4 to 4.5. Trimming at a target fall or a trail past 200 ms is the rule, not a regression. Also on 2026-11-13, for the same change, the congestion rows' trimmed_ms_per_min ceilings were raised by the same rule from two runs of each on a loaded developer host (x86_64 Linux, the debug build, seed 7, 60 s a row): to 3800 on chromium AAC (worst 2740.3 ms/min), 3700 on chromium Opus (2697.2), 3900 on native AAC (2996.9) and 4600 on native Opus (3532.3), whose player_skips_per_min rose to 15 (9.8). The trim is the outage's audio skipped onto the clock rather than played seconds late: against main on the same host, chromium's A/V lag p95 fell from 1396.8 to 61.6 ms on AAC and 1424.8 to 64.3 on Opus, and native's from 1246.3 to 116.7 and 826.9 to 117.5. These four ceilings are provisional until the nightly re-measures the congestion rows. Also on 2026-11-13, the estimator began counting one outage, the intervals its stalled frames span and the empty ones before them, as one observation, and every replay row was re-measured on top of the snap: only relay-mic-stall moved. Its single stall no longer raises the target, so its target p95 fell from 1540 to 80 ms and the trail the outage leaves is skipped onto the clock at once rather than through the target's falls: 2 skips a minute where it took 6.1, 5122.3 trimmed ms a minute where it trimmed 4678.2, and its A/V lag p95 from 118.6 to 19.7 ms. With 80 ms of buffer rather than 1540, more of the outage plays as silence: its stalled share rose from 0.067 to 0.092 and silence from 0.085 to 0.092. On 2026-11-14 every player began following the clock by its lag alone: a continuous WSOLA time stretch for any content, at a rate proportional to the lag and capped at 10%, which leaves a lag within half a 10 ms hop alone, and slows down while the audio received ahead of the playhead is about to run out, replacing NetEq's buffer-level decision and pitch-period splices. Every replay row was re-measured. Audio now rests within half a hop of the clock rather than within a pitch period: the A/V lag p50 fell from 10 to 0.2 ms on bursty-aac, whose p95 fell from 49.2 to 0.2, from 1.7 to -1.3 on local-aac, 2.2 to 1.8 on relay-mic and 0.9 to 0.6 on relay-mic-rtt40, and moved from -2 to 2.7 on relay-bbb and 2.2 to 3.1 on relay-mic-stall, each within the half hop the rule leaves alone. The p95 rose from 3.6 to 6.2 ms on relay-bbb, 4.5 to 6.9 on relay-mic, 2.9 to 6.9 on relay-mic-rtt40 and 19.7 to 32.1 on relay-mic-stall, and fell from 15.1 to 14.3 on local-aac: a lag under a hop is corrected only once its pace adds up to one. player_underruns_per_min rose from 4.4 to 6.6 on bursty-aac and 4 to 8.1 on local-aac, whose recorded outages outlast what slowing down at 10% bridges, and fell from 3.1 to 1 on relay-mic-rtt40, whose tap's underruns fell from 0.7 to 0.3 a minute; bursty-aac's silence rose from 0.007 to 0.008. Nothing more is trimmed on any row. The browser and native rows were measured on a loaded developer host (x86_64 Linux, the debug build, seed 7, 60 s a row) against main the same day and left to the nightly runner: every browser row's A/V lag p50 now sits between 27 and 39 ms, where the fixed-250 control does on that host, where wide and bursty sat up to 58 ms behind, and every native row's within 15 ms of the clock. Also on 2026-11-14 the estimator stopped folding the intervals a subscription's join spans, those holding a frame due before its backlog finished arriving, and every replay row was re-measured: only relay-mic and relay-mic-stall moved. Their first frame arrives slower than the path after it, so their first interval folds nothing and the target leaves the prior 500 ms later, which moves where audio rests within the half hop the rule leaves alone: relay-mic's A/V lag p50 from 1.8 to -0.3 ms and p95 from 6.9 to 9, and relay-mic-stall's p50 from 3.1 to 1.7. relay-mic-rtt40 did not move: the browser consumer closes its join's stale groups below the cursor unread, so the estimator never sees when that backlog ended, and its target p95 held at 320 ms. Later on 2026-11-14 both container consumers began reporting when each group they close unread arrived, if it is at or below the publisher's largest group as the subscription began, which extends a join still open. On 2026-11-15 the traces gained that largest group (version 4), so the replay's consumer learns it as a wire subscriber does, and relay-mic-rtt40 was re-measured: its target p95 fell from 320 to 120 ms, underruns per minute rose from 0.3 to 0.7, player skips per minute fell from 0.3 to 0, trimmed ms per minute from 83 to 0, A/V lag p50 rose from 0.6 to 2.3 ms and p95 from 6.9 to 8.6, the trade of reporting the join's backlog. No other replay row moved. On 2026-11-17 the browser player began reading audio through the ordered reader, which waits for a hole as long as the ring could still play it and reports each group it gives up on as a gap, and the replay dropped the trace's largest group: a second subscription now observes every arrival for the estimate, the join's backlog included. Every replay row was re-measured. bursty-aac's player underruns per minute fell from 6.6 to 4.4 and silence share from 0.008 to 0.007; audio rests at 0.1 ms until a stall at 19.5 s, from which the stretch catches up to 4.2 ms behind the clock, inside the half hop it leaves alone, so its A/V lag p50 and p95 rose from 0.2 to 4.2 ms. relay-bbb's A/V lag p50 fell from 2.7 to 1.4 ms and p95 rose from 6.2 to 7.6. relay-mic-rtt40's underruns per minute fell from 0.7 to 0.3 (player underruns the same), underrun ms per minute from 0.8 to 0.2, A/V lag p50 from 2.3 to 0.6 ms, and p95 rose from 8.6 to 9.1, its target p95 holding at 120 ms. No other replay row moved.", "rows": [ { "runtime": "chromium", @@ -426,16 +426,16 @@ "codec": "aac", "rate": 44100, "profile": "bursty-aac", - "player_underruns_per_min": 6.6, + "player_underruns_per_min": 4.4, "player_skips_per_min": 1.1, "underruns_per_min": 0, "underrun_ms_per_min": 0, "trimmed_ms_per_min": 312.7, "stalled_share": 0.005, - "silence_share": 0.008, + "silence_share": 0.007, "target_ms_p95": 343.2, - "av_lag_ms_p50": 0.2, - "av_lag_ms_p95": 0.2 + "av_lag_ms_p50": 4.2, + "av_lag_ms_p95": 4.2 }, { "runtime": "replay", @@ -466,8 +466,8 @@ "stalled_share": 0, "silence_share": 0, "target_ms_p95": 223.2, - "av_lag_ms_p50": 2.7, - "av_lag_ms_p95": 6.2 + "av_lag_ms_p50": 1.4, + "av_lag_ms_p95": 7.6 }, { "runtime": "replay", @@ -490,16 +490,16 @@ "codec": "opus", "rate": 48000, "profile": "relay-mic-rtt40", - "player_underruns_per_min": 0.7, + "player_underruns_per_min": 0.3, "player_skips_per_min": 0, - "underruns_per_min": 0.7, - "underrun_ms_per_min": 0.8, + "underruns_per_min": 0.3, + "underrun_ms_per_min": 0.2, "trimmed_ms_per_min": 0, "stalled_share": 0, "silence_share": 0, "target_ms_p95": 120, - "av_lag_ms_p50": 2.3, - "av_lag_ms_p95": 8.6 + "av_lag_ms_p50": 0.6, + "av_lag_ms_p95": 9.1 }, { "runtime": "replay", diff --git a/test/interop/clients/js-native/ranges.ts b/test/interop/clients/js-native/ranges.ts index 6416990ad74..ef7ec659767 100644 --- a/test/interop/clients/js-native/ranges.ts +++ b/test/interop/clients/js-native/ranges.ts @@ -62,7 +62,10 @@ try { try { const seen: bigint[] = []; const ordered = reader.ordered(); - for (let group = await ordered.nextGroup(); group; group = await ordered.nextGroup()) { + for (let item = await ordered.nextGroup(); item; item = await ordered.nextGroup()) { + // A key the range never produced may read as a gap; only the groups are graded. + if (item.kind === "gap") continue; + const group = item.group; seen.push(group.start); try { for (const size of [1024, 513, 513]) { From 77064db8bb4a1b825df26a43345fb8a5bbd4ff7c Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 17 Nov 2026 22:32:48 -0800 Subject: [PATCH 11/23] docs(quest): narrow browser-audio-hole-skip to grading the Chromium rows The replay README says its consumer reads ordered and observes every arrival, rather than being told the trace's largest group. Co-Authored-By: Claude Opus 5.5 --- .../audio-playout/browser-audio-hole-skip.md | 87 +++++++------------ quest/m2/unused-api/net.md | 2 +- test/audio-quality/README.md | 9 +- 3 files changed, 37 insertions(+), 61 deletions(-) diff --git a/quest/m2/audio-playout/browser-audio-hole-skip.md b/quest/m2/audio-playout/browser-audio-hole-skip.md index 94a78d40555..8186963f382 100644 --- a/quest/m2/audio-playout/browser-audio-hole-skip.md +++ b/quest/m2/audio-playout/browser-audio-hole-skip.md @@ -1,71 +1,46 @@ -# [L] Browser audio takes its holes from the ordered reader +# [M] Browser audio's ordered reader grades no worse than before #8799 ## Goal -`@moq/watch`'s audio reads its track through `@moq/net`'s ordered reader with -a reader budget equal to what the ring holds, and plays each `Gap` the reader -reports as the hole: the audio container consumer keeps no hole wait of its -own and no longer passes `playhead`. Video keeps the playhead. The Chromium -`bursty` and `congestion` rows of `just test audio-quality` grade no worse -than before [moq-dev/moq#8799](https://github.com/moq-dev/moq/pull/8799) -gave the audio consumer the player's clock, and the Firefox `after resume` -window that PR fixed stays audible. +The Chromium `bursty` and `congestion` rows of `just test audio-quality`, with +browser audio reading its holes from `@moq/net`'s ordered reader, grade no +worse than before [moq-dev/moq#8799](https://github.com/moq-dev/moq/pull/8799) +gave the audio consumer the player's clock, measured on the nightly runner, +and the one full starvation seen locally is explained or fixed. ## Plan Decided 2026-11-16 (maintainer, /quest-run): ✅ the transport decides an audio hole, through an ordered reader whose budget is the ring's size (rejected: first measure the playhead rule against a hand-written wait in -the container consumer, as this quest planned before; keep the playhead rule -and the separate wait). - -Interim rule, decided 2026-11-17 (maintainer, /quest-run, -[moq-dev/moq#8982](https://github.com/moq-dev/moq/pull/8982)): ✅ browser -audio ends a hole once the group past it trails the clock by the ring's -stretch bound (`playable(sync, output)` in `js/watch/src/audio/playhead.ts`), -the rule #8982 ships (rejected: main's bare clock with only the replay harness -fixed and re-budgeted; the estimate wait, which brought back the Firefox resume -silence). It is the only option with no measured regression in the browser, -and native audio keeps its estimate wait until -[moq-dev/moq#8984](https://github.com/moq-dev/moq/pull/8984) settles one rule. -The work below replaces `playable` with the ordered reader's `Gap`, so -`playable` and the audio consumer's clock go with it. - -Why the playhead rule goes: natively, ending an audio hole once the clock -reaches the group past it took `bursty` from 3 to 155 underruns a minute -(`just test audio-quality --runtimes native --codecs opus --duration 40 ---seed 7`). A burst's groups land late together, so the group past a hole is -already due when the missing one lands a moment later in the same burst. -Native audio instead waits a hole out for its playout estimate from the -arrival of the group past it (`rs/moq-audio/src/decode/consumer.rs`), and -[moq-dev/moq#8984](https://github.com/moq-dev/moq/pull/8984) makes that wait -the subscription's `Delay::min`. Rust `track::Ordered` -([moq-dev/moq#8910](https://github.com/moq-dev/moq/pull/8910)) gives up on a -missing group by the same two clocks: the live edge's timestamp a budget past -it, or its successor's arrival a budget ago. So the rule lives once, in the -transport. +the container consumer; keep the playhead rule and the separate wait). + +[moq-dev/moq#9068](https://github.com/moq-dev/moq/pull/9068) moved browser +audio onto the ordered reader: `Ordered.nextGroup` returns a `Gap` for each +group it gives up on, audio reads through a second subscription whose +budget is what the ring holds plus the stretch bound and the warmup, and +the audio container consumer plays each `Gap` as its hole. Firefox's +`after resume` window stays audible. + +Its local Chromium measurement, three runs each of the PR, its merge base, +and `cf23b5ae04~1` (before #8799), could not grade the rows: the machine sat +at a load average of 30 to 70, and render underruns reached 580 a minute on +the merge base. The player-side numbers were level with the merge base on +`congestion`, which also trimmed about half the audio it did before #8799. +On `bursty` they were mixed, and one Opus `bursty` run of seven starved for +its last 7.5 s: the playhead held still while the render clock ran, which no +merge-base or pre-#8799 run did, and four reruns did not repeat it. Work: -- Mirror `track::Ordered`'s `Item::{Group, Gap { range, error }}` in - `@moq/net`, whose `Ordered` handle (`js/net/src/track.ts`) skips a stale or - dropped group silently today, with the reader's own budget as in Rust. - This is #8910's follow-up "mirror `Item` in `@moq/net` once a consumer - needs it"; the bindings follow when a binding consumer needs it. -- The budget is what the ring holds (`ring.held(delay)` in - `js/watch/src/audio/decoder.ts`), and follows it as the delay estimate, - stretch, and output latency move. It is the reader's, not the - subscription's: the subscription keeps reaching the estimator's 2 s - ceiling past the delay, since a group the relay expires is never observed - and the estimate could not rise after underruns. -- The audio container consumer (`js/hang/src/container/consumer.ts`, used - from `js/watch/src/audio/decoder.ts` and `replay.ts`) reads ordered for - audio, turns each `Gap` into its hole, and drops its own hole wait and the - `playhead` it is passed. -- Measure the Chromium `bursty` and `congestion` rows before and after, a few - runs each, since `congestion` is noisy. Confirm the resume hole with - #8799's repro, `taskset -c 4-5 nix develop --command just test media - --media-engines firefox --media-cases rename,pause`. +- Grade the Chromium `bursty` and `congestion` rows from the nightly + runner's `audio-quality-run` artifacts after #9068 lands, against the + nights before it and before #8799. +- Find what starved that run. The audio container consumer + (`js/hang/src/container/consumer.ts`) in ordered mode has nothing that + passes an active group that opened but never delivers a frame until the + max buffer fills, which #8799's playhead covered. A trace recorded with + `--trace` from a run that starves would replay it. ## Related diff --git a/quest/m2/unused-api/net.md b/quest/m2/unused-api/net.md index d26237a297f..b74f5895109 100644 --- a/quest/m2/unused-api/net.md +++ b/quest/m2/unused-api/net.md @@ -76,4 +76,4 @@ Wire: none. ## Related -- [Browser audio holes](/quest/m2/audio-playout/browser-audio-hole-skip.md) - the browser counterpart of the reader moving onto `Gap` +- [Browser audio holes](/quest/m2/audio-playout/browser-audio-hole-skip.md) - grading the browser counterpart, which already reads `Gap`s diff --git a/test/audio-quality/README.md b/test/audio-quality/README.md index ea75e7544a5..83b97d56642 100644 --- a/test/audio-quality/README.md +++ b/test/audio-quality/README.md @@ -226,8 +226,9 @@ receives it, with the same transport, container, and codec-duration readers over on the delay, so the replay decides those again. `replay.ts` plays a trace through the player's own `Container.Consumer` and ring on a simulated -clock ([`js/watch/src/audio/replay.ts`](../../js/watch/src/audio/replay.ts)), whose consumer is told -the trace's `largest` as a wire subscriber is told by the publisher, at the "auto" delay a +clock ([`js/watch/src/audio/replay.ts`](../../js/watch/src/audio/replay.ts)), whose consumer reads +the groups through an ordered reader and observes every arrival through a second subscription, as +the browser player does, at the "auto" delay a real `Sync` resolves from the playout target that consumer measures, and reads each quantum through the tap's classifier. The consumer makes the player's group ordering, max delay skips, and discontinuity resets again at that delay, and the ring follows the delay as it moves; a group's stream is taken to finish with its last recorded frame. Every @@ -256,8 +257,8 @@ microphone, instead of publishing Chromium's fake capture device. Name the brows the trace's `source` before checking it in. Version 4 adds `largest`, the publisher's largest group as the subscription began, which a wire -subscriber learns from the publisher's answer and the replay's consumer needs to tell a group it -skips unread as the join's backlog. The recorder and the `--capture` observer read it the way +subscriber learns from the publisher's answer. The replay no longer reads it: its consumer observes +every arrival, the join's backlog included, through its second subscription. The recorder and the `--capture` observer read it the way `js/hang`'s consumer does: once the track's info or first group shows the subscription established and its start resolved, so a cached group racing the answer, or live groups landing after it, do not set it. No earlier recording kept the answer, and re-recording needs a person at the microphone and From 08e280a9f5757c6d331ea5f8c4c284e1b40e4da0 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 17 Nov 2026 22:58:17 -0800 Subject: [PATCH 12/23] fix(net): an ordered read folds its record, and passes what it reports - A record past 1024 runs folds its older half into a floor below the read, as Rust's Record folds under pool pressure, so timestamp-keyed audio no longer grows it per group. - A gap moves the key cursor past it, so a group landing there after is never handed out. - A group held past a gap under a cap lowered off it still polls the cursor, so the read sees the track or itself end. - A stale or headless group passes the owed keys below it as gaps. Co-Authored-By: Claude Opus 5.5 --- js/net/src/ordered.test.ts | 66 +++++++++++++++++++++++++++++++++++++- js/net/src/track.ts | 51 +++++++++++++++++++++++++---- 2 files changed, 109 insertions(+), 8 deletions(-) diff --git a/js/net/src/ordered.test.ts b/js/net/src/ordered.test.ts index f5e27969541..eb4a2b380f4 100644 --- a/js/net/src/ordered.test.ts +++ b/js/net/src/ordered.test.ts @@ -1,7 +1,7 @@ // What an ordered read returns: groups in key order, and a gap for every group it gives up on. // Ports the Rust `track::Ordered` item tests, so both read the same. import { expect, test } from "bun:test"; -import { Duration } from "@moq/clock"; +import { Duration, sleep } from "@moq/clock"; import { Manual } from "@moq/clock/test"; import { StreamCode, StreamError } from "./error.ts"; import { hooks } from "./internal.ts"; @@ -200,3 +200,67 @@ test("a local track waits for what it asked a fill for, and reports a gap once t expect(items(ordered)).toEqual(["gap 3..4 (old)", "group 4"]); requests.close(); })); + +test("a gap moves the read past it, so a group landing there after is no group", () => { + const producer = new TrackProducer("test"); + const ordered = producer.subscribe({ delay: { max: null } }).ordered(); + put(producer, 0n); + expect(items(ordered)).toEqual(["group 0"]); + drop(producer, 1n, 2n); + expect(items(ordered)).toEqual(["gap 1..2 (delivery timeout)"]); + put(producer, 1n); + expect(items(ordered)).toEqual([]); + put(producer, 2n); + expect(items(ordered)).toEqual(["group 2"]); +}); + +test("a group held past a gap, under a cap lowered off it, still sees the read end", async () => { + const producer = new TrackProducer("test"); + const ordered = producer.subscribe({ delay: { max: null } }).ordered(); + put(producer, 0n); + drop(producer, 1n, 2n); + put(producer, 2n); + expect((await ordered.nextGroup())?.group?.start).toBe(0n); + expect((await ordered.nextGroup())?.kind).toBe("gap"); + ordered.withRange({ end: { excluded: 2n } }); + expect(ordered.tryNextGroup()).toBeUndefined(); + const pending = ordered.nextGroup(); + ordered.close(); + const ended = await Promise.race([ + pending.then( + () => "ended", + () => "ended", + ), + sleep(Duration.millis(100)).then(() => "hung"), + ]); + expect(ended).toBe("ended"); +}); + +test("a stale group passes the owed holes below it as gaps", () => + withClock((clock) => { + const producer = receivedTrack(); + const ordered = producer.subscribe({ delay: { max: Duration.millis(50) } }).ordered(); + put(producer, 0n, false); + expect(items(ordered)).toEqual(["group 0"]); + // Group 1 is owed; group 3 lands, then group 2 after it, which turns stale while the wall + // clock still spares the hole at 1. + put(producer, 3n, false); + clock.jump(Duration.millis(30)); + put(producer, 2n, false); + clock.jump(Duration.millis(30)); + expect(items(ordered)).toEqual(["gap 1..3 (old)", "group 3"]); + })); + +test("an ordered read's record folds, so it costs a bounded number of runs", () => { + const producer = new TrackProducer("test"); + const ordered = producer.subscribe({ delay: { max: null } }).ordered(); + // Keyed apart, as audio by timestamp is: each group is a run of its own. + for (let i = 0n; i < 3000n; i++) { + put(producer, i * 20n); + expect(items(ordered)).toEqual([`group ${i * 20n}`]); + } + // A group landing far below the floor is told as nothing; one above it is still a gap. + put(producer, 10n); + put(producer, 2990n * 20n + 10n); + expect(items(ordered)).toEqual([`gap ${2990n * 20n + 10n}..${2990n * 20n + 11n} (old)`]); +}); diff --git a/js/net/src/track.ts b/js/net/src/track.ts index 9ae775fea82..3edaa60ce9d 100644 --- a/js/net/src/track.ts +++ b/js/net/src/track.ts @@ -2632,6 +2632,10 @@ type Drift = { // the highest key returned, as a group or the end of a gap. type Items = { held?: GroupConsumer; gaps: DropRun[]; at: bigint }; +// The most runs an ordered read's record keeps before it folds the older half into its floor. +// Audio keyed by timestamp leaves a run per group, so without it the record grows with playback. +const RECORD_RUNS = 1024; + // A group that landed after an ordered read passed its key. function late(): Hole { return { error: new StreamError(StreamCode.Old, { message: "group landed after the read passed it" }) }; @@ -2785,6 +2789,10 @@ export class Subscriber { coverage?: Coverage; }; #reported = new Runs(sameReport); + // Everything below was settled for good and folded out of #reported: handed out, told, or + // passed, so nothing there is reported again. Mirrors the Rust `Record::floor`, which folds + // under pool pressure; an ordered read folds once its record passes RECORD_RUNS. + #floor = 0n; // What an ordered read owes before its next group; unset before its first read. See #tryItem. #items?: Items; // The group the frame-level helpers are currently draining, acquired through the @@ -4591,7 +4599,7 @@ export class Subscriber { // The first part of `[from, to)` nothing already reported blocks, now reported, with why, // replacing what it goes out over. Mirrors the Rust `Record::report`. #reportRun(from: bigint, to: bigint, hole: Hole): (Recv & { kind: "drop" }) | undefined { - const start = from; + const start = max(from, this.#floor); if (start >= to) return undefined; const blocked = this.#reported.overlapping(start, to).filter((reported) => blocksHole(reported, hole)); const [gap] = runGaps(blocked, start, to); @@ -4840,6 +4848,7 @@ export class Subscriber { // The drop record starts before the first read, so the cursor keeps what it gives up. this.#findGaps(items); } + this.#fold(items); const read = this.#readHeld(items); this.#findGaps(items); switch (read.kind) { @@ -4886,11 +4895,15 @@ export class Subscriber { if (held) { items.held = undefined; if (this.#covered(held.start, held.start + 1n).length > 0) return { kind: "group", group: held }; - // The bounds moved off it. With nothing they cover above, it waits for them to widen again; - // otherwise the read passes it. + // The bounds moved off it. With nothing they cover above, it waits for them to widen again, + // still polling the cursor so the read sees the track or itself end; otherwise the read + // passes it. if (this.#covered(held.start, UNBOUNDED).length === 0) { - items.held = held; - return { kind: "idle" }; + const read = this.#tryNextGroup(); + // A clean end keeps it, as the buffer keeps a group past the cap, for a raise to read. + if (read.kind === "error") held.close(); + else items.held = held; + return read.kind === "done" || read.kind === "error" ? read : { kind: "idle" }; } held.close(); } @@ -4937,6 +4950,14 @@ export class Subscriber { items.at = max(items.at, given.end); // Told once: no later drop of these keys is a gap again. this.#settled(given.start, given.end); + // Passed for good: no group there is handed out after it, whether it lands late here or on + // a resumed reader's copy. + this.#delivered.addRun(given.start, given.end); + if (!this.#resume && this.#nextKey < given.end) { + const passed = this.#nextKey; + this.#nextKey = given.end; + this.#stoppedReading(passed, given.end); + } return { kind: "gap", start: given.start, end: given.end, error }; } @@ -4952,7 +4973,20 @@ export class Subscriber { // Record `[start, end)` as settled: handed out, or told as a gap. #settled(start: bigint, end: bigint): void { - this.#reported.set(start, end, { start, end, kind: "settled" }); + start = max(start, this.#floor); + if (start < end) this.#reported.set(start, end, { start, end, kind: "settled" }); + } + + // Fold the older half of the record into the floor once it passes RECORD_RUNS, never past + // where the read is, so the record costs a bounded number of runs however long it plays. A + // group landing below the floor, which no read could take, is then told as nothing. + #fold(items: Items): void { + const runs = this.#reported.all; + if (runs.length <= RECORD_RUNS) return; + const floor = min(runs[runs.length - RECORD_RUNS / 2].start, items.at); + if (floor <= this.#floor) return; + this.#floor = floor; + this.#reported.set(0n, floor); } // The key cursor passes `[start, end)` to hand out the group at `end`. Each key there that the @@ -5062,6 +5096,8 @@ export class Subscriber { // Every frame this group could still hold is past the budget, so keep // scanning: one pass walks a whole backlog off rather than replaying it. if (this.#staleAt(group.start, drift)) { + // Passing it passes the owed keys below it too, which the budget gives up with it. + this.#passOwed(start, group.start, drift); this.#giveUp({ start: group.start, end: group.start + 1n }, staleHole(drift.budget)); const passed = this.#nextKey; this.#pass(groups, index); @@ -5082,7 +5118,8 @@ export class Subscriber { this.#fillWait = true; return { kind: "idle" }; } - // Given up: past it, as past any group no fill can serve. + // Given up: past it, as past any group no fill can serve, and the owed keys below it. + this.#passOwed(start, group.start, drift); this.#giveUp({ start: group.start, end: group.start + 1n }, headless()); const passed = this.#nextKey; this.#pass(groups, index); From e2cfd619d44e2fcaaeb2cde43942378456ee129c Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 17 Nov 2026 23:10:12 -0800 Subject: [PATCH 13/23] fix(net): a resumed reader's copies fold their records, and a gap compacts what was handed out The fold runs where the record grows, for every key-order read but a wire publisher's, whose record is what its wire was told. A gap forgets below its end as a hand-out does. Co-Authored-By: Claude Opus 5.5 --- js/net/src/internal.ts | 5 +++++ js/net/src/ordered.test.ts | 33 ++++++++++++++++++++++++++++++++- js/net/src/track.ts | 38 ++++++++++++++++++++++++-------------- 3 files changed, 61 insertions(+), 15 deletions(-) diff --git a/js/net/src/internal.ts b/js/net/src/internal.ts index 24b86efa33d..3564edb98e3 100644 --- a/js/net/src/internal.ts +++ b/js/net/src/internal.ts @@ -825,6 +825,8 @@ export const hooks: { exhaustedFor: (subscriber: Subscriber, delivered: Delivered) => boolean; /** How many runs of handed-out groups a subscriber remembers: one per gap, plus the floor. Tests only. */ deliveredRuns: (subscriber: Subscriber) => number; + /** How many runs a subscriber's record of what it reported holds. Tests only. */ + reportedRuns: (subscriber: Subscriber) => number; /** Whether the subscriber already handed out group `key`, or no longer expects it. */ handedOut: (subscriber: Subscriber, key: bigint) => boolean; /** Forget the gaps in another reader's `delivered` below each group past this subscriber's budget. */ @@ -1178,6 +1180,9 @@ export const hooks: { deliveredRuns: () => { throw new Error("track.ts not loaded"); }, + reportedRuns: () => { + throw new Error("track.ts not loaded"); + }, handedOut: () => { throw new Error("track.ts not loaded"); }, diff --git a/js/net/src/ordered.test.ts b/js/net/src/ordered.test.ts index eb4a2b380f4..8d26a1152fc 100644 --- a/js/net/src/ordered.test.ts +++ b/js/net/src/ordered.test.ts @@ -253,14 +253,45 @@ test("a stale group passes the owed holes below it as gaps", () => test("an ordered read's record folds, so it costs a bounded number of runs", () => { const producer = new TrackProducer("test"); - const ordered = producer.subscribe({ delay: { max: null } }).ordered(); + const sub = producer.subscribe({ delay: { max: null } }); + const ordered = sub.ordered(); // Keyed apart, as audio by timestamp is: each group is a run of its own. for (let i = 0n; i < 3000n; i++) { put(producer, i * 20n); expect(items(ordered)).toEqual([`group ${i * 20n}`]); } // A group landing far below the floor is told as nothing; one above it is still a gap. + expect(hooks.reportedRuns(sub)).toBeLessThanOrEqual(1024); put(producer, 10n); put(producer, 2990n * 20n + 10n); expect(items(ordered)).toEqual([`gap ${2990n * 20n + 10n}..${2990n * 20n + 11n} (old)`]); }); + +test("a key-order read draining its drops folds its record, as a resumed reader's copy does", () => { + const producer = new TrackProducer("test"); + const sub = producer.subscribe({ delay: { max: null } }); + // Keyed apart with the keys between skipped, so each skip is a run of its own. + for (let i = 0n; i < 3000n; i++) { + put(producer, i * 20n); + producer.skipGroups(i * 20n + 1n, i * 20n + 20n); + const read = hooks.tryNextGroup(sub); + if (read.kind === "group") read.group.close(); + while (hooks.tryDrop(sub)); + } + expect(hooks.reportedRuns(sub)).toBeLessThanOrEqual(1024); + sub.close(); +}); + +test("a read returning only gaps keeps its handed-out record compact", () => { + const producer = new TrackProducer("test"); + const sub = producer.subscribe({ delay: { max: null } }); + const ordered = sub.ordered(); + put(producer, 0n); + expect(items(ordered)).toEqual(["group 0"]); + for (let i = 1n; i <= 100n; i++) { + producer.skipGroups(i * 20n - 19n, i * 20n); + drop(producer, i * 20n, i * 20n + 1n); + expect(items(ordered)).toEqual([`gap ${i * 20n}..${i * 20n + 1n} (delivery timeout)`]); + } + expect(hooks.deliveredRuns(sub)).toBe(1); +}); diff --git a/js/net/src/track.ts b/js/net/src/track.ts index 3edaa60ce9d..2ad32c933d5 100644 --- a/js/net/src/track.ts +++ b/js/net/src/track.ts @@ -2791,8 +2791,10 @@ export class Subscriber { #reported = new Runs(sameReport); // Everything below was settled for good and folded out of #reported: handed out, told, or // passed, so nothing there is reported again. Mirrors the Rust `Record::floor`, which folds - // under pool pressure; an ordered read folds once its record passes RECORD_RUNS. + // under pool pressure; a key-order read folds once its record passes RECORD_RUNS. #floor = 0n; + // A wire publisher reads #reported as what its wire was told, so it never folds. + #wired = false; // What an ordered read owes before its next group; unset before its first read. See #tryItem. #items?: Items; // The group the frame-level helpers are currently draining, acquired through the @@ -3264,6 +3266,7 @@ export class Subscriber { // The publisher's view of this reader's record. #wireRecord(): WireRecord { + this.#wired = true; const reported = this.#reported; return { told: (key) => reported.at(key) !== undefined, @@ -4001,6 +4004,7 @@ export class Subscriber { hooks.forgetPastBudget = (subscriber, delivered) => subscriber.#forgetPastBudget(delivered); hooks.wire = (subscriber) => subscriber.#wireRecord(); hooks.deliveredRuns = (subscriber) => subscriber.#delivered.runs; + hooks.reportedRuns = (subscriber) => subscriber.#reported.size; hooks.handedOut = (subscriber, key) => subscriber.#delivered.has(key); hooks.hasUnreadGroup = (subscriber, start, end, delivered) => subscriber.#state.groups @@ -4605,6 +4609,7 @@ export class Subscriber { const [gap] = runGaps(blocked, start, to); if (!gap) return undefined; this.#reported.set(gap.start, gap.end, { ...gap, kind: hole.skip ? "skip" : "dropped" }); + this.#fold(); return { kind: "drop", ...gap, error: hole.error, skip: hole.skip, stale: hole.stale }; } @@ -4848,7 +4853,6 @@ export class Subscriber { // The drop record starts before the first read, so the cursor keeps what it gives up. this.#findGaps(items); } - this.#fold(items); const read = this.#readHeld(items); this.#findGaps(items); switch (read.kind) { @@ -4950,14 +4954,14 @@ export class Subscriber { items.at = max(items.at, given.end); // Told once: no later drop of these keys is a gap again. this.#settled(given.start, given.end); - // Passed for good: no group there is handed out after it, whether it lands late here or on - // a resumed reader's copy. - this.#delivered.addRun(given.start, given.end); - if (!this.#resume && this.#nextKey < given.end) { - const passed = this.#nextKey; - this.#nextKey = given.end; - this.#stoppedReading(passed, given.end); - } + // Passed for good, as a group handed out is: an ordered read never goes back, so no group + // below its end is handed out after it, whether it lands late here or on a resumed + // reader's copy, and a fill no longer owes it there. + const floor = this.#delivered.runEnd(0n) ?? 0n; + this.#delivered.forgetBelow(given.end); + const forgot = this.#delivered.runEnd(0n) ?? 0n; + if (forgot > floor) this.#stoppedReading(floor, forgot); + if (!this.#resume) this.#nextKey = max(this.#nextKey, given.end); return { kind: "gap", start: given.start, end: given.end, error }; } @@ -4975,15 +4979,21 @@ export class Subscriber { #settled(start: bigint, end: bigint): void { start = max(start, this.#floor); if (start < end) this.#reported.set(start, end, { start, end, kind: "settled" }); + this.#fold(); } // Fold the older half of the record into the floor once it passes RECORD_RUNS, never past // where the read is, so the record costs a bounded number of runs however long it plays. A - // group landing below the floor, which no read could take, is then told as nothing. - #fold(items: Items): void { + // group landing below the floor, which no read could take, is then told as nothing. A key-order + // read folds, an ordered one or a resumed reader's copy; a wire publisher's record is what its + // wire was told, which it keeps. + #fold(): void { const runs = this.#reported.all; - if (runs.length <= RECORD_RUNS) return; - const floor = min(runs[runs.length - RECORD_RUNS / 2].start, items.at); + if (runs.length <= RECORD_RUNS || this.#wired) return; + // Where the read is: the keys it handed out or passed, and the items it returned. + let at = this.#delivered.runEnd(0n) ?? 0n; + if (this.#items) at = min(at, this.#items.at); + const floor = min(runs[runs.length - RECORD_RUNS / 2].start, at); if (floor <= this.#floor) return; this.#floor = floor; this.#reported.set(0n, floor); From 7d9b48693be1ce130c6ad116c6408ad301d0d4eb Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 18 Nov 2026 02:48:15 -0800 Subject: [PATCH 14/23] fix(net): an ordered read folds its record at where it is, with no run cap The floor follows the read: a key-order read folds below the keys it handed out or passed, held below every run it still owes a report and every gap it found and not returned. A resumed reader's copies fold at the reader's position, so a copy that hands out nothing while the reader returns gaps stays bounded too. Replaces the 1024-run fold. Unlike Rust, a group a local track produces after the read passed its key is no gap; a session-fed track still reports every key it passed. Co-Authored-By: Claude Opus 5.5 --- js/net/src/internal.ts | 5 ++++ js/net/src/ordered.test.ts | 55 +++++++++++++++++++++++++++++++------- js/net/src/resume.test.ts | 37 +++++++++++++++++++++++++ js/net/src/resume.ts | 4 +++ js/net/src/track.ts | 53 +++++++++++++++++++----------------- 5 files changed, 119 insertions(+), 35 deletions(-) diff --git a/js/net/src/internal.ts b/js/net/src/internal.ts index 3564edb98e3..8875cf85b42 100644 --- a/js/net/src/internal.ts +++ b/js/net/src/internal.ts @@ -831,6 +831,8 @@ export const hooks: { handedOut: (subscriber: Subscriber, key: bigint) => boolean; /** Forget the gaps in another reader's `delivered` below each group past this subscriber's budget. */ forgetPastBudget: (subscriber: Subscriber, delivered: Delivered) => void; + /** Fold a route copy's record below `at`, where the reader it feeds is, which reports nothing there. */ + fold: (subscriber: Subscriber, at: bigint) => void; /** * What a lite publisher told its wire about a subscriber's keys, kept in the * subscriber's own record. Mirrors the Rust crate-private `track::Subscriber::record_mut`. @@ -1171,6 +1173,9 @@ export const hooks: { forgetPastBudget: () => { throw new Error("track.ts not loaded"); }, + fold: () => { + throw new Error("track.ts not loaded"); + }, wire: () => { throw new Error("track.ts not loaded"); }, diff --git a/js/net/src/ordered.test.ts b/js/net/src/ordered.test.ts index 8d26a1152fc..4d32b5a94b9 100644 --- a/js/net/src/ordered.test.ts +++ b/js/net/src/ordered.test.ts @@ -150,14 +150,15 @@ test("a cached group the seek passes as stale is a gap", () => expect(items(ordered)).toEqual(["gap 0..1 (old)", "group 1", "group 2"]); })); -test("a late arrival is a gap, told once", () => { +// Rust reports it Old; JS keeps no record below the read, so its memory stays bounded. +test("a local track's late arrival is no gap", () => { const producer = new TrackProducer("test"); const ordered = producer.subscribe({ delay: { max: null } }).ordered(); put(producer, 0n); put(producer, 5n); expect(items(ordered)).toEqual(["group 0", "group 5"]); put(producer, 3n); - expect(items(ordered)).toEqual(["gap 3..4 (old)"]); + expect(items(ordered)).toEqual([]); put(producer, 6n); expect(items(ordered)).toEqual(["group 6"]); }); @@ -251,23 +252,57 @@ test("a stale group passes the owed holes below it as gaps", () => expect(items(ordered)).toEqual(["gap 1..3 (old)", "group 3"]); })); -test("an ordered read's record folds, so it costs a bounded number of runs", () => { +test("an ordered read's record holds only what lies ahead of it", () => { const producer = new TrackProducer("test"); const sub = producer.subscribe({ delay: { max: null } }); const ordered = sub.ordered(); - // Keyed apart, as audio by timestamp is: each group is a run of its own. + // Keyed apart, as audio by timestamp is: each group would be a run of its own. for (let i = 0n; i < 3000n; i++) { put(producer, i * 20n); expect(items(ordered)).toEqual([`group ${i * 20n}`]); + expect(hooks.reportedRuns(sub)).toBeLessThanOrEqual(1); } - // A group landing far below the floor is told as nothing; one above it is still a gap. - expect(hooks.reportedRuns(sub)).toBeLessThanOrEqual(1024); + // Unlike Rust, a group a local track produces below the read is told as nothing. put(producer, 10n); - put(producer, 2990n * 20n + 10n); - expect(items(ordered)).toEqual([`gap ${2990n * 20n + 10n}..${2990n * 20n + 11n} (old)`]); + put(producer, 2998n * 20n + 10n); + expect(items(ordered)).toEqual([]); }); -test("a key-order read draining its drops folds its record, as a resumed reader's copy does", () => { +// A key-order read, as a route copy is read, folds at each hand-out while the keys it passed +// still wait to be reported. +test("a session-fed key-order read folds without losing the keys it passed", () => + withClock((clock) => { + const producer = receivedTrack(); + const sub = producer.subscribe({ delay: { max: Duration.millis(50) } }); + const read = () => { + const out: string[] = []; + for (let drop = hooks.tryDrop(sub); drop; drop = hooks.tryDrop(sub)) + out.push(`drop ${drop.start}..${drop.end}`); + const next = hooks.tryNextGroup(sub); + if (next.kind === "group") { + next.group.close(); + out.push(`group ${next.group.start}`); + } + for (let drop = hooks.tryDrop(sub); drop; drop = hooks.tryDrop(sub)) + out.push(`drop ${drop.start}..${drop.end}`); + return out; + }; + put(producer, 0n, false); + expect(read()).toEqual(["group 0"]); + for (let i = 1n; i <= 100n; i++) { + // Group 3i-2 never lands, and 3i-1 turns stale behind 3i: the read passes both to hand + // out 3i, and still reports them. + put(producer, 3n * i, false); + clock.jump(Duration.millis(30)); + put(producer, 3n * i - 1n, false); + clock.jump(Duration.millis(30)); + expect(read()).toEqual([`group ${3n * i}`, `drop ${3n * i - 2n}..${3n * i}`]); + } + expect(hooks.reportedRuns(sub)).toBeLessThanOrEqual(2); + sub.close(); + })); + +test("a key-order read draining its drops folds its record", () => { const producer = new TrackProducer("test"); const sub = producer.subscribe({ delay: { max: null } }); // Keyed apart with the keys between skipped, so each skip is a run of its own. @@ -278,7 +313,7 @@ test("a key-order read draining its drops folds its record, as a resumed reader' if (read.kind === "group") read.group.close(); while (hooks.tryDrop(sub)); } - expect(hooks.reportedRuns(sub)).toBeLessThanOrEqual(1024); + expect(hooks.reportedRuns(sub)).toBeLessThanOrEqual(1); sub.close(); }); diff --git a/js/net/src/resume.test.ts b/js/net/src/resume.test.ts index 03fdab08ef5..4f6e8e4dca1 100644 --- a/js/net/src/resume.test.ts +++ b/js/net/src/resume.test.ts @@ -2077,6 +2077,43 @@ test("a resumed reader reports a drop once and still serves a late group", async a.close(); }); +// A copy folds its record at where the reader is, so one that only reports drops while the reader +// returns gaps holds a bounded record however long it plays. +test("a route copy's record folds while the reader returns only gaps", () => { + const copies = new Set(); + const fold = hooks.fold; + hooks.fold = (sub, at) => { + copies.add(sub); + fold(sub, at); + }; + const front = new Front(); + const a = new BroadcastProducer(); + const ta = copy(a); + front.serve(a.consume()); + const ordered = front.consumer + .track("seq") + .subscribe({ delay: { max: null } }) + .ordered(); + try { + ta.write(0n); + expect(ordered.tryNextGroup()).toMatchObject({ kind: "group" }); + const cut = new StreamError(StreamCode(70), { message: "cut" }); + for (let i = 1n; i <= 1000n; i++) { + // A drop and a skip apart, so each would be a run of its own in the copy's record. + hooks.dropTrackGroups(ta.producer, 2n * i - 1n, 2n * i, { error: cut }); + ta.producer.skipGroups(2n * i, 2n * i + 1n); + expect(ordered.tryNextGroup()).toMatchObject({ kind: "gap", start: 2n * i - 1n, end: 2n * i }); + } + expect(copies.size).toBeGreaterThan(0); + for (const sub of copies) expect(hooks.reportedRuns(sub)).toBeLessThanOrEqual(4); + } finally { + hooks.fold = fold; + ordered.close(); + front.consumer.close(); + a.close(); + } +}); + // A skip of a run the serving copy already dropped replaces the drop, so the resumed reader // reports it again, as a skip, and only once. Mirrors Rust. test("a resumed reader reports a skip over a reported drop", () => { diff --git a/js/net/src/resume.ts b/js/net/src/resume.ts index a20d591635f..18980d23acd 100644 --- a/js/net/src/resume.ts +++ b/js/net/src/resume.ts @@ -913,6 +913,10 @@ class Reader implements ResumeSource { */ #tryDrop(delivered: Delivered): (Recv & { kind: "drop" }) | undefined { if (this.#closed) return undefined; + // Below what the reader handed out or passed, no copy's drop is reported, so each copy's + // record folds there, even one that hands out nothing while the reader returns gaps. + const at = delivered.runEnd(0n) ?? 0n; + for (const copy of this.#copies) hooks.fold(copy.sub, at); const serving = this.#serving(); if (serving) { // A received stale run queued here that a new upstream subscription superseded since is diff --git a/js/net/src/track.ts b/js/net/src/track.ts index 2ad32c933d5..71cd2231761 100644 --- a/js/net/src/track.ts +++ b/js/net/src/track.ts @@ -2632,10 +2632,6 @@ type Drift = { // the highest key returned, as a group or the end of a gap. type Items = { held?: GroupConsumer; gaps: DropRun[]; at: bigint }; -// The most runs an ordered read's record keeps before it folds the older half into its floor. -// Audio keyed by timestamp leaves a run per group, so without it the record grows with playback. -const RECORD_RUNS = 1024; - // A group that landed after an ordered read passed its key. function late(): Hole { return { error: new StreamError(StreamCode.Old, { message: "group landed after the read passed it" }) }; @@ -2791,7 +2787,7 @@ export class Subscriber { #reported = new Runs(sameReport); // Everything below was settled for good and folded out of #reported: handed out, told, or // passed, so nothing there is reported again. Mirrors the Rust `Record::floor`, which folds - // under pool pressure; a key-order read folds once its record passes RECORD_RUNS. + // under pool pressure; a key-order read folds at where it is instead (see #fold). #floor = 0n; // A wire publisher reads #reported as what its wire was told, so it never folds. #wired = false; @@ -3122,6 +3118,7 @@ export class Subscriber { const forgot = this.#delivered.runEnd(0n) ?? 0n; if (forgot > floor) this.#stoppedReading(floor, forgot); if (key >= forgot) this.#stoppedReading(key, key + 1n); + if (ordered) this.#fold(forgot); } // This reader stopped reading `[start, end)` for good: clip what it asked there, and judge @@ -4002,6 +3999,7 @@ export class Subscriber { return subscriber.#peekGroup(ordered); }; hooks.forgetPastBudget = (subscriber, delivered) => subscriber.#forgetPastBudget(delivered); + hooks.fold = (subscriber, at) => subscriber.#fold(at); hooks.wire = (subscriber) => subscriber.#wireRecord(); hooks.deliveredRuns = (subscriber) => subscriber.#delivered.runs; hooks.reportedRuns = (subscriber) => subscriber.#reported.size; @@ -4609,7 +4607,6 @@ export class Subscriber { const [gap] = runGaps(blocked, start, to); if (!gap) return undefined; this.#reported.set(gap.start, gap.end, { ...gap, kind: hole.skip ? "skip" : "dropped" }); - this.#fold(); return { kind: "drop", ...gap, error: hole.error, skip: hole.skip, stale: hole.stale }; } @@ -4870,6 +4867,7 @@ export class Subscriber { // A group handed out is no gap, even one a drop also named, as a cut group is. if (lowest && lowest.span.start === key) this.#cutGap(items, lowest.index, key, key + 1n); items.at = max(items.at, key + 1n); + this.#fold(this.#delivered.runEnd(0n) ?? 0n); return read; } case "done": @@ -4962,6 +4960,7 @@ export class Subscriber { const forgot = this.#delivered.runEnd(0n) ?? 0n; if (forgot > floor) this.#stoppedReading(floor, forgot); if (!this.#resume) this.#nextKey = max(this.#nextKey, given.end); + this.#fold(forgot); return { kind: "gap", start: given.start, end: given.end, error }; } @@ -4979,24 +4978,25 @@ export class Subscriber { #settled(start: bigint, end: bigint): void { start = max(start, this.#floor); if (start < end) this.#reported.set(start, end, { start, end, kind: "settled" }); - this.#fold(); - } - - // Fold the older half of the record into the floor once it passes RECORD_RUNS, never past - // where the read is, so the record costs a bounded number of runs however long it plays. A - // group landing below the floor, which no read could take, is then told as nothing. A key-order - // read folds, an ordered one or a resumed reader's copy; a wire publisher's record is what its - // wire was told, which it keeps. - #fold(): void { - const runs = this.#reported.all; - if (runs.length <= RECORD_RUNS || this.#wired) return; - // Where the read is: the keys it handed out or passed, and the items it returned. - let at = this.#delivered.runEnd(0n) ?? 0n; - if (this.#items) at = min(at, this.#items.at); - const floor = min(runs[runs.length - RECORD_RUNS / 2].start, at); - if (floor <= this.#floor) return; - this.#floor = floor; - this.#reported.set(0n, floor); + } + + // Fold the record below `at`, where a key-order read is, into the floor, held below every run + // still to report there: a run given up and not reported yet, and a gap found and not returned. + // The record then holds only what lies ahead of the read, bounded however long it plays. A + // session-fed read loses nothing, since every key it passed was handed out or reported; a group + // a local track produces below the floor is told as nothing, where Rust, folding only under pool + // pressure, would report it Old. A wire publisher's record is what its wire was told, which it + // keeps. + #fold(at: bigint): void { + if (this.#wired) return; + if (this.#items) { + at = min(at, this.#items.at); + for (const gap of this.#items.gaps) at = min(at, gap.start); + } + for (const run of this.#pending) if (run.end > this.#floor) at = min(at, run.start); + if (at <= this.#floor) return; + this.#floor = at; + this.#reported.set(0n, at); } // The key cursor passes `[start, end)` to hand out the group at `end`. Each key there that the @@ -5370,7 +5370,10 @@ export class Ordered { * fill could not find, or that landed after the read passed its key. It carries the keys it * spans and is returned once, after any group the read still owes below it and before the * next group above it, or when the track ends. Keys the publisher declared skipped were never - * groups, so they are no gap, and nor is a key a local track never produced. Honors the bounds + * groups, so they are no gap, and nor is a key a local track never produced. Unlike Rust, nor + * is a group a local track produces after the read moved past its key: the read keeps no record + * below where it is, so its memory stays bounded. A session-fed track reports such a key at + * the latest when the read passes it. Honors the bounds * set by {@link withRange}. Like {@link Subscriber.recvGroup}, a read whose ranges all end * finishes once nothing in them is left to deliver. Later reads return `undefined` immediately * too; widening the ranges with {@link update} reads on above the last key returned. From 0097b738d5e937dd2c9ace0966d02a22349a2533 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 18 Nov 2026 03:02:03 -0800 Subject: [PATCH 15/23] fix(net): an ordered read drops the gaps its bounds left out below it A gap the bounds excluded and the read then passed can never come in key order, and an ordered read never goes back, so holding it only pinned the record's floor. It is dropped as the read passes it. Co-Authored-By: Claude Opus 5.5 --- js/net/src/ordered.test.ts | 22 ++++++++++++++++++++++ js/net/src/track.ts | 16 +++++++++++----- 2 files changed, 33 insertions(+), 5 deletions(-) diff --git a/js/net/src/ordered.test.ts b/js/net/src/ordered.test.ts index 4d32b5a94b9..adaffecdc3f 100644 --- a/js/net/src/ordered.test.ts +++ b/js/net/src/ordered.test.ts @@ -302,6 +302,28 @@ test("a session-fed key-order read folds without losing the keys it passed", () sub.close(); })); +test("a gap the bounds left out below the read never pins its record", () => { + const producer = receivedTrack(); + const sub = producer.subscribe({ delay: { max: null } }); + const ordered = sub.ordered(); + put(producer, 0n, false); + expect(items(ordered)).toEqual(["group 0"]); + // Group 1 is owed, so the gap at 2 waits; the bounds then leave both out. + drop(producer, 2n, 3n); + expect(items(ordered)).toEqual([]); + ordered.withRange({ start: { included: 3n } }); + for (let i = 0n; i < 1000n; i++) { + const key = 3n + i * 20n; + put(producer, key, false); + producer.skipGroups(key + 1n, key + 20n); + expect(items(ordered)).toEqual([`group ${key}`]); + } + expect(hooks.reportedRuns(sub)).toBeLessThanOrEqual(1); + // The read never goes back, so widening the bounds again offers nothing below it. + ordered.withRange({ start: { included: 0n } }); + expect(items(ordered)).toEqual([]); +}); + test("a key-order read draining its drops folds its record", () => { const producer = new TrackProducer("test"); const sub = producer.subscribe({ delay: { max: null } }); diff --git a/js/net/src/track.ts b/js/net/src/track.ts index 71cd2231761..e0ebfdedd6f 100644 --- a/js/net/src/track.ts +++ b/js/net/src/track.ts @@ -4981,7 +4981,8 @@ export class Subscriber { } // Fold the record below `at`, where a key-order read is, into the floor, held below every run - // still to report there: a run given up and not reported yet, and a gap found and not returned. + // still to report there: a run given up and not reported yet, and a gap found and not returned + // that the read may still reach. // The record then holds only what lies ahead of the read, bounded however long it plays. A // session-fed read loses nothing, since every key it passed was handed out or reported; a group // a local track produces below the floor is told as nothing, where Rust, folding only under pool @@ -4989,9 +4990,13 @@ export class Subscriber { // keeps. #fold(at: bigint): void { if (this.#wired) return; - if (this.#items) { - at = min(at, this.#items.at); - for (const gap of this.#items.gaps) at = min(at, gap.start); + const items = this.#items; + if (items) { + // A gap the bounds left out below where the read is can never come in key order, and an + // ordered read never goes back, so it is dropped rather than held for a widening. + if ((items.gaps[0]?.start ?? items.at) < items.at) items.gaps = removeRun(items.gaps, 0n, items.at); + at = min(at, items.at); + for (const gap of items.gaps) at = min(at, gap.start); } for (const run of this.#pending) if (run.end > this.#floor) at = min(at, run.start); if (at <= this.#floor) return; @@ -5344,7 +5349,8 @@ export class Ordered { /** * Limit subsequent reads to these groups and return this reader for chaining; see * {@link Subscriber.withRange}. An ordered read never goes back, so lowering the floor - * below a group it already returned offers nothing. + * below a group it already returned offers nothing, not even a gap it passed while the + * range left it out. */ withRange(groups: Groups): this { this.#subscriber.withRange(groups); From 1fc4da3c755e93f217a138de7a0d1d19818bbf3f Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 18 Nov 2026 03:10:07 -0800 Subject: [PATCH 16/23] feat(net): an ordered read's nextGroup yields groups, and nextItem its gaps Follows the maintainer's 2026-11-18 decision for Rust (#9076, quest/m2/outcome-enums/ordered-gaps.md): `Ordered.nextGroup()` and `tryNextGroup()` return groups again, passing any gap, and the new `nextItem()` and `tryNextItem()` return `Item` for the reader that needs the gaps, the audio container consumer. The callers this PR had moved onto `Item` go back to main's code, so the change is additive. Co-Authored-By: Claude Opus 5.5 --- js/hang/src/container/consumer.ts | 2 +- js/json/src/snapshot/consumer.ts | 15 ++-- js/json/src/snapshot/snapshot.test.ts | 21 +++-- js/json/src/stream/codec.test.ts | 2 +- js/json/src/stream/stream.test.ts | 4 +- js/json/src/window/consumer.ts | 7 +- js/json/src/window/window.test.ts | 4 +- js/net/api/index.api.md | 6 +- js/net/bench/drift.ts | 4 +- js/net/bench/frames.ts | 2 +- js/net/src/broadcast.test.ts | 7 +- js/net/src/connection/reload.test.ts | 13 ++- js/net/src/consume.test.ts | 3 +- js/net/src/fill.test.ts | 51 ++++++------ js/net/src/ietf/join.test.ts | 39 +++++---- js/net/src/ietf/range.test.ts | 33 ++++---- js/net/src/ietf/subscriber.test.ts | 29 ++++--- js/net/src/integration.test.ts | 27 +++--- js/net/src/lite/connection.test.ts | 27 +++--- js/net/src/lite/copy_fill.test.ts | 9 +- js/net/src/lite/subscriber.test.ts | 5 +- js/net/src/ordered.test-util.ts | 20 ----- js/net/src/ordered.test.ts | 30 +++++-- js/net/src/resume.test.ts | 31 ++++--- js/net/src/retention.test.ts | 5 +- js/net/src/track.test.ts | 101 +++++++++++------------ js/net/src/track.ts | 63 +++++++++----- js/net/src/untimed.test.ts | 7 +- js/publish/bench/audio-page.ts | 2 +- js/publish/src/announce.test.ts | 2 +- js/publish/src/audio/encoder.test.ts | 18 ++-- js/publish/src/broadcast.test.ts | 6 +- js/publish/src/catalog.test.ts | 6 +- js/publish/src/video/encoder.test.ts | 2 +- test/interop/clients/js-native/ranges.ts | 5 +- 35 files changed, 298 insertions(+), 310 deletions(-) delete mode 100644 js/net/src/ordered.test-util.ts diff --git a/js/hang/src/container/consumer.ts b/js/hang/src/container/consumer.ts index 0b2f794c265..85e12fba925 100644 --- a/js/hang/src/container/consumer.ts +++ b/js/hang/src/container/consumer.ts @@ -403,7 +403,7 @@ export class Consumer { while (this.#full() && this.#groups.length >= 2 && !this.#signals.abort.aborted) await this.#park(); if (this.#signals.abort.aborted) break; - const item = await ordered.nextGroup(); + const item = await ordered.nextItem(); if (!item) break; if (item.kind === "gap") { this.#gap = true; diff --git a/js/json/src/snapshot/consumer.ts b/js/json/src/snapshot/consumer.ts index 6ea2af08922..52bc5054a9b 100644 --- a/js/json/src/snapshot/consumer.ts +++ b/js/json/src/snapshot/consumer.ts @@ -99,26 +99,21 @@ export class Consumer { // the sequence space). // Mirrors the Rust consumer. A newer group restarts from a full snapshot, so switching mid-group loses // nothing but stale state. - for (let item = this.#track.tryNextGroup(); item; item = this.#track.tryNextGroup()) { - // A gap needs nothing: the next group restarts from its own snapshot. - if (item.kind === "gap") continue; + for (let group = this.#track.tryNextGroup(); group; group = this.#track.tryNextGroup()) { this.#group?.close(); - this.#group = item.group; + this.#group = group; this.#framesRead = 0; } } if (!this.#group) { // Advance to the next group with a higher sequence number (skipping late arrivals). - const item = await this.#track.nextGroup(); + const next = await this.#track.nextGroup(); if (this.#closed) { - item?.group?.close(); + next?.close(); return undefined; } - if (!item) return undefined; - // Each group starts from a full snapshot, so a gap needs nothing. - if (item.kind === "gap") continue; - const next = item.group; + if (!next) return undefined; this.#group = next; // The next frame is the new group's snapshot, which also restarts the decoder's window. this.#framesRead = 0; diff --git a/js/json/src/snapshot/snapshot.test.ts b/js/json/src/snapshot/snapshot.test.ts index 036d62592ac..6080e6c9bb6 100644 --- a/js/json/src/snapshot/snapshot.test.ts +++ b/js/json/src/snapshot/snapshot.test.ts @@ -40,7 +40,7 @@ function reader(track: Track.Producer | Consumer): Consumer { async function structure(track: Track.Ordered): Promise { const counts: number[] = []; for (;;) { - const group = (await track.nextGroup())?.group; + const group = await track.nextGroup(); if (!group) break; let frames = 0; @@ -476,7 +476,7 @@ test("a refresh reuses the newest timestamp", async () => { const ordered = track.subscribe({ delay: { max: REPLAY_LATENCY } }).ordered(); const timestamps: (number | undefined)[] = []; - for (let group = (await ordered.nextGroup())?.group; group; group = (await ordered.nextGroup())?.group) { + for (let group = await ordered.nextGroup(); group; group = await ordered.nextGroup()) { const frame = await group.readFrame(); timestamps.push(frame?.timestamp?.asMillis()); while ((await group.readFrame()) !== undefined) {} @@ -506,7 +506,7 @@ test("a refresh after older updates waits for a later one", async () => { const ordered = track.subscribe({ delay: { max: REPLAY_LATENCY } }).ordered(); const restated: [number | undefined, unknown][] = []; - for (let group = (await ordered.nextGroup())?.group; group; group = (await ordered.nextGroup())?.group) { + for (let group = await ordered.nextGroup(); group; group = await ordered.nextGroup()) { const frame = await group.readFrame(); restated.push([frame?.timestamp?.asMillis(), frame && JSON.parse(new TextDecoder().decode(frame.payload))]); while ((await group.readFrame()) !== undefined) {} @@ -537,7 +537,7 @@ test("a scale-less refresh waits for an update past the open group's key", async const ordered = track.subscribe({ delay: { max: REPLAY_LATENCY } }).ordered(); const restated: [bigint, unknown][] = []; - for (let group = (await ordered.nextGroup())?.group; group; group = (await ordered.nextGroup())?.group) { + for (let group = await ordered.nextGroup(); group; group = await ordered.nextGroup()) { const frame = await group.readFrame(); restated.push([group.start, frame && JSON.parse(new TextDecoder().decode(frame.payload))]); while ((await group.readFrame()) !== undefined) {} @@ -679,9 +679,9 @@ test("a delta that would overflow the snapshot rolls a new one instead", async ( // Two groups, a self-contained snapshot each, rather than one whose frame 0 was evicted. const subscriber = track.subscribe({ delay: { max: REPLAY_LATENCY } }).ordered(); - expect((await subscriber.nextGroup())?.group?.start).toBe(0n); - expect((await subscriber.nextGroup())?.group?.start).toBe(1n); - expect((await subscriber.nextGroup())?.group).toBeUndefined(); + expect((await subscriber.nextGroup())?.start).toBe(0n); + expect((await subscriber.nextGroup())?.start).toBe(1n); + expect(await subscriber.nextGroup()).toBeUndefined(); // The newest value is readable with no earlier frame to apply it to. expect(await drain(track)).toEqual([{ v: "y".repeat(size) }]); @@ -744,7 +744,7 @@ test("a scale-less snapshot opens its group at its key, and a delta carries that }, Time.Timestamp.unscaled(9n)); producer.finish(); - const group = (await track.subscribe().ordered().nextGroup())?.group; + const group = await track.subscribe().ordered().nextGroup(); expect(group?.start).toBe(5n); expect((await group?.readFrame())?.timestamp).toEqual(Time.Timestamp.unscaled(5n)); expect((await group?.readFrame())?.timestamp).toEqual(Time.Timestamp.unscaled(5n)); @@ -762,8 +762,7 @@ test("a scale-less snapshot at a key not past the newest group is refused", asyn const ordered = track.subscribe({ delay: { max: REPLAY_LATENCY } }).ordered(); const sequences: bigint[] = []; - for (let group = (await ordered.nextGroup())?.group; group; group = (await ordered.nextGroup())?.group) - sequences.push(group.start); + for (let group = await ordered.nextGroup(); group; group = await ordered.nextGroup()) sequences.push(group.start); expect(sequences).toEqual([5n, 8n]); expect(await drain(track)).toEqual([{ n: 1 }]); }); @@ -783,7 +782,7 @@ test("a capture timestamp is written on snapshots and deltas alike", async () => producer.update({ a: 2, b: "x".repeat(64) }, Time.Timestamp.fromMillis(2_000)); producer.finish(); - const group = (await track.subscribe().ordered().nextGroup())?.group; + const group = await track.subscribe().ordered().nextGroup(); expect((await group?.readFrame())?.timestamp?.as(Time.Timescale.MILLI)).toBe(1_000); expect((await group?.readFrame())?.timestamp?.as(Time.Timescale.MILLI)).toBe(2_000); }); diff --git a/js/json/src/stream/codec.test.ts b/js/json/src/stream/codec.test.ts index 1fdc71a0081..e1ab5b4bdc5 100644 --- a/js/json/src/stream/codec.test.ts +++ b/js/json/src/stream/codec.test.ts @@ -78,7 +78,7 @@ test("a failed write on the very first record still ends the track", async () => // The consumer is handed the group that was already published, and reading it surfaces the // abort. Without ending the track that group stays open and empty, so this read hangs instead. - const group = (await subscriber.nextGroup())?.group; + const group = await subscriber.nextGroup(); expect(group).toBeDefined(); await expect(group?.readFrame()).rejects.toThrow(failure); }); diff --git a/js/json/src/stream/stream.test.ts b/js/json/src/stream/stream.test.ts index 955a79d5edd..a7976113ca9 100644 --- a/js/json/src/stream/stream.test.ts +++ b/js/json/src/stream/stream.test.ts @@ -61,9 +61,9 @@ test("the whole log rides one group, never rolled", async () => { // A single group holds everything, and the consumer reads it all in order. const subscriber = track.subscribe().ordered(); - const group0 = (await subscriber.nextGroup())?.group; + const group0 = await subscriber.nextGroup(); expect(group0?.start).toBe(0n); - const group1 = (await subscriber.nextGroup())?.group; + const group1 = await subscriber.nextGroup(); expect(group1).toBeUndefined(); }); diff --git a/js/json/src/window/consumer.ts b/js/json/src/window/consumer.ts index 7285de51280..9f5232a91ed 100644 --- a/js/json/src/window/consumer.ts +++ b/js/json/src/window/consumer.ts @@ -67,11 +67,8 @@ export class Consumer { if (event && this.#at) return { value: event, at: this.#at }; if (!this.#group) { - const item = await this.#track.nextGroup(); - if (!item) return undefined; - // The next group starts with a checkpoint that accounts for what the gap missed. - if (item.kind === "gap") continue; - this.#group = item.group; + this.#group = await this.#track.nextGroup(); + if (!this.#group) return undefined; this.#codec = this.#decoder.group(); } diff --git a/js/json/src/window/window.test.ts b/js/json/src/window/window.test.ts index f7364d0f25e..0d7e9f480ea 100644 --- a/js/json/src/window/window.test.ts +++ b/js/json/src/window/window.test.ts @@ -217,7 +217,7 @@ test("compressed round-trip across rolls", async () => { async function groups(track: Track.Producer): Promise<[number, number | undefined][]> { const ordered = track.subscribe({ delay: { max: Duration.millis(30_000) } }).ordered(); const out: [number, number | undefined][] = []; - for (let group = (await ordered.nextGroup())?.group; group; group = (await ordered.nextGroup())?.group) { + for (let group = await ordered.nextGroup(); group; group = await ordered.nextGroup()) { const first = await group.readFrame(); let frames = first ? 1 : 0; while ((await group.readFrame()) !== undefined) frames++; @@ -571,7 +571,7 @@ test("edits keep their timestamps, and a scale-less edit its group's key", async producer.finish(); // A scale-less header opens its group at its key, and an op carries that key. - const group = (await track.subscribe().ordered().nextGroup())?.group; + const group = await track.subscribe().ordered().nextGroup(); for (let i = 0; i < 2; i++) expect((await group?.readFrame())?.timestamp).toEqual(at); } }); diff --git a/js/net/api/index.api.md b/js/net/api/index.api.md index 7dafb5fc62f..1eef85f1f6f 100644 --- a/js/net/api/index.api.md +++ b/js/net/api/index.api.md @@ -767,7 +767,8 @@ export namespace Track { isSkipped(start: bigint, end: bigint): boolean; largest(): Promise; readonly name: string; - nextGroup(): Promise; + nextGroup(): Promise; + nextItem(): Promise; readFrame(): Promise<{ frame: number; group: bigint; @@ -775,7 +776,8 @@ export namespace Track { readJson(): Promise; readString(): Promise; get subscription(): Signals.Getter; - tryNextGroup(): Track.Item | undefined; + tryNextGroup(): Group.Consumer | undefined; + tryNextItem(): Track.Item | undefined; update(options: Track.Subscription): void; withRange(groups: Track.Groups): this; } diff --git a/js/net/bench/drift.ts b/js/net/bench/drift.ts index b760dcc7719..639c21c5e89 100644 --- a/js/net/bench/drift.ts +++ b/js/net/bench/drift.ts @@ -75,13 +75,13 @@ export async function run(): Promise { const ordered = subscribers.map((sub) => sub.ordered()); for (let sequence = 0; sequence < retained; sequence++) for (const reader of ordered) { - const group = (await reader.nextGroup())?.group; + const group = await reader.nextGroup(); if (group?.start !== BigInt(sequence)) throw new Error("history missing"); await group.readFrame(); } sources.push(hooks.appendNext(track)); for (const reader of ordered) { - const group = (await reader.nextGroup())?.group; + const group = await reader.nextGroup(); if (!group) throw new Error("live group missing"); consumers.push(group); } diff --git a/js/net/bench/frames.ts b/js/net/bench/frames.ts index 97773915c13..9f6a6d0407a 100644 --- a/js/net/bench/frames.ts +++ b/js/net/bench/frames.ts @@ -108,7 +108,7 @@ const ietf: Protocol = { flags: IETF_FLAGS, }); const done = subscriber.handleGroup(header, new Reader(stream, undefined, IETF_VERSION)); - return { group: ordered.nextGroup().then((item) => item?.group), done }; + return { group: ordered.nextGroup(), done }; }; return { open, close: () => track.close() }; }, diff --git a/js/net/src/broadcast.test.ts b/js/net/src/broadcast.test.ts index 0e5eb31cae8..ba986238ebe 100644 --- a/js/net/src/broadcast.test.ts +++ b/js/net/src/broadcast.test.ts @@ -6,7 +6,6 @@ import * as cache from "./cache.ts"; import { NotFound, StreamCode, TooFarBehind, toStreamCode } from "./error.ts"; import { hooks } from "./internal.ts"; import { textFrame } from "./mock.ts"; -import { nextGroup } from "./ordered.test-util.ts"; import { Timescale, Timestamp } from "./time.ts"; import type { Request as TrackRequest } from "./track.ts"; import { unwanted } from "./util/demand.ts"; @@ -431,7 +430,7 @@ test("subscribe serves a statically inserted track without a request", async () // The track already exists, so subscribe resolves immediately (no requested()). const sub1 = broadcast.track("track1").subscribe().ordered(); - expect((await nextGroup(sub1))?.start).toBe(0n); + expect((await sub1.nextGroup())?.start).toBe(0n); // No on-demand request was emitted for it. expect(await pendingRequest(broadcast)).toBeUndefined(); @@ -441,7 +440,7 @@ test("subscribe serves a statically inserted track without a request", async () const sub2 = broadcast.track("track2").subscribe().ordered(); hooks.appendNext(track2).finish(); - expect((await nextGroup(sub2))?.start).toBe(0n); + expect((await sub2.nextGroup())?.start).toBe(0n); }); test("two subscribers to one inserted track each get a full copy", async () => { @@ -574,7 +573,7 @@ test("a finished track is still served from its cache", async () => { .subscribe({ delay: { max: Duration.millis(5000) } }) .ordered(); expect(await late.readString()).toBe("last"); - expect(await nextGroup(late)).toBeUndefined(); + expect(await late.nextGroup()).toBeUndefined(); expect(await broadcast.track("track1").info()).toBeDefined(); expect(await pendingRequest(broadcast)).toBeUndefined(); }); diff --git a/js/net/src/connection/reload.test.ts b/js/net/src/connection/reload.test.ts index a2428f4fe77..2ac9e84f12a 100644 --- a/js/net/src/connection/reload.test.ts +++ b/js/net/src/connection/reload.test.ts @@ -14,7 +14,6 @@ import { ALPN as IetfALPN } from "../ietf/version.ts"; import { hooks } from "../internal.ts"; import * as Lite from "../lite/index.ts"; import { createMockTransportPair, type MockTransport, manual, textFrame, waitFor } from "../mock.ts"; -import { nextGroup } from "../ordered.test-util.ts"; import { Producer as OriginProducer } from "../origin.ts"; import * as Path from "../path.ts"; import { Stream } from "../stream.ts"; @@ -878,7 +877,7 @@ for (const [name, teardown] of Object.entries(teardowns)) { try { hooks.appendNext(producer).writeFrame(textFrame("first", Timestamp.fromMillis(0))); - expect(await (await nextGroup(track))?.readString()).toBe("first"); + expect(await (await track.nextGroup())?.readString()).toBe("first"); if (teardown.goaway) { const stream = await Stream.open(first.quic, { version: Lite.Version.DRAFT_06 }); @@ -898,7 +897,7 @@ for (const [name, teardown] of Object.entries(teardowns)) { if (teardown.hide) win.dispatchEvent(new Event("pagehide")); if (teardown.drains) { - expect(await (await nextGroup(track))?.readString()).toBe("last"); + expect(await (await track.nextGroup())?.readString()).toBe("last"); await fin.hold?.reached; // Just short of the close deadline, the session still waits for the FIN. await clock.advance(Duration.millis(999)); @@ -970,7 +969,7 @@ for (const [name, drainEnd] of Object.entries(drainEnds)) { try { // The group stays open, so the old session's drain waits out its deadline. hooks.appendNext(producer).writeFrame(textFrame("live")); - expect(await (await nextGroup(track))?.readString()).toBe("live"); + expect(await (await track.nextGroup())?.readString()).toBe("live"); reload.url.set(new URL("https://example.com/b")); await waitUntil(() => dials.length === 2 && reload.status.peek() === "connected"); @@ -1032,7 +1031,7 @@ test("a retired GOAWAY predecessor still closes by its handover cap", async () = try { // The group stays open, so a graceful close of the predecessor would wait out its deadline. hooks.appendNext(producer).writeFrame(textFrame("live")); - expect(await (await nextGroup(track))?.readString()).toBe("live"); + expect(await (await track.nextGroup())?.readString()).toBe("live"); const stream = await Stream.open(first.quic, { version: Lite.Version.DRAFT_06 }); await stream.writer.u53(Lite.StreamId.Goaway); @@ -1105,7 +1104,7 @@ test("closing the loop keeps the tokens until the session drains", async () => { const track = remote.track("video").subscribe().ordered(); try { hooks.appendNext(producer).writeFrame(textFrame("first", Timestamp.fromMillis(0))); - expect(await (await nextGroup(track))?.readString()).toBe("first"); + expect(await (await track.nextGroup())?.readString()).toBe("first"); fin.hold?.enable(); const last = hooks.appendNext(producer); @@ -1115,7 +1114,7 @@ test("closing the loop keeps the tokens until the session drains", async () => { producer.close(); reload.close(); - expect(await (await nextGroup(track))?.readString()).toBe("last"); + expect(await (await track.nextGroup())?.readString()).toBe("last"); await fin.hold?.reached; await clock.advance(Duration.millis(999)); expect(fin.closed).toBe(false); diff --git a/js/net/src/consume.test.ts b/js/net/src/consume.test.ts index 5661526a030..c1cf0a7a526 100644 --- a/js/net/src/consume.test.ts +++ b/js/net/src/consume.test.ts @@ -5,7 +5,6 @@ import { StreamCode, StreamError } from "./error.ts"; import { WireRoute } from "./hop.ts"; import * as Instance from "./instance.ts"; import { hooks } from "./internal.ts"; -import { nextGroup } from "./ordered.test-util.ts"; import * as Path from "./path.ts"; test("cache identity follows the serving announcement, preserving held tracks", async () => { @@ -34,7 +33,7 @@ test("cache identity follows the serving announcement, preserving held tracks", expect(shared?.closed).toBe(fresh.closed); // Cache replacement never transfers or closes the track an old handle is reading. hooks.appendNext(track).finish(); - expect((await nextGroup(ordered))?.start).toBe(0n); + expect((await ordered.nextGroup())?.start).toBe(0n); cache.withdraw(job, specific); expect(cache.get(job, cache.instance(job))).toBeUndefined(); for (const consumer of [held, same, fresh, shared]) consumer?.close(); diff --git a/js/net/src/fill.test.ts b/js/net/src/fill.test.ts index 5d508910381..ae181a96bf5 100644 --- a/js/net/src/fill.test.ts +++ b/js/net/src/fill.test.ts @@ -10,7 +10,6 @@ import type { Consumer as GroupConsumer } from "./group.ts"; import { hooks, staleHole } from "./internal.ts"; import * as Lite from "./lite/index.ts"; import { createMockTransportPair, groupsOf, requestedGroups } from "./mock.ts"; -import { nextGroup } from "./ordered.test-util.ts"; import { Producer as OriginProducer } from "./origin.ts"; import * as Path from "./path.ts"; import { Timescale, Timestamp } from "./time.ts"; @@ -253,7 +252,7 @@ async function failedAnswerHoldsTheEnd(error: Error) { const reader = track.subscribe({ delay: { max: null } }); const ordered = reader.ordered(); for (const key of [0n, 2n]) hooks.receiveGroup(track, { start: key, offset: 0 }).finish(); - expect((await nextGroup(ordered))?.start).toBe(0n); + expect((await ordered.nextGroup())?.start).toBe(0n); const requests = track.requests(); const fetching = wireOf(broadcast).fetchGroup("video", 1n); const fill = await requestedGroups(requests); @@ -268,17 +267,17 @@ async function failedAnswerHoldsTheEnd(error: Error) { // A subscriber arriving after the failure is not handed the failed answer either. const late = track.subscribe({ delay: { max: null } }); const lateOrdered = late.ordered(); - expect((await nextGroup(lateOrdered))?.start).toBe(0n); - const lateNext = nextGroup(lateOrdered); + expect((await lateOrdered.nextGroup())?.start).toBe(0n); + const lateNext = lateOrdered.nextGroup(); expect(await Promise.race([lateNext.then(() => "moved"), yieldNow().then(() => "waiting")])).toBe("waiting"); // The failed answer is no verdict on group 1, so an ordered reader still waits for it rather // than moving on to group 2, and gets it once the feed delivers it. - const next = nextGroup(ordered); + const next = ordered.nextGroup(); expect(await Promise.race([next.then(() => "moved"), yieldNow().then(() => "waiting")])).toBe("waiting"); hooks.receiveGroup(track, { start: 1n, offset: 0 }).finish(); expect((await next)?.start).toBe(1n); - expect((await nextGroup(ordered))?.start).toBe(2n); + expect((await ordered.nextGroup())?.start).toBe(2n); expect((await lateNext)?.start).toBe(1n); reader.close(); @@ -377,7 +376,7 @@ test("fill: an answer withheld after a probe judged it is asked again", async () delay: { max: null }, }); const ordered = reader.ordered(); - const first = nextGroup(ordered); + const first = ordered.nextGroup(); const fill = await requestedGroups(requests); expect(fill && [fill.start, fill.end]).toEqual([0n, 4n]); if (fill?.kind !== "groups") throw new Error("no fill of groups"); @@ -386,13 +385,13 @@ test("fill: an answer withheld after a probe judged it is asked again", async () answer.writeFrame({ payload: enc.encode("fill 2"), timestamp: Timestamp.unscaled(answer.start) }); expect((await first)?.start).toBe(0n); // Waiting on group 1, the bounded window probes everything it names, group 2 held among it. - const second = nextGroup(ordered); + const second = ordered.nextGroup(); await yieldNow(); answer.abort(new Error("archive failed")); fill.accept(1n).finish(); expect((await second)?.start).toBe(1n); - const third = nextGroup(ordered); + const third = ordered.nextGroup(); const again = groupsOf(await Promise.race([requests.requestedFill(), yieldNow().then(() => undefined)])); expect(again && [again.start, again.end]).toEqual([2n, 3n]); if (again) serve(again, new Map([[2n, ["again"]]])); @@ -421,7 +420,7 @@ test("fill: a gap below a group that fails after a probe is asked", async () => await reader.start(); group.abort(new StreamError(StreamCode.Cancel)); await yieldNow(); - const next = nextGroup(ordered); + const next = ordered.nextGroup(); const fill = groupsOf(await Promise.race([requests.requestedFill(), yieldNow().then(() => undefined)])); expect(fill && [fill.start, fill.end]).toEqual([0n, 2n]); @@ -496,7 +495,7 @@ test("fill: a reader reaching back for history gets the misses filled in order", const ordered = reader.ordered(); const seen: [bigint, string[]][] = []; for (let i = 0; i < 4; i++) { - const group = await nextGroup(ordered); + const group = await ordered.nextGroup(); if (!group) break; seen.push([group.start, await frames(group)]); } @@ -710,7 +709,7 @@ test("fill: an ordered reader stops waiting on an unanswered fill once its budge delay: { max: Duration.millis(1000) }, order: "ascending", }); - const next = nextGroup(reader.ordered()); + const next = reader.ordered().nextGroup(); // The handler takes the fill for the missing groups and never answers. const fill = await requestedGroups(requests); expect([fill?.start, fill?.end]).toEqual([0n, 5n]); @@ -770,7 +769,7 @@ test("fill: a handler hears that a reader stopped wanting what it handed out pas delay: { max: Duration.millis(1000) }, order: "ascending", }); - const next = nextGroup(reader.ordered()); + const next = reader.ordered().nextGroup(); const fill = await requestedGroups(requests); if (fill?.kind !== "groups") throw new Error("no fill of groups"); expect(await fill.wantedChanged()).toBe(0n); @@ -996,10 +995,10 @@ test("fill: a filled group stays wanted only while a reader will still read it", const requests = track.requests(); // A live reader already passed every group below the edge. const live = track.subscribe({ ranges: [{ start: { relative: 0n } }], delay: { max: null } }); - expect((await nextGroup(live.ordered()))?.start).toBe(5n); + expect((await live.ordered().nextGroup())?.start).toBe(5n); const reader = track.subscribe(history); - const next = nextGroup(reader.ordered()); + const next = reader.ordered().nextGroup(); const fill = await requestedGroups(requests); if (fill?.kind !== "groups") throw new Error("no fill of groups"); expect(fill.wanted()).toBe(0n); @@ -1437,7 +1436,7 @@ test.each(["arrival", "sequence"])( ? () => reader.recvGroup() : (() => { const ordered = reader.ordered(); - return () => nextGroup(ordered); + return () => ordered.nextGroup(); })(); const got: [bigint, string[]][] = []; for (let group = await next(); group; group = await next()) got.push([group.start, await frames(group)]); @@ -1450,7 +1449,7 @@ test.each(["arrival", "sequence"])( // An open reader takes the whole copy that replaced the headless one in the cache. const open = track.subscribe(history); - const first = await nextGroup(open.ordered()); + const first = await open.ordered().nextGroup(); expect([first?.start, first && (await frames(first))]).toEqual([2n, ["c0", "c1", "c2", "c3", "c4"]]); open.close(); @@ -1472,7 +1471,7 @@ test("fill: a refused head gives its group up, and the bounded reader moves past const reader = track.subscribe(twoAndThree); const ordered = reader.ordered(); const got: bigint[] = []; - for (let group = await nextGroup(ordered); group; group = await nextGroup(ordered)) got.push(group.start); + for (let group = await ordered.nextGroup(); group; group = await ordered.nextGroup()) got.push(group.start); expect(got).toEqual([3n]); requests.close(); @@ -1499,7 +1498,7 @@ test.each([ const reader = track.subscribe(twoAndThree); const ordered = mode === "sequence" ? reader.ordered() : undefined; - const next = () => (ordered ? nextGroup(ordered) : reader.recvGroup()); + const next = () => (ordered ? ordered.nextGroup() : reader.recvGroup()); const got: bigint[] = []; for (let group = await next(); group; group = await next()) got.push(group.start); expect(got).toEqual([3n]); @@ -1513,7 +1512,7 @@ test("fill: a drop of a held group landing while its head is asked leaves the he const { broadcast, track } = headless(); const requests = track.requests(); const ordered = track.subscribe(twoAndThree).ordered(); - const first = nextGroup(ordered); + const first = ordered.nextGroup(); const fill = await requestedGroups(requests); if (!fill) throw new Error("no head asked"); expect([fill.start, fill.end]).toEqual([2n, 3n]); @@ -1546,7 +1545,7 @@ test("fill: with no handler, a bounded reader gives a headless group up while an expect(toStreamCode(fetched)).toBe(StreamCode.NotFound); const open = track.subscribe(history); - const first = await nextGroup(open.ordered()); + const first = await open.ordered().nextGroup(); expect([first?.start, first && (await frames(first))]).toEqual([2n, ["c3", "c4"]]); open.close(); @@ -1625,7 +1624,7 @@ test("fill: a time start no held group resolves is looked up, and the range star const reader = track.subscribe(fromTime(2n)); const ordered = reader.ordered(); const got: bigint[] = []; - for (let i = 0; i < 4; i++) got.push((await nextGroup(ordered))?.start ?? -1n); + for (let i = 0; i < 4; i++) got.push((await ordered.nextGroup())?.start ?? -1n); expect(got).toEqual([2n, 3n, 4n, 5n]); expect(times).toEqual([2n]); @@ -1657,7 +1656,7 @@ test("fill: a lookup answered below the eviction watermark starts the range ther const reader = track.subscribe(fromTime(2n)); const ordered = reader.ordered(); const got: bigint[] = []; - for (let i = 0; i < 4; i++) got.push((await nextGroup(ordered))?.start ?? -1n); + for (let i = 0; i < 4; i++) got.push((await ordered.nextGroup())?.start ?? -1n); expect(got).toEqual([2n, 3n, 4n, 5n]); expect(times).toEqual([2n]); @@ -1673,7 +1672,7 @@ test("fill: a lookup's answer is read at once, before its first frame: its key i const { broadcast, track } = timed(); const requests = track.requests(); const reader = track.subscribe(fromTime(2n)); - const next = nextGroup(reader.ordered()); + const next = reader.ordered().nextGroup(); // The handler answers with group 2 but writes no frame yet. const lookup = await requests.requestedFill(); if (lookup?.kind !== "lookup") throw new Error("no lookup"); @@ -1697,7 +1696,7 @@ test("fill: a lookup closed unanswered starts the range at its time, asking noth const reader = track.subscribe(fromTime(2n)); const ordered = reader.ordered(); const got: bigint[] = []; - for (let i = 0; i < 4; i++) got.push((await nextGroup(ordered))?.start ?? -1n); + for (let i = 0; i < 4; i++) got.push((await ordered.nextGroup())?.start ?? -1n); expect(got).toEqual([2n, 3n, 4n, 5n]); expect(times).toEqual([2n]); @@ -1712,7 +1711,7 @@ test("fill: a time start the held groups place asks no lookup", async () => { const times = lookups(requests, () => 0n); const reader = track.subscribe(fromTime(6n)); - expect((await nextGroup(reader.ordered()))?.start).toBe(5n); + expect((await reader.ordered().nextGroup())?.start).toBe(5n); expect(times).toEqual([]); reader.close(); diff --git a/js/net/src/ietf/join.test.ts b/js/net/src/ietf/join.test.ts index 98f6f10ddaa..0b87dc5a98e 100644 --- a/js/net/src/ietf/join.test.ts +++ b/js/net/src/ietf/join.test.ts @@ -6,7 +6,6 @@ import { StreamCode } from "../error.ts"; import { hooks } from "../internal.ts"; import { GRACE } from "../ledger.ts"; import { createMockTransportPair, manual, settlesWithin, textFrame } from "../mock.ts"; -import { nextGroup } from "../ordered.test-util.ts"; import { Producer as OriginProducer } from "../origin.ts"; import * as Path from "../path.ts"; import { Reader, Stream, Writer } from "../stream.ts"; @@ -197,7 +196,7 @@ test("a head that lands before its tail is continued by it", async () => { await subscriber.handleFetch(await head(fetch.requestId, ["h0", "h1"])); await subscriber.handleGroup(...liveStream(GROUP, 2, ["t2", "t3"])); - const group = await nextGroup(consumer.ordered()); + const group = await consumer.ordered().nextGroup(); expect(group?.start).toBe(GROUP); expect(await frames(group)).toEqual(["h0", "h1", "t2", "t3"]); }); @@ -210,7 +209,7 @@ test("a tail that lands before its head waits for it", async () => { await subscriber.handleFetch(await head(fetch.requestId, ["h0", "h1"])); await tail; - const group = await nextGroup(consumer.ordered()); + const group = await consumer.ordered().nextGroup(); expect(await frames(group)).toEqual(["h0", "h1", "t2"]); }); @@ -221,7 +220,7 @@ test("a catalog written once is readable from the head alone", async () => { // No live stream ever comes: the group was written before the subscription. await subscriber.handleFetch(await head(fetch.requestId, ['{"video":{}}'], 0n)); - const group = await nextGroup(consumer.ordered()); + const group = await consumer.ordered().nextGroup(); expect(group?.start).toBe(0n); expect(untext((await group?.readFrame())?.payload)).toBe('{"video":{}}'); }); @@ -235,7 +234,7 @@ test("an empty tail finishes a group the head already holds whole", async () => header.flags = flags(false); await subscriber.handleGroup(header, new Reader(undefined, new Uint8Array(), VERSION)); - const group = await nextGroup(consumer.ordered()); + const group = await consumer.ordered().nextGroup(); expect(await frames(group)).toEqual(["h0", "h1"]); expect(await group?.closed).toBeNull(); }); @@ -257,7 +256,7 @@ for (const outcome of ["a refused joining FETCH", "an empty joining FETCH"] as c await subscriber.handleGroup(...liveStream(GROUP, 2, ["t2"])); await subscriber.handleGroup(...liveStream(GROUP + 1n, 0, ["n0"])); - const group = await nextGroup(consumer.ordered()); + const group = await consumer.ordered().nextGroup(); expect(group?.start).toBe(GROUP + 1n); expect(await frames(group)).toEqual(["n0"]); }); @@ -272,7 +271,7 @@ test("a reader in sequence order with no delay budget skips headless groups", as await subscriber.handleGroup(...liveStream(GROUP + 1n, 1, ["m1"])); await subscriber.handleGroup(...liveStream(GROUP + 2n, 0, ["n0"])); - const group = await nextGroup(consumer.ordered()); + const group = await consumer.ordered().nextGroup(); expect(group?.start).toBe(GROUP + 2n); }); @@ -288,7 +287,7 @@ for (const version of VERSIONS) { // Largest is inclusive, including object 0: its following tail is no whole message. await subscriber.handleGroup(...liveStream(0n, Number(objectId) + 1, ["cut"], version)); await subscriber.handleGroup(...liveStream(1n, 0, ["whole"], version)); - const group = await nextGroup(consumer.ordered()); + const group = await consumer.ordered().nextGroup(); expect(group?.start).toBe(1n); expect(await frames(group)).toEqual(["whole"]); }); @@ -303,7 +302,7 @@ test("a tail parked on a refused joining FETCH is dropped", async () => { await tail; await subscriber.handleGroup(...liveStream(GROUP + 1n, 0, ["n0"])); - const group = await nextGroup(consumer.ordered()); + const group = await consumer.ordered().nextGroup(); expect(group?.start).toBe(GROUP + 1n); }); @@ -319,7 +318,7 @@ test("a joining FETCH has no deadline of its own", async () => { await subscriber.handleFetch(await head(fetch.requestId, ["h0", "h1"])); await tail; - const group = await nextGroup(consumer.ordered()); + const group = await consumer.ordered().nextGroup(); expect(group?.start).toBe(GROUP); expect(await frames(group)).toEqual(["h0", "h1", "t2"]); }); @@ -350,7 +349,7 @@ test("SUBSCRIPTION_ENDED cancels a head nothing claimed", async () => { const { subscriber, consumer, fetching, fetch, peer } = await join(); await accept(fetching); await subscriber.handleFetch(await head(fetch.requestId, ["h0", "h1"])); - const group = await nextGroup(consumer.ordered()); + const group = await consumer.ordered().nextGroup(); expect(group?.start).toBe(GROUP); // The group may run past the head upstream, so it must not read as whole. @@ -387,7 +386,7 @@ test("a whole group that precedes the head wins the sequence", async () => { await subscriber.handleGroup(...liveStream(GROUP, 0, ["w0", "w1", "w2"])); await subscriber.handleFetch(await head(fetch.requestId, ["h0", "h1"])); - const group = await nextGroup(consumer.ordered()); + const group = await consumer.ordered().nextGroup(); expect(await frames(group)).toEqual(["w0", "w1", "w2"]); }); @@ -398,7 +397,7 @@ test("a whole group for a headed sequence is refused, with its head", async () = await subscriber.handleFetch(await head(fetch.requestId, ["h0", "h1"])); await subscriber.handleGroup(...liveStream(GROUP, 0, ["w0"])); - const group = await nextGroup(consumer.ordered()); + const group = await consumer.ordered().nextGroup(); expect(group?.start).toBe(GROUP); expect(await group?.closed).toBeInstanceOf(Error); }); @@ -411,7 +410,7 @@ test("a head that does not meet its tail is refused", async () => { // Object 2 is missing. await subscriber.handleGroup(...liveStream(GROUP, 3, ["t3"])); - const group = await nextGroup(consumer.ordered()); + const group = await consumer.ordered().nextGroup(); expect(await group?.closed).toBeInstanceOf(Error); }); @@ -442,7 +441,7 @@ test("a head that spells Object ID Delta 1 is contiguous", async () => { await subscriber.handleFetch(await deltaHead(fetch.requestId, ["h0", "h1"], 1)); await subscriber.handleGroup(...liveStream(GROUP, 2, ["t2"])); - const group = await nextGroup(consumer.ordered()); + const group = await consumer.ordered().nextGroup(); expect(await frames(group)).toEqual(["h0", "h1", "t2"]); }); @@ -452,7 +451,7 @@ test("a head that repeats an Object ID is dropped", async () => { await subscriber.handleFetch(await deltaHead(fetch.requestId, ["h0", "h0"], 0)); - const group = await nextGroup(consumer.ordered()); + const group = await consumer.ordered().nextGroup(); expect(await group?.closed).toBeInstanceOf(Error); }); @@ -466,7 +465,7 @@ test("a tail that is only an End of Group finishes the head", async () => { // Object ID 2, an empty payload, then status End of Group. await subscriber.handleGroup(header, new Reader(undefined, new Uint8Array([2, 0, 3]), VERSION)); - const group = await nextGroup(consumer.ordered()); + const group = await consumer.ordered().nextGroup(); expect(await frames(group)).toEqual(["h0", "h1"]); expect(await group?.closed).toBeNull(); }); @@ -490,7 +489,7 @@ test("a joining FETCH spanning another group drops the head", async () => { }); await subscriber.handleFetch(new Reader(undefined, bytes, VERSION)); - const group = await nextGroup(consumer.ordered()); + const group = await consumer.ordered().nextGroup(); expect(await group?.closed).toBeInstanceOf(Error); }); @@ -516,7 +515,7 @@ for (const version of VERSIONS) { await subscriber.handleFetch(await head(subscribe.requestId, ["h0", "h1"], GROUP, version)); await tail; - const group = await nextGroup(consumer.ordered()); + const group = await consumer.ordered().nextGroup(); expect(group?.start).toBe(GROUP); expect(await frames(group)).toEqual(["h0", "h1", "t2"]); }); @@ -528,7 +527,7 @@ for (const version of VERSIONS) { await fill; await subscriber.handleGroup(...liveStream(GROUP, 2, ["t2"], version)); - const group = await nextGroup(consumer.ordered()); + const group = await consumer.ordered().nextGroup(); expect(await frames(group)).toEqual(["h0", "h1", "t2"]); }); diff --git a/js/net/src/ietf/range.test.ts b/js/net/src/ietf/range.test.ts index b2939ad2065..849e860290c 100644 --- a/js/net/src/ietf/range.test.ts +++ b/js/net/src/ietf/range.test.ts @@ -2,7 +2,6 @@ import { expect, onTestFinished, test } from "bun:test"; import { StreamCode, StreamError } from "../error.ts"; import { hooks } from "../internal.ts"; import { createMockTransportPair } from "../mock.ts"; -import { nextGroup } from "../ordered.test-util.ts"; import * as Path from "../path.ts"; import { Reader, Stream, Writer } from "../stream.ts"; import { type Subscription, Producer as TrackProducer } from "../track.ts"; @@ -152,7 +151,7 @@ for (const version of VERSIONS) { const reader = fx.broadcast.track("video").subscribe(ranges(1n, 5n)); fx.readers.push(reader); const ordered = reader.ordered(); - const read = nextGroup(ordered); + const read = ordered.nextGroup(); await fx.status(); const { stream, request } = await fx.fetch(); await fx.answer(stream, 4n); @@ -163,17 +162,17 @@ for (const version of VERSIONS) { expect(await payloads(first)).toEqual(["1a", "", "1c"]); first.close(); for (const key of [3n, 4n]) { - const group = await nextGroup(ordered); + const group = await ordered.nextGroup(); expect(group?.start).toBe(key); if (!group) throw new Error("missing group"); expect(await payloads(group)).toEqual([`${key}a`, "", `${key}c`]); group.close(); } - expect(await nextGroup(ordered)).toBeUndefined(); + expect(await ordered.nextGroup()).toBeUndefined(); const overlapping = fx.broadcast.track("video").subscribe(ranges(0n, 5n)); fx.readers.push(overlapping); const overlap = overlapping.ordered(); - const missing = nextGroup(overlap); + const missing = overlap.nextGroup(); const backfill = await fx.fetch(); await fx.answer(backfill.stream, 0n); await fx.data(backfill.request.requestId, [0n]); @@ -181,14 +180,14 @@ for (const version of VERSIONS) { expect(zero?.start).toBe(0n); zero?.close(); for (const key of [1n, 3n, 4n]) { - const group = await nextGroup(overlap); + const group = await overlap.nextGroup(); expect(group?.start).toBe(key); group?.close(); } - expect(await nextGroup(overlap)).toBeUndefined(); + expect(await overlap.nextGroup()).toBeUndefined(); overlapping.close(); reader.update(ranges(5n, 6n)); - const more = nextGroup(ordered); + const more = ordered.nextGroup(); const second = await fx.fetch(); await fx.answer(second.stream, 5n); await fx.data(second.request.requestId, [5n]); @@ -258,7 +257,7 @@ for (const version of VERSIONS) { const fx = fixture(version); const reader = fx.broadcast.track("video").subscribe(ranges(1n, 2n)); fx.readers.push(reader); - const pending = nextGroup(reader.ordered()); + const pending = reader.ordered().nextGroup(); await fx.status(); const { stream, request } = await fx.fetch(); await fx.answer(stream, 1n); @@ -322,7 +321,7 @@ for (const version of VERSIONS) { const history = fx.broadcast.track("video").subscribe(ranges(1n, 3n)); fx.readers.push(history); const ordered = history.ordered(); - const first = nextGroup(ordered); + const first = ordered.nextGroup(); await fx.status(); const fetching = await fx.fetch(); await fx.answer(fetching.stream, 2n); @@ -341,12 +340,12 @@ for (const version of VERSIONS) { if (!group) throw new Error("missing history group"); expect(await payloads(group)).toEqual(["1a", "", "1c"]); group?.close(); - const second = await nextGroup(ordered); + const second = await ordered.nextGroup(); expect(second?.start).toBe(2n); if (!second) throw new Error("missing history group"); expect(await payloads(second)).toEqual(["2a", "", "2c"]); second?.close(); - expect(await nextGroup(ordered)).toBeUndefined(); + expect(await ordered.nextGroup()).toBeUndefined(); const cached = await fx.broadcast.track("video").fetchGroup(1n); expect(await payloads(cached)).toEqual(["1a", "", "1c"]); cached.close(); @@ -357,7 +356,7 @@ for (const version of VERSIONS) { const history = fx.broadcast.track("video").subscribe(ranges(1n, 3n)); fx.readers.push(history); const ordered = history.ordered(); - const first = nextGroup(ordered); + const first = ordered.nextGroup(); await fx.status(); const fetching = await fx.fetch(); await fx.answer(fetching.stream, 2n); @@ -375,11 +374,11 @@ for (const version of VERSIONS) { if (!group) throw new Error("missing history group"); expect(await payloads(group)).toEqual(["1a", "", "1c"]); group.close(); - const second = await nextGroup(ordered); + const second = await ordered.nextGroup(); if (!second) throw new Error("missing history group"); expect(await payloads(second)).toEqual(["2a", "", "2c"]); second.close(); - expect(await nextGroup(ordered)).toBeUndefined(); + expect(await ordered.nextGroup()).toBeUndefined(); }); test(`${version}: a relative end on an empty track subscribes for the first group`, async () => { @@ -391,7 +390,7 @@ for (const version of VERSIONS) { }); fx.readers.push(reader); const ordered = reader.ordered(); - const first = nextGroup(ordered); + const first = ordered.nextGroup(); await fx.status(null); const live = await fx.next(); expect(await live.reader.u53()).toBe(Subscribe.id); @@ -422,7 +421,7 @@ for (const version of VERSIONS) { if (!group) throw new Error("missing first group"); expect(await payloads(group)).toEqual(["0a"]); group.close(); - expect(await nextGroup(ordered)).toBeUndefined(); + expect(await ordered.nextGroup()).toBeUndefined(); }); test(`${version}: a nonexistent trailing object range preserves the group's payloads`, async () => { diff --git a/js/net/src/ietf/subscriber.test.ts b/js/net/src/ietf/subscriber.test.ts index 5f990d4a342..70a0ce233c7 100644 --- a/js/net/src/ietf/subscriber.test.ts +++ b/js/net/src/ietf/subscriber.test.ts @@ -7,7 +7,6 @@ import { ProtocolViolation, StreamCode, Stream as StreamError } from "../error.t import { type Hop, toHop, UNKNOWN_HOP } from "../hop.ts"; import { hooks } from "../internal.ts"; import { createMockTransportPair, manual, settlesWithin } from "../mock.ts"; -import { nextGroup } from "../ordered.test-util.ts"; import * as Path from "../path.ts"; import { Reader, Stream } from "../stream.ts"; import { Tail } from "../tail.ts"; @@ -809,7 +808,7 @@ test("a track without TIMESCALE arrives untimed, even if an object carries a Tim // Property 0x10 (Timestamp) = 5, with no units to read it in. await subscriber.handleGroup(stampedGroup(0n), new Reader(undefined, encodeStamped([0x10, 5]), VERSION)); - const group = await nextGroup(track.ordered()); + const group = await track.ordered().nextGroup(); const frame = await group?.readFrame(); expect(frame?.payload).toEqual(new Uint8Array([42])); // Its group's key, not the object's Timestamp. @@ -825,7 +824,7 @@ test("a received frame's time is its group's key in the track's TIMESCALE", asyn // neither is read. The second object carries no properties at all. const objects = new Uint8Array([...encodeStamped([0x08, 1, 0x08, 5]), ...encodeStamped([])]); await subscriber.handleGroup(stampedGroup(7n), new Reader(undefined, objects, VERSION)); - const group = await nextGroup(track.ordered()); + const group = await track.ordered().nextGroup(); for (let i = 0; i < 2; i++) { const frame = await group?.readFrame(); expect(frame?.payload).toEqual(new Uint8Array([42])); @@ -1145,7 +1144,7 @@ test("early group waits for SUBSCRIBE_OK priority before track acceptance", asyn expect((await track.info()).priority).toBe(127 - 37); expect(group.publisherPriority).toBe(37); const ordered = track.ordered(); - expect((await nextGroup(ordered))?.start).toBe(3n); + expect((await ordered.nextGroup())?.start).toBe(3n); const explicit = new GroupMessage({ trackAlias: ALIAS, groupId: 4n, @@ -1156,7 +1155,7 @@ test("early group waits for SUBSCRIBE_OK priority before track acceptance", asyn await subscriber.handleGroup(explicit, new Reader(undefined, encodeObjects([0]), VERSION)); expect(explicit.publisherPriority).toBe(9); expect((await track.info()).priority).toBe(127 - 37); - expect((await nextGroup(ordered))?.start).toBe(4n); + expect((await ordered.nextGroup())?.start).toBe(4n); ordered.close(); track.close(); }); @@ -1204,7 +1203,7 @@ test.each([Version.DRAFT_18, Version.DRAFT_20, Version.DRAFT_22])( const ordered = consumer.ordered(); try { for (const key of [1n, 2n]) { - const group = await nextGroup(ordered); + const group = await ordered.nextGroup(); expect(group?.start).toBe(key); if (!group) throw new Error("missing prefix group"); expect(await group.readString()).toBe("object 0"); @@ -1260,7 +1259,7 @@ test.each([Version.DRAFT_18, Version.DRAFT_20, Version.DRAFT_22])( new Reader(undefined, encodeObjects([0, 0]), version), ); // The reader waits on group 0, which only a FETCH can bring. - void nextGroup(ordered).catch(() => {}); + void ordered.nextGroup().catch(() => {}); fetch = await nextStream(pair.client, version); expect(await fetch.reader.u53()).toBe(Fetch.id); const { type } = await Fetch.decode(fetch.reader, version); @@ -1338,7 +1337,7 @@ test("a group served from partway through is dropped", async () => { new Reader(undefined, encodeObjects([0, 0]), VERSION), ); - const group = await nextGroup(track.ordered()); + const group = await track.ordered().nextGroup(); expect(group?.start).toBe(4n); track.close(); @@ -1358,7 +1357,7 @@ test("a clear FIRST_OBJECT at object 0 is the whole group", async () => { new Reader(undefined, encodeObjects([0, 0]), VERSION), ); - const group = await nextGroup(track.ordered()); + const group = await track.ordered().nextGroup(); expect(group?.start).toBe(3n); if (!group) return; expect(await group.readString()).toBe("object 0"); @@ -1383,7 +1382,7 @@ test("an END_OF_GROUP status on a marked stream finishes the group", async () => new Reader(undefined, objects, VERSION), ); - const group = await nextGroup(track.ordered()); + const group = await track.ordered().nextGroup(); expect(group?.start).toBe(3n); if (!group) return; for (let i = 0; i < 5; i++) { @@ -1449,7 +1448,7 @@ test("a clear FIRST_OBJECT past object 0 is dropped", async () => { new Reader(undefined, encodeObjects([0]), VERSION), ); - const group = await nextGroup(track.ordered()); + const group = await track.ordered().nextGroup(); expect(group?.start).toBe(4n); track.close(); @@ -1509,7 +1508,7 @@ test("a group that claims its first object must start at zero", async () => { const header = new GroupMessage({ trackAlias: ALIAS, groupId: 3n, subGroupId: 0n, publisherPriority: 0, flags }); await subscriber.handleGroup(header, new Reader(undefined, encodeObjects([5, 0, 0]), VERSION)); - const group = await nextGroup(track.ordered()); + const group = await track.ordered().nextGroup(); expect(group).toBeDefined(); if (!group) return; await expect(group.readFrameIndex()).rejects.toThrow(/object IDs must start at 0/); @@ -1627,7 +1626,7 @@ test("every object in a chunk reaches the reader before it wakes", async () => { }); const handled = subscriber.handleGroup(header, new Reader(readable, undefined, VERSION)); - const group = await nextGroup(track.ordered()); + const group = await track.ordered().nextGroup(); if (!group) throw new Error("no group"); expect(await group.readString()).toBe("object 0"); expect(group.frameCount).toBe(10); @@ -1687,7 +1686,7 @@ test("object extension limit accepts 64 KiB and stops one byte over before readi await subscriber.handleGroup(header, reader); if (size === 65536) { expect(stop.mock.calls).toEqual([]); - const group = await nextGroup(track.ordered()); + const group = await track.ordered().nextGroup(); expect(group?.frameCount).toBe(first ? 1 : 2); expect(await group?.readString()).toBe("*"); } else { @@ -1758,7 +1757,7 @@ for (const version of [Version.DRAFT_18, Version.DRAFT_20, Version.DRAFT_22]) { message, new Reader(undefined, new Uint8Array([0, 0, 0, 0, 1, 42, 0, 0, 3]), version), ); - const group = await nextGroup(track.ordered()); + const group = await track.ordered().nextGroup(); expect((await group?.readFrame())?.payload).toEqual(new Uint8Array()); expect((await group?.readFrame())?.payload).toEqual(new Uint8Array([42])); expect(await group?.readFrame()).toBeUndefined(); diff --git a/js/net/src/integration.test.ts b/js/net/src/integration.test.ts index ccbba2d4d50..38d4000184e 100644 --- a/js/net/src/integration.test.ts +++ b/js/net/src/integration.test.ts @@ -22,7 +22,6 @@ import { hooks } from "./internal.ts"; import * as Lite from "./lite/index.ts"; import { Publisher as LitePublisher } from "./lite/publisher.ts"; import { createMockTransportPair, manual, settlesWithin, textFrame, waitFor } from "./mock.ts"; -import { nextGroup } from "./ordered.test-util.ts"; import type { Consumer as OriginConsumer } from "./origin.ts"; import { Producer as OriginProducer } from "./origin.ts"; import * as Path from "./path.ts"; @@ -355,11 +354,11 @@ test("integration: lite applies initial and updated group bounds", async () => { }) .ordered(); try { - expect((await nextGroup(subscriber))?.start).toBe(INITIAL_START_GROUP); - expect((await nextGroup(subscriber))?.start).toBe(INITIAL_END_GROUP - 1n); + expect((await subscriber.nextGroup())?.start).toBe(INITIAL_START_GROUP); + expect((await subscriber.nextGroup())?.start).toBe(INITIAL_END_GROUP - 1n); // A bounded read ends once its window is read, as in Rust. - expect(await nextGroup(subscriber)).toBeUndefined(); + expect(await subscriber.nextGroup()).toBeUndefined(); // Replacing the ranges reads on from the same reader, the update going upstream. subscriber.update({ @@ -368,15 +367,15 @@ test("integration: lite applies initial and updated group bounds", async () => { }); const updated = (pending: Promise) => withTimeout(pending, Duration.millis(UPDATE_TIMEOUT_MS), "updated group bound timed out"); - expect(((await updated(nextGroup(subscriber))) as { start: bigint } | undefined)?.start).toBe(UPDATED_GROUP); - expect(await updated(nextGroup(subscriber))).toBeUndefined(); + expect(((await updated(subscriber.nextGroup())) as { start: bigint } | undefined)?.start).toBe(UPDATED_GROUP); + expect(await updated(subscriber.nextGroup())).toBeUndefined(); // An open range parks at the live edge instead. subscriber.update({ delay: { max: Duration.millis(REPLAY_LATENCY_MS) }, ranges: [{ start: { time: GROUP_COUNT } }], }); - expect(await settlesWithin(nextGroup(subscriber), clock, Duration.millis(PENDING_ASSERT_MS))).toBe(false); + expect(await settlesWithin(subscriber.nextGroup(), clock, Duration.millis(PENDING_ASSERT_MS))).toBe(false); } finally { subscriber.close(); remote.close(); @@ -424,12 +423,12 @@ test("integration: lite refuses an empty requested range on open and on update", ranges: [{ start: { time: 1n }, end: { time: 1n } }], }) .ordered(); - expect((await nextGroup(live))?.start).toBe(1n); + expect((await live.nextGroup())?.start).toBe(1n); live.update({ delay: { max: Duration.millis(REPLAY_LATENCY_MS) }, ranges: [{ start: { time: 3n }, end: { time: 2n } }], }); - expect(await nextGroup(live)).toBeUndefined(); + expect(await live.nextGroup()).toBeUndefined(); expect( await withTimeout(Promise.resolve(live.closed), Duration.millis(TIMEOUT_MS), "empty update never settled"), ).toHaveProperty("message", "empty subscription range cannot be encoded"); @@ -471,9 +470,9 @@ test("integration: lite-07 serves sparse and relative ranges", async () => { .ordered(); // Covering the ranges ends the subscription upstream, and the read with its window. const got: bigint[] = []; - for (let i = 0; i < 4; i++) got.push((await nextGroup(reader))?.start ?? -1n); + for (let i = 0; i < 4; i++) got.push((await reader.nextGroup())?.start ?? -1n); expect(got).toEqual([1n, 2n, 7n, 8n]); - expect(await nextGroup(reader)).toBeUndefined(); + expect(await reader.nextGroup()).toBeUndefined(); reader.close(); } finally { remote.close(); @@ -563,7 +562,7 @@ test("integration: lite-07 joins a late relative start at the live edge", async "the update never reached the publisher", ); late = remote.track("video").subscribe(subscription).ordered(); - expect((await nextGroup(late))?.start).toBe(3n); + expect((await late.nextGroup())?.start).toBe(3n); } finally { late?.close(); first.close(); @@ -863,7 +862,7 @@ test("integration: a group reset carries the peer's code to the subscriber", asy const group = hooks.appendNext(producer); group.writeFrame(textFrame("frame")); - const consumer = await nextGroup(track); + const consumer = await track.nextGroup(); if (!consumer) throw new Error("expected a group"); expect(await consumer.readString()).toBe("frame"); @@ -903,7 +902,7 @@ test("integration: a locally raised group error reaches the peer as its own code const group = hooks.appendNext(producer); group.writeFrame(textFrame("frame")); - const consumer = await nextGroup(track); + const consumer = await track.nextGroup(); if (!consumer) throw new Error("expected a group"); expect(await consumer.readString()).toBe("frame"); diff --git a/js/net/src/lite/connection.test.ts b/js/net/src/lite/connection.test.ts index 49f41b573e5..a8a17a49203 100644 --- a/js/net/src/lite/connection.test.ts +++ b/js/net/src/lite/connection.test.ts @@ -8,7 +8,6 @@ import { inspect } from "../connection/stats.ts"; import { SessionCode, SessionError } from "../error.ts"; import { hooks } from "../internal.ts"; import { createMockTransportPair, type MockTransport, manual, settlesWithin, textFrame } from "../mock.ts"; -import { nextGroup } from "../ordered.test-util.ts"; import { Producer } from "../origin.ts"; import * as Path from "../path.ts"; import { acceptBudget, Readers, Stream, Writer } from "../stream.ts"; @@ -371,7 +370,7 @@ for (const [alpn, version] of [ first.finish(); // A frame can arrive while its sender still yields on the write. Drain the setup group // before a zero-delay subscription supersedes its still-unfinished sender. - const received = await nextGroup(track); + const received = await track.nextGroup(); expect(await received?.readString()).toBe("first"); expect(await received?.readString()).toBeUndefined(); received?.close(); @@ -384,7 +383,7 @@ for (const [alpn, version] of [ producer.close(); const closing = server.close(); - expect(await (await nextGroup(track))?.readString()).toBe("last"); + expect(await (await track.nextGroup())?.readString()).toBe("last"); await fin.reached; await settle(); expect(closed).toBe(false); @@ -392,7 +391,7 @@ for (const [alpn, version] of [ fin.release(); await closing; expect(closed).toBe(true); - expect(await nextGroup(track)).toBeUndefined(); + expect(await track.nextGroup()).toBeUndefined(); } finally { fin.release(); track.close(); @@ -434,7 +433,7 @@ for (const [alpn, version] of [ const first = hooks.appendNext(producer); first.writeFrame(textFrame("first", Timestamp.fromMillis(Number(first.start)))); first.finish(); - const received = await nextGroup(track); + const received = await track.nextGroup(); expect(await received?.readString()).toBe("first"); expect(await received?.readString()).toBeUndefined(); received?.close(); @@ -443,14 +442,14 @@ for (const [alpn, version] of [ const last = hooks.appendNext(producer); last.writeFrame(textFrame("last", Timestamp.fromMillis(Number(last.start)))); last.finish(); - expect(await (await nextGroup(track))?.readString()).toBe("last"); + expect(await (await track.nextGroup())?.readString()).toBe("last"); await fin.reached; replies.enable(); producer.finish(); producer.close(); const closing = server.close(); - expect(await nextGroup(track)).toBeUndefined(); + expect(await track.nextGroup()).toBeUndefined(); await settle(); expect(closed).toBe(false); @@ -497,7 +496,7 @@ for (const [alpn, version] of [ const first = hooks.appendNext(producer); first.writeFrame(textFrame("first", Timestamp.fromMillis(Number(first.start)))); first.finish(); - expect(await (await nextGroup(track))?.readString()).toBe("first"); + expect(await (await track.nextGroup())?.readString()).toBe("first"); const frames = Array.from({ length: 32 }, (_, i) => `frame ${i}`); const last = hooks.appendNext(producer); @@ -507,10 +506,10 @@ for (const [alpn, version] of [ producer.close(); await server.close(); - const group = await nextGroup(track); + const group = await track.nextGroup(); for (const frame of frames) expect(await group?.readString()).toBe(frame); expect(await group?.readString()).toBeUndefined(); - expect(await nextGroup(track)).toBeUndefined(); + expect(await track.nextGroup()).toBeUndefined(); } finally { yielding.mockRestore(); track.close(); @@ -548,14 +547,14 @@ for (const [alpn, version] of [ const group = hooks.appendNext(producer); group.writeFrame(textFrame("only", Timestamp.fromMillis(Number(group.start)))); group.finish(); - expect(await (await nextGroup(track))?.readString()).toBe("only"); + expect(await (await track.nextGroup())?.readString()).toBe("only"); producer.finish(); producer.close(); await settle(); client.abort(); - expect(await nextGroup(track)).toBeUndefined(); + expect(await track.nextGroup()).toBeUndefined(); expect(await track.closed).toBeNull(); } finally { track.close(); @@ -592,12 +591,12 @@ for (const [alpn, version] of [ const group = hooks.appendNext(producer); group.writeFrame(textFrame("only", Timestamp.fromMillis(Number(group.start)))); group.finish(); - expect(await (await nextGroup(track))?.readString()).toBe("only"); + expect(await (await track.nextGroup())?.readString()).toBe("only"); producer.finish(); producer.close(); await server.close(); - expect(await nextGroup(track)).toBeUndefined(); + expect(await track.nextGroup()).toBeUndefined(); } finally { track.close(); remote.close(); diff --git a/js/net/src/lite/copy_fill.test.ts b/js/net/src/lite/copy_fill.test.ts index eeb105956d1..2fcab947259 100644 --- a/js/net/src/lite/copy_fill.test.ts +++ b/js/net/src/lite/copy_fill.test.ts @@ -13,7 +13,6 @@ import type { Consumer as GroupConsumer } from "../group.ts"; import { hooks } from "../internal.ts"; import { createMockTransportPair, requestedGroups } from "../mock.ts"; import { lines } from "../open.ts"; -import { nextGroup } from "../ordered.test-util.ts"; import { Producer as OriginProducer } from "../origin.ts"; import * as Path from "../path.ts"; import { Timescale, Timestamp } from "../time.ts"; @@ -269,7 +268,7 @@ test("copy fill: a filled group stops downloading once every reader left or pass // A live reader keeps the copy up, and has read past group 0 before it lands. It never // reads again, so the copy it still buffers is all that is left of it. const reader = remote.track("video").subscribe({ ranges: [{ start: { relative: 0n } }] }); - expect((await nextGroup(reader.ordered()))?.start).toBe(1n); + expect((await reader.ordered().nextGroup())?.start).toBe(1n); const history = remote .track("video") .subscribe({ ...WIDE, ranges: [{ start: { time: 0n }, end: { time: 0n } }] }); @@ -336,7 +335,7 @@ test("copy fill: a filled group nobody holds any more stops downloading", async // A live reader keeps the copy up. It reads in order, so it lets go of what it passes. const reader = remote.track("video").subscribe({ ranges: [{ start: { relative: 0n } }] }); const live = reader.ordered(); - expect((await nextGroup(live))?.start).toBe(1n); + expect((await live.nextGroup())?.start).toBe(1n); const history = remote .track("video") .subscribe({ ...WIDE, ranges: [{ start: { time: 0n }, end: { time: 0n } }] }); @@ -354,7 +353,7 @@ test("copy fill: a filled group nobody holds any more stops downloading", async group?.close(); history.close(); write(track.createGroup(2n), 2n, "live"); - expect((await nextGroup(live))?.start).toBe(2n); + expect((await live.nextGroup())?.start).toBe(2n); await clock.drive( timeout( Duration.millis(2000), @@ -407,7 +406,7 @@ test("copy fill: a group reset to make room ends", async () => { const remote = wireOf(client).consume(Path.from("room")); try { const reader = remote.track("video").subscribe({ ranges: [{ start: { relative: 0n } }] }); - const live = await nextGroup(reader.ordered()); + const live = await reader.ordered().nextGroup(); expect(live?.start).toBe(2n); expect(dec.decode((await live?.readFrame())?.payload)).toBe("live 2"); expect(await live?.readFrame()).toBeUndefined(); diff --git a/js/net/src/lite/subscriber.test.ts b/js/net/src/lite/subscriber.test.ts index d6101335220..d04c0b1350f 100644 --- a/js/net/src/lite/subscriber.test.ts +++ b/js/net/src/lite/subscriber.test.ts @@ -25,7 +25,6 @@ import { type Hop, isAnonymous, MAX_HOPS, toHop, UNKNOWN_HOP, WireRoute } from " import * as Instance from "../instance.ts"; import { hooks } from "../internal.ts"; import { GRACE } from "../ledger.ts"; -import { nextGroup } from "../ordered.test-util.ts"; import * as Path from "../path.ts"; import { Reader, Writer } from "../stream.ts"; import { Timescale } from "../time.ts"; @@ -1813,7 +1812,7 @@ test("a grant that shrinks while the subscription sets up refuses it", async () const subscriber = new Subscriber(quic, Version.DRAFT_05, toHop(1n), undefined, undefined, undefined, grant); const track = subscriber.consume(Path.from("room/cam")).track("video").subscribe().ordered(); - const next = nextGroup(track).catch((err: unknown) => err); + const next = track.nextGroup().catch((err: unknown) => err); // Parked on TRACK_INFO when the grant shrinks, which ends the TRACK exchange too. await opened(0); @@ -2580,7 +2579,7 @@ test("a local unsubscribe owes no SUBSCRIBE_FINISH", async () => { await opened(0); await answerTrackInfo(streams[0], Version.DRAFT_07); await (await opened(1)).reading; - const next = nextGroup(ordered); + const next = ordered.nextGroup(); await subscriber.runGroup( new Group({ subscribe: 0n, key: 0n }), new Reader( diff --git a/js/net/src/ordered.test-util.ts b/js/net/src/ordered.test-util.ts deleted file mode 100644 index 46838c2ba60..00000000000 --- a/js/net/src/ordered.test-util.ts +++ /dev/null @@ -1,20 +0,0 @@ -// Group-only reads of an ordered track, for tests that check what it delivers rather than the -// gaps it reports. -import type * as Group from "./group.ts"; -import type * as Track from "./track.ts"; - -/** The next group `ordered` returns, past any gap it reports first. */ -export async function nextGroup(ordered: Track.Ordered): Promise { - for (;;) { - const item = await ordered.nextGroup(); - if (item?.kind !== "gap") return item?.group; - } -} - -/** The next group `ordered` holds now, past any gap, without waiting. */ -export function tryNextGroup(ordered: Track.Ordered): Group.Consumer | undefined { - for (;;) { - const item = ordered.tryNextGroup(); - if (item?.kind !== "gap") return item?.group; - } -} diff --git a/js/net/src/ordered.test.ts b/js/net/src/ordered.test.ts index adaffecdc3f..37b62b03bc1 100644 --- a/js/net/src/ordered.test.ts +++ b/js/net/src/ordered.test.ts @@ -1,4 +1,4 @@ -// What an ordered read returns: groups in key order, and a gap for every group it gives up on. +// What an ordered read returns from nextItem: groups in key order, and a gap for every group it gives up on. // Ports the Rust `track::Ordered` item tests, so both read the same. import { expect, test } from "bun:test"; import { Duration, sleep } from "@moq/clock"; @@ -38,7 +38,7 @@ function items(ordered: Ordered): string[] { const out: string[] = []; for (;;) { if (out.length > 20) throw new Error(`no end to the items: ${out.join(", ")}`); - const item = ordered.tryNextGroup(); + const item = ordered.tryNextItem(); if (!item) return out; if (item.kind === "group") { out.push(`group ${item.group.start}`); @@ -72,13 +72,27 @@ test("an ordered read reports what it gives up, in key order, but no skip", () = // A group handed out and then dropped is never reported again. const cut = producer.createGroup(7n); - const read = ordered.tryNextGroup(); + const read = ordered.tryNextItem(); expect(read?.group?.start).toBe(7n); drop(producer, 7n, 8n); cut.abort(new StreamError(StreamCode.Cancel)); expect(items(ordered)).toEqual([]); }); +test("nextGroup and tryNextGroup pass the gaps nextItem reports", async () => { + const producer = new TrackProducer("test"); + const ordered = producer.subscribe({ delay: { max: null } }).ordered(); + put(producer, 0n); + drop(producer, 1n, 2n); + put(producer, 2n); + drop(producer, 3n, 4n); + put(producer, 4n); + expect((await ordered.nextGroup())?.start).toBe(0n); + expect(ordered.tryNextGroup()?.start).toBe(2n); + expect(ordered.tryNextItem()).toMatchObject({ kind: "gap", start: 3n, end: 4n }); + expect((await ordered.nextGroup())?.start).toBe(4n); +}); + test("a key a local track never produced is no gap", () => { const producer = new TrackProducer("test"); const ordered = producer.subscribe({ delay: { max: Duration.secs(1) } }).ordered(); @@ -106,7 +120,7 @@ test("a gap waits behind what is owed below it, and goes out before the end", () drop(local, 1n, 2n); local.finish(); expect(items(read)).toEqual(["group 0", "gap 1..2 (delivery timeout)"]); - expect(read.tryNextGroup()).toBeUndefined(); + expect(read.tryNextItem()).toBeUndefined(); })); test("a gap is returned once, even when a later drop names it again", () => @@ -221,11 +235,11 @@ test("a group held past a gap, under a cap lowered off it, still sees the read e put(producer, 0n); drop(producer, 1n, 2n); put(producer, 2n); - expect((await ordered.nextGroup())?.group?.start).toBe(0n); - expect((await ordered.nextGroup())?.kind).toBe("gap"); + expect((await ordered.nextItem())?.group?.start).toBe(0n); + expect((await ordered.nextItem())?.kind).toBe("gap"); ordered.withRange({ end: { excluded: 2n } }); - expect(ordered.tryNextGroup()).toBeUndefined(); - const pending = ordered.nextGroup(); + expect(ordered.tryNextItem()).toBeUndefined(); + const pending = ordered.nextItem(); ordered.close(); const ended = await Promise.race([ pending.then( diff --git a/js/net/src/resume.test.ts b/js/net/src/resume.test.ts index 4f6e8e4dca1..659d2260e61 100644 --- a/js/net/src/resume.test.ts +++ b/js/net/src/resume.test.ts @@ -12,7 +12,6 @@ import { Version as IetfVersion } from "./ietf/version.ts"; import * as Instance from "./instance.ts"; import { hooks, staleHole } from "./internal.ts"; import type { Lister } from "./listing.ts"; -import { nextGroup, tryNextGroup } from "./ordered.test-util.ts"; import { Producer } from "./origin.ts"; import * as Path from "./path.ts"; import { Front, routeFailed } from "./resume.ts"; @@ -1852,15 +1851,15 @@ test("an ordered reader takes a replaced copy's buffered group before the new co .subscribe({ delay: { max: Duration.millis(10_000) } }) .ordered(); ta.write(0n); - expect((await nextGroup(ordered))?.start).toBe(0n); + expect((await ordered.nextGroup())?.start).toBe(0n); // The old copy holds group 1 unread; the new one only has group 2. ta.write(1n); tb.write(2n); front.serve(b.consume()); await settle(); - expect((await nextGroup(ordered))?.start).toBe(1n); - expect((await nextGroup(ordered))?.start).toBe(2n); + expect((await ordered.nextGroup())?.start).toBe(1n); + expect((await ordered.nextGroup())?.start).toBe(2n); ordered.close(); front.consumer.close(); @@ -1883,7 +1882,7 @@ test("a routed read right after an update picks its group under the new preferen await settle(); // The copy learns of the update a microtask later; the read must not pick under its old budget. ordered.update({ delay: { max: Duration.ZERO } }); - expect(tryNextGroup(ordered)?.start).toBe(1n); + expect(ordered.tryNextGroup()?.start).toBe(1n); } finally { ordered.close(); front.consumer.close(); @@ -1909,13 +1908,13 @@ for (const resolution of ["arrival", "drop", "other copy", "budget"] as const) { .ordered(); try { ta.write(4n); - expect((await nextGroup(ordered))?.start).toBe(4n); + expect((await ordered.nextGroup())?.start).toBe(4n); ta.write(6n); tb.write(7n); hooks.startTrack(tb.producer, { start: 7n, requested: 4n }); front.serve(b.consume()); await settle(); - const held = nextGroup(ordered); + const held = ordered.nextGroup(); expect(await isPending(held)).toBe(true); if (resolution === "arrival") ta.write(5n); if (resolution === "other copy") { @@ -1927,7 +1926,7 @@ for (const resolution of ["arrival", "drop", "other copy", "budget"] as const) { if (resolution === "budget") await clock.advance(Duration.millis(1000)); const expected = resolution === "arrival" || resolution === "other copy" ? [5n, 6n, 7n] : [6n, 7n]; expect((await held)?.start).toBe(expected[0]); - for (const key of expected.slice(1)) expect((await nextGroup(ordered))?.start).toBe(key); + for (const key of expected.slice(1)) expect((await ordered.nextGroup())?.start).toBe(key); } finally { ordered.close(); front.consumer.close(); @@ -2096,13 +2095,13 @@ test("a route copy's record folds while the reader returns only gaps", () => { .ordered(); try { ta.write(0n); - expect(ordered.tryNextGroup()).toMatchObject({ kind: "group" }); + expect(ordered.tryNextItem()).toMatchObject({ kind: "group" }); const cut = new StreamError(StreamCode(70), { message: "cut" }); for (let i = 1n; i <= 1000n; i++) { // A drop and a skip apart, so each would be a run of its own in the copy's record. hooks.dropTrackGroups(ta.producer, 2n * i - 1n, 2n * i, { error: cut }); ta.producer.skipGroups(2n * i, 2n * i + 1n); - expect(ordered.tryNextGroup()).toMatchObject({ kind: "gap", start: 2n * i - 1n, end: 2n * i }); + expect(ordered.tryNextItem()).toMatchObject({ kind: "gap", start: 2n * i - 1n, end: 2n * i }); } expect(copies.size).toBeGreaterThan(0); for (const sub of copies) expect(hooks.reportedRuns(sub)).toBeLessThanOrEqual(4); @@ -2616,7 +2615,7 @@ test.each([true, false])( const sub = front.consumer.track("seq").subscribe(); const view = ordered ? sub.ordered() : undefined; const next = async () => { - const group = await (view ? nextGroup(view) : sub.recvGroup()); + const group = await (view ? view.nextGroup() : sub.recvGroup()); group?.close(); return group?.start; }; @@ -2658,7 +2657,7 @@ test.each([ front.serve(a.consume()); const sub = front.consumer.track("seq").subscribe(); const view = ordered ? sub.ordered() : undefined; - const next = () => (view ? nextGroup(view) : sub.recvGroup()); + const next = () => (view ? view.nextGroup() : sub.recvGroup()); ta.write(0n); (await next())?.close(); front.serve(b.consume()); @@ -2701,7 +2700,7 @@ test.each([true, false])( front.serve(a.consume()); const sub = front.consumer.track("seq").subscribe(); const view = ordered ? sub.ordered() : undefined; - const next = () => (view ? nextGroup(view) : sub.recvGroup()); + const next = () => (view ? view.nextGroup() : sub.recvGroup()); ta.write(0n); (await next())?.close(); front.serve(b.consume()); @@ -3205,7 +3204,7 @@ test.each([true, false])( front.serve(a.consume()); const sub = front.consumer.track("seq").subscribe({ delay: { max: Duration.millis(3_600_000) } }); const view = ordered ? sub.ordered() : undefined; - const next = () => (view ? nextGroup(view) : sub.recvGroup()); + const next = () => (view ? view.nextGroup() : sub.recvGroup()); ta.write(0n); (await next())?.close(); front.serve(b.consume()); @@ -3247,7 +3246,7 @@ test.each([true, false])("a replaced copy backs a group before its first arrival front.serve(a.consume()); const sub = front.consumer.track("seq").subscribe({ delay: { max: Duration.millis(3_600_000) } }); const view = ordered ? sub.ordered() : undefined; - const next = () => (view ? nextGroup(view) : sub.recvGroup()); + const next = () => (view ? view.nextGroup() : sub.recvGroup()); ta.write(0n); (await next())?.close(); front.serve(b.consume()); @@ -3569,7 +3568,7 @@ test.each([ const inOrder = ordered ? sub.ordered() : undefined; const read = () => { const keys: bigint[] = []; - const next = () => (inOrder ? tryNextGroup(inOrder) : sub.tryRecvGroup()); + const next = () => (inOrder ? inOrder.tryNextGroup() : sub.tryRecvGroup()); for (let group = next(); group; group = next()) { keys.push(group.start); group.close(); diff --git a/js/net/src/retention.test.ts b/js/net/src/retention.test.ts index a54367f5c7b..7f43534d31a 100644 --- a/js/net/src/retention.test.ts +++ b/js/net/src/retention.test.ts @@ -6,7 +6,6 @@ import * as Ietf from "./ietf/index.ts"; import { hooks } from "./internal.ts"; import * as Lite from "./lite/index.ts"; import { createMockTransportPair } from "./mock.ts"; -import { nextGroup } from "./ordered.test-util.ts"; import { Producer as OriginProducer } from "./origin.ts"; import * as Path from "./path.ts"; import { Timescale, Timestamp } from "./time.ts"; @@ -120,7 +119,7 @@ for (const [name, alpn] of [ const group = hooks.appendNext(producer); group.writeFrame(frame(0)); - const consumer = await nextGroup(track); + const consumer = await track.nextGroup(); if (!consumer) throw new Error("no group"); await readFrames(consumer, 1); @@ -143,7 +142,7 @@ for (const [name, alpn] of [ const group = hooks.appendNext(producer); group.writeFrame(frame(offset + i)); group.finish(); - const consumer = await nextGroup(track); + const consumer = await track.nextGroup(); if (!consumer) throw new Error("no group"); await readFrames(consumer, 1); } diff --git a/js/net/src/track.test.ts b/js/net/src/track.test.ts index a153edf3234..eb353b62b67 100644 --- a/js/net/src/track.test.ts +++ b/js/net/src/track.test.ts @@ -8,7 +8,6 @@ import type { Consumer as GroupConsumer, Producer as GroupProducer } from "./gro import { Version as IetfVersion } from "./ietf/version.ts"; import { hooks, skipHole, staleHole } from "./internal.ts"; import { textFrame } from "./mock.ts"; -import { nextGroup, tryNextGroup } from "./ordered.test-util.ts"; import { rescale, rescaleIn } from "./rescale.ts"; import { Timescale, Timestamp } from "./time.ts"; import { authoredInfo, Subscription, Producer as TrackProducer } from "./track.ts"; @@ -97,7 +96,7 @@ function appendFrozen(producer: TrackProducer, text = "x"): bigint { function drainOrdered(reader: import("./track.ts").Ordered) { const keys: bigint[] = []; - for (let group = tryNextGroup(reader); group; group = tryNextGroup(reader)) { + for (let group = reader.tryNextGroup(); group; group = reader.tryNextGroup()) { keys.push(group.start); group.close(); } @@ -133,7 +132,7 @@ test("an ordered owed hole wakes exactly at its wall budget", async () => { expect(drainOrdered(reader)).toEqual([0n]); putGroup(producer, 2n); let resolved = false; - const pending = nextGroup(reader).then((group) => { + const pending = reader.nextGroup().then((group) => { resolved = true; return group; }); @@ -192,7 +191,7 @@ test("an ordered owed hole follows media time and a lower successor", async () = edge.writeFrame(textFrame("edge", Timestamp.fromMillis(4000))); expect(drainOrdered(reader)).toEqual([]); let resolved = false; - const pending = nextGroup(reader).then((group) => { + const pending = reader.nextGroup().then((group) => { resolved = true; return group; }); @@ -204,7 +203,7 @@ test("an ordered owed hole follows media time and a lower successor", async () = expect(drainOrdered(reader)).toEqual([]); // Group 3 is still owed. edge.writeFrame(textFrame("within", Timestamp.fromMillis(4999))); expect(drainOrdered(reader)).toEqual([]); - const deadline = nextGroup(reader); + const deadline = reader.nextGroup(); edge.writeFrame(textFrame("deadline", Timestamp.fromMillis(5000))); await settle(); expect((await deadline)?.start).toBe(4n); @@ -229,7 +228,7 @@ test("an ordered owed hole wakes when its ledger gap folds", async () => { putGroup(producer, 3n); opener.abort(new StreamError(StreamCode.Cancel)); let resolved = false; - const pending = nextGroup(reader).then((group) => { + const pending = reader.nextGroup().then((group) => { resolved = true; return group; }); @@ -263,7 +262,7 @@ test("ordered owed holes follow zero, narrowed, unlimited, and publisher budgets putGroup(producer, 1n); expect(drainOrdered(reader)).toEqual([1n, 2n]); } else if (!maxDelay.isZero()) { - const pending = nextGroup(reader); + const pending = reader.nextGroup(); reader.update({ delay: { max: Duration.ZERO } }); expect((await pending)?.start).toBe(2n); } @@ -276,7 +275,7 @@ test("ordered owed holes follow zero, narrowed, unlimited, and publisher budgets putGroup(producer, 0n); putGroup(producer, 2n); expect(drainOrdered(reader)).toEqual([0n]); - const pending = nextGroup(reader); + const pending = reader.nextGroup(); await clock.advance(3_600_050); expect((await pending)?.start).toBe(2n); reader.close(); @@ -800,11 +799,11 @@ test("an ordered reader keeps a group between its ranges until the cursor passes }) .ordered(); for (const key of [0n, 1n]) producer.createGroup(key).finish(); - expect(tryNextGroup(track)?.start).toBe(0n); - expect(tryNextGroup(track)).toBeUndefined(); + expect(track.tryNextGroup()?.start).toBe(0n); + expect(track.tryNextGroup()).toBeUndefined(); track.update({ delay: { max: null }, ranges: [{ start: { time: 0n }, end: { time: 3n } }] }); - expect(tryNextGroup(track)?.start).toBe(1n); + expect(track.tryNextGroup()?.start).toBe(1n); track.close(); producer.finish(); producer.close(); @@ -1021,7 +1020,7 @@ test("a time start resolves on keys alone, before any group's first frame", () = for (let group = reader.tryRecvGroup(); group; group = reader.tryRecvGroup()) got.push(group.start); expect(got.sort()).toEqual([1000n, 2000n]); const inOrder: bigint[] = []; - for (let group = tryNextGroup(ordered); group; group = tryNextGroup(ordered)) inOrder.push(group.start); + for (let group = ordered.tryNextGroup(); group; group = ordered.tryNextGroup()) inOrder.push(group.start); expect(inOrder).toEqual([1000n, 2000n]); } }); @@ -1100,7 +1099,7 @@ test("nextGroup skips late arrivals", async () => { producer.createGroup(5n); - const first = await nextGroup(track); + const first = await track.nextGroup(); expect(first?.start).toBe(5n); // Late arrivals with sequence <= last returned are skipped. @@ -1108,7 +1107,7 @@ test("nextGroup skips late arrivals", async () => { producer.createGroup(4n); producer.createGroup(7n); - const next = await nextGroup(track); + const next = await track.nextGroup(); expect(next?.start).toBe(7n); }); @@ -1119,8 +1118,8 @@ test("nextGroup returns buffered groups in sequence", async () => { producer.createGroup(3n); producer.createGroup(5n); - expect((await nextGroup(track))?.start).toBe(3n); - expect((await nextGroup(track))?.start).toBe(5n); + expect((await track.nextGroup())?.start).toBe(3n); + expect((await track.nextGroup())?.start).toBe(5n); }); test.each([false, true])("a reordered tail keeps the group PTS drift verdict (B-frame: %s)", async (reordered) => { @@ -1200,13 +1199,13 @@ test("the latency budget skips a buffered timeline on either cursor", async () = } expect((await arrival.recvGroup())?.start).toBe(2000n); - expect((await nextGroup(ordered))?.start).toBe(2000n); + expect((await ordered.nextGroup())?.start).toBe(2000n); // The budget is the only gate: one that spans the backlog bursts it in order. const replay = producer.subscribe({ delay: { max: Duration.millis(30_000) } }).ordered(); - expect((await nextGroup(replay))?.start).toBe(0n); - expect((await nextGroup(replay))?.start).toBe(1000n); - expect((await nextGroup(replay))?.start).toBe(2000n); + expect((await replay.nextGroup())?.start).toBe(0n); + expect((await replay.nextGroup())?.start).toBe(1000n); + expect((await replay.nextGroup())?.start).toBe(2000n); }); // A frameless successor is not content, so the next started group bounds the group before @@ -1289,7 +1288,7 @@ for (const take of ["nextGroup", "tryNextGroup"] as const) { // The frame path enters group 0; a direct take then claims group 1. expect((await track.readFrame())?.group).toBe(0n); - expect((await track[take]())?.group?.start).toBe(1n); + expect((await track[take]())?.start).toBe(1n); // The frame path must not resume group 0 behind the cursor: it continues at 2. const next = await track.readFrame(); @@ -1441,19 +1440,19 @@ test("the ordered cursor sheds a stale backlog", async () => { // The whole backlog is already buffered, so no read ever blocks on it: without the // budget here the cursor would replay four seconds of history at 1x and stay behind. const live = producer.subscribe().ordered(); - expect((await nextGroup(live))?.start).toBe(3000n); + expect((await live.nextGroup())?.start).toBe(3000n); // Only what is provably too old goes. Group 0 reaches 1s, a full 2s behind the 3s // edge; group 1000 reaches 2s and could still present inside a 1.5s budget. const bounded = producer.subscribe({ delay: { max: Duration.millis(1500) } }).ordered(); - expect((await nextGroup(bounded))?.start).toBe(1000n); - expect((await nextGroup(bounded))?.start).toBe(2000n); - expect((await nextGroup(bounded))?.start).toBe(3000n); + expect((await bounded.nextGroup())?.start).toBe(1000n); + expect((await bounded.nextGroup())?.start).toBe(2000n); + expect((await bounded.nextGroup())?.start).toBe(3000n); // A budget spanning the history still bursts it in full, gap-free. const replay = producer.subscribe({ delay: { max: Duration.millis(30_000) } }).ordered(); for (const key of [0n, 1000n, 2000n, 3000n]) { - expect((await nextGroup(replay))?.start).toBe(key); + expect((await replay.nextGroup())?.start).toBe(key); } }); @@ -2209,7 +2208,7 @@ test.each(["arrival", "ordered"] as const)("subscription bounds stay reader-loca ranges: [{ start: { time: 1n }, end: { time: 2n } }], }); const ordered = order === "ordered" ? subscriber.ordered() : undefined; - const read = () => (ordered ? nextGroup(ordered) : subscriber.recvGroup()); + const read = () => (ordered ? ordered.nextGroup() : subscriber.recvGroup()); try { for (let key = 0n; key < 5n; key++) producer.createGroup(key); expect((await everything.recvGroup())?.start).toBe(0n); @@ -2369,10 +2368,10 @@ test("local cursor bounds can skip, pause, and release buffered groups", async ( for (let key = 0n; key < 5n; key++) producer.createGroup(key); track.withRange({ start: { included: 1n }, end: { excluded: 3n } }); - expect((await nextGroup(track))?.start).toBe(1n); - expect((await nextGroup(track))?.start).toBe(2n); + expect((await track.nextGroup())?.start).toBe(1n); + expect((await track.nextGroup())?.start).toBe(2n); - const pending = nextGroup(track); + const pending = track.nextGroup(); expect(await Promise.race([pending, Promise.resolve("pending")])).toBe("pending"); track.withRange({ start: { included: 4n }, end: { excluded: 5n } }); @@ -2536,7 +2535,7 @@ test("the ordered and arrival cursors are independent", async () => { const arrival = producer.subscribe({ delay: { max: Duration.millis(5000) } }); producer.createGroup(5n); - expect((await nextGroup(ordered))?.start).toBe(5n); + expect((await ordered.nextGroup())?.start).toBe(5n); // A late seq 3 is skipped by the ordered cursor, which has already passed it, but the // arrival cursor has both buffered and still delivers each exactly once. @@ -2566,8 +2565,8 @@ test("the first group read commits the cursor and refuses the other order", asyn const ordered = inert.ordered(); expect(inert.recvGroup()).rejects.toThrow("sequence order"); expect(() => inert.ordered()).toThrow("sequence order"); - expect((await nextGroup(ordered))?.start).toBe(3n); - expect((await nextGroup(ordered))?.start).toBe(5n); + expect((await ordered.nextGroup())?.start).toBe(3n); + expect((await ordered.nextGroup())?.start).toBe(5n); }); // Datagrams are a separate cursor on either handle, so reading them must not commit @@ -2577,7 +2576,7 @@ test("nextGroup returns undefined when track closes", async () => { const track = producer.subscribe().ordered(); producer.finish(); producer.close(); - expect(await nextGroup(track)).toBeUndefined(); + expect(await track.nextGroup()).toBeUndefined(); }); // A clean close ends a pending ordered read without erasing beyond-cap frames. @@ -2592,23 +2591,23 @@ test("a closed track still delivers a group parked above the cap once the cap is } track.withRange({ end: { excluded: 2n } }); - expect((await nextGroup(track))?.start).toBe(0n); - expect((await nextGroup(track))?.start).toBe(1n); + expect((await track.nextGroup())?.start).toBe(0n); + expect((await track.nextGroup())?.start).toBe(1n); // Group 2 parks while open; a clean close completes the current range. - const parked = nextGroup(track); + const parked = track.nextGroup(); producer.finish(); producer.close(); expect(await parked).toBeUndefined(); // Raising the cap after close releases the buffered group, frames intact. track.withRange({ end: { excluded: 3n } }); - const released = await nextGroup(track); + const released = await track.nextGroup(); expect(released?.start).toBe(2n); expect(await released?.readString()).toBe("frame-2"); // Drained and closed: now it's finished. - expect(await nextGroup(track)).toBeUndefined(); + expect(await track.nextGroup()).toBeUndefined(); }); // 0 is the only encoding for "nothing produced"; an abort declares no boundary at all. @@ -3028,7 +3027,7 @@ for (const ordered of [false, true]) { const producer = new TrackProducer("test"); const subscriber = producer.subscribe({ delay: { max: Duration.millis(60_000) } }); const track = ordered ? subscriber.ordered() : subscriber; - const receive = () => ("nextGroup" in track ? nextGroup(track) : track.recvGroup()); + const receive = () => ("nextGroup" in track ? track.nextGroup() : track.recvGroup()); try { producer.finishAt({ group: 3n, frame: 0 }); const waiting = receive(); @@ -3218,7 +3217,7 @@ test("an abort keeps finished groups for a slow reader, then reports it", async const boom = new Error("boom"); producer.abort(boom); - for (const next of [() => arrival.recvGroup(), () => nextGroup(ordered)]) { + for (const next of [() => arrival.recvGroup(), () => ordered.nextGroup()]) { for (let i = 0; i < 2; i++) { const group = await next(); expect(group?.start).toBe(BigInt(i)); @@ -3241,7 +3240,7 @@ test("an abort after the declared end settles ends clean", async () => { producer.finishAt({ group: 2n, frame: 0 }); producer.abort(new Error("boom")); - for (const next of [() => arrival.recvGroup(), () => nextGroup(ordered)]) { + for (const next of [() => arrival.recvGroup(), () => ordered.nextGroup()]) { expect((await next())?.start).toBe(0n); expect((await next())?.start).toBe(1n); expect(await next()).toBeUndefined(); @@ -3361,7 +3360,7 @@ test("an abort leaves a group already taken readable, then reports the abort", a const arrival = producer.subscribe({ delay: { max: Duration.millis(10_000) } }); const ordered = producer.subscribe({ delay: { max: Duration.millis(10_000) } }).ordered(); hooks.appendNext(producer).writeFrame(textFrame("held")); - const held = [await arrival.recvGroup(), await nextGroup(ordered)]; + const held = [await arrival.recvGroup(), await ordered.nextGroup()]; const boom = new Error("boom"); producer.abort(boom); @@ -4969,7 +4968,7 @@ for (const refresh of [undefined, 0]) { const subscriber = producer.subscribe(); const ordered = subscriber.ordered(); const group = hooks.appendNext(producer); - const consumer = await nextGroup(ordered); + const consumer = await ordered.nextGroup(); if (!consumer) throw new Error("missing group"); for (let index = 0; index < 40; index++) group.writeFrame({ payload: new Uint8Array(1024 * 1024), timestamp: Timestamp.unscaled(group.start) }); @@ -4991,7 +4990,7 @@ test("reading a shed frame head requests refresh", async () => { const subscriber = producer.subscribe(); const ordered = subscriber.ordered(); const group = hooks.appendNext(producer); - const consumer = await nextGroup(ordered); + const consumer = await ordered.nextGroup(); if (!consumer) throw new Error("missing group"); const MiB = 1024 * 1024; const frame = group.createFrame({ size: 40 * MiB, timestamp: Timestamp.unscaled(group.start) }); @@ -5026,9 +5025,9 @@ test("a failed track keeps its history", async () => { await expect(arrival.recvGroup()).rejects.toBe(failed); const ordered = producer.subscribe(replay).ordered(); - expect((await nextGroup(ordered))?.start).toBe(0n); - expect((await nextGroup(ordered))?.start).toBe(1n); - await expect(nextGroup(ordered)).rejects.toBe(failed); + expect((await ordered.nextGroup())?.start).toBe(0n); + expect((await ordered.nextGroup())?.start).toBe(1n); + await expect(ordered.nextGroup()).rejects.toBe(failed); // The nonblocking reads end the same way. const polled = producer.subscribe(replay); @@ -5036,9 +5035,9 @@ test("a failed track keeps its history", async () => { expect(polled.tryRecvGroup()?.start).toBe(1n); expect(() => polled.tryRecvGroup()).toThrow(failed); const polledOrdered = producer.subscribe(replay).ordered(); - expect(tryNextGroup(polledOrdered)?.start).toBe(0n); - expect(tryNextGroup(polledOrdered)?.start).toBe(1n); - expect(() => tryNextGroup(polledOrdered)).toThrow(failed); + expect(polledOrdered.tryNextGroup()?.start).toBe(0n); + expect(polledOrdered.tryNextGroup()?.start).toBe(1n); + expect(() => polledOrdered.tryNextGroup()).toThrow(failed); }); // `fail` ends where `finish` would, after the highest group written, so a late group below it is diff --git a/js/net/src/track.ts b/js/net/src/track.ts index e0ebfdedd6f..16bf7542c90 100644 --- a/js/net/src/track.ts +++ b/js/net/src/track.ts @@ -83,7 +83,7 @@ function taken(read: () => Recv, ended: () => undefined): GroupConsumer | undefi } } -/** What an {@link Ordered} read returns next. Mirrors the Rust `track::Item`. */ +/** What {@link Ordered.nextItem} returns next. Mirrors the Rust `track::Item`. */ export type Item = /** A group, with a higher key than any group or gap returned before. */ | { kind: "group"; group: GroupConsumer } @@ -1080,6 +1080,7 @@ let fillsOf: (producer: Producer) => FillState; // assigned in the class's static block. let makeOrdered: (subscriber: Subscriber) => Ordered; let ordered_: { + nextGroup(subscriber: Subscriber): Promise; nextItem(subscriber: Subscriber): Promise; tryItem(subscriber: Subscriber): ItemRecv; ended(subscriber: Subscriber): undefined; @@ -4152,6 +4153,7 @@ export class Subscriber { // The key cursor lives here (it shares the buffer and the drift anchor with // the arrival cursor); `Ordered` is the handle that reaches it. ordered_ = { + nextGroup: (subscriber) => subscriber.#nextGroup(), nextItem: (subscriber) => subscriber.#nextItem(), tryItem: (subscriber) => subscriber.#tryItem(), ended: (subscriber) => subscriber.#ended(), @@ -4833,7 +4835,7 @@ export class Subscriber { } } - // The next group in key order, past any gap, for the frame helpers. + // The next group in key order, past any gap. async #nextGroup(): Promise { for (;;) { const item = await this.#nextItem(); @@ -5368,32 +5370,55 @@ export class Ordered { } /** - * The next group with a higher key than any returned before, or a gap this reader gave up on - * below the next group, as the Rust `next_group` returns. Mirrors its `Item`. + * Return the next group with a strictly-greater sequence number than the last returned, + * passing any gap {@link nextItem} would report below it. Mirrors the Rust `next_group`. + * + * Late arrivals (key at or below the last returned) are silently skipped, as is a + * group whose every frame is further behind the live edge than `delay.max` (the default + * subscription's zero keeps only what nothing newer has superseded). Honors the bounds set by + * {@link withRange}. Like {@link Subscriber.recvGroup}, a read whose ranges all end + * finishes once nothing in them is left to deliver. Later reads return `undefined` + * immediately too; widening the ranges with {@link update} reads on above the last key returned. + */ + nextGroup(): Promise { + return ordered_.nextGroup(this.#subscriber); + } + + /** + * Take the next group as {@link nextGroup} would, without waiting: `undefined` when nothing + * is deliverable right now, which is not by itself the end of the track. Mirrors the Rust + * `poll_next_group`. + */ + tryNextGroup(): GroupConsumer | undefined { + for (;;) { + const item = this.tryNextItem(); + if (item?.kind !== "gap") return item?.group; + } + } + + /** + * The next group, as {@link nextGroup} returns it, or a gap this reader gave up on below it. + * Mirrors the Rust `next_item` and its `Item`. * * A gap is every group the publisher or a relay dropped, the transport evicted, `delay.max` - * aged out (the default subscription's zero keeps only what nothing newer has superseded), a - * fill could not find, or that landed after the read passed its key. It carries the keys it - * spans and is returned once, after any group the read still owes below it and before the - * next group above it, or when the track ends. Keys the publisher declared skipped were never - * groups, so they are no gap, and nor is a key a local track never produced. Unlike Rust, nor - * is a group a local track produces after the read moved past its key: the read keeps no record - * below where it is, so its memory stays bounded. A session-fed track reports such a key at - * the latest when the read passes it. Honors the bounds - * set by {@link withRange}. Like {@link Subscriber.recvGroup}, a read whose ranges all end - * finishes once nothing in them is left to deliver. Later reads return `undefined` immediately - * too; widening the ranges with {@link update} reads on above the last key returned. + * aged out, a fill could not find, or that landed after the read passed its key. It carries + * the keys it spans and is returned once, after any group the read still owes below it and + * before the next group above it, or when the track ends. Keys the publisher declared skipped + * were never groups, so they are no gap, and nor is a key a local track never produced. + * Unlike Rust, nor is a group a local track produces after the read moved past its key: the + * read keeps no record below where it is, so its memory stays bounded. A session-fed track + * reports such a key at the latest when the read passes it. */ - nextGroup(): Promise { + nextItem(): Promise { return ordered_.nextItem(this.#subscriber); } /** - * Take the next item as {@link nextGroup} would, without waiting: `undefined` when nothing + * Take the next item as {@link nextItem} would, without waiting: `undefined` when nothing * is ready right now, which is not by itself the end of the track. Mirrors the Rust - * `poll_next_group`. + * `poll_next_item`. */ - tryNextGroup(): Item | undefined { + tryNextItem(): Item | undefined { const recv = ordered_.tryItem(this.#subscriber); switch (recv.kind) { case "group": diff --git a/js/net/src/untimed.test.ts b/js/net/src/untimed.test.ts index 7ddf69bda02..f3722e5b715 100644 --- a/js/net/src/untimed.test.ts +++ b/js/net/src/untimed.test.ts @@ -8,7 +8,6 @@ import * as Ietf from "./ietf/index.ts"; import { hooks } from "./internal.ts"; import * as Lite from "./lite/index.ts"; import { createMockTransportPair } from "./mock.ts"; -import { nextGroup } from "./ordered.test-util.ts"; import { Producer as OriginProducer } from "./origin.ts"; import * as Path from "./path.ts"; import { Timescale, Timestamp } from "./time.ts"; @@ -73,7 +72,7 @@ async function roundTrip(wire: Wire, timescale: Timescale | undefined, timestamp const remote = wireOf(client).consume(Path.from("test")); const subscriber = remote.track("video").subscribe(); const info = await subscriber.info(); - const group = await nextGroup(subscriber.ordered()); + const group = await subscriber.ordered().nextGroup(); const frames = []; for (let frame = await group?.readFrame(); frame; frame = await group?.readFrame()) frames.push(frame); @@ -93,7 +92,7 @@ async function republish(input: BroadcastConsumer): Promise { void (async () => { try { const groups = subscription.ordered(); - for (let group = await nextGroup(groups); group; group = await nextGroup(groups)) { + for (let group = await groups.nextGroup(); group; group = await groups.nextGroup()) { // The same group, so a scale-less frame's key still names it. const out = video.createGroup(group.start); for (let frame = await group.readFrame(); frame; frame = await group.readFrame()) out.writeFrame(frame); @@ -153,7 +152,7 @@ test("a forwarded untimed track stays untimed", async () => { const remote = wireOf(subscriber).consume(Path.from("test")); const track = remote.track("video").subscribe(); expect((await track.info()).timescale).toBeNull(); - const frame = await (await nextGroup(track.ordered()))?.readFrame(); + const frame = await (await track.ordered().nextGroup())?.readFrame(); expect(frame?.payload).toEqual(new Uint8Array([7])); expect(frame?.timestamp).toEqual(Timestamp.unscaled(0n)); diff --git a/js/publish/bench/audio-page.ts b/js/publish/bench/audio-page.ts index fa2ea13f1ac..cf7e9a64d6d 100644 --- a/js/publish/bench/audio-page.ts +++ b/js/publish/bench/audio-page.ts @@ -132,7 +132,7 @@ async function measure(tracks: number, seconds: number, onDemand: boolean) { const catchup = performance.now() - joining; for (const subscriber of subscribers) { const reader = subscriber.ordered(); - const group = (await reader.nextGroup())?.group; + const group = await reader.nextGroup(); const frame = await group?.readFrame(); if (!frame) throw new Error("missing retained audio"); const timestamp = Moq.Varint.decode(frame.payload)[0]; diff --git a/js/publish/src/announce.test.ts b/js/publish/src/announce.test.ts index f415f894d80..8c663f512db 100644 --- a/js/publish/src/announce.test.ts +++ b/js/publish/src/announce.test.ts @@ -96,7 +96,7 @@ test("a subscriber arriving at announce time sees every rendition in its first c const net = env.broadcast.net.peek(); if (!net) throw new Error("expected a network producer once connected"); const subscriber = net.track(Broadcast.CATALOG_TRACK).subscribe({ delay: { max: null } }); - const group = (await subscriber.ordered().nextGroup())?.group; + const group = await subscriber.ordered().nextGroup(); // Reaching back over every group, the oldest is also the newest: nothing was published before it. expect(group?.start).toBe((await subscriber.largest())?.group); const catalog = (await group?.readJson()) as Catalog.Root; diff --git a/js/publish/src/audio/encoder.test.ts b/js/publish/src/audio/encoder.test.ts index 909e379387e..b7e160c5f87 100644 --- a/js/publish/src/audio/encoder.test.ts +++ b/js/publish/src/audio/encoder.test.ts @@ -1360,7 +1360,7 @@ test.each([undefined, "off", "all"] as const)( expect(encoder.out.active.peek()).toBe(true); await push(3); - const group = (await late.ordered().nextGroup())?.group; + const group = await late.ordered().nextGroup(); if (!group) throw new Error("expected a group"); const frame = await group.readFrame(); if (!frame) throw new Error("expected a frame"); @@ -1482,13 +1482,7 @@ test("default audio replays the last second after three seconds without a subscr // The subscription's one second reaches back from the newest frame, 152, to 102. const reader = late.ordered(); for (let index = 102; index < 153; index++) { - let item = await reader.nextGroup(); - // The replay's older groups, past the subscription's second, read as gaps ahead of it. - while (item?.kind === "gap") { - expect(item.end).toBeLessThanOrEqual(BigInt(index * 20_000)); - item = await reader.nextGroup(); - } - const group = item?.group; + const group = await reader.nextGroup(); if (!group) throw new Error("expected buffered group"); const frame = await group.readFrame(); if (!frame) throw new Error("expected buffered frame"); @@ -1546,7 +1540,7 @@ for (const [name, subscription] of [ expect(encoder.out.stats.peek().frames).toBe(7 - FakeAudioEncoder.LAG); await feed.push({ timestamp: Duration.micros(150 * 20_000), channels: [new Float32Array(960)] }); await feed.drain(); - const group = (await late.ordered().nextGroup())?.group; + const group = await late.ordered().nextGroup(); const frame = await group?.readFrame(); if (!frame) throw new Error("expected a replayed frame"); expect(Moq.Varint.decode(frame.payload)[0]).toBe(143 * 20_000); @@ -1765,7 +1759,7 @@ test.each([false, true])("audio retained before a disable is encoded on demand ( expect(encoder.out.stats.peek().frames).toBe(4); const reader = late.ordered(); for (let index = 0; index < 4; index++) { - const group = (await reader.nextGroup())?.group; + const group = await reader.nextGroup(); const frame = await group?.readFrame(); if (!frame) throw new Error("expected retained frame"); expect(Moq.Varint.decode(frame.payload)[0]).toBe(index * 20_000); @@ -1828,7 +1822,7 @@ test("audio retained across a disable and re-enable is served before the break", const reader = late.ordered(); const read: [number, number][] = []; while (read.length < 6) { - const group = (await reader.nextGroup())?.group; + const group = await reader.nextGroup(); const frame = await group?.readFrame(); if (!frame) throw new Error("expected a frame"); const [timestamp, payload] = Moq.Varint.decode(frame.payload); @@ -1895,7 +1889,7 @@ test("a capture gap inside replayed audio keeps every frame on both sides of it" const reader = late.ordered(); const read: [number, number][] = []; while (read.length < 7) { - const group = (await reader.nextGroup())?.group; + const group = await reader.nextGroup(); const frame = await group?.readFrame(); if (!frame) throw new Error("expected a frame"); const [timestamp, payload] = Moq.Varint.decode(frame.payload); diff --git a/js/publish/src/broadcast.test.ts b/js/publish/src/broadcast.test.ts index 0337efccac8..277e2e3e33c 100644 --- a/js/publish/src/broadcast.test.ts +++ b/js/publish/src/broadcast.test.ts @@ -381,7 +381,7 @@ test("serves no catalog until announced, so the first snapshot is the one at ann if (!net) throw new Error("expected a network producer once connected"); const subscriber = net.track(Broadcast.CATALOG_TRACK).subscribe({ delay: { max: null } }); - const group = (await subscriber.ordered().nextGroup())?.group; + const group = await subscriber.ordered().nextGroup(); // Reaching back over every group, the oldest is also the newest: nothing was published before it. expect(group?.start).toBe((await subscriber.largest())?.group); const catalog = (await group?.readJson()) as Catalog.Root; @@ -409,7 +409,7 @@ test("a re-announce continues the catalog's group sequence", async () => { if (!net) throw new Error("expected a network producer once connected"); const announced = broadcast.in.origin.peek()?.follow(broadcast.in.name.peek()); const first = net.track(Broadcast.CATALOG_TRACK).subscribe().ordered(); - const start = (await first.nextGroup())?.group?.start; + const start = (await first.nextGroup())?.start; if (start === undefined) throw new Error("expected the first catalog"); const instance = announced?.active.peek()?.instance; expect(instance).toBeDefined(); @@ -426,7 +426,7 @@ test("a re-announce continues the catalog's group sequence", async () => { // is past the first. expect(announced?.active.peek()?.instance).toBe(instance); expect(broadcast.net.peek()).toBe(net); - const group = (await first.nextGroup())?.group; + const group = await first.nextGroup(); expect(group?.start).toBeGreaterThan(start); const catalog = (await group?.readJson()) as Catalog.Root; expect(Object.keys(catalog.audio?.renditions ?? {})).toEqual(["audio"]); diff --git a/js/publish/src/catalog.test.ts b/js/publish/src/catalog.test.ts index d8524060e76..994bd5663b9 100644 --- a/js/publish/src/catalog.test.ts +++ b/js/publish/src/catalog.test.ts @@ -89,7 +89,7 @@ test("catalog producer publishes every update as a snapshot group", async () => catalog.serve(track, effect); const subscriber = track.subscribe().ordered(); - const first = (await subscriber.nextGroup())?.group; + const first = await subscriber.nextGroup(); if (!first) throw new Error("expected the first snapshot"); expect(await first?.readJson()).toEqual({ sync: { clock: expect.anything() }, video: { renditions: {} } }); expect(first?.done).toBe(true); @@ -98,7 +98,7 @@ test("catalog producer publishes every update as a snapshot group", async () => c.scte35 = { splices: [] }; }); - const second = (await subscriber.nextGroup())?.group; + const second = await subscriber.nextGroup(); // Each snapshot opens a group at its timestamp, past the previous one. expect(second?.start).toBeGreaterThan(first.start); expect(await second?.readJson()).toEqual({ @@ -160,7 +160,7 @@ test("catalog producer omits the clock when the page's wall clock is unset", asy const track = new Track.Producer("catalog.json").accept({ timescale: Time.Timescale.MILLI }); catalog.serve(track, effect); const subscriber = track.subscribe().ordered(); - const group = (await subscriber.nextGroup())?.group; + const group = await subscriber.nextGroup(); expect(await group?.readJson()).toEqual({ video: { renditions: {} } }); effect.close(); } finally { diff --git a/js/publish/src/video/encoder.test.ts b/js/publish/src/video/encoder.test.ts index 14ac2a6b654..ae12d852d21 100644 --- a/js/publish/src/video/encoder.test.ts +++ b/js/publish/src/video/encoder.test.ts @@ -1553,7 +1553,7 @@ test.each(["off", "all"] as const)( const groups: bigint[] = []; const firsts: number[] = []; for (let i = 0; i < (onDemand ? 1 : 2); i++) { - const group = (await ordered.nextGroup())?.group; + const group = await ordered.nextGroup(); if (!group) throw new Error("expected a group"); groups.push(group.start); const frame = await group.readFrame(); diff --git a/test/interop/clients/js-native/ranges.ts b/test/interop/clients/js-native/ranges.ts index ef7ec659767..6416990ad74 100644 --- a/test/interop/clients/js-native/ranges.ts +++ b/test/interop/clients/js-native/ranges.ts @@ -62,10 +62,7 @@ try { try { const seen: bigint[] = []; const ordered = reader.ordered(); - for (let item = await ordered.nextGroup(); item; item = await ordered.nextGroup()) { - // A key the range never produced may read as a gap; only the groups are graded. - if (item.kind === "gap") continue; - const group = item.group; + for (let group = await ordered.nextGroup(); group; group = await ordered.nextGroup()) { seen.push(group.start); try { for (const size of [1024, 513, 513]) { From 5cc07b3dfdc94350f25f3c1a11c08266f7fc7a1d Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 18 Nov 2026 03:10:18 -0800 Subject: [PATCH 17/23] docs(quest): ordered-gaps notes js/net already has nextItem Co-Authored-By: Claude Opus 5.5 --- quest/m2/outcome-enums/ordered-gaps.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/quest/m2/outcome-enums/ordered-gaps.md b/quest/m2/outcome-enums/ordered-gaps.md index 62f552e93a8..6c016aabab4 100644 --- a/quest/m2/outcome-enums/ordered-gaps.md +++ b/quest/m2/outcome-enums/ordered-gaps.md @@ -26,7 +26,8 @@ points the container reader at `next_item`. Public API: breaking in moq-net; callers of `next_group` that matched `Item` drop the match, and the gap-reading one calls `next_item`. No JS or binding -change: js/net's ordered reads and moq-ffi already hide gaps. Wire: none. +change: js/net's `Ordered` already has `nextGroup` and `nextItem`, and moq-ffi +hides gaps. Wire: none. ## Related From 6f807aff65b0edc807ed7f1b12681226db06343e Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 18 Nov 2026 03:31:55 -0800 Subject: [PATCH 18/23] fix(net,hang,watch): answer the review of the ordered reader - A routed read in key order takes what its copies gave up below a group before it hands the group out, so a session-fed copy's report of a key it passed is a gap rather than lost. - An ordered read's passed keys are owed from where the session's live feed starts, plus what a fill was asked for. - A reader's close releases a group held behind a gap. - The hang consumer marks the next frame lost when an empty group carries a reported gap, and releases a group read after it closed. - The audio replay's ordered reader takes the warmup into its budget, as the browser's does; relay-mic-rtt40 is re-measured. Co-Authored-By: Claude Opus 5.5 --- doc/concept/audio-jitter.md | 4 +- .../src/container/consumer.ordered.test.ts | 7 +++- js/hang/src/container/consumer.ts | 18 ++++++-- js/net/src/internal.ts | 7 +++- js/net/src/ordered.test.ts | 26 +++++++++++- js/net/src/resume.test.ts | 31 ++++++++++++++ js/net/src/resume.ts | 11 +++-- js/net/src/track.ts | 41 ++++++++++++++----- js/watch/src/audio/replay.ts | 9 ++-- .../audio-playout/browser-audio-hole-skip.md | 11 ++--- test/audio-quality/budgets.json | 4 +- 11 files changed, 133 insertions(+), 36 deletions(-) diff --git a/doc/concept/audio-jitter.md b/doc/concept/audio-jitter.md index 3de4119f1fb..b80f4e4a880 100644 --- a/doc/concept/audio-jitter.md +++ b/doc/concept/audio-jitter.md @@ -59,8 +59,8 @@ arrived that long ago. A late burst that fills a hole a moment after the group past it lands still plays it, and a viewer resuming behind a replayed backlog does not hold the live audio for the backlog's oldest group. That reader's budget is its own: a second subscription to the same track, read in arrival -order, observes every frame, so the late groups the reader gives up on are -still measured. A caller that estimates keeps the budget past the target, which is why +order, observes every frame its own wider budget receives, so the late groups +the reader gives up on are still measured. A caller that estimates keeps the budget past the target, which is why `moq play` waits on a stalled audio group for the delay plus the estimate's 2 s ceiling. The observation is also only as honest as the caller is prompt: `read()` is timed when it resolves, so a player drains it diff --git a/js/hang/src/container/consumer.ordered.test.ts b/js/hang/src/container/consumer.ordered.test.ts index f86e49d4901..80c7e86d178 100644 --- a/js/hang/src/container/consumer.ordered.test.ts +++ b/js/hang/src/container/consumer.ordered.test.ts @@ -58,8 +58,11 @@ function setup(wait: number) { requests.close(); track.finish(); track.close(); - await reading; - installed.close(); + try { + await reading; + } finally { + installed.close(); + } }, }; } diff --git a/js/hang/src/container/consumer.ts b/js/hang/src/container/consumer.ts index 85e12fba925..fb7f70a7d7b 100644 --- a/js/hang/src/container/consumer.ts +++ b/js/hang/src/container/consumer.ts @@ -76,7 +76,8 @@ export interface ConsumerProps { predecessor?: Consumer; /** * Read the media in key order from this reader of the same track instead of `track`'s arrival - * order, so it decides every hole: a missing group is a hole once the reader reports it as a gap, + * order, so it decides every hole. It must be a second subscription, never `track`'s own, which + * keeps reading in arrival order to feed the estimate: a missing group is a hole once the reader reports it as a gap, * and never waited for here. Its `delay.max` is then how long a hole is waited for, so size it to * what the player can still play late. `track` only feeds the arrival estimate, read frame by frame * as it lands, so give it a `delay.max` reaching as far as lateness can move the estimate. @@ -357,6 +358,11 @@ export class Consumer { const consumer = await this.#track.recvGroup(); if (!consumer) break; + // Closed while the read waited: cleanup already ran, so nothing would release it. + if (this.#signals.abort.aborted) { + consumer.close(); + break; + } // Delivery starts at the floor the ranges name, raised to where the publisher says its feed // starts: it serves nothing below, and resolved a relative start against its own latest @@ -405,6 +411,11 @@ export class Consumer { const item = await ordered.nextItem(); if (!item) break; + // Closed while the read waited: cleanup already ran, so nothing would release it. + if (this.#signals.abort.aborted) { + item.group?.close(); + break; + } if (item.kind === "gap") { this.#gap = true; continue; @@ -1068,8 +1079,9 @@ export class Consumer { full || ended !== undefined ) { - // What an ordered reader gives up it reports as a gap; a key it skips without one was never a group. - if (!contiguous && !empty && (!decided || head.gap)) { + // What an ordered reader gives up it reports as a gap; a key it skips without one was never a + // group. A gap an empty group carries still marks the next frame, which follows the loss. + if (!contiguous && (decided ? head.gap : !empty)) { this.#lost = true; if (!startup) { console.warn( diff --git a/js/net/src/internal.ts b/js/net/src/internal.ts index 8875cf85b42..60fac91431a 100644 --- a/js/net/src/internal.ts +++ b/js/net/src/internal.ts @@ -474,8 +474,11 @@ export interface ResumeSource { * `dispositions`, a run no copy may still deliver is reported once as a `drop`. */ tryGroup(ordered: boolean, delivered: Delivered, dispositions: boolean): Recv; - /** The next run no copy may still deliver, reported once as a `drop`, without taking a group. */ - tryDrop(delivered: Delivered): (Recv & { kind: "drop" }) | undefined; + /** + * The next run no copy may still deliver, reported once as a `drop`, without taking a group. + * Below `passing`, which a key-order read is about to pass, no copy can deliver one later. + */ + tryDrop(delivered: Delivered, passing?: bigint): (Recv & { kind: "drop" }) | undefined; /** * Whether the reader's bounded `window` has nothing left to deliver, judged by the serving * copy against what it and the logical reader (`delivered`) handed out. A copy that may still diff --git a/js/net/src/ordered.test.ts b/js/net/src/ordered.test.ts index 37b62b03bc1..c2967cd9d06 100644 --- a/js/net/src/ordered.test.ts +++ b/js/net/src/ordered.test.ts @@ -93,6 +93,28 @@ test("nextGroup and tryNextGroup pass the gaps nextItem reports", async () => { expect((await ordered.nextGroup())?.start).toBe(4n); }); +test("keys below where a session's feed starts are no gap unless a fill owed them", () => { + const producer = receivedTrack(); + hooks.startTrack(producer, { start: 10n }); + const ordered = producer.subscribe({ delay: { max: null } }).ordered(); + // Group 0 comes from history, as a fill would bring it; the feed owes nothing below 10. + put(producer, 0n, false); + put(producer, 10n, false); + expect(items(ordered)).toEqual(["group 0", "group 10"]); +}); + +test("a group held behind a gap is not returned once the reader closes", () => { + const producer = new TrackProducer("test"); + const ordered = producer.subscribe({ delay: { max: null } }).ordered(); + put(producer, 0n); + drop(producer, 1n, 2n); + put(producer, 2n); + expect(ordered.tryNextItem()?.group?.start).toBe(0n); + expect(ordered.tryNextItem()).toMatchObject({ kind: "gap", start: 1n, end: 2n }); + ordered.close(); + expect(ordered.tryNextItem()).toBeUndefined(); +}); + test("a key a local track never produced is no gap", () => { const producer = new TrackProducer("test"); const ordered = producer.subscribe({ delay: { max: Duration.secs(1) } }).ordered(); @@ -243,8 +265,8 @@ test("a group held past a gap, under a cap lowered off it, still sees the read e ordered.close(); const ended = await Promise.race([ pending.then( - () => "ended", - () => "ended", + (item) => (item === undefined ? "ended" : `item ${item.kind}`), + (err: Error) => `rejected ${err.message}`, ), sleep(Duration.millis(100)).then(() => "hung"), ]); diff --git a/js/net/src/resume.test.ts b/js/net/src/resume.test.ts index 659d2260e61..854ccc3bd1e 100644 --- a/js/net/src/resume.test.ts +++ b/js/net/src/resume.test.ts @@ -1890,6 +1890,37 @@ test("a routed read right after an update picks its group under the new preferen } }); +// The copy reports the owed key it passed to take the group above, and the reader returns that +// gap before the group, as a direct read of the same track does. +test("a routed ordered read returns the gap its copy passed to take a group", async () => { + const clock = new Manual(); + const installed = clock.install(); + const front = new Front(); + const a = new BroadcastProducer(); + const ta = copy(a); + hooks.receiveTrack(ta.producer); + front.serve(a.consume()); + const ordered = front.consumer + .track("seq") + .subscribe({ delay: { max: Duration.millis(1000) } }) + .ordered(); + try { + ta.write(4n); + expect((await ordered.nextItem())?.group?.start).toBe(4n); + ta.write(6n); + const held = ordered.nextItem(); + expect(await isPending(held)).toBe(true); + await clock.advance(Duration.millis(1000)); + expect(await held).toMatchObject({ kind: "gap", start: 5n, end: 6n }); + expect((await ordered.nextItem())?.group?.start).toBe(6n); + } finally { + ordered.close(); + front.consumer.close(); + a.close(); + installed.close(); + } +}); + for (const resolution of ["arrival", "drop", "other copy", "budget"] as const) { test(`an ordered resumed reader keeps an older copy's owed hole until ${resolution}`, async () => { const clock = new Manual(); diff --git a/js/net/src/resume.ts b/js/net/src/resume.ts index 18980d23acd..09882f1174e 100644 --- a/js/net/src/resume.ts +++ b/js/net/src/resume.ts @@ -898,11 +898,11 @@ class Reader implements ResumeSource { return hooks.exhaustedFor(serving.sub, delivered); } - tryDrop(delivered: Delivered): (Recv & { kind: "drop" }) | undefined { + tryDrop(delivered: Delivered, passing?: bigint): (Recv & { kind: "drop" }) | undefined { this.#delivered = delivered; this.sync(); this.#learnEnd(); - return this.#tryDrop(delivered); + return this.#tryDrop(delivered, passing); } /** @@ -911,7 +911,7 @@ class Reader implements ResumeSource { * is under its bound, so a run there waits until that copy no longer feeds. Mirrors the * Rust `Reader::poll_drop`. */ - #tryDrop(delivered: Delivered): (Recv & { kind: "drop" }) | undefined { + #tryDrop(delivered: Delivered, passing = 0n): (Recv & { kind: "drop" }) | undefined { if (this.#closed) return undefined; // Below what the reader handed out or passed, no copy's drop is reported, so each copy's // record folds there, even one that hands out nothing while the reader returns gaps. @@ -948,7 +948,10 @@ class Reader implements ResumeSource { for (const run of this.#drops) { const end = min(run.end, cursor.end ?? run.end); for (const gap of delivered.gaps(max(run.start, cursor.start), end)) { - const [open] = runGaps(feeding, gap.start, gap.end); + const [open] = + gap.start < passing + ? [{ start: gap.start, end: min(gap.end, passing) }] + : runGaps(feeding, gap.start, gap.end); if (open) { // Report once without marking it delivered: a late fill may still land. this.#drops = removeRun(this.#drops, open.start, open.end); diff --git a/js/net/src/track.ts b/js/net/src/track.ts index 16bf7542c90..a494f7e1b57 100644 --- a/js/net/src/track.ts +++ b/js/net/src/track.ts @@ -984,6 +984,8 @@ let mayLand: (producer: Producer, land: Land) => boolean; // Recompute the producer's aggregates now, for a sink that just became a fetch; assigned in its // static block. let resubscribe: (producer: Producer) => void; +// Where a session's live feed starts owing groups, if known: it owes none below. +let feedFloor: (producer: Producer) => bigint | undefined; let owedRuns: (producer: Producer, start: bigint, end: bigint) => Iterable; // Whether a wire subscription feeds the producer, so it owes every group it has not accounted for. let wireFed: (producer: Producer) => boolean; @@ -1499,10 +1501,14 @@ export class Producer { }; mayLand = (producer, land) => producer.#landable(land) !== undefined; wireFed = (producer) => producer.#wire !== undefined; + feedFloor = (producer) => { + if (!producer.#wire) return undefined; + const feed = producer.#feedStart(); + return feed === "pending" ? producer.#wire.served?.requested : feed; + }; owedRuns = (producer, start, end) => { if (!producer.#wire) return []; - const feed = producer.#feedStart(); - const floor = feed === "pending" ? producer.#wire.served?.requested : feed; + const floor = feedFloor(producer); return producer.#landing({ start: max(start, floor ?? 0n), end, @@ -4427,6 +4433,9 @@ export class Subscriber { }); if (this.#frameGroup) hooks.releaseGroupReader(this.#frameGroup, abort); this.#frameGroup = undefined; + // A group an ordered read holds behind a gap is buffered too, so the read ends without it. + if (this.#items?.held) hooks.releaseGroupReader(this.#items.held, abort); + if (this.#items) this.#items.held = undefined; this.#state.timeline.length = 0; this.#wall.timer?.abort(); this.#wall.timer = undefined; @@ -4718,8 +4727,21 @@ export class Subscriber { this.#queueResumedDrop(recv); continue; } - if (recv.kind === "group") this.#handOut(recv.group.start, ordered); - else if (recv.kind === "idle" && this.#exhausted()) return { kind: "done" }; + if (recv.kind === "group") { + // Passing the keys below it hands them out as far as #delivered knows, so first take what + // the copies gave up there: a session-fed copy reports a key it passed to take this group. + if (ordered) { + const key = recv.group.start; + for ( + let drop = resume.tryDrop(this.#delivered, key); + drop; + drop = resume.tryDrop(this.#delivered, key) + ) { + this.#queueResumedDrop(drop); + } + } + this.#handOut(recv.group.start, ordered); + } else if (recv.kind === "idle" && this.#exhausted()) return { kind: "done" }; return recv; } } @@ -5008,15 +5030,14 @@ export class Subscriber { // The key cursor passes `[start, end)` to hand out the group at `end`. Each key there that the // track owed and no group or drop accounts for was given up, whether the budget convicted it or - // the tail's grace folded it, so it is stale. A wire-fed copy owes every key; a local track only - // what this reader asked a fill for. Below the first group passed is where the read joined, - // which is no gap. + // the tail's grace folded it, so it is stale. A wire-fed copy's feed owes every key from where it + // starts, and a fill what this reader asked it for. Below the first group passed is where the + // read joined, which is no gap. #passOwed(start: bigint, end: bigint, drift: Drift): void { const producer = this.#state.producer; if (start >= end || this.#nextKey === 0n || !this.#dropsSeen || !producer) return; - const owed = wireFed(producer) - ? this.#window.runs(start, end) - : [...intersect(this.#asked, start, end), ...intersect(this.#givenUp, start, end)]; + const owed = [...intersect(this.#asked, start, end), ...intersect(this.#givenUp, start, end)]; + if (wireFed(producer)) owed.push(...this.#window.runs(max(start, feedFloor(producer) ?? 0n), end)); const drops = this.#state.drops; for (const run of owed) { for (const passed of runGaps(drops.overlapping(run.start, run.end), run.start, run.end)) { diff --git a/js/watch/src/audio/replay.ts b/js/watch/src/audio/replay.ts index 51be9e7b6a0..b6b484f9238 100644 --- a/js/watch/src/audio/replay.ts +++ b/js/watch/src/audio/replay.ts @@ -22,7 +22,7 @@ import type * as Catalog from "@moq/hang/catalog"; import * as Container from "@moq/hang/container"; import { type Group, Time, Track } from "@moq/net"; import { Derived, Effect, Signal } from "@moq/signals"; -import { type Delay, STRETCH, Sync } from "../sync"; +import { DELAY_MAX, type Delay, STRETCH, Sync } from "../sync"; import { Backpressure, holeWait } from "./buffer"; import { frameDuration } from "./config"; import { maxDelay as audioMaxDelay, bound, ringHold, target } from "./latency"; @@ -254,12 +254,13 @@ export async function* replay(trace: Arrival[], options: Options): AsyncGenerato : undefined; const audio = sync.track({ target: playout, startup }); signals.cleanup(() => audio.close()); - // The ordered reader waits a hole out as the decoder's does. A replay's ring holds the whole delay: - // it has no output. + // The ordered reader waits a hole out as the decoder's does, the warmup included. A replay's ring + // holds the whole delay: it has no output. + const warmup = Duration.millis(config.warmup ?? 0).min(DELAY_MAX); signals.run((effect) => { const delay = effect.get(sync.out.delay); const max = holeWait(delay, bound({ delay, maxDelay: effect.get(sync.out.maxDelay), stretch })); - ordered.update({ delay: { min: delay, max } }); + ordered.update({ delay: { min: delay.add(warmup), max: max.add(warmup) } }); }); signals.cleanup(() => requests.close()); await settle(); diff --git a/quest/m2/audio-playout/browser-audio-hole-skip.md b/quest/m2/audio-playout/browser-audio-hole-skip.md index 8186963f382..55d07dfeccb 100644 --- a/quest/m2/audio-playout/browser-audio-hole-skip.md +++ b/quest/m2/audio-playout/browser-audio-hole-skip.md @@ -16,10 +16,10 @@ audio hole, through an ordered reader whose budget is the ring's size the container consumer; keep the playhead rule and the separate wait). [moq-dev/moq#9068](https://github.com/moq-dev/moq/pull/9068) moved browser -audio onto the ordered reader: `Ordered.nextGroup` returns a `Gap` for each -group it gives up on, audio reads through a second subscription whose -budget is what the ring holds plus the stretch bound and the warmup, and -the audio container consumer plays each `Gap` as its hole. Firefox's +audio onto the ordered reader: `Ordered.nextItem` returns a gap for each +half-open range of keys it gives up on, audio reads through a second +subscription whose budget is what the ring holds plus the stretch bound and +the warmup, and the audio container consumer plays each gap as its hole. Firefox's `after resume` window stays audible. Its local Chromium measurement, three runs each of the PR, its merge base, @@ -40,7 +40,8 @@ Work: (`js/hang/src/container/consumer.ts`) in ordered mode has nothing that passes an active group that opened but never delivers a frame until the max buffer fills, which #8799's playhead covered. A trace recorded with - `--trace` from a run that starves would replay it. + `--trace` holds only the frames that arrived, so replaying such a group + also needs the trace to record when each group opens. ## Related diff --git a/test/audio-quality/budgets.json b/test/audio-quality/budgets.json index d3ab793c3d8..494691f7145 100644 --- a/test/audio-quality/budgets.json +++ b/test/audio-quality/budgets.json @@ -1,5 +1,5 @@ { - "note": "The browser rows are measured on the nightly runner (ubuntu-24.04-arm, headless Chromium, seed 7, 60 s a row), from the audio-quality-run artifacts of the seven scheduled Nightly runs on main from 2026-10-29 to 2026-11-04 (40885347517, 41065371094, 41204380716, 41313466339, 41483654426, 41656613559, 41852517544), the first after a fresh subscriber stopped receiving the relay's cached history. The six AAC rows other than congestion are measured the same way from the seven runs from 2026-11-05 to 2026-11-11 (42050683248, 42236107954, 42377867523, 42487375545, 42659882487, 42842827718, 43041909115), the first after the TS importer published each PES as one group; the first four predate the browser's time stretch, and the six rows keep the four provisional ceilings set below from 2026-11-09 and 2026-11-10. Each ceiling is the worst of its seven nights times 1.25, plus one runner hiccup, rounded up to two significant figures. The hiccup is sized from the single gaps the 2026-10-08 night put on otherwise clean rows, the fixed-250 control among them: 250 underruns/min, 700 gap ms/min, 3.3 skips/min, 280 dropped ms/min (both sized on the playhead's skip-ahead inference, and now applied to player_skips_per_min and trimmed_ms_per_min), 0.01 stalled, 0.015 silence, and one 20 ms bucket of target. Budgeted this way, every night passes when it is held out of its row's measurement except one, and that row's own ceiling includes it: the 2026-11-03 Opus bursty row raised its target to 300 ms 2.6 s in and held it for one 20 s half-life before settling at 180. Such startup holds, Opus near-zero's 100 ms on 2026-10-30 and 10-31 among them, are budgeted as measured. These ceilings record today's player as the runner hears it, not target audio quality. To re-measure, download the same artifact from the latest scheduled nightlies (`gh run download -n audio-quality-run`), which keep every run, and apply the same rule. On 2026-11-10 the inferred skip_aheads and discarded_ms keys were dropped, since they read a time stretch's catch-up as dropped audio, and every browser row gained player_skips_per_min, trimmed_ms_per_min, and av_lag_ms p50 and p95, by the same rule from the only two scheduled nights on main with today's browser player and its trim counter, 2026-11-09 and 2026-11-10 (42659882487, 42842827718). A lag is signed, so its ceiling is the worst night plus a quarter of its size plus one 20 ms bucket. These four keys are provisional until seven nights with the stretch model re-measure every row. The grade follows the model: audio rests on the shared clock, trails it through a stall, and catches up after. When a change moves a row, a steady-state lag (av_lag_ms p50) that rises, or audio the player trimmed, is a regression to fix rather than budget; a p95 lag that rises through a stall, or an underrun count that moves, is re-measured in. No ceiling is fixed at zero underruns or zero stalls; a replay row's is exactly what it measured. The replay rows are deterministic, so their ceilings are exactly what they measured, through the end of each recording, with no headroom: any regression fails them, and an improvement should be tightened in. They were last re-measured on 2026-10-22 using version 3 traces with encoded frame durations: AAC-LC uses its fixed 1024 samples, and relay-mic retains Opus packet TOC durations. relay-mic was re-recorded on 2026-11-03 from a real microphone, Chrome 156 on a MacBook Air publishing its built-in microphone through the public relay, recorded by headless Chromium on a Linux host (35 s, minimum RTT 2 ms), which raised its target ceiling from 60 to 80 ms and its silence from 0 to 0.001 as measured. The recording path itself has no added RTT. relay-mic-rtt40 is the 2026-11-03 Chrome row at 40 ms of added RTT on that laptop (180 s, minimum RTT 47 ms), kept as the baseline time stretch improves on; like every replay row, its player_underruns_per_min ceiling is what it measures, not a fixed zero. player_underruns_per_min, the player's own counter that its stats panel shows, is budgeted on the replay rows only; it counts the run-dry re-stalls the tap files as stalled time. On 2026-11-07, after the ordered read stopped delivering groups below its cursor (#8071) and took Rust's hole and age bounds (#8218), relay-bbb was re-measured at 16.1 player underruns/min, 0.025 stalled and 0.02 silence, and relay-mic-rtt40 at 8.2, its discarded audio at 70.9 ms/min and its target p95 at 320 ms rather than 780, since the stale backlog it never played no longer reaches the estimator; neither row lost audio the previous player heard. On 2026-11-08 the player began time-stretching live playback with NetEq's accelerate, deciding on the ring's depth right after each arrival and never expanding, and every replay row was re-measured with it, the browser rows left to the nightly runner. Each row's av_lag_ms, how far the playhead trails the shared clock video plays from, is what it measured: the ring rests one frame ahead of the newest arrival's playout, as the trim it replaces left it, so audio leads the clock by 19 to 23 ms at p50. Against the trim, the A/V lag p50 fell from 0.7, -17.5, -21.5, -18.2 and -15.6 ms to -22.4 on bursty-aac, -22.2 on local-aac, -22.7 on relay-bbb, -19 on relay-mic and -20.1 on relay-mic-rtt40, and its p95 fell on every row, most on relay-bbb (10.5 to -4.2) and relay-mic-rtt40 (-0.9 to -13.4). Underruns stayed where the trim had them, as the latency they would cost is not spent: player_underruns_per_min held at 4.4, 12.1, 16.1 and 6.1 and rose from 8.2 to 10.6 on relay-mic-rtt40, and relay-mic's tap now files 2 short quanta a minute, 2 ms of missing audio, where it filed none. What the stretch buys is the audio the trim dropped: discarded_ms_per_min fell from 87.8 to 0 on relay-bbb and from 127.5 to 100.6 on local-aac, whose remainder drops nothing: two receive stalls 14 and 15.3 s in leave audio 159 and 132 ms behind the clock, and the fast accelerate brings it back within half a second. player_skips_per_min and trimmed_ms_per_min, the ring's own count of re-anchors that dropped buffered audio and the media they dropped, are budgeted beside it, at 0 on every recorded row. relay-mic-stall, added 2026-11-10, is relay-mic with nothing arriving from 15 s to 16.5 s and the held frames then trickling in at twice real time until 18 s; today's player trims 2152.5 ms/min of it and its target p95 rises to 1540 ms. Once durations became whole nanoseconds, relay-bbb's delay, 200 ms plus one 1024-sample AAC frame, rounds up by a fraction of a sample, so its ring holds one more sample (23 µs) and its A/V lag p50 measures -22.6 rather than -22.7. Neither replay calibration changed the browser or native ceilings. bursty-aac is the 2026-10-18 AAC bursty isolated capture, recorded with the observer subscribed at the decoder's 2 s budget, so it holds every group the player saw. The native rows are provisional: measured on a loaded developer host (x86_64 Linux, the private PulseAudio null sink, seed 7, 60 s a row) on 2026-10-17, three runs of every row from the debug build nightly uses plus three more of the AAC rows from a release build, which played alike. Each ceiling is the worst clean run times 1.25, plus one native hiccup sized from the unimpaired Opus row's worst run (20 underruns/min, 50 gap ms/min, 2.2 skips/min, 110 discarded ms/min, 0.01 stalled, 0.005 silence, one 20 ms bucket of target), rounded up to two significant figures. On 2026-11-10, after native playback began reporting its A/V lag (#8361), the native rows' player_skips_per_min, trimmed_ms_per_min, and av_lag_ms p50 and p95, and every key of the native and browser congestion rows, were measured by the same rules from three runs of each on a loaded developer host (x86_64 Linux, the debug build, seed 7, 60 s a row), with no void; native audio rests 9 to 95 ms behind its clock at p50. These are provisional until the stretch model's nightly re-measure, which also moves the browser congestion rows onto the runner. On the 2026-10-17 host the null sink's clock ran about 150 ppm slow against the monotonic clock, read within 5 ms at p95 per sample, and its output latency sat between 14 and 28 ms. Five of the 36 AAC rows (none of the 18 Opus rows) voided on the clock: the device stopped pulling for about two seconds mid-row, sometimes after a backend error and a stream restart, which is a native playback defect rather than noise, and the ceilings exclude those runs. Re-measure from the nightly runner's artifacts once it has a week of native rows. On 2026-11-11 every player began following one stretch rule on the shared clock: it slows down below its target, speeds up above it, and skips only past its bound, which in the browser is the subscription's max delay. Every replay row was re-measured with it, the browser and native rows left to the nightly runner. Audio now rests on the clock rather than one frame ahead of it, so the A/V lag p50 rose from about -20 ms to 0.4 ms on relay-bbb, 1.1 on relay-mic, 1.2 on relay-mic-rtt40 and 1.8 on local-aac. Its p95 rose on every row, since audio that falls behind is now caught up by speeding up rather than trimmed: the shared clock steps forward as its reference converges through a tune-in backlog, and again when a target falls, and audio follows at the accelerate's pace, which on the replay's constant tone is one 2.5 ms period a window, slower than on speech. bursty-aac rests 5 ms behind its clock, so its p50 of 10.4 ms is mostly its catch-ups, and relay-mic-stall's p50 of 66.1 ms is the catch-up after its target falls from 1540 to 80 ms, which outlasts half the row. In exchange nothing is trimmed: relay-mic-stall's trimmed_ms_per_min fell from 2152.5 to 0, its skips from 6.1 to 0, and its underruns from 24.2 to 0 a minute, and player_underruns_per_min fell from 12.1 to 4 on local-aac, 16.1 to 0 on relay-bbb, 6.1 to 0 on relay-mic, 10.6 to 2.7 on relay-mic-rtt40 and 6.1 to 4 on relay-mic-stall, holding at 4.4 on bursty-aac. The tap now files 3.3 to 6.1 short quanta a minute on the AAC rows, under 0.3 ms of missing audio, where it filed none. To deliver the audio a stall delays, the container consumer now waits and skips at the subscription's max delay, as native already does, rather than at the delay plus lookahead. relay-mic-rtt40's join backlog arrives reordered, so the consumer now waits on its holes and the estimator observes the frames that fill them, up to 775 ms late, and its target p95 returns from 320 to 780 ms, held for one half-life after the join. Later on 2026-11-11 audio began skipping as far as the shared clock's reference moves earlier, once those moves add up to one stretch window and only as far as it holds audio past its target, rather than speeding through them, and every replay row was re-measured. The tune-in backlog's jumps now land before the graded window, so the A/V lag p95 fell from 453.1 to 2.1 ms on relay-bbb (its p50 from 0.4 to -1.3), 743.7 to 1.9 on relay-mic-rtt40, whose p50 fell from 1.2 to 0.4 and its tap's missing audio rose from 0.6 to 0.9 ms a minute, since a jump past what is decoded skips the rest once it lands,, 335.5 to 39.2 on local-aac and 88.6 to 0.3 on relay-mic, and the p50 from 66.1 to 25.3 on relay-mic-stall, with nothing trimmed in any graded window. The tap's underruns fell from 6.1 to 2 a minute on local-aac and 6.1 to 0 on relay-bbb; local-aac's silence rose from 0.001 to 0.002. Later on 2026-11-11 the container consumer began waiting on a missing group only for the delay plus the lookahead, while still delivering groups that arrived until they age past the max delay, and every replay row was re-measured. relay-mic-rtt40's target p95 fell from 780 back to 320 ms, since the holes in its reordered join backlog no longer delay the frames behind them; its tap's missing audio rose from 0.9 to 1.1 ms a minute and its A/V lag p50 and p95 from 0.4 and 1.9 to 0.7 and 2.4 ms. bursty-aac's silence rose from 0.007 to 0.009 and its A/V lag p95 fell from 162.1 to 156.3 ms, and relay-bbb's lag p50 and p95 moved from -1.3 and 2.1 to -1.2 and 2.2 ms. relay-mic-stall did not move. Also on 2026-11-11 the stretch became a player setting, 2 s by default, and the audio subscription's max delay became the delay plus it rather than the 2 s constant, so the container consumer delivers a late group that much longer before it ages out, and every replay row was re-measured: only relay-mic moved, its A/V lag p50 and p95 from 0.3 to 1.6 ms, under the 2.5 ms pitch period the stretch can move it by. Holding the constant max delay with the new bound reproduces the old values exactly. On 2026-11-12 the replays stopped playing a constant and began playing a seeded speech-like signal (syllables gliding a 90 to 220 Hz fundamental, with pauses held above the silence classifier), since the stretch's pitch search found only its shortest period in a constant, and the browser ring stopped zero-filling a hole of up to a millisecond and two samples between frames, as native stopped writing silence for one: the recorded AAC timestamps land up to 2.5 samples either side of a 1024-sample boundary, and on speech the 2-sample holes this filled ended 119.1 quanta a minute short on bursty-aac. Every replay row was re-measured. The tap's underruns fell to 0 on bursty-aac (from 3.3) and local-aac (from 2), and relay-mic-rtt40's missing audio from 1.1 to 0.3 ms a minute while its player underruns rose from 2.7 to 3.1. The A/V lag p95 fell from 156.3 to 104.8 ms on bursty-aac, 39.2 to 15.1 on local-aac, 2.2 to 1.4 on relay-bbb and 501.8 to 484.9 on relay-mic-stall, whose p50 fell from 25.3 to 1.1, and rose from 1.6 to 3.4 on relay-mic and 2.4 to 3.5 on relay-mic-rtt40. Where audio rests moved within one speech pitch period, which is as close as one stretch seam can steer it: the p50 is 11 ms on bursty-aac (from 10.4), -4.2 on relay-bbb (from -1.2), 1.1 on relay-mic (from 1.6), 0.9 on relay-mic-rtt40 (from 0.7) and 1.7 on local-aac (from 1.8). On 2026-11-13 the stretch default fell from 2 s to 200 ms and audio trailing the clock past it began skipping onto the clock rather than back to the bound, as video skips, with the audio subscription still reaching 2 s past the delay; every replay row was re-measured. A target fall past 200 ms now costs one skip rather than seconds of catch-up, and so does a trail past it, and a rise past it pads silence until the clock arrives rather than slowing down: relay-mic-stall skips the 1.46 s it trails after the outage and its 1540 to 1020 and 1020 to 80 ms falls, and pads the 0.5 s its 60 to 1540 ms rise leaves it ahead, where it slowed down for 4 s, so it trims 4678.2 ms a minute where it trimmed none and its stalled share rose from 0.05 to 0.067 and silence from 0.049 to 0.085. The frames it holds through the outage then trickle in at twice real time, so its low buffer slows it to 154 ms behind the clock, where it had sat ahead of it: its A/V lag p95 fell from 484.9 to 118.6 ms and its p50 rose from 1.1 to 2.2. relay-mic-rtt40 skips its 320 to 80 ms fall, 0.3 skips and 83.3 trimmed ms a minute, its p95 from 3.5 to 2.9 ms. bursty-aac skips a 225 ms trail 6 s in, 1.1 skips and 312.7 trimmed ms a minute, its p95 from 102.7 to 49.2 ms and p50 from 11 to 10. relay-mic trims nothing, but its tune-in's skips land on the clock rather than at the bound, which moves where it rests within a pitch period: its p50 from 1.1 to 2.2 ms and p95 from 3.4 to 4.5. Trimming at a target fall or a trail past 200 ms is the rule, not a regression. Also on 2026-11-13, for the same change, the congestion rows' trimmed_ms_per_min ceilings were raised by the same rule from two runs of each on a loaded developer host (x86_64 Linux, the debug build, seed 7, 60 s a row): to 3800 on chromium AAC (worst 2740.3 ms/min), 3700 on chromium Opus (2697.2), 3900 on native AAC (2996.9) and 4600 on native Opus (3532.3), whose player_skips_per_min rose to 15 (9.8). The trim is the outage's audio skipped onto the clock rather than played seconds late: against main on the same host, chromium's A/V lag p95 fell from 1396.8 to 61.6 ms on AAC and 1424.8 to 64.3 on Opus, and native's from 1246.3 to 116.7 and 826.9 to 117.5. These four ceilings are provisional until the nightly re-measures the congestion rows. Also on 2026-11-13, the estimator began counting one outage, the intervals its stalled frames span and the empty ones before them, as one observation, and every replay row was re-measured on top of the snap: only relay-mic-stall moved. Its single stall no longer raises the target, so its target p95 fell from 1540 to 80 ms and the trail the outage leaves is skipped onto the clock at once rather than through the target's falls: 2 skips a minute where it took 6.1, 5122.3 trimmed ms a minute where it trimmed 4678.2, and its A/V lag p95 from 118.6 to 19.7 ms. With 80 ms of buffer rather than 1540, more of the outage plays as silence: its stalled share rose from 0.067 to 0.092 and silence from 0.085 to 0.092. On 2026-11-14 every player began following the clock by its lag alone: a continuous WSOLA time stretch for any content, at a rate proportional to the lag and capped at 10%, which leaves a lag within half a 10 ms hop alone, and slows down while the audio received ahead of the playhead is about to run out, replacing NetEq's buffer-level decision and pitch-period splices. Every replay row was re-measured. Audio now rests within half a hop of the clock rather than within a pitch period: the A/V lag p50 fell from 10 to 0.2 ms on bursty-aac, whose p95 fell from 49.2 to 0.2, from 1.7 to -1.3 on local-aac, 2.2 to 1.8 on relay-mic and 0.9 to 0.6 on relay-mic-rtt40, and moved from -2 to 2.7 on relay-bbb and 2.2 to 3.1 on relay-mic-stall, each within the half hop the rule leaves alone. The p95 rose from 3.6 to 6.2 ms on relay-bbb, 4.5 to 6.9 on relay-mic, 2.9 to 6.9 on relay-mic-rtt40 and 19.7 to 32.1 on relay-mic-stall, and fell from 15.1 to 14.3 on local-aac: a lag under a hop is corrected only once its pace adds up to one. player_underruns_per_min rose from 4.4 to 6.6 on bursty-aac and 4 to 8.1 on local-aac, whose recorded outages outlast what slowing down at 10% bridges, and fell from 3.1 to 1 on relay-mic-rtt40, whose tap's underruns fell from 0.7 to 0.3 a minute; bursty-aac's silence rose from 0.007 to 0.008. Nothing more is trimmed on any row. The browser and native rows were measured on a loaded developer host (x86_64 Linux, the debug build, seed 7, 60 s a row) against main the same day and left to the nightly runner: every browser row's A/V lag p50 now sits between 27 and 39 ms, where the fixed-250 control does on that host, where wide and bursty sat up to 58 ms behind, and every native row's within 15 ms of the clock. Also on 2026-11-14 the estimator stopped folding the intervals a subscription's join spans, those holding a frame due before its backlog finished arriving, and every replay row was re-measured: only relay-mic and relay-mic-stall moved. Their first frame arrives slower than the path after it, so their first interval folds nothing and the target leaves the prior 500 ms later, which moves where audio rests within the half hop the rule leaves alone: relay-mic's A/V lag p50 from 1.8 to -0.3 ms and p95 from 6.9 to 9, and relay-mic-stall's p50 from 3.1 to 1.7. relay-mic-rtt40 did not move: the browser consumer closes its join's stale groups below the cursor unread, so the estimator never sees when that backlog ended, and its target p95 held at 320 ms. Later on 2026-11-14 both container consumers began reporting when each group they close unread arrived, if it is at or below the publisher's largest group as the subscription began, which extends a join still open. On 2026-11-15 the traces gained that largest group (version 4), so the replay's consumer learns it as a wire subscriber does, and relay-mic-rtt40 was re-measured: its target p95 fell from 320 to 120 ms, underruns per minute rose from 0.3 to 0.7, player skips per minute fell from 0.3 to 0, trimmed ms per minute from 83 to 0, A/V lag p50 rose from 0.6 to 2.3 ms and p95 from 6.9 to 8.6, the trade of reporting the join's backlog. No other replay row moved. On 2026-11-17 the browser player began reading audio through the ordered reader, which waits for a hole as long as the ring could still play it and reports each group it gives up on as a gap, and the replay dropped the trace's largest group: a second subscription now observes every arrival for the estimate, the join's backlog included. Every replay row was re-measured. bursty-aac's player underruns per minute fell from 6.6 to 4.4 and silence share from 0.008 to 0.007; audio rests at 0.1 ms until a stall at 19.5 s, from which the stretch catches up to 4.2 ms behind the clock, inside the half hop it leaves alone, so its A/V lag p50 and p95 rose from 0.2 to 4.2 ms. relay-bbb's A/V lag p50 fell from 2.7 to 1.4 ms and p95 rose from 6.2 to 7.6. relay-mic-rtt40's underruns per minute fell from 0.7 to 0.3 (player underruns the same), underrun ms per minute from 0.8 to 0.2, A/V lag p50 from 2.3 to 0.6 ms, and p95 rose from 8.6 to 9.1, its target p95 holding at 120 ms. No other replay row moved.", + "note": "The browser rows are measured on the nightly runner (ubuntu-24.04-arm, headless Chromium, seed 7, 60 s a row), from the audio-quality-run artifacts of the seven scheduled Nightly runs on main from 2026-10-29 to 2026-11-04 (40885347517, 41065371094, 41204380716, 41313466339, 41483654426, 41656613559, 41852517544), the first after a fresh subscriber stopped receiving the relay's cached history. The six AAC rows other than congestion are measured the same way from the seven runs from 2026-11-05 to 2026-11-11 (42050683248, 42236107954, 42377867523, 42487375545, 42659882487, 42842827718, 43041909115), the first after the TS importer published each PES as one group; the first four predate the browser's time stretch, and the six rows keep the four provisional ceilings set below from 2026-11-09 and 2026-11-10. Each ceiling is the worst of its seven nights times 1.25, plus one runner hiccup, rounded up to two significant figures. The hiccup is sized from the single gaps the 2026-10-08 night put on otherwise clean rows, the fixed-250 control among them: 250 underruns/min, 700 gap ms/min, 3.3 skips/min, 280 dropped ms/min (both sized on the playhead's skip-ahead inference, and now applied to player_skips_per_min and trimmed_ms_per_min), 0.01 stalled, 0.015 silence, and one 20 ms bucket of target. Budgeted this way, every night passes when it is held out of its row's measurement except one, and that row's own ceiling includes it: the 2026-11-03 Opus bursty row raised its target to 300 ms 2.6 s in and held it for one 20 s half-life before settling at 180. Such startup holds, Opus near-zero's 100 ms on 2026-10-30 and 10-31 among them, are budgeted as measured. These ceilings record today's player as the runner hears it, not target audio quality. To re-measure, download the same artifact from the latest scheduled nightlies (`gh run download -n audio-quality-run`), which keep every run, and apply the same rule. On 2026-11-10 the inferred skip_aheads and discarded_ms keys were dropped, since they read a time stretch's catch-up as dropped audio, and every browser row gained player_skips_per_min, trimmed_ms_per_min, and av_lag_ms p50 and p95, by the same rule from the only two scheduled nights on main with today's browser player and its trim counter, 2026-11-09 and 2026-11-10 (42659882487, 42842827718). A lag is signed, so its ceiling is the worst night plus a quarter of its size plus one 20 ms bucket. These four keys are provisional until seven nights with the stretch model re-measure every row. The grade follows the model: audio rests on the shared clock, trails it through a stall, and catches up after. When a change moves a row, a steady-state lag (av_lag_ms p50) that rises, or audio the player trimmed, is a regression to fix rather than budget; a p95 lag that rises through a stall, or an underrun count that moves, is re-measured in. No ceiling is fixed at zero underruns or zero stalls; a replay row's is exactly what it measured. The replay rows are deterministic, so their ceilings are exactly what they measured, through the end of each recording, with no headroom: any regression fails them, and an improvement should be tightened in. They were last re-measured on 2026-10-22 using version 3 traces with encoded frame durations: AAC-LC uses its fixed 1024 samples, and relay-mic retains Opus packet TOC durations. relay-mic was re-recorded on 2026-11-03 from a real microphone, Chrome 156 on a MacBook Air publishing its built-in microphone through the public relay, recorded by headless Chromium on a Linux host (35 s, minimum RTT 2 ms), which raised its target ceiling from 60 to 80 ms and its silence from 0 to 0.001 as measured. The recording path itself has no added RTT. relay-mic-rtt40 is the 2026-11-03 Chrome row at 40 ms of added RTT on that laptop (180 s, minimum RTT 47 ms), kept as the baseline time stretch improves on; like every replay row, its player_underruns_per_min ceiling is what it measures, not a fixed zero. player_underruns_per_min, the player's own counter that its stats panel shows, is budgeted on the replay rows only; it counts the run-dry re-stalls the tap files as stalled time. On 2026-11-07, after the ordered read stopped delivering groups below its cursor (#8071) and took Rust's hole and age bounds (#8218), relay-bbb was re-measured at 16.1 player underruns/min, 0.025 stalled and 0.02 silence, and relay-mic-rtt40 at 8.2, its discarded audio at 70.9 ms/min and its target p95 at 320 ms rather than 780, since the stale backlog it never played no longer reaches the estimator; neither row lost audio the previous player heard. On 2026-11-08 the player began time-stretching live playback with NetEq's accelerate, deciding on the ring's depth right after each arrival and never expanding, and every replay row was re-measured with it, the browser rows left to the nightly runner. Each row's av_lag_ms, how far the playhead trails the shared clock video plays from, is what it measured: the ring rests one frame ahead of the newest arrival's playout, as the trim it replaces left it, so audio leads the clock by 19 to 23 ms at p50. Against the trim, the A/V lag p50 fell from 0.7, -17.5, -21.5, -18.2 and -15.6 ms to -22.4 on bursty-aac, -22.2 on local-aac, -22.7 on relay-bbb, -19 on relay-mic and -20.1 on relay-mic-rtt40, and its p95 fell on every row, most on relay-bbb (10.5 to -4.2) and relay-mic-rtt40 (-0.9 to -13.4). Underruns stayed where the trim had them, as the latency they would cost is not spent: player_underruns_per_min held at 4.4, 12.1, 16.1 and 6.1 and rose from 8.2 to 10.6 on relay-mic-rtt40, and relay-mic's tap now files 2 short quanta a minute, 2 ms of missing audio, where it filed none. What the stretch buys is the audio the trim dropped: discarded_ms_per_min fell from 87.8 to 0 on relay-bbb and from 127.5 to 100.6 on local-aac, whose remainder drops nothing: two receive stalls 14 and 15.3 s in leave audio 159 and 132 ms behind the clock, and the fast accelerate brings it back within half a second. player_skips_per_min and trimmed_ms_per_min, the ring's own count of re-anchors that dropped buffered audio and the media they dropped, are budgeted beside it, at 0 on every recorded row. relay-mic-stall, added 2026-11-10, is relay-mic with nothing arriving from 15 s to 16.5 s and the held frames then trickling in at twice real time until 18 s; today's player trims 2152.5 ms/min of it and its target p95 rises to 1540 ms. Once durations became whole nanoseconds, relay-bbb's delay, 200 ms plus one 1024-sample AAC frame, rounds up by a fraction of a sample, so its ring holds one more sample (23 µs) and its A/V lag p50 measures -22.6 rather than -22.7. Neither replay calibration changed the browser or native ceilings. bursty-aac is the 2026-10-18 AAC bursty isolated capture, recorded with the observer subscribed at the decoder's 2 s budget, so it holds every group the player saw. The native rows are provisional: measured on a loaded developer host (x86_64 Linux, the private PulseAudio null sink, seed 7, 60 s a row) on 2026-10-17, three runs of every row from the debug build nightly uses plus three more of the AAC rows from a release build, which played alike. Each ceiling is the worst clean run times 1.25, plus one native hiccup sized from the unimpaired Opus row's worst run (20 underruns/min, 50 gap ms/min, 2.2 skips/min, 110 discarded ms/min, 0.01 stalled, 0.005 silence, one 20 ms bucket of target), rounded up to two significant figures. On 2026-11-10, after native playback began reporting its A/V lag (#8361), the native rows' player_skips_per_min, trimmed_ms_per_min, and av_lag_ms p50 and p95, and every key of the native and browser congestion rows, were measured by the same rules from three runs of each on a loaded developer host (x86_64 Linux, the debug build, seed 7, 60 s a row), with no void; native audio rests 9 to 95 ms behind its clock at p50. These are provisional until the stretch model's nightly re-measure, which also moves the browser congestion rows onto the runner. On the 2026-10-17 host the null sink's clock ran about 150 ppm slow against the monotonic clock, read within 5 ms at p95 per sample, and its output latency sat between 14 and 28 ms. Five of the 36 AAC rows (none of the 18 Opus rows) voided on the clock: the device stopped pulling for about two seconds mid-row, sometimes after a backend error and a stream restart, which is a native playback defect rather than noise, and the ceilings exclude those runs. Re-measure from the nightly runner's artifacts once it has a week of native rows. On 2026-11-11 every player began following one stretch rule on the shared clock: it slows down below its target, speeds up above it, and skips only past its bound, which in the browser is the subscription's max delay. Every replay row was re-measured with it, the browser and native rows left to the nightly runner. Audio now rests on the clock rather than one frame ahead of it, so the A/V lag p50 rose from about -20 ms to 0.4 ms on relay-bbb, 1.1 on relay-mic, 1.2 on relay-mic-rtt40 and 1.8 on local-aac. Its p95 rose on every row, since audio that falls behind is now caught up by speeding up rather than trimmed: the shared clock steps forward as its reference converges through a tune-in backlog, and again when a target falls, and audio follows at the accelerate's pace, which on the replay's constant tone is one 2.5 ms period a window, slower than on speech. bursty-aac rests 5 ms behind its clock, so its p50 of 10.4 ms is mostly its catch-ups, and relay-mic-stall's p50 of 66.1 ms is the catch-up after its target falls from 1540 to 80 ms, which outlasts half the row. In exchange nothing is trimmed: relay-mic-stall's trimmed_ms_per_min fell from 2152.5 to 0, its skips from 6.1 to 0, and its underruns from 24.2 to 0 a minute, and player_underruns_per_min fell from 12.1 to 4 on local-aac, 16.1 to 0 on relay-bbb, 6.1 to 0 on relay-mic, 10.6 to 2.7 on relay-mic-rtt40 and 6.1 to 4 on relay-mic-stall, holding at 4.4 on bursty-aac. The tap now files 3.3 to 6.1 short quanta a minute on the AAC rows, under 0.3 ms of missing audio, where it filed none. To deliver the audio a stall delays, the container consumer now waits and skips at the subscription's max delay, as native already does, rather than at the delay plus lookahead. relay-mic-rtt40's join backlog arrives reordered, so the consumer now waits on its holes and the estimator observes the frames that fill them, up to 775 ms late, and its target p95 returns from 320 to 780 ms, held for one half-life after the join. Later on 2026-11-11 audio began skipping as far as the shared clock's reference moves earlier, once those moves add up to one stretch window and only as far as it holds audio past its target, rather than speeding through them, and every replay row was re-measured. The tune-in backlog's jumps now land before the graded window, so the A/V lag p95 fell from 453.1 to 2.1 ms on relay-bbb (its p50 from 0.4 to -1.3), 743.7 to 1.9 on relay-mic-rtt40, whose p50 fell from 1.2 to 0.4 and its tap's missing audio rose from 0.6 to 0.9 ms a minute, since a jump past what is decoded skips the rest once it lands,, 335.5 to 39.2 on local-aac and 88.6 to 0.3 on relay-mic, and the p50 from 66.1 to 25.3 on relay-mic-stall, with nothing trimmed in any graded window. The tap's underruns fell from 6.1 to 2 a minute on local-aac and 6.1 to 0 on relay-bbb; local-aac's silence rose from 0.001 to 0.002. Later on 2026-11-11 the container consumer began waiting on a missing group only for the delay plus the lookahead, while still delivering groups that arrived until they age past the max delay, and every replay row was re-measured. relay-mic-rtt40's target p95 fell from 780 back to 320 ms, since the holes in its reordered join backlog no longer delay the frames behind them; its tap's missing audio rose from 0.9 to 1.1 ms a minute and its A/V lag p50 and p95 from 0.4 and 1.9 to 0.7 and 2.4 ms. bursty-aac's silence rose from 0.007 to 0.009 and its A/V lag p95 fell from 162.1 to 156.3 ms, and relay-bbb's lag p50 and p95 moved from -1.3 and 2.1 to -1.2 and 2.2 ms. relay-mic-stall did not move. Also on 2026-11-11 the stretch became a player setting, 2 s by default, and the audio subscription's max delay became the delay plus it rather than the 2 s constant, so the container consumer delivers a late group that much longer before it ages out, and every replay row was re-measured: only relay-mic moved, its A/V lag p50 and p95 from 0.3 to 1.6 ms, under the 2.5 ms pitch period the stretch can move it by. Holding the constant max delay with the new bound reproduces the old values exactly. On 2026-11-12 the replays stopped playing a constant and began playing a seeded speech-like signal (syllables gliding a 90 to 220 Hz fundamental, with pauses held above the silence classifier), since the stretch's pitch search found only its shortest period in a constant, and the browser ring stopped zero-filling a hole of up to a millisecond and two samples between frames, as native stopped writing silence for one: the recorded AAC timestamps land up to 2.5 samples either side of a 1024-sample boundary, and on speech the 2-sample holes this filled ended 119.1 quanta a minute short on bursty-aac. Every replay row was re-measured. The tap's underruns fell to 0 on bursty-aac (from 3.3) and local-aac (from 2), and relay-mic-rtt40's missing audio from 1.1 to 0.3 ms a minute while its player underruns rose from 2.7 to 3.1. The A/V lag p95 fell from 156.3 to 104.8 ms on bursty-aac, 39.2 to 15.1 on local-aac, 2.2 to 1.4 on relay-bbb and 501.8 to 484.9 on relay-mic-stall, whose p50 fell from 25.3 to 1.1, and rose from 1.6 to 3.4 on relay-mic and 2.4 to 3.5 on relay-mic-rtt40. Where audio rests moved within one speech pitch period, which is as close as one stretch seam can steer it: the p50 is 11 ms on bursty-aac (from 10.4), -4.2 on relay-bbb (from -1.2), 1.1 on relay-mic (from 1.6), 0.9 on relay-mic-rtt40 (from 0.7) and 1.7 on local-aac (from 1.8). On 2026-11-13 the stretch default fell from 2 s to 200 ms and audio trailing the clock past it began skipping onto the clock rather than back to the bound, as video skips, with the audio subscription still reaching 2 s past the delay; every replay row was re-measured. A target fall past 200 ms now costs one skip rather than seconds of catch-up, and so does a trail past it, and a rise past it pads silence until the clock arrives rather than slowing down: relay-mic-stall skips the 1.46 s it trails after the outage and its 1540 to 1020 and 1020 to 80 ms falls, and pads the 0.5 s its 60 to 1540 ms rise leaves it ahead, where it slowed down for 4 s, so it trims 4678.2 ms a minute where it trimmed none and its stalled share rose from 0.05 to 0.067 and silence from 0.049 to 0.085. The frames it holds through the outage then trickle in at twice real time, so its low buffer slows it to 154 ms behind the clock, where it had sat ahead of it: its A/V lag p95 fell from 484.9 to 118.6 ms and its p50 rose from 1.1 to 2.2. relay-mic-rtt40 skips its 320 to 80 ms fall, 0.3 skips and 83.3 trimmed ms a minute, its p95 from 3.5 to 2.9 ms. bursty-aac skips a 225 ms trail 6 s in, 1.1 skips and 312.7 trimmed ms a minute, its p95 from 102.7 to 49.2 ms and p50 from 11 to 10. relay-mic trims nothing, but its tune-in's skips land on the clock rather than at the bound, which moves where it rests within a pitch period: its p50 from 1.1 to 2.2 ms and p95 from 3.4 to 4.5. Trimming at a target fall or a trail past 200 ms is the rule, not a regression. Also on 2026-11-13, for the same change, the congestion rows' trimmed_ms_per_min ceilings were raised by the same rule from two runs of each on a loaded developer host (x86_64 Linux, the debug build, seed 7, 60 s a row): to 3800 on chromium AAC (worst 2740.3 ms/min), 3700 on chromium Opus (2697.2), 3900 on native AAC (2996.9) and 4600 on native Opus (3532.3), whose player_skips_per_min rose to 15 (9.8). The trim is the outage's audio skipped onto the clock rather than played seconds late: against main on the same host, chromium's A/V lag p95 fell from 1396.8 to 61.6 ms on AAC and 1424.8 to 64.3 on Opus, and native's from 1246.3 to 116.7 and 826.9 to 117.5. These four ceilings are provisional until the nightly re-measures the congestion rows. Also on 2026-11-13, the estimator began counting one outage, the intervals its stalled frames span and the empty ones before them, as one observation, and every replay row was re-measured on top of the snap: only relay-mic-stall moved. Its single stall no longer raises the target, so its target p95 fell from 1540 to 80 ms and the trail the outage leaves is skipped onto the clock at once rather than through the target's falls: 2 skips a minute where it took 6.1, 5122.3 trimmed ms a minute where it trimmed 4678.2, and its A/V lag p95 from 118.6 to 19.7 ms. With 80 ms of buffer rather than 1540, more of the outage plays as silence: its stalled share rose from 0.067 to 0.092 and silence from 0.085 to 0.092. On 2026-11-14 every player began following the clock by its lag alone: a continuous WSOLA time stretch for any content, at a rate proportional to the lag and capped at 10%, which leaves a lag within half a 10 ms hop alone, and slows down while the audio received ahead of the playhead is about to run out, replacing NetEq's buffer-level decision and pitch-period splices. Every replay row was re-measured. Audio now rests within half a hop of the clock rather than within a pitch period: the A/V lag p50 fell from 10 to 0.2 ms on bursty-aac, whose p95 fell from 49.2 to 0.2, from 1.7 to -1.3 on local-aac, 2.2 to 1.8 on relay-mic and 0.9 to 0.6 on relay-mic-rtt40, and moved from -2 to 2.7 on relay-bbb and 2.2 to 3.1 on relay-mic-stall, each within the half hop the rule leaves alone. The p95 rose from 3.6 to 6.2 ms on relay-bbb, 4.5 to 6.9 on relay-mic, 2.9 to 6.9 on relay-mic-rtt40 and 19.7 to 32.1 on relay-mic-stall, and fell from 15.1 to 14.3 on local-aac: a lag under a hop is corrected only once its pace adds up to one. player_underruns_per_min rose from 4.4 to 6.6 on bursty-aac and 4 to 8.1 on local-aac, whose recorded outages outlast what slowing down at 10% bridges, and fell from 3.1 to 1 on relay-mic-rtt40, whose tap's underruns fell from 0.7 to 0.3 a minute; bursty-aac's silence rose from 0.007 to 0.008. Nothing more is trimmed on any row. The browser and native rows were measured on a loaded developer host (x86_64 Linux, the debug build, seed 7, 60 s a row) against main the same day and left to the nightly runner: every browser row's A/V lag p50 now sits between 27 and 39 ms, where the fixed-250 control does on that host, where wide and bursty sat up to 58 ms behind, and every native row's within 15 ms of the clock. Also on 2026-11-14 the estimator stopped folding the intervals a subscription's join spans, those holding a frame due before its backlog finished arriving, and every replay row was re-measured: only relay-mic and relay-mic-stall moved. Their first frame arrives slower than the path after it, so their first interval folds nothing and the target leaves the prior 500 ms later, which moves where audio rests within the half hop the rule leaves alone: relay-mic's A/V lag p50 from 1.8 to -0.3 ms and p95 from 6.9 to 9, and relay-mic-stall's p50 from 3.1 to 1.7. relay-mic-rtt40 did not move: the browser consumer closes its join's stale groups below the cursor unread, so the estimator never sees when that backlog ended, and its target p95 held at 320 ms. Later on 2026-11-14 both container consumers began reporting when each group they close unread arrived, if it is at or below the publisher's largest group as the subscription began, which extends a join still open. On 2026-11-15 the traces gained that largest group (version 4), so the replay's consumer learns it as a wire subscriber does, and relay-mic-rtt40 was re-measured: its target p95 fell from 320 to 120 ms, underruns per minute rose from 0.3 to 0.7, player skips per minute fell from 0.3 to 0, trimmed ms per minute from 83 to 0, A/V lag p50 rose from 0.6 to 2.3 ms and p95 from 6.9 to 8.6, the trade of reporting the join's backlog. No other replay row moved. On 2026-11-17 the browser player began reading audio through the ordered reader, which waits for a hole as long as the ring could still play it and reports each group it gives up on as a gap, and the replay dropped the trace's largest group: a second subscription now observes every arrival for the estimate, the join's backlog included. Every replay row was re-measured. bursty-aac's player underruns per minute fell from 6.6 to 4.4 and silence share from 0.008 to 0.007; audio rests at 0.1 ms until a stall at 19.5 s, from which the stretch catches up to 4.2 ms behind the clock, inside the half hop it leaves alone, so its A/V lag p50 and p95 rose from 0.2 to 4.2 ms. relay-bbb's A/V lag p50 fell from 2.7 to 1.4 ms and p95 rose from 6.2 to 7.6. relay-mic-rtt40's underruns per minute fell from 0.7 to 0.3, as did its player underruns per minute, underrun ms per minute from 0.8 to 0.2, A/V lag p50 from 2.3 to 0.6 ms, and p95 rose from 8.6 to 9.7, its target p95 holding at 120 ms; 0.6 ms of that rise is the replay's ordered reader taking the catalog's warmup into its budget, as the browser's does. No other replay row moved.", "rows": [ { "runtime": "chromium", @@ -499,7 +499,7 @@ "silence_share": 0, "target_ms_p95": 120, "av_lag_ms_p50": 0.6, - "av_lag_ms_p95": 9.1 + "av_lag_ms_p95": 9.7 }, { "runtime": "replay", From a235e5028301d64424737dd46ab99fc73c965f93 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 18 Nov 2026 03:34:09 -0800 Subject: [PATCH 19/23] fix(hang): keep the ordered loss rule, which the timeline check already covers for an empty group Co-Authored-By: Claude Opus 5.5 --- js/hang/src/container/consumer.ordered.test.ts | 17 +++++++++++++++++ js/hang/src/container/consumer.ts | 5 ++--- 2 files changed, 19 insertions(+), 3 deletions(-) diff --git a/js/hang/src/container/consumer.ordered.test.ts b/js/hang/src/container/consumer.ordered.test.ts index 80c7e86d178..89be532f690 100644 --- a/js/hang/src/container/consumer.ordered.test.ts +++ b/js/hang/src/container/consumer.ordered.test.ts @@ -41,6 +41,7 @@ function setup(wait: number) { }; return { clock, + track, consumer, reads, write, @@ -85,6 +86,22 @@ test("a hole is waited for as long as the ordered reader waits, then read as a g } }); +test("a gap reported before an empty group still reads as a gap before the next frame", async () => { + const t = setup(100); + try { + t.write(0n, 0); + t.write(3n, 60); + // Group 2 holds nothing, so the gap the reader reports for group 1 rides on an empty group; the + // timeline breaking at group 3 still reads as the gap. + t.track.createGroup(2n).finish(); + await t.clock.advance(Duration.millis(100)); + await flush(); + expect(t.read()).toEqual(["frame 0", "gap 0+60", "frame 60"]); + } finally { + await t.close(); + } +}); + test("a group that lands within the reader's wait fills its hole", async () => { const t = setup(100); try { diff --git a/js/hang/src/container/consumer.ts b/js/hang/src/container/consumer.ts index fb7f70a7d7b..f1c47861731 100644 --- a/js/hang/src/container/consumer.ts +++ b/js/hang/src/container/consumer.ts @@ -1079,9 +1079,8 @@ export class Consumer { full || ended !== undefined ) { - // What an ordered reader gives up it reports as a gap; a key it skips without one was never a - // group. A gap an empty group carries still marks the next frame, which follows the loss. - if (!contiguous && (decided ? head.gap : !empty)) { + // What an ordered reader gives up it reports as a gap; a key it skips without one was never a group. + if (!contiguous && !empty && (!decided || head.gap)) { this.#lost = true; if (!startup) { console.warn( From ccaebbd9a16cb7e8a53f300e8c04f8513fd583a6 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 18 Nov 2026 03:38:55 -0800 Subject: [PATCH 20/23] perf(net): an ordered read appends a gap past every one waiting Drops come lowest first, so copying the whole gap list for each one made a first read with many drops ahead quadratic: 20,000 disjoint drops took 21.2 s, and take 67 ms now. Co-Authored-By: Claude Opus 5.5 --- js/net/src/track.ts | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/js/net/src/track.ts b/js/net/src/track.ts index a494f7e1b57..a95b304620d 100644 --- a/js/net/src/track.ts +++ b/js/net/src/track.ts @@ -4949,9 +4949,18 @@ export class Subscriber { } // Take every run the record gave up into the gaps waiting, in whatever order they come. A drop - // replaces what it overlaps, and a skip was never a group, so it removes them. + // replaces what it overlaps, and a skip was never a group, so it removes them. Runs come lowest + // first, so one past every gap waiting is appended without copying the rest. #findGaps(items: Items): void { for (let dropped = this.#tryDrop(); dropped; dropped = this.#tryDrop()) { + const last = items.gaps.at(-1); + if (!last || last.end <= dropped.start) { + if (dropped.skip) continue; + const gap = { start: dropped.start, end: dropped.end, error: dropped.error }; + if (last && last.end === gap.start && sameHole(last, gap)) last.end = gap.end; + else items.gaps.push(gap); + continue; + } items.gaps = dropped.skip ? removeRun(items.gaps, dropped.start, dropped.end) : insertDrop(items.gaps, dropped.start, dropped.end, { error: dropped.error }); From 6a0531e8d1d713eb856577c2e0a21eec674c6f7c Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 18 Nov 2026 03:46:57 -0800 Subject: [PATCH 21/23] fix(net): a key passed under a stale verdict that binds another reader is still a gap #passOwed subtracted every drop in the track's record from the keys it passed, so a stale verdict under a tighter budget, which #tryDrop rightly declines for this reader, left the key reported by neither. It now subtracts only the drops that settle this reader. Co-Authored-By: Claude Opus 5.5 --- js/net/src/ordered.test.ts | 35 ++++++++++++++++++++++++++--------- js/net/src/track.ts | 10 ++++++++-- 2 files changed, 34 insertions(+), 11 deletions(-) diff --git a/js/net/src/ordered.test.ts b/js/net/src/ordered.test.ts index c2967cd9d06..b29bdcf5b2f 100644 --- a/js/net/src/ordered.test.ts +++ b/js/net/src/ordered.test.ts @@ -4,7 +4,7 @@ import { expect, test } from "bun:test"; import { Duration, sleep } from "@moq/clock"; import { Manual } from "@moq/clock/test"; import { StreamCode, StreamError } from "./error.ts"; -import { hooks } from "./internal.ts"; +import { hooks, staleHole } from "./internal.ts"; import { textFrame } from "./mock.ts"; import { Timestamp } from "./time.ts"; import { type Ordered, Producer as TrackProducer } from "./track.ts"; @@ -115,6 +115,20 @@ test("a group held behind a gap is not returned once the reader closes", () => { expect(ordered.tryNextItem()).toBeUndefined(); }); +test("a key passed under a stale verdict that does not settle this reader is still a gap", () => + withClock((clock) => { + const producer = receivedTrack(); + const ordered = producer.subscribe({ delay: { max: Duration.millis(50) } }).ordered(); + put(producer, 0n, false); + expect(items(ordered)).toEqual(["group 0"]); + // The feed gave key 1 up under a 10 ms budget, which binds no reader waiting 50 ms. + hooks.dropTrackGroups(producer, 1n, 2n, staleHole(10)); + put(producer, 2n, false); + clock.jump(Duration.millis(60)); + put(producer, 3n, false); + expect(items(ordered)).toEqual(["gap 1..2 (old)", "group 2", "group 3"]); + })); + test("a key a local track never produced is no gap", () => { const producer = new TrackProducer("test"); const ordered = producer.subscribe({ delay: { max: Duration.secs(1) } }).ordered(); @@ -135,16 +149,19 @@ test("a gap waits behind what is owed below it, and goes out before the end", () expect(items(ordered)).toEqual(["group 1", "group 2"]); put(producer, 3n, false); expect(items(ordered)).toEqual(["group 3", "gap 4..5 (delivery timeout)"]); - - const local = new TrackProducer("test"); - const read = local.subscribe({ delay: { max: null } }).ordered(); - put(local, 0n); - drop(local, 1n, 2n); - local.finish(); - expect(items(read)).toEqual(["group 0", "gap 1..2 (delivery timeout)"]); - expect(read.tryNextItem()).toBeUndefined(); })); +test("the last gap goes out before the end, and the read then ends", async () => { + const local = new TrackProducer("test"); + const read = local.subscribe({ delay: { max: null } }).ordered(); + put(local, 0n); + drop(local, 1n, 2n); + local.finish(); + expect(items(read)).toEqual(["group 0", "gap 1..2 (delivery timeout)"]); + const end = await Promise.race([read.nextItem(), sleep(Duration.millis(100)).then(() => "hung")]); + expect(end).toBeUndefined(); +}); + test("a gap is returned once, even when a later drop names it again", () => withClock((clock) => { const producer = receivedTrack(); diff --git a/js/net/src/track.ts b/js/net/src/track.ts index a95b304620d..3dedb0345cd 100644 --- a/js/net/src/track.ts +++ b/js/net/src/track.ts @@ -5047,9 +5047,15 @@ export class Subscriber { if (start >= end || this.#nextKey === 0n || !this.#dropsSeen || !producer) return; const owed = [...intersect(this.#asked, start, end), ...intersect(this.#givenUp, start, end)]; if (wireFed(producer)) owed.push(...this.#window.runs(max(start, feedFloor(producer) ?? 0n), end)); - const drops = this.#state.drops; + // Only a drop that settles this reader reports the key; a stale verdict under a tighter budget + // does not, so the key is still this reader's to give up. + const { drops, refused } = this.#state; + const coverage = this.#coverage(); for (const run of owed) { - for (const passed of runGaps(drops.overlapping(run.start, run.end), run.start, run.end)) { + const settled = givenUp(drops, refused.peek(), run.start, run.end, (drop) => + settles(drop, drift.budget, coverage), + ).filter((drop) => settles(drop, drift.budget, coverage)); + for (const passed of runGaps(settled, run.start, run.end)) { this.#giveUp(passed, staleHole(drift.budget)); } } From 1cb7b69b0c9c1173e8be6ba169f1b5a7d96f653f Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 18 Nov 2026 03:57:44 -0800 Subject: [PATCH 22/23] fix(net,hang): apply Pullfrog's two suggestions - #passOwed judges whether a drop settles this reader where it meets the passed run, as every other givenUp caller does. - The hang consumer's estimate reader releases a group read after it closed, as #run and #runOrdered now do. - The empty-group test says what it shows: the ordered reader never hands out a group lacking its head, so the gap rides on the next group. Co-Authored-By: Claude Opus 5.5 --- js/hang/src/container/consumer.ordered.test.ts | 8 ++++---- js/hang/src/container/consumer.ts | 7 ++++++- js/net/src/track.ts | 2 +- 3 files changed, 11 insertions(+), 6 deletions(-) diff --git a/js/hang/src/container/consumer.ordered.test.ts b/js/hang/src/container/consumer.ordered.test.ts index 89be532f690..a82ada59aff 100644 --- a/js/hang/src/container/consumer.ordered.test.ts +++ b/js/hang/src/container/consumer.ordered.test.ts @@ -86,14 +86,14 @@ test("a hole is waited for as long as the ordered reader waits, then read as a g } }); -test("a gap reported before an empty group still reads as a gap before the next frame", async () => { +test("an empty group after a gap never hides it: the reader gives the group up with the gap", async () => { const t = setup(100); try { t.write(0n, 0); - t.write(3n, 60); - // Group 2 holds nothing, so the gap the reader reports for group 1 rides on an empty group; the - // timeline breaking at group 3 still reads as the gap. + // Group 2 holds nothing, so the ordered reader, which hands out no group lacking its head, gives + // it up with group 1, and the gap rides on group 3. t.track.createGroup(2n).finish(); + t.write(3n, 60); await t.clock.advance(Duration.millis(100)); await flush(); expect(t.read()).toEqual(["frame 0", "gap 0+60", "frame 60"]); diff --git a/js/hang/src/container/consumer.ts b/js/hang/src/container/consumer.ts index f1c47861731..da655750a39 100644 --- a/js/hang/src/container/consumer.ts +++ b/js/hang/src/container/consumer.ts @@ -481,7 +481,12 @@ export class Consumer { try { for (;;) { const group = await this.#track.recvGroup(); - if (!group || this.#signals.abort.aborted) return; + if (!group) return; + // Closed while the read waited: cleanup already ran, so nothing would release it. + if (this.#signals.abort.aborted) { + group.close(); + return; + } this.#signals.spawn(this.#observeGroup.bind(this, group)); } } catch { diff --git a/js/net/src/track.ts b/js/net/src/track.ts index 3dedb0345cd..350548760e2 100644 --- a/js/net/src/track.ts +++ b/js/net/src/track.ts @@ -5054,7 +5054,7 @@ export class Subscriber { for (const run of owed) { const settled = givenUp(drops, refused.peek(), run.start, run.end, (drop) => settles(drop, drift.budget, coverage), - ).filter((drop) => settles(drop, drift.budget, coverage)); + ).filter((drop) => settles({ ...drop, start: max(drop.start, run.start) }, drift.budget, coverage)); for (const passed of runGaps(settled, run.start, run.end)) { this.#giveUp(passed, staleHole(drift.budget)); } From 4d6d19028edb51dc4affd34555251bcd462fda81 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 18 Nov 2026 04:08:17 -0800 Subject: [PATCH 23/23] fix(hang): a gap the ordered reader puts on an empty group still marks the next frame The reader can hand out an empty group with the gap below it, when the hole ages out before the empty group does. The consumer passed the empty group without marking the loss, so the next frame read as continuous. Co-Authored-By: Claude Opus 5.5 --- js/hang/src/container/consumer.ordered.test.ts | 9 +++++---- js/hang/src/container/consumer.ts | 5 +++-- test/audio-quality/budgets.json | 2 +- 3 files changed, 9 insertions(+), 7 deletions(-) diff --git a/js/hang/src/container/consumer.ordered.test.ts b/js/hang/src/container/consumer.ordered.test.ts index a82ada59aff..e5dabb08fa6 100644 --- a/js/hang/src/container/consumer.ordered.test.ts +++ b/js/hang/src/container/consumer.ordered.test.ts @@ -86,15 +86,16 @@ test("a hole is waited for as long as the ordered reader waits, then read as a g } }); -test("an empty group after a gap never hides it: the reader gives the group up with the gap", async () => { +test("a gap the reader reports before an empty group still reads as a gap before the next frame", async () => { const t = setup(100); try { t.write(0n, 0); - // Group 2 holds nothing, so the ordered reader, which hands out no group lacking its head, gives - // it up with group 1, and the gap rides on group 3. + // Group 2 holds nothing. The hole at 1 ages from group 2's arrival, while group 2 ages from + // group 3's later one, so the reader hands out the empty group 2 with the gap on it. t.track.createGroup(2n).finish(); + await t.clock.advance(Duration.millis(90)); t.write(3n, 60); - await t.clock.advance(Duration.millis(100)); + await t.clock.advance(Duration.millis(10)); await flush(); expect(t.read()).toEqual(["frame 0", "gap 0+60", "frame 60"]); } finally { diff --git a/js/hang/src/container/consumer.ts b/js/hang/src/container/consumer.ts index da655750a39..3da434e5de1 100644 --- a/js/hang/src/container/consumer.ts +++ b/js/hang/src/container/consumer.ts @@ -1084,8 +1084,9 @@ export class Consumer { full || ended !== undefined ) { - // What an ordered reader gives up it reports as a gap; a key it skips without one was never a group. - if (!contiguous && !empty && (!decided || head.gap)) { + // What an ordered reader gives up it reports as a gap; a key it skips without one was never a + // group. A gap an empty group carries still marks the next frame, which follows the loss. + if (!contiguous && (decided ? head.gap : !empty)) { this.#lost = true; if (!startup) { console.warn( diff --git a/test/audio-quality/budgets.json b/test/audio-quality/budgets.json index 494691f7145..19fdb4937c9 100644 --- a/test/audio-quality/budgets.json +++ b/test/audio-quality/budgets.json @@ -1,5 +1,5 @@ { - "note": "The browser rows are measured on the nightly runner (ubuntu-24.04-arm, headless Chromium, seed 7, 60 s a row), from the audio-quality-run artifacts of the seven scheduled Nightly runs on main from 2026-10-29 to 2026-11-04 (40885347517, 41065371094, 41204380716, 41313466339, 41483654426, 41656613559, 41852517544), the first after a fresh subscriber stopped receiving the relay's cached history. The six AAC rows other than congestion are measured the same way from the seven runs from 2026-11-05 to 2026-11-11 (42050683248, 42236107954, 42377867523, 42487375545, 42659882487, 42842827718, 43041909115), the first after the TS importer published each PES as one group; the first four predate the browser's time stretch, and the six rows keep the four provisional ceilings set below from 2026-11-09 and 2026-11-10. Each ceiling is the worst of its seven nights times 1.25, plus one runner hiccup, rounded up to two significant figures. The hiccup is sized from the single gaps the 2026-10-08 night put on otherwise clean rows, the fixed-250 control among them: 250 underruns/min, 700 gap ms/min, 3.3 skips/min, 280 dropped ms/min (both sized on the playhead's skip-ahead inference, and now applied to player_skips_per_min and trimmed_ms_per_min), 0.01 stalled, 0.015 silence, and one 20 ms bucket of target. Budgeted this way, every night passes when it is held out of its row's measurement except one, and that row's own ceiling includes it: the 2026-11-03 Opus bursty row raised its target to 300 ms 2.6 s in and held it for one 20 s half-life before settling at 180. Such startup holds, Opus near-zero's 100 ms on 2026-10-30 and 10-31 among them, are budgeted as measured. These ceilings record today's player as the runner hears it, not target audio quality. To re-measure, download the same artifact from the latest scheduled nightlies (`gh run download -n audio-quality-run`), which keep every run, and apply the same rule. On 2026-11-10 the inferred skip_aheads and discarded_ms keys were dropped, since they read a time stretch's catch-up as dropped audio, and every browser row gained player_skips_per_min, trimmed_ms_per_min, and av_lag_ms p50 and p95, by the same rule from the only two scheduled nights on main with today's browser player and its trim counter, 2026-11-09 and 2026-11-10 (42659882487, 42842827718). A lag is signed, so its ceiling is the worst night plus a quarter of its size plus one 20 ms bucket. These four keys are provisional until seven nights with the stretch model re-measure every row. The grade follows the model: audio rests on the shared clock, trails it through a stall, and catches up after. When a change moves a row, a steady-state lag (av_lag_ms p50) that rises, or audio the player trimmed, is a regression to fix rather than budget; a p95 lag that rises through a stall, or an underrun count that moves, is re-measured in. No ceiling is fixed at zero underruns or zero stalls; a replay row's is exactly what it measured. The replay rows are deterministic, so their ceilings are exactly what they measured, through the end of each recording, with no headroom: any regression fails them, and an improvement should be tightened in. They were last re-measured on 2026-10-22 using version 3 traces with encoded frame durations: AAC-LC uses its fixed 1024 samples, and relay-mic retains Opus packet TOC durations. relay-mic was re-recorded on 2026-11-03 from a real microphone, Chrome 156 on a MacBook Air publishing its built-in microphone through the public relay, recorded by headless Chromium on a Linux host (35 s, minimum RTT 2 ms), which raised its target ceiling from 60 to 80 ms and its silence from 0 to 0.001 as measured. The recording path itself has no added RTT. relay-mic-rtt40 is the 2026-11-03 Chrome row at 40 ms of added RTT on that laptop (180 s, minimum RTT 47 ms), kept as the baseline time stretch improves on; like every replay row, its player_underruns_per_min ceiling is what it measures, not a fixed zero. player_underruns_per_min, the player's own counter that its stats panel shows, is budgeted on the replay rows only; it counts the run-dry re-stalls the tap files as stalled time. On 2026-11-07, after the ordered read stopped delivering groups below its cursor (#8071) and took Rust's hole and age bounds (#8218), relay-bbb was re-measured at 16.1 player underruns/min, 0.025 stalled and 0.02 silence, and relay-mic-rtt40 at 8.2, its discarded audio at 70.9 ms/min and its target p95 at 320 ms rather than 780, since the stale backlog it never played no longer reaches the estimator; neither row lost audio the previous player heard. On 2026-11-08 the player began time-stretching live playback with NetEq's accelerate, deciding on the ring's depth right after each arrival and never expanding, and every replay row was re-measured with it, the browser rows left to the nightly runner. Each row's av_lag_ms, how far the playhead trails the shared clock video plays from, is what it measured: the ring rests one frame ahead of the newest arrival's playout, as the trim it replaces left it, so audio leads the clock by 19 to 23 ms at p50. Against the trim, the A/V lag p50 fell from 0.7, -17.5, -21.5, -18.2 and -15.6 ms to -22.4 on bursty-aac, -22.2 on local-aac, -22.7 on relay-bbb, -19 on relay-mic and -20.1 on relay-mic-rtt40, and its p95 fell on every row, most on relay-bbb (10.5 to -4.2) and relay-mic-rtt40 (-0.9 to -13.4). Underruns stayed where the trim had them, as the latency they would cost is not spent: player_underruns_per_min held at 4.4, 12.1, 16.1 and 6.1 and rose from 8.2 to 10.6 on relay-mic-rtt40, and relay-mic's tap now files 2 short quanta a minute, 2 ms of missing audio, where it filed none. What the stretch buys is the audio the trim dropped: discarded_ms_per_min fell from 87.8 to 0 on relay-bbb and from 127.5 to 100.6 on local-aac, whose remainder drops nothing: two receive stalls 14 and 15.3 s in leave audio 159 and 132 ms behind the clock, and the fast accelerate brings it back within half a second. player_skips_per_min and trimmed_ms_per_min, the ring's own count of re-anchors that dropped buffered audio and the media they dropped, are budgeted beside it, at 0 on every recorded row. relay-mic-stall, added 2026-11-10, is relay-mic with nothing arriving from 15 s to 16.5 s and the held frames then trickling in at twice real time until 18 s; today's player trims 2152.5 ms/min of it and its target p95 rises to 1540 ms. Once durations became whole nanoseconds, relay-bbb's delay, 200 ms plus one 1024-sample AAC frame, rounds up by a fraction of a sample, so its ring holds one more sample (23 µs) and its A/V lag p50 measures -22.6 rather than -22.7. Neither replay calibration changed the browser or native ceilings. bursty-aac is the 2026-10-18 AAC bursty isolated capture, recorded with the observer subscribed at the decoder's 2 s budget, so it holds every group the player saw. The native rows are provisional: measured on a loaded developer host (x86_64 Linux, the private PulseAudio null sink, seed 7, 60 s a row) on 2026-10-17, three runs of every row from the debug build nightly uses plus three more of the AAC rows from a release build, which played alike. Each ceiling is the worst clean run times 1.25, plus one native hiccup sized from the unimpaired Opus row's worst run (20 underruns/min, 50 gap ms/min, 2.2 skips/min, 110 discarded ms/min, 0.01 stalled, 0.005 silence, one 20 ms bucket of target), rounded up to two significant figures. On 2026-11-10, after native playback began reporting its A/V lag (#8361), the native rows' player_skips_per_min, trimmed_ms_per_min, and av_lag_ms p50 and p95, and every key of the native and browser congestion rows, were measured by the same rules from three runs of each on a loaded developer host (x86_64 Linux, the debug build, seed 7, 60 s a row), with no void; native audio rests 9 to 95 ms behind its clock at p50. These are provisional until the stretch model's nightly re-measure, which also moves the browser congestion rows onto the runner. On the 2026-10-17 host the null sink's clock ran about 150 ppm slow against the monotonic clock, read within 5 ms at p95 per sample, and its output latency sat between 14 and 28 ms. Five of the 36 AAC rows (none of the 18 Opus rows) voided on the clock: the device stopped pulling for about two seconds mid-row, sometimes after a backend error and a stream restart, which is a native playback defect rather than noise, and the ceilings exclude those runs. Re-measure from the nightly runner's artifacts once it has a week of native rows. On 2026-11-11 every player began following one stretch rule on the shared clock: it slows down below its target, speeds up above it, and skips only past its bound, which in the browser is the subscription's max delay. Every replay row was re-measured with it, the browser and native rows left to the nightly runner. Audio now rests on the clock rather than one frame ahead of it, so the A/V lag p50 rose from about -20 ms to 0.4 ms on relay-bbb, 1.1 on relay-mic, 1.2 on relay-mic-rtt40 and 1.8 on local-aac. Its p95 rose on every row, since audio that falls behind is now caught up by speeding up rather than trimmed: the shared clock steps forward as its reference converges through a tune-in backlog, and again when a target falls, and audio follows at the accelerate's pace, which on the replay's constant tone is one 2.5 ms period a window, slower than on speech. bursty-aac rests 5 ms behind its clock, so its p50 of 10.4 ms is mostly its catch-ups, and relay-mic-stall's p50 of 66.1 ms is the catch-up after its target falls from 1540 to 80 ms, which outlasts half the row. In exchange nothing is trimmed: relay-mic-stall's trimmed_ms_per_min fell from 2152.5 to 0, its skips from 6.1 to 0, and its underruns from 24.2 to 0 a minute, and player_underruns_per_min fell from 12.1 to 4 on local-aac, 16.1 to 0 on relay-bbb, 6.1 to 0 on relay-mic, 10.6 to 2.7 on relay-mic-rtt40 and 6.1 to 4 on relay-mic-stall, holding at 4.4 on bursty-aac. The tap now files 3.3 to 6.1 short quanta a minute on the AAC rows, under 0.3 ms of missing audio, where it filed none. To deliver the audio a stall delays, the container consumer now waits and skips at the subscription's max delay, as native already does, rather than at the delay plus lookahead. relay-mic-rtt40's join backlog arrives reordered, so the consumer now waits on its holes and the estimator observes the frames that fill them, up to 775 ms late, and its target p95 returns from 320 to 780 ms, held for one half-life after the join. Later on 2026-11-11 audio began skipping as far as the shared clock's reference moves earlier, once those moves add up to one stretch window and only as far as it holds audio past its target, rather than speeding through them, and every replay row was re-measured. The tune-in backlog's jumps now land before the graded window, so the A/V lag p95 fell from 453.1 to 2.1 ms on relay-bbb (its p50 from 0.4 to -1.3), 743.7 to 1.9 on relay-mic-rtt40, whose p50 fell from 1.2 to 0.4 and its tap's missing audio rose from 0.6 to 0.9 ms a minute, since a jump past what is decoded skips the rest once it lands,, 335.5 to 39.2 on local-aac and 88.6 to 0.3 on relay-mic, and the p50 from 66.1 to 25.3 on relay-mic-stall, with nothing trimmed in any graded window. The tap's underruns fell from 6.1 to 2 a minute on local-aac and 6.1 to 0 on relay-bbb; local-aac's silence rose from 0.001 to 0.002. Later on 2026-11-11 the container consumer began waiting on a missing group only for the delay plus the lookahead, while still delivering groups that arrived until they age past the max delay, and every replay row was re-measured. relay-mic-rtt40's target p95 fell from 780 back to 320 ms, since the holes in its reordered join backlog no longer delay the frames behind them; its tap's missing audio rose from 0.9 to 1.1 ms a minute and its A/V lag p50 and p95 from 0.4 and 1.9 to 0.7 and 2.4 ms. bursty-aac's silence rose from 0.007 to 0.009 and its A/V lag p95 fell from 162.1 to 156.3 ms, and relay-bbb's lag p50 and p95 moved from -1.3 and 2.1 to -1.2 and 2.2 ms. relay-mic-stall did not move. Also on 2026-11-11 the stretch became a player setting, 2 s by default, and the audio subscription's max delay became the delay plus it rather than the 2 s constant, so the container consumer delivers a late group that much longer before it ages out, and every replay row was re-measured: only relay-mic moved, its A/V lag p50 and p95 from 0.3 to 1.6 ms, under the 2.5 ms pitch period the stretch can move it by. Holding the constant max delay with the new bound reproduces the old values exactly. On 2026-11-12 the replays stopped playing a constant and began playing a seeded speech-like signal (syllables gliding a 90 to 220 Hz fundamental, with pauses held above the silence classifier), since the stretch's pitch search found only its shortest period in a constant, and the browser ring stopped zero-filling a hole of up to a millisecond and two samples between frames, as native stopped writing silence for one: the recorded AAC timestamps land up to 2.5 samples either side of a 1024-sample boundary, and on speech the 2-sample holes this filled ended 119.1 quanta a minute short on bursty-aac. Every replay row was re-measured. The tap's underruns fell to 0 on bursty-aac (from 3.3) and local-aac (from 2), and relay-mic-rtt40's missing audio from 1.1 to 0.3 ms a minute while its player underruns rose from 2.7 to 3.1. The A/V lag p95 fell from 156.3 to 104.8 ms on bursty-aac, 39.2 to 15.1 on local-aac, 2.2 to 1.4 on relay-bbb and 501.8 to 484.9 on relay-mic-stall, whose p50 fell from 25.3 to 1.1, and rose from 1.6 to 3.4 on relay-mic and 2.4 to 3.5 on relay-mic-rtt40. Where audio rests moved within one speech pitch period, which is as close as one stretch seam can steer it: the p50 is 11 ms on bursty-aac (from 10.4), -4.2 on relay-bbb (from -1.2), 1.1 on relay-mic (from 1.6), 0.9 on relay-mic-rtt40 (from 0.7) and 1.7 on local-aac (from 1.8). On 2026-11-13 the stretch default fell from 2 s to 200 ms and audio trailing the clock past it began skipping onto the clock rather than back to the bound, as video skips, with the audio subscription still reaching 2 s past the delay; every replay row was re-measured. A target fall past 200 ms now costs one skip rather than seconds of catch-up, and so does a trail past it, and a rise past it pads silence until the clock arrives rather than slowing down: relay-mic-stall skips the 1.46 s it trails after the outage and its 1540 to 1020 and 1020 to 80 ms falls, and pads the 0.5 s its 60 to 1540 ms rise leaves it ahead, where it slowed down for 4 s, so it trims 4678.2 ms a minute where it trimmed none and its stalled share rose from 0.05 to 0.067 and silence from 0.049 to 0.085. The frames it holds through the outage then trickle in at twice real time, so its low buffer slows it to 154 ms behind the clock, where it had sat ahead of it: its A/V lag p95 fell from 484.9 to 118.6 ms and its p50 rose from 1.1 to 2.2. relay-mic-rtt40 skips its 320 to 80 ms fall, 0.3 skips and 83.3 trimmed ms a minute, its p95 from 3.5 to 2.9 ms. bursty-aac skips a 225 ms trail 6 s in, 1.1 skips and 312.7 trimmed ms a minute, its p95 from 102.7 to 49.2 ms and p50 from 11 to 10. relay-mic trims nothing, but its tune-in's skips land on the clock rather than at the bound, which moves where it rests within a pitch period: its p50 from 1.1 to 2.2 ms and p95 from 3.4 to 4.5. Trimming at a target fall or a trail past 200 ms is the rule, not a regression. Also on 2026-11-13, for the same change, the congestion rows' trimmed_ms_per_min ceilings were raised by the same rule from two runs of each on a loaded developer host (x86_64 Linux, the debug build, seed 7, 60 s a row): to 3800 on chromium AAC (worst 2740.3 ms/min), 3700 on chromium Opus (2697.2), 3900 on native AAC (2996.9) and 4600 on native Opus (3532.3), whose player_skips_per_min rose to 15 (9.8). The trim is the outage's audio skipped onto the clock rather than played seconds late: against main on the same host, chromium's A/V lag p95 fell from 1396.8 to 61.6 ms on AAC and 1424.8 to 64.3 on Opus, and native's from 1246.3 to 116.7 and 826.9 to 117.5. These four ceilings are provisional until the nightly re-measures the congestion rows. Also on 2026-11-13, the estimator began counting one outage, the intervals its stalled frames span and the empty ones before them, as one observation, and every replay row was re-measured on top of the snap: only relay-mic-stall moved. Its single stall no longer raises the target, so its target p95 fell from 1540 to 80 ms and the trail the outage leaves is skipped onto the clock at once rather than through the target's falls: 2 skips a minute where it took 6.1, 5122.3 trimmed ms a minute where it trimmed 4678.2, and its A/V lag p95 from 118.6 to 19.7 ms. With 80 ms of buffer rather than 1540, more of the outage plays as silence: its stalled share rose from 0.067 to 0.092 and silence from 0.085 to 0.092. On 2026-11-14 every player began following the clock by its lag alone: a continuous WSOLA time stretch for any content, at a rate proportional to the lag and capped at 10%, which leaves a lag within half a 10 ms hop alone, and slows down while the audio received ahead of the playhead is about to run out, replacing NetEq's buffer-level decision and pitch-period splices. Every replay row was re-measured. Audio now rests within half a hop of the clock rather than within a pitch period: the A/V lag p50 fell from 10 to 0.2 ms on bursty-aac, whose p95 fell from 49.2 to 0.2, from 1.7 to -1.3 on local-aac, 2.2 to 1.8 on relay-mic and 0.9 to 0.6 on relay-mic-rtt40, and moved from -2 to 2.7 on relay-bbb and 2.2 to 3.1 on relay-mic-stall, each within the half hop the rule leaves alone. The p95 rose from 3.6 to 6.2 ms on relay-bbb, 4.5 to 6.9 on relay-mic, 2.9 to 6.9 on relay-mic-rtt40 and 19.7 to 32.1 on relay-mic-stall, and fell from 15.1 to 14.3 on local-aac: a lag under a hop is corrected only once its pace adds up to one. player_underruns_per_min rose from 4.4 to 6.6 on bursty-aac and 4 to 8.1 on local-aac, whose recorded outages outlast what slowing down at 10% bridges, and fell from 3.1 to 1 on relay-mic-rtt40, whose tap's underruns fell from 0.7 to 0.3 a minute; bursty-aac's silence rose from 0.007 to 0.008. Nothing more is trimmed on any row. The browser and native rows were measured on a loaded developer host (x86_64 Linux, the debug build, seed 7, 60 s a row) against main the same day and left to the nightly runner: every browser row's A/V lag p50 now sits between 27 and 39 ms, where the fixed-250 control does on that host, where wide and bursty sat up to 58 ms behind, and every native row's within 15 ms of the clock. Also on 2026-11-14 the estimator stopped folding the intervals a subscription's join spans, those holding a frame due before its backlog finished arriving, and every replay row was re-measured: only relay-mic and relay-mic-stall moved. Their first frame arrives slower than the path after it, so their first interval folds nothing and the target leaves the prior 500 ms later, which moves where audio rests within the half hop the rule leaves alone: relay-mic's A/V lag p50 from 1.8 to -0.3 ms and p95 from 6.9 to 9, and relay-mic-stall's p50 from 3.1 to 1.7. relay-mic-rtt40 did not move: the browser consumer closes its join's stale groups below the cursor unread, so the estimator never sees when that backlog ended, and its target p95 held at 320 ms. Later on 2026-11-14 both container consumers began reporting when each group they close unread arrived, if it is at or below the publisher's largest group as the subscription began, which extends a join still open. On 2026-11-15 the traces gained that largest group (version 4), so the replay's consumer learns it as a wire subscriber does, and relay-mic-rtt40 was re-measured: its target p95 fell from 320 to 120 ms, underruns per minute rose from 0.3 to 0.7, player skips per minute fell from 0.3 to 0, trimmed ms per minute from 83 to 0, A/V lag p50 rose from 0.6 to 2.3 ms and p95 from 6.9 to 8.6, the trade of reporting the join's backlog. No other replay row moved. On 2026-11-17 the browser player began reading audio through the ordered reader, which waits for a hole as long as the ring could still play it and reports each group it gives up on as a gap, and the replay dropped the trace's largest group: a second subscription now observes every arrival for the estimate, the join's backlog included. Every replay row was re-measured. bursty-aac's player underruns per minute fell from 6.6 to 4.4 and silence share from 0.008 to 0.007; audio rests at 0.1 ms until a stall at 19.5 s, from which the stretch catches up to 4.2 ms behind the clock, inside the half hop it leaves alone, so its A/V lag p50 and p95 rose from 0.2 to 4.2 ms. relay-bbb's A/V lag p50 fell from 2.7 to 1.4 ms and p95 rose from 6.2 to 7.6. relay-mic-rtt40's underruns per minute fell from 0.7 to 0.3, as did its player underruns per minute, underrun ms per minute from 0.8 to 0.2, A/V lag p50 from 2.3 to 0.6 ms, and p95 rose from 8.6 to 9.7, its target p95 holding at 120 ms; 0.6 ms of that rise is the replay's ordered reader taking the catalog's warmup into its budget, as the browser's does. No other replay row moved.", + "note": "The browser rows are measured on the nightly runner (ubuntu-24.04-arm, headless Chromium, seed 7, 60 s a row), from the audio-quality-run artifacts of the seven scheduled Nightly runs on main from 2026-10-29 to 2026-11-04 (40885347517, 41065371094, 41204380716, 41313466339, 41483654426, 41656613559, 41852517544), the first after a fresh subscriber stopped receiving the relay's cached history. The six AAC rows other than congestion are measured the same way from the seven runs from 2026-11-05 to 2026-11-11 (42050683248, 42236107954, 42377867523, 42487375545, 42659882487, 42842827718, 43041909115), the first after the TS importer published each PES as one group; the first four predate the browser's time stretch, and the six rows keep the four provisional ceilings set below from 2026-11-09 and 2026-11-10. Each ceiling is the worst of its seven nights times 1.25, plus one runner hiccup, rounded up to two significant figures. The hiccup is sized from the single gaps the 2026-10-08 night put on otherwise clean rows, the fixed-250 control among them: 250 underruns/min, 700 gap ms/min, 3.3 skips/min, 280 dropped ms/min (both sized on the playhead's skip-ahead inference, and now applied to player_skips_per_min and trimmed_ms_per_min), 0.01 stalled, 0.015 silence, and one 20 ms bucket of target. Budgeted this way, every night passes when it is held out of its row's measurement except one, and that row's own ceiling includes it: the 2026-11-03 Opus bursty row raised its target to 300 ms 2.6 s in and held it for one 20 s half-life before settling at 180. Such startup holds, Opus near-zero's 100 ms on 2026-10-30 and 10-31 among them, are budgeted as measured. These ceilings record today's player as the runner hears it, not target audio quality. To re-measure, download the same artifact from the latest scheduled nightlies (`gh run download -n audio-quality-run`), which keep every run, and apply the same rule. On 2026-11-10 the inferred skip_aheads and discarded_ms keys were dropped, since they read a time stretch's catch-up as dropped audio, and every browser row gained player_skips_per_min, trimmed_ms_per_min, and av_lag_ms p50 and p95, by the same rule from the only two scheduled nights on main with today's browser player and its trim counter, 2026-11-09 and 2026-11-10 (42659882487, 42842827718). A lag is signed, so its ceiling is the worst night plus a quarter of its size plus one 20 ms bucket. These four keys are provisional until seven nights with the stretch model re-measure every row. The grade follows the model: audio rests on the shared clock, trails it through a stall, and catches up after. When a change moves a row, a steady-state lag (av_lag_ms p50) that rises, or audio the player trimmed, is a regression to fix rather than budget; a p95 lag that rises through a stall, or an underrun count that moves, is re-measured in. No ceiling is fixed at zero underruns or zero stalls; a replay row's is exactly what it measured. The replay rows are deterministic, so their ceilings are exactly what they measured, through the end of each recording, with no headroom: any regression fails them, and an improvement should be tightened in. They were last re-measured on 2026-10-22 using version 3 traces with encoded frame durations: AAC-LC uses its fixed 1024 samples, and relay-mic retains Opus packet TOC durations. relay-mic was re-recorded on 2026-11-03 from a real microphone, Chrome 156 on a MacBook Air publishing its built-in microphone through the public relay, recorded by headless Chromium on a Linux host (35 s, minimum RTT 2 ms), which raised its target ceiling from 60 to 80 ms and its silence from 0 to 0.001 as measured. The recording path itself has no added RTT. relay-mic-rtt40 is the 2026-11-03 Chrome row at 40 ms of added RTT on that laptop (180 s, minimum RTT 47 ms), kept as the baseline time stretch improves on; like every replay row, its player_underruns_per_min ceiling is what it measures, not a fixed zero. player_underruns_per_min, the player's own counter that its stats panel shows, is budgeted on the replay rows only; it counts the run-dry re-stalls the tap files as stalled time. On 2026-11-07, after the ordered read stopped delivering groups below its cursor (#8071) and took Rust's hole and age bounds (#8218), relay-bbb was re-measured at 16.1 player underruns/min, 0.025 stalled and 0.02 silence, and relay-mic-rtt40 at 8.2, its discarded audio at 70.9 ms/min and its target p95 at 320 ms rather than 780, since the stale backlog it never played no longer reaches the estimator; neither row lost audio the previous player heard. On 2026-11-08 the player began time-stretching live playback with NetEq's accelerate, deciding on the ring's depth right after each arrival and never expanding, and every replay row was re-measured with it, the browser rows left to the nightly runner. Each row's av_lag_ms, how far the playhead trails the shared clock video plays from, is what it measured: the ring rests one frame ahead of the newest arrival's playout, as the trim it replaces left it, so audio leads the clock by 19 to 23 ms at p50. Against the trim, the A/V lag p50 fell from 0.7, -17.5, -21.5, -18.2 and -15.6 ms to -22.4 on bursty-aac, -22.2 on local-aac, -22.7 on relay-bbb, -19 on relay-mic and -20.1 on relay-mic-rtt40, and its p95 fell on every row, most on relay-bbb (10.5 to -4.2) and relay-mic-rtt40 (-0.9 to -13.4). Underruns stayed where the trim had them, as the latency they would cost is not spent: player_underruns_per_min held at 4.4, 12.1, 16.1 and 6.1 and rose from 8.2 to 10.6 on relay-mic-rtt40, and relay-mic's tap now files 2 short quanta a minute, 2 ms of missing audio, where it filed none. What the stretch buys is the audio the trim dropped: discarded_ms_per_min fell from 87.8 to 0 on relay-bbb and from 127.5 to 100.6 on local-aac, whose remainder drops nothing: two receive stalls 14 and 15.3 s in leave audio 159 and 132 ms behind the clock, and the fast accelerate brings it back within half a second. player_skips_per_min and trimmed_ms_per_min, the ring's own count of re-anchors that dropped buffered audio and the media they dropped, are budgeted beside it, at 0 on every recorded row. relay-mic-stall, added 2026-11-10, is relay-mic with nothing arriving from 15 s to 16.5 s and the held frames then trickling in at twice real time until 18 s; today's player trims 2152.5 ms/min of it and its target p95 rises to 1540 ms. Once durations became whole nanoseconds, relay-bbb's delay, 200 ms plus one 1024-sample AAC frame, rounds up by a fraction of a sample, so its ring holds one more sample (23 µs) and its A/V lag p50 measures -22.6 rather than -22.7. Neither replay calibration changed the browser or native ceilings. bursty-aac is the 2026-10-18 AAC bursty isolated capture, recorded with the observer subscribed at the decoder's 2 s budget, so it holds every group the player saw. The native rows are provisional: measured on a loaded developer host (x86_64 Linux, the private PulseAudio null sink, seed 7, 60 s a row) on 2026-10-17, three runs of every row from the debug build nightly uses plus three more of the AAC rows from a release build, which played alike. Each ceiling is the worst clean run times 1.25, plus one native hiccup sized from the unimpaired Opus row's worst run (20 underruns/min, 50 gap ms/min, 2.2 skips/min, 110 discarded ms/min, 0.01 stalled, 0.005 silence, one 20 ms bucket of target), rounded up to two significant figures. On 2026-11-10, after native playback began reporting its A/V lag (#8361), the native rows' player_skips_per_min, trimmed_ms_per_min, and av_lag_ms p50 and p95, and every key of the native and browser congestion rows, were measured by the same rules from three runs of each on a loaded developer host (x86_64 Linux, the debug build, seed 7, 60 s a row), with no void; native audio rests 9 to 95 ms behind its clock at p50. These are provisional until the stretch model's nightly re-measure, which also moves the browser congestion rows onto the runner. On the 2026-10-17 host the null sink's clock ran about 150 ppm slow against the monotonic clock, read within 5 ms at p95 per sample, and its output latency sat between 14 and 28 ms. Five of the 36 AAC rows (none of the 18 Opus rows) voided on the clock: the device stopped pulling for about two seconds mid-row, sometimes after a backend error and a stream restart, which is a native playback defect rather than noise, and the ceilings exclude those runs. Re-measure from the nightly runner's artifacts once it has a week of native rows. On 2026-11-11 every player began following one stretch rule on the shared clock: it slows down below its target, speeds up above it, and skips only past its bound, which in the browser is the subscription's max delay. Every replay row was re-measured with it, the browser and native rows left to the nightly runner. Audio now rests on the clock rather than one frame ahead of it, so the A/V lag p50 rose from about -20 ms to 0.4 ms on relay-bbb, 1.1 on relay-mic, 1.2 on relay-mic-rtt40 and 1.8 on local-aac. Its p95 rose on every row, since audio that falls behind is now caught up by speeding up rather than trimmed: the shared clock steps forward as its reference converges through a tune-in backlog, and again when a target falls, and audio follows at the accelerate's pace, which on the replay's constant tone is one 2.5 ms period a window, slower than on speech. bursty-aac rests 5 ms behind its clock, so its p50 of 10.4 ms is mostly its catch-ups, and relay-mic-stall's p50 of 66.1 ms is the catch-up after its target falls from 1540 to 80 ms, which outlasts half the row. In exchange nothing is trimmed: relay-mic-stall's trimmed_ms_per_min fell from 2152.5 to 0, its skips from 6.1 to 0, and its underruns from 24.2 to 0 a minute, and player_underruns_per_min fell from 12.1 to 4 on local-aac, 16.1 to 0 on relay-bbb, 6.1 to 0 on relay-mic, 10.6 to 2.7 on relay-mic-rtt40 and 6.1 to 4 on relay-mic-stall, holding at 4.4 on bursty-aac. The tap now files 3.3 to 6.1 short quanta a minute on the AAC rows, under 0.3 ms of missing audio, where it filed none. To deliver the audio a stall delays, the container consumer now waits and skips at the subscription's max delay, as native already does, rather than at the delay plus lookahead. relay-mic-rtt40's join backlog arrives reordered, so the consumer now waits on its holes and the estimator observes the frames that fill them, up to 775 ms late, and its target p95 returns from 320 to 780 ms, held for one half-life after the join. Later on 2026-11-11 audio began skipping as far as the shared clock's reference moves earlier, once those moves add up to one stretch window and only as far as it holds audio past its target, rather than speeding through them, and every replay row was re-measured. The tune-in backlog's jumps now land before the graded window, so the A/V lag p95 fell from 453.1 to 2.1 ms on relay-bbb (its p50 from 0.4 to -1.3), 743.7 to 1.9 on relay-mic-rtt40, whose p50 fell from 1.2 to 0.4 and its tap's missing audio rose from 0.6 to 0.9 ms a minute, since a jump past what is decoded skips the rest once it lands,, 335.5 to 39.2 on local-aac and 88.6 to 0.3 on relay-mic, and the p50 from 66.1 to 25.3 on relay-mic-stall, with nothing trimmed in any graded window. The tap's underruns fell from 6.1 to 2 a minute on local-aac and 6.1 to 0 on relay-bbb; local-aac's silence rose from 0.001 to 0.002. Later on 2026-11-11 the container consumer began waiting on a missing group only for the delay plus the lookahead, while still delivering groups that arrived until they age past the max delay, and every replay row was re-measured. relay-mic-rtt40's target p95 fell from 780 back to 320 ms, since the holes in its reordered join backlog no longer delay the frames behind them; its tap's missing audio rose from 0.9 to 1.1 ms a minute and its A/V lag p50 and p95 from 0.4 and 1.9 to 0.7 and 2.4 ms. bursty-aac's silence rose from 0.007 to 0.009 and its A/V lag p95 fell from 162.1 to 156.3 ms, and relay-bbb's lag p50 and p95 moved from -1.3 and 2.1 to -1.2 and 2.2 ms. relay-mic-stall did not move. Also on 2026-11-11 the stretch became a player setting, 2 s by default, and the audio subscription's max delay became the delay plus it rather than the 2 s constant, so the container consumer delivers a late group that much longer before it ages out, and every replay row was re-measured: only relay-mic moved, its A/V lag p50 and p95 from 0.3 to 1.6 ms, under the 2.5 ms pitch period the stretch can move it by. Holding the constant max delay with the new bound reproduces the old values exactly. On 2026-11-12 the replays stopped playing a constant and began playing a seeded speech-like signal (syllables gliding a 90 to 220 Hz fundamental, with pauses held above the silence classifier), since the stretch's pitch search found only its shortest period in a constant, and the browser ring stopped zero-filling a hole of up to a millisecond and two samples between frames, as native stopped writing silence for one: the recorded AAC timestamps land up to 2.5 samples either side of a 1024-sample boundary, and on speech the 2-sample holes this filled ended 119.1 quanta a minute short on bursty-aac. Every replay row was re-measured. The tap's underruns fell to 0 on bursty-aac (from 3.3) and local-aac (from 2), and relay-mic-rtt40's missing audio from 1.1 to 0.3 ms a minute while its player underruns rose from 2.7 to 3.1. The A/V lag p95 fell from 156.3 to 104.8 ms on bursty-aac, 39.2 to 15.1 on local-aac, 2.2 to 1.4 on relay-bbb and 501.8 to 484.9 on relay-mic-stall, whose p50 fell from 25.3 to 1.1, and rose from 1.6 to 3.4 on relay-mic and 2.4 to 3.5 on relay-mic-rtt40. Where audio rests moved within one speech pitch period, which is as close as one stretch seam can steer it: the p50 is 11 ms on bursty-aac (from 10.4), -4.2 on relay-bbb (from -1.2), 1.1 on relay-mic (from 1.6), 0.9 on relay-mic-rtt40 (from 0.7) and 1.7 on local-aac (from 1.8). On 2026-11-13 the stretch default fell from 2 s to 200 ms and audio trailing the clock past it began skipping onto the clock rather than back to the bound, as video skips, with the audio subscription still reaching 2 s past the delay; every replay row was re-measured. A target fall past 200 ms now costs one skip rather than seconds of catch-up, and so does a trail past it, and a rise past it pads silence until the clock arrives rather than slowing down: relay-mic-stall skips the 1.46 s it trails after the outage and its 1540 to 1020 and 1020 to 80 ms falls, and pads the 0.5 s its 60 to 1540 ms rise leaves it ahead, where it slowed down for 4 s, so it trims 4678.2 ms a minute where it trimmed none and its stalled share rose from 0.05 to 0.067 and silence from 0.049 to 0.085. The frames it holds through the outage then trickle in at twice real time, so its low buffer slows it to 154 ms behind the clock, where it had sat ahead of it: its A/V lag p95 fell from 484.9 to 118.6 ms and its p50 rose from 1.1 to 2.2. relay-mic-rtt40 skips its 320 to 80 ms fall, 0.3 skips and 83.3 trimmed ms a minute, its p95 from 3.5 to 2.9 ms. bursty-aac skips a 225 ms trail 6 s in, 1.1 skips and 312.7 trimmed ms a minute, its p95 from 102.7 to 49.2 ms and p50 from 11 to 10. relay-mic trims nothing, but its tune-in's skips land on the clock rather than at the bound, which moves where it rests within a pitch period: its p50 from 1.1 to 2.2 ms and p95 from 3.4 to 4.5. Trimming at a target fall or a trail past 200 ms is the rule, not a regression. Also on 2026-11-13, for the same change, the congestion rows' trimmed_ms_per_min ceilings were raised by the same rule from two runs of each on a loaded developer host (x86_64 Linux, the debug build, seed 7, 60 s a row): to 3800 on chromium AAC (worst 2740.3 ms/min), 3700 on chromium Opus (2697.2), 3900 on native AAC (2996.9) and 4600 on native Opus (3532.3), whose player_skips_per_min rose to 15 (9.8). The trim is the outage's audio skipped onto the clock rather than played seconds late: against main on the same host, chromium's A/V lag p95 fell from 1396.8 to 61.6 ms on AAC and 1424.8 to 64.3 on Opus, and native's from 1246.3 to 116.7 and 826.9 to 117.5. These four ceilings are provisional until the nightly re-measures the congestion rows. Also on 2026-11-13, the estimator began counting one outage, the intervals its stalled frames span and the empty ones before them, as one observation, and every replay row was re-measured on top of the snap: only relay-mic-stall moved. Its single stall no longer raises the target, so its target p95 fell from 1540 to 80 ms and the trail the outage leaves is skipped onto the clock at once rather than through the target's falls: 2 skips a minute where it took 6.1, 5122.3 trimmed ms a minute where it trimmed 4678.2, and its A/V lag p95 from 118.6 to 19.7 ms. With 80 ms of buffer rather than 1540, more of the outage plays as silence: its stalled share rose from 0.067 to 0.092 and silence from 0.085 to 0.092. On 2026-11-14 every player began following the clock by its lag alone: a continuous WSOLA time stretch for any content, at a rate proportional to the lag and capped at 10%, which leaves a lag within half a 10 ms hop alone, and slows down while the audio received ahead of the playhead is about to run out, replacing NetEq's buffer-level decision and pitch-period splices. Every replay row was re-measured. Audio now rests within half a hop of the clock rather than within a pitch period: the A/V lag p50 fell from 10 to 0.2 ms on bursty-aac, whose p95 fell from 49.2 to 0.2, from 1.7 to -1.3 on local-aac, 2.2 to 1.8 on relay-mic and 0.9 to 0.6 on relay-mic-rtt40, and moved from -2 to 2.7 on relay-bbb and 2.2 to 3.1 on relay-mic-stall, each within the half hop the rule leaves alone. The p95 rose from 3.6 to 6.2 ms on relay-bbb, 4.5 to 6.9 on relay-mic, 2.9 to 6.9 on relay-mic-rtt40 and 19.7 to 32.1 on relay-mic-stall, and fell from 15.1 to 14.3 on local-aac: a lag under a hop is corrected only once its pace adds up to one. player_underruns_per_min rose from 4.4 to 6.6 on bursty-aac and 4 to 8.1 on local-aac, whose recorded outages outlast what slowing down at 10% bridges, and fell from 3.1 to 1 on relay-mic-rtt40, whose tap's underruns fell from 0.7 to 0.3 a minute; bursty-aac's silence rose from 0.007 to 0.008. Nothing more is trimmed on any row. The browser and native rows were measured on a loaded developer host (x86_64 Linux, the debug build, seed 7, 60 s a row) against main the same day and left to the nightly runner: every browser row's A/V lag p50 now sits between 27 and 39 ms, where the fixed-250 control does on that host, where wide and bursty sat up to 58 ms behind, and every native row's within 15 ms of the clock. Also on 2026-11-14 the estimator stopped folding the intervals a subscription's join spans, those holding a frame due before its backlog finished arriving, and every replay row was re-measured: only relay-mic and relay-mic-stall moved. Their first frame arrives slower than the path after it, so their first interval folds nothing and the target leaves the prior 500 ms later, which moves where audio rests within the half hop the rule leaves alone: relay-mic's A/V lag p50 from 1.8 to -0.3 ms and p95 from 6.9 to 9, and relay-mic-stall's p50 from 3.1 to 1.7. relay-mic-rtt40 did not move: the browser consumer closes its join's stale groups below the cursor unread, so the estimator never sees when that backlog ended, and its target p95 held at 320 ms. Later on 2026-11-14 both container consumers began reporting when each group they close unread arrived, if it is at or below the publisher's largest group as the subscription began, which extends a join still open. On 2026-11-15 the traces gained that largest group (version 4), so the replay's consumer learns it as a wire subscriber does, and relay-mic-rtt40 was re-measured: its target p95 fell from 320 to 120 ms, underruns per minute rose from 0.3 to 0.7, player skips per minute fell from 0.3 to 0, trimmed ms per minute from 83 to 0, A/V lag p50 rose from 0.6 to 2.3 ms and p95 from 6.9 to 8.6, the trade of reporting the join's backlog. No other replay row moved. On 2026-11-17 the browser player began reading audio through the ordered reader, which waits for a hole as long as the ring could still play it and reports each half-open range of keys it gives up on as one gap, and the replay dropped the trace's largest group: a second subscription now observes every arrival for the estimate, the join's backlog included. Every replay row was re-measured. bursty-aac's player underruns per minute fell from 6.6 to 4.4 and silence share from 0.008 to 0.007; audio rests at 0.1 ms until a stall at 19.5 s, from which the stretch catches up to 4.2 ms behind the clock, inside the half hop it leaves alone, so its A/V lag p50 and p95 rose from 0.2 to 4.2 ms. relay-bbb's A/V lag p50 fell from 2.7 to 1.4 ms and p95 rose from 6.2 to 7.6. relay-mic-rtt40's underruns per minute fell from 0.7 to 0.3, as did its player underruns per minute, underrun ms per minute from 0.8 to 0.2, A/V lag p50 from 2.3 to 0.6 ms, and p95 rose from 8.6 to 9.7, its target p95 holding at 120 ms; 0.6 ms of that rise is the replay's ordered reader taking the catalog's warmup into its budget, as the browser's does. No other replay row moved.", "rows": [ { "runtime": "chromium",