diff --git a/js/net/src/connection/pool.test.ts b/js/net/src/connection/pool.test.ts index e9dc3a9d313..101114ca703 100644 --- a/js/net/src/connection/pool.test.ts +++ b/js/net/src/connection/pool.test.ts @@ -3,10 +3,10 @@ import { type Installed, Manual, Milli, Nano } from "@moq/clock"; import { Signal } from "@moq/signals"; import { SessionCode, SessionError } from "../error.ts"; import * as Lite from "../lite/index.ts"; -import { createMockTransportPair } from "../mock.ts"; +import { createMockTransportPair, type MockTransport } from "../mock.ts"; import { Producer as OriginProducer, type Table } from "../origin.ts"; import * as Path from "../path.ts"; -import { Stream } from "../stream.ts"; +import { Stream, Writer } from "../stream.ts"; import * as Time from "../time.ts"; import { connect } from "./connect.ts"; import { type AcceptProps, accept as acceptSession } from "./index.ts"; @@ -598,6 +598,72 @@ test("pooled probe readers share demand and carry it through reconnects", async } }); +/** + * Play a lite-06 peer on `server` that advertises PROBE `Increase`, returning each PROBE + * target it reads, with 0 for a retraction. + */ +function increasePeer(server: MockTransport): number[] { + const version = Lite.Version.DRAFT_06; + const targets: number[] = []; + const readProbe = async (stream: Stream) => { + if ((await stream.reader.u53()) !== Lite.StreamId.Probe) return; + for (;;) { + const probe = await Lite.Probe.decodeMaybe(stream.reader, version); + if (!probe) return; + targets.push(probe.bitrate ?? 0); + } + }; + const run = async () => { + const setup = await Writer.open(server, { version }); + await setup.u53(Lite.DataType.Setup); + await new Lite.Setup({ probe: Lite.ProbeLevel.Increase }).encode(setup, version); + setup.close(); + for (;;) { + const stream = await Stream.accept(server, version); + if (!stream) return; + // The session's end ends every read. + void readProbe(stream).catch(() => {}); + } + }; + void run().catch(() => {}); + return targets; +} + +test("pooled viewers send their summed target to an Increase peer across a reconnect", async () => { + const peers: { server: MockTransport; targets: number[] }[] = []; + const stub = function StubWebTransport() { + const pair = createMockTransportPair(Lite.ALPN_06); + peers.push({ server: pair.server, targets: increasePeer(pair.server) }); + return pair.client; + }; + globalThis.WebTransport = stub as unknown as typeof WebTransport; + const first = new Connection({ url }); + const second = new Connection({ url }); + try { + await advance(); + const one = first.viewers.peek()?.watch(3_000_000); + const two = second.viewers.peek()?.watch(2_000_000); + await advance(); + expect(peers).toHaveLength(1); + expect(peers[0].targets.at(-1)).toBe(5_000_000); + + peers[0].server.close({ closeCode: SessionCode.Internal, reason: "reconnect" }); + await advance(2_000); + expect(peers).toHaveLength(2); + expect(peers[1].targets).toEqual([5_000_000]); + + // The new session follows the live handles, not a snapshot of them. + one?.close(); + await advance(); + expect(peers[1].targets).toEqual([5_000_000, 2_000_000]); + two?.close(); + } finally { + first.close(); + second.close(); + await advance(linger); + } +}); + test("a handle's announcements sync with the shared origin", async () => { stubTransports(); diff --git a/js/net/src/lite/subscriber.test.ts b/js/net/src/lite/subscriber.test.ts index 3dbc4bc20e2..5f99860d3a7 100644 --- a/js/net/src/lite/subscriber.test.ts +++ b/js/net/src/lite/subscriber.test.ts @@ -2937,6 +2937,8 @@ function probeTargetHarness(level: ProbeLevel, options?: { failTarget?: boolean; let writes = 0; let stall!: () => void; const stalled = new Promise((resolve) => (stall = resolve)); + let release!: () => void; + const released = new Promise((resolve) => (release = resolve)); let reset!: (reason: unknown) => void; const aborted = new Promise((resolve) => (reset = resolve)); const quic = { @@ -2947,10 +2949,12 @@ function probeTargetHarness(level: ProbeLevel, options?: { failTarget?: boolean; // Only the stream type precedes the first target. if (writes++ > 0) { if (options?.failTarget) throw new Error("write failed"); - // A peer that never drains the stream: only a reset ends the write. - if (options?.stallTarget) { + // A peer that stops draining the stream at the first target: only `release` + // or a reset ends that write. + if (options?.stallTarget && writes === 2) { stall(); - await new Promise((_, reject) => { + await new Promise((resolve, reject) => { + void released.then(resolve); controller.signal.addEventListener("abort", () => { reset(controller.signal.reason); reject(controller.signal.reason); @@ -2971,6 +2975,7 @@ function probeTargetHarness(level: ProbeLevel, options?: { failTarget?: boolean; sent, version, stalled, + release, aborted, finish: () => inbound.close(), }; @@ -2979,6 +2984,9 @@ function probeTargetHarness(level: ProbeLevel, options?: { failTarget?: boolean; // The viewers' sum reaches the peer as its PROBE target: only once nonzero, on every change, // and retracted with a zero, while an opt-out sends nothing at all. test("the PROBE stream sends the viewers' target to an Increase peer", async () => { + const clock = new Manual(); + const installed = clock.install(); + using _clock = { [Symbol.dispose]: () => installed.close() }; const { subscriber, sent, version, finish } = probeTargetHarness(ProbeLevel.Increase); const viewers = new Viewers(); viewers.setTarget(0); @@ -3000,6 +3008,9 @@ test("the PROBE stream sends the viewers' target to an Increase peer", async () second.close(); expect((await Probe.decode(sent, version)).bitrate).toBeUndefined(); + // Reading the target back only proves its bytes were written: the writer may still be + // yielding its write budget, and a FIN then would reset the stream instead of closing it. + await clock.advance(Nano.zero); finish(); await running; expect(await sent.done()).toBe(true); @@ -3041,6 +3052,39 @@ test("ending the probe resets a stalled PROBE target write", async () => { viewers.close(); }); +// A peer that stops reading holds one target: the changes made meanwhile queue nothing +// behind it, and only the latest is sent once the write drains. +test("a stalled PROBE writer sends only the latest target once it drains", async () => { + const clock = new Manual(); + const installed = clock.install(); + using _clock = { [Symbol.dispose]: () => installed.close() }; + const { subscriber, sent, version, stalled, release, finish } = probeTargetHarness(ProbeLevel.Increase, { + stallTarget: true, + }); + const viewers = new Viewers(); + const viewer = viewers.watch(1_000_000); + const running = subscriber.runProbe(undefined, viewers.target); + expect(await sent.u53()).toBe(StreamId.Probe); + await stalled; + + for (const rate of [2_000_000, 3_000_000, 4_000_000]) { + viewer.update(rate); + await drainReactions(); + } + release(); + expect((await Probe.decode(sent, version)).bitrate).toBe(1_000_000); + expect((await Probe.decode(sent, version)).bitrate).toBe(4_000_000); + + // Let the last write finish yielding before the FIN, as in the test above. + await clock.advance(Nano.zero); + finish(); + await running; + expect(await sent.done()).toBe(true); + viewer.close(); + subscriber.close(); + viewers.close(); +}); + // A Report-level peer only measures, so it is never sent a target to ignore. test("the PROBE stream sends no target to a Report peer", async () => { const { subscriber, sent, finish } = probeTargetHarness(ProbeLevel.Report); diff --git a/py/moq-rs/docs/index.md b/py/moq-rs/docs/index.md index ca99b9bde53..e3263960e4b 100644 --- a/py/moq-rs/docs/index.md +++ b/py/moq-rs/docs/index.md @@ -87,6 +87,29 @@ asyncio.run(main()) GroupConsumer ``` +## Bandwidth + +A session's estimates, split among what shares the connection: an `Allocator` +divides the send estimate among tracks, which a `RateControl` turns into each sender's +`RateTarget`, and `Viewers` divides the receive estimate among watched broadcasts, +whose ceilings summed ask the peer to probe for more. + +```{eval-rst} +.. currentmodule:: moq + +.. autosummary:: + :toctree: api + :nosignatures: + + Allocator + Reservation + RateControl + RateTarget + BandwidthConsumer + Viewers + Viewer +``` + ## Native codecs ```{eval-rst} diff --git a/quest/m2/probe/README.md b/quest/m2/probe/README.md index 88931d6bae5..6d4ccd373eb 100644 --- a/quest/m2/probe/README.md +++ b/quest/m2/probe/README.md @@ -102,7 +102,6 @@ This README's own work, once the children land: - [JS rung disable](/quest/m2/probe/rung-disable-js.md) - `@moq/publish` applies the native rung rule, recovering through padding - [Players set viewer targets](/quest/m2/probe/players.md) - players hold a viewer handle per watched broadcast at its highest enabled rendition's bitrate - [Viewer up-switch](/quest/m2/probe/viewer-upswitch.md) - a viewer capped by its small rendition finds headroom through PROBE and moves up -- [Viewer targets are tested end to end and documented in Python](/quest/m2/probe/viewer-followups.md) - three gaps moq-dev/moq#7090 left are closed ## Related diff --git a/quest/m2/probe/viewer-followups.md b/quest/m2/probe/viewer-followups.md deleted file mode 100644 index 7b3812a2d15..00000000000 --- a/quest/m2/probe/viewer-followups.md +++ /dev/null @@ -1,39 +0,0 @@ -# [M] Viewer targets are tested end to end and documented in Python - -## Goal - -Three gaps [moq-dev/moq#7090](https://github.com/moq-dev/moq/pull/7090) -left are closed: - -- A `js/net` test shows a viewer's target reaching a fake peer that - advertises PROBE `Increase` over a pooled connection, and reaching it - again after the connection reconnects. -- A test in each language stalls the PROBE writer and shows one target in - flight, with the latest target sent once the writer drains. -- `py/moq-rs/docs/index.md` has a Bandwidth section listing `Allocator`, - `Reservation`, `BandwidthConsumer`, `Viewers`, and `Viewer`. - -## Plan - -Decided 2026-10-31 (user, /quest-plan of the follow-ups from the 2026-10-31 /quest-complete run), from [moq-dev/moq#7090](https://github.com/moq-dev/moq/pull/7090), -which finishes viewer targets. - -- Pooled reconnect: the `Reload`/pool `viewers` wiring - (`js/net/src/connection/reload.ts`) is covered only by type checks and - the subscriber's wire tests. Drive a reconnect through the pool against a - fake peer and assert the live handles' sum arrives on the new session. -- Stalled PROBE: [moq-dev/moq#7090](https://github.com/moq-dev/moq/pull/7090) fixed targets piling up behind a blocked PROBE - writer but couldn't test it, since the test setups can't stall a stream. - Use a transport double whose PROBE stream stops granting credit (Rust: - the in-memory session; JS: a fake writer whose pending write the test - resolves by hand). Assert one target is in flight, change the target - several times, release the write, and assert exactly the latest target is - sent. -- Python docs: list the five types with one-line descriptions, following - the file's existing sections. - -Native players (`moq play`, `moqsrc`, and the OBS source) holding a -viewer once they adapt renditions is [players](/quest/m2/probe/players.md)' -work, not this quest's. - -Public API: none (tests and docs). Wire: none. diff --git a/rs/moq-net/src/lite/subscriber.rs b/rs/moq-net/src/lite/subscriber.rs index 0ac030e46ae..d9752196067 100644 --- a/rs/moq-net/src/lite/subscriber.rs +++ b/rs/moq-net/src/lite/subscriber.rs @@ -6721,6 +6721,78 @@ mod tests { } } + /// A peer that stops reading holds one PROBE target, and once it drains, only the + /// latest is sent: the targets set while the writer was stalled never pile up behind it. + #[kio::test] + async fn a_stalled_probe_writer_sends_only_the_latest_target() { + use crate::transport::poll::{RecvStream as _, Session as _}; + let version = Version::Lite06; + // One queued message per stream, so a peer that stops reading stalls the writer. + let config = crate::transport::memory::Config { + stream_buffer: 0, + ..Default::default() + }; + let (session, peer) = crate::transport::memory::pair(config); + let producer = bandwidth::Producer::new(); + let _estimate = producer.consume(); + let peer_setup = lite::PeerSetup::new(false, crate::transport::Address::Setup); + peer_setup + .set(lite::Setup { + probe: lite::ProbeLevel::Increase, + ..Default::default() + }) + .unwrap(); + let subscriber = Subscriber::new(SubscriberConfig { + runtime: crate::time::sim(), + session: crate::driver::Transport::new(session.clone()), + origin: origin::Config::new(crate::Hop::new(1).unwrap()).produce(), + recv_bandwidth: Some(producer), + version, + peer_setup, + peer_hop: None, + cost: None, + going_away: Default::default(), + auth: crate::auth::Link::new(false), + }); + let viewer = subscriber.viewers.watch(bandwidth::Rate::from_mbps(1)).unwrap(); + let mut probe = RecvBandwidth::new(subscriber); + + // The stream type fills the stream, so the first target waits in the writer. + let (_send, mut recv) = kio::wait(|waiter| { + let _ = probe.poll(waiter); + peer.poll_accept_bi(waiter) + }) + .await + .unwrap(); + assert!(probe.poll(&kio::Waiter::noop()).is_pending()); + for mbps in 2..=4 { + viewer.update(bandwidth::Rate::from_mbps(mbps)).unwrap(); + assert!(probe.poll(&kio::Waiter::noop()).is_pending()); + } + + let target = |mbps| lite::Probe { + bitrate: Some(bandwidth::Rate::from_mbps(mbps).as_bps()), + rtt: None, + }; + let expected = [ + lite::ControlType::Probe.encode_bytes(version).unwrap(), + target(1).encode_bytes(version).unwrap(), + target(4).encode_bytes(version).unwrap(), + ]; + for expected in expected { + let chunk = kio::wait(|waiter| { + let _ = probe.poll(waiter); + recv.poll_read_chunk(waiter, usize::MAX) + }) + .await + .unwrap() + .expect("the stream stays open"); + assert_eq!(chunk, expected); + } + assert!(probe.poll(&kio::Waiter::noop()).is_pending()); + assert!(recv.poll_read_chunk(&kio::Waiter::noop(), usize::MAX).is_pending()); + } + /// The model's groups map to wire ranges starting and ending at a group's first frame, /// with empty ranges dropped. Off by one here would silently drop or duplicate a group /// at every relay hop.