From 87c19b198396bb99e8083d9959e2a26eb5177ac5 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 28 Oct 2026 05:09:38 -0700 Subject: [PATCH 01/20] chore(quest): claim quest/m2/probe/viewer-target.md Quest-Claim: b5533f79e32a2134 From 0158e795011584bf0ab481db2157239b792464be Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 28 Oct 2026 05:36:39 -0700 Subject: [PATCH 02/20] feat(net): viewer probe targets and receive grants A session divides its receive estimate among viewer handles, one per watched broadcast, and sends their ceilings summed to the peer as its PROBE target. A session with a sender advertises Increase and probes to the larger of its own reservations and the peer's target. Co-Authored-By: Claude Opus 5.5 --- doc/concept/standard.md | 7 +- doc/lib/js/net.md | 1 + js/net/api/index.api.md | 16 + js/net/src/bandwidth.test.ts | 88 ++++- js/net/src/bandwidth.ts | 325 +++++++++++++----- js/net/src/bandwidth_api.ts | 2 +- js/net/src/connection/connect.ts | 13 +- js/net/src/connection/pool.ts | 15 +- js/net/src/connection/reload.ts | 19 +- js/net/src/lite/connection.ts | 8 +- js/net/src/lite/subscriber.test.ts | 81 +++++ js/net/src/lite/subscriber.ts | 27 +- rs/moq-net/benches/bandwidth.rs | 26 +- rs/moq-net/src/client.rs | 29 ++ rs/moq-net/src/fuzz.rs | 7 +- rs/moq-net/src/lite/publisher.rs | 36 +- rs/moq-net/src/lite/session.rs | 15 + rs/moq-net/src/lite/setup.rs | 21 +- rs/moq-net/src/lite/subscriber.rs | 52 ++- rs/moq-net/src/model/bandwidth.rs | 243 +++++++++++-- rs/moq-net/src/server.rs | 12 + rs/moq-net/src/session.rs | 84 ++++- rs/moq-net/tests/integration/main.rs | 1 + .../tests/integration/support/harness.rs | 5 + rs/moq-net/tests/integration/support/mock.rs | 23 ++ rs/moq-net/tests/integration/viewer_target.rs | 134 ++++++++ rs/moq-tokio/src/client.rs | 6 + rs/moq-tokio/src/connection.rs | 15 +- 28 files changed, 1158 insertions(+), 153 deletions(-) create mode 100644 rs/moq-net/tests/integration/viewer_target.rs diff --git a/doc/concept/standard.md b/doc/concept/standard.md index 6d56cad8c94..b84acc7d2d9 100644 --- a/doc/concept/standard.md +++ b/doc/concept/standard.md @@ -50,8 +50,11 @@ before a `SUBSCRIBE_NAMESPACE` is synced, [epoch](/draft/moq-epoch) to carry [publisher epochs](/concept/moq-lite#publisher-epochs) without changing a path, and [probe](/draft/moq-probe) for bandwidth estimation. Rust sessions request PROBE -only while an owned `recv_bandwidth()` consumer is held. Read estimates through -its `peek()` or `changed()` methods; session statistics do not request PROBE. +only while an owned `recv_bandwidth()` consumer or a `viewers()` viewer is held. +Read estimates through its `peek()` or `changed()` methods; session statistics do +not request PROBE. The viewers' ceilings, summed, are the PROBE target, sent only +to a peer advertising `Increase`, which a native session over moq-quic with BBR3 +does and a browser session does not yet. Both libraries offer solicit, auth, and epoch unless a side's `extensions` setting declines one, which connects it as a peer that does not speak that extension. The pooled JavaScript `Connection` has no such setting yet. diff --git a/doc/lib/js/net.md b/doc/lib/js/net.md index 6d05c601615..37b60da1f65 100644 --- a/doc/lib/js/net.md +++ b/doc/lib/js/net.md @@ -47,6 +47,7 @@ publication.announce(); - **Connections share by URL and versions.** `new Connection({ url })` pools and reconnects with backoff, which the elements use. An ordered `versions` list, spelled like `moq-lite-06` as in Rust, applies to both WebTransport and WebSocket; equivalent lists share, while a different order or an omitted list gets its own pool entry. Supplying your own transport options or origin selects a private loop. Receive estimates are on demand: observe `connection.probe` reactively or subscribe while you need them; `peek()` alone opens no PROBE stream. - **GOAWAY moves the session.** The connection dials the replacement at once while the old session keeps serving its groups, up to `goaway.handover` (default 10s, or the relay's deadline when that is sooner). New requests keep opening on the old session until the replacement's route outranks it, which is a restart without an epoch: an unpinned announced request follows the replacement, while a blind or epoch-pinned request stays on its accepted instance. With an epoch, which travels only when `moq-lite-07-wip` is offered, the replacement serves the same broadcast, so open subscriptions move across without missing a group. An empty GOAWAY redials the same URL. A redirect stays on the same host unless `goaway.redirect` is `"follow"`, which also presents the tokens on the connection's `auth` handle to the new host. - **One send estimate per connection.** `Bandwidth.Allocator` divides it by track priority, max-min fair within a tier. An idle track claims nothing, though its reservation still reads the share it would get. Publishers reserve against it so their targets sum to the estimate. +- **One receive estimate per connection.** `connection.viewers` divides it among watched broadcasts, max-min fair by each viewer's ceiling, so several players on one pooled connection don't each select against the whole downlink. Holding a viewer requests PROBE, and the viewers' ceilings, summed, are the PROBE target a relay advertising `Increase` probes the downlink up to. `setTarget(0)` opts out. - **List a broadcast's tracks.** `for await (const event of broadcast.tracks())` reports each track the broadcast lists (`added`, with its `Track.Info`), one `synced`, then `added` and `removed` as tracks come and go, until the broadcast ends; leaving the loop stops listing. Over a session it needs `moq-lite-07-wip`, syncs at once with what this side holds, and the peer's tracks follow as `added`. A track served only on request is never listed. See [discovery](/concept/moq-lite#discovery). - **One track per name.** Concurrent subscriptions share one request and producer. `createTrack` on a name with a request still queued answers it. The application owns sequence numbers: the broadcast keeps nothing of an ended track, so a track that replaces it, created or requested, starts at 0. A name always means the same content, so the replacement continues past its predecessor's groups by writing its first group with an explicit sequence. - **Timing is per track, with no default.** A track that declares a `timescale` carries a `timestamp` on every frame; one without is [untimed](/concept/moq-lite#subscriptions) and its frames carry none. Omitting it means untimed, as in Rust. Nothing stamps a frame for you: the publisher passes the timestamp, and the `Timed` type (`{ value, at }`) carries one into the `@moq/json` and `@moq/flate` producers. diff --git a/js/net/api/index.api.md b/js/net/api/index.api.md index 550c115edfa..487f2f97932 100644 --- a/js/net/api/index.api.md +++ b/js/net/api/index.api.md @@ -70,6 +70,20 @@ export namespace Bandwidth { get rate(): Signals.Getter; update(max: number): void; } + export class Viewer implements Disposable { + [Symbol.dispose](): void; + close(): void; + peek(): number | undefined; + get rate(): Signals.Getter; + update(max: number): void; + } + export class Viewers { + constructor(estimate?: Signals.Getter); + close(): void; + setTarget(target: number | undefined): void; + readonly target: Signals.Getter; + watch(max: number): Bandwidth.Viewer; + } } export namespace Broadcast { @@ -146,6 +160,7 @@ export namespace Connection { transport?: WebTransport; url: URL; versions?: readonly string[]; + viewers?: Bandwidth.Viewers; websocket?: Connection.WebSocketProps; webtransport?: Connection.WebTransportProps; } @@ -236,6 +251,7 @@ export class Connection { readonly transport: Signals.Getter; url: Signals.Signal; versions: Signals.Signal; + readonly viewers: Signals.Getter | undefined>; } export namespace Epoch { diff --git a/js/net/src/bandwidth.test.ts b/js/net/src/bandwidth.test.ts index 92c9d1269d3..0f828ee0f16 100644 --- a/js/net/src/bandwidth.test.ts +++ b/js/net/src/bandwidth.test.ts @@ -1,7 +1,8 @@ import { expect, test } from "bun:test"; import { Signal } from "@moq/signals"; -import { Allocator, allocate, type Want } from "./bandwidth.ts"; +import { Allocator, allocate, Viewers, type Want } from "./bandwidth.ts"; import { Producer as TrackProducer } from "./track.ts"; +import { Observed } from "./util/observed.ts"; /** Priorities matching hang's, which is what the allocator sees in practice. */ const AUDIO = 80; @@ -313,3 +314,88 @@ test("reserve and update reject a non-finite or negative ceiling", () => { allocator.close(); }); + +// Several players on one connection must not each select against the whole downlink: +// the receive estimate splits max-min fair by each viewer's ceiling, and never sums above it. +test("viewers split the receive estimate max-min fair", () => { + const estimate = new Signal(6_000_000); + const viewers = new Viewers(estimate); + + const small = viewers.watch(1_000_000); + const large = viewers.watch(8_000_000); + expect(small.peek()).toBe(1_000_000); + expect(large.peek()).toBe(5_000_000); + + // Three even claims on a link too small for any of them: an even cut each, never above it. + estimate.set(2_000_000); + small.update(4_000_000); + large.update(4_000_000); + const third = viewers.watch(4_000_000); + const grants = [small.peek() ?? 0, large.peek() ?? 0, third.peek() ?? 0]; + for (const grant of grants) expect(Math.abs(grant - 666_666)).toBeLessThanOrEqual(1); + expect(grants.reduce((sum, grant) => sum + grant, 0)).toBe(2_000_000); + + // No estimate is "hold your selection", not zero. + estimate.set(undefined); + expect(small.peek()).toBeUndefined(); + + viewers.close(); +}); + +test("the viewers' target sums their ceilings until overridden", () => { + const viewers = new Viewers(new Signal(1_000_000)); + expect(viewers.target.peek()).toBe(0); + + const first = viewers.watch(1_000_000); + const second = viewers.watch(2_000_000); + expect(viewers.target.peek()).toBe(3_000_000); + + second.update(4_000_000); + expect(viewers.target.peek()).toBe(5_000_000); + + // Zero turns probing off; clearing the override follows the viewers again. + viewers.setTarget(0); + expect(viewers.target.peek()).toBe(0); + viewers.setTarget(10_000_000); + expect(viewers.target.peek()).toBe(10_000_000); + viewers.setTarget(undefined); + expect(viewers.target.peek()).toBe(5_000_000); + + first.close(); + expect(viewers.target.peek()).toBe(4_000_000); + second.close(); + expect(viewers.target.peek()).toBe(0); + + viewers.close(); +}); + +// Observing a connection's receive estimate is what requests PROBE, so a registry with +// nobody watching must not hold that demand. +test("an idle viewers registry does not observe the estimate", async () => { + const estimate = new Observed(1_000_000); + const viewers = new Viewers(estimate); + expect(estimate.used.peek()).toBe(false); + + const viewer = viewers.watch(1_000_000); + await settled(); + expect(estimate.used.peek()).toBe(true); + + viewer.close(); + await settled(); + expect(estimate.used.peek()).toBe(false); + + viewers.close(); +}); + +// Let queued signal reactions run without relying on host timers. +function settled(): Promise { + return new Promise((resolve) => { + const channel = new MessageChannel(); + channel.port1.onmessage = () => { + channel.port1.close(); + channel.port2.close(); + resolve(); + }; + channel.port2.postMessage(null); + }); +} diff --git a/js/net/src/bandwidth.ts b/js/net/src/bandwidth.ts index 5e2788d2d1a..2dedb218655 100644 --- a/js/net/src/bandwidth.ts +++ b/js/net/src/bandwidth.ts @@ -5,9 +5,13 @@ * an {@link Allocator} rather than each targeting the whole thing. How a sender * then follows its share is policy and lives with the sender. * + * The receive direction mirrors it: {@link Viewers} divides the receive estimate + * among the broadcasts watched over one connection, and their ceilings summed are + * the PROBE target the connection asks its peer to probe up to. + * * @module */ -import { Effect, type Getter, Signal } from "@moq/signals"; +import { Derived, Effect, type Getter, Signal } from "@moq/signals"; import { hooks } from "./internal.ts"; import type { Demand } from "./track.ts"; @@ -78,7 +82,8 @@ export function allocate(estimate: number, wants: readonly Want[], id: number): interface Entry { id: number; - demand: Demand; + /** The track whose demand gates the claim, or undefined for a claim that is always active. */ + demand?: Demand; priority: number; max: number; rate: Signal; @@ -93,8 +98,10 @@ interface Registry { function wantsOf(entries: readonly Entry[]): Want[] { const wants: Want[] = []; for (const entry of entries) { - if (hooks.demandReleased(entry.demand).peek() !== undefined) continue; - if (entry.demand.wanted.peek() === undefined) continue; + if (entry.demand) { + if (hooks.demandReleased(entry.demand).peek() !== undefined) continue; + if (entry.demand.wanted.peek() === undefined) continue; + } wants.push({ id: entry.id, priority: entry.priority, max: entry.max }); } return wants; @@ -108,9 +115,11 @@ function wantsOf(entries: readonly Entry[]): Want[] { * needs that to know when to resume. */ function shareOf(estimate: number, wants: readonly Want[], entry: Entry): number | undefined { - if (entry.demand.closed.peek() !== undefined) return undefined; - if (entry.demand.wanted.peek() === undefined) { - wants = [...wants, { id: entry.id, priority: entry.priority, max: entry.max }]; + if (entry.demand) { + if (entry.demand.closed.peek() !== undefined) return undefined; + if (entry.demand.wanted.peek() === undefined) { + wants = [...wants, { id: entry.id, priority: entry.priority, max: entry.max }]; + } } return allocate(estimate, wants, entry.id); } @@ -122,6 +131,117 @@ function ceiling(max: number): number { return max; } +/** + * The registry behind {@link Allocator} and {@link Viewers}: divides one estimate + * among its claims, publishing each claim's slice. + */ +class Divider { + #estimate: Getter | undefined; + readonly entries = new Signal([]); + #alive = new Signal(true); + #nextId = 0; + #signals = new Effect(); + #registry: Registry; + + constructor(estimate?: Getter) { + this.#estimate = estimate; + + this.#registry = { + peek: (id) => this.#peek(id), + update: (id, max) => this.#update(id, max), + release: (id) => this.#release(id), + }; + + this.#signals.run((effect) => { + if (!effect.get(this.#alive)) return; + const entries = effect.get(this.entries); + // Observe the estimate only while something claims it: reading a session's + // receive estimate is what requests PROBE, so an empty registry asks for nothing. + if (entries.length === 0) return; + if (this.#estimate) effect.get(this.#estimate); + for (const entry of entries) { + if (!entry.demand) continue; + effect.get(entry.demand.wanted); + effect.get(hooks.demandReleased(entry.demand)); + } + this.#publish(); + }); + } + + /** Claim up to `max`, active whenever `demand` is, or always without one. */ + claim(demand: Demand | undefined, priority: number, max: number): Reservation { + max = ceiling(max); + this.#prune(); + + const id = this.#nextId++; + const rate = new Signal(undefined); + this.entries.mutate((entries) => { + entries.push({ id, demand, priority, max, rate }); + }); + + const reservation = makeReservation(this.#registry, id, rate); + this.#publish(); + return reservation; + } + + close(): void { + if (!this.#alive.peek()) return; + this.#alive.set(false); + for (const entry of this.entries.peek()) { + entry.rate.set(undefined); + } + this.entries.set([]); + this.#signals.close(); + } + + #prune(): void { + const entries = this.entries.peek(); + const live = entries.filter( + (entry) => !entry.demand || hooks.demandReleased(entry.demand).peek() === undefined, + ); + if (live.length !== entries.length) this.entries.set(live); + } + + #publish(): void { + if (!this.#alive.peek()) return; + const estimate = this.#estimate?.peek(); + const entries = this.entries.peek(); + const wants = wantsOf(entries); + for (const entry of entries) { + entry.rate.set(estimate == null ? undefined : shareOf(estimate, wants, entry)); + } + } + + #peek(id: number): number | undefined { + if (!this.#alive.peek()) return undefined; + const estimate = this.#estimate?.peek(); + if (estimate == null) return undefined; + const entries = this.entries.peek(); + const entry = entries.find((candidate) => candidate.id === id); + if (!entry) return undefined; + return shareOf(estimate, wantsOf(entries), entry); + } + + #update(id: number, max: number): void { + if (!this.#alive.peek()) return; + max = ceiling(max); + this.entries.mutate((entries) => { + const entry = entries.find((candidate) => candidate.id === id); + if (entry) entry.max = max; + }); + this.#publish(); + } + + #release(id: number): void { + if (!this.#alive.peek()) return; + this.entries.mutate((entries) => { + const index = entries.findIndex((entry) => entry.id === id); + if (index >= 0) entries.splice(index, 1); + }); + this.#publish(); + } +} + /** * A non-owning handle on an allocator: reserve a slice, without its lifecycle. * @@ -151,12 +271,7 @@ export interface Handle { * Hand the same instance to every sender on the connection. */ export class Allocator implements Handle { - #estimate: Getter | undefined; - #entries = new Signal([]); - #alive = new Signal(true); - #nextId = 0; - #signals = new Effect(); - #registry: Registry; + #divider: Divider; /** * Divide `estimate`, normally a connection's sampled send rate. @@ -165,24 +280,7 @@ export class Allocator implements Handle { * reports `undefined`, which already means "no opinion, hold your rate". */ constructor(estimate?: Getter) { - this.#estimate = estimate; - - this.#registry = { - peek: (id) => this.#peek(id), - update: (id, max) => this.#update(id, max), - release: (id) => this.#release(id), - }; - - this.#signals.run((effect) => { - if (!effect.get(this.#alive)) return; - if (this.#estimate) effect.get(this.#estimate); - const entries = effect.get(this.#entries); - for (const entry of entries) { - effect.get(entry.demand.wanted); - effect.get(hooks.demandReleased(entry.demand)); - } - this.#publish(); - }); + this.#divider = new Divider(estimate); } /** @@ -219,83 +317,130 @@ export class Allocator implements Handle { * report the slice the track would get back, without claiming it from the others. */ reserve(track: Demand, max: number): Reservation { - max = ceiling(max); - this.#prune(); + return this.#divider.claim(track, hooks.demandPriority(track), max); + } - const id = this.#nextId++; - const rate = new Signal(undefined); - this.#entries.mutate((entries) => { - entries.push({ - id, - demand: track, - priority: hooks.demandPriority(track), - max, - rate, - }); + /** + * Stop dividing. Existing reservations report `undefined` and further + * {@link reserve} calls still return a handle that never claims. + */ + close(): void { + this.#divider.close(); + } +} + +/** + * Divides one connection's receive estimate among the broadcasts watched over it. + * + * The receive-side mirror of {@link Allocator}. Every player on a connection reads the + * same receive estimate, so N players each selecting against all of it oversubscribe + * the downlink N times over. {@link watch} a broadcast here and its {@link Viewer} + * reports only its own slice, split max-min fair by each viewer's ceiling, so the + * slices sum to the estimate instead of each matching it. Viewers carry no priority: + * a viewer asking for less than an even cut takes all it asked for and leaves the + * rest to the others. + * + * The viewers' ceilings summed are also the PROBE target the connection sends its + * peer, which probes up to it when it advertised `Increase`, so the estimate can rise + * to fund a larger rendition. The target never leaves this hop. + * + * The estimate is observed only while a viewer is live, since observing a + * connection's receive estimate is what requests PROBE. + */ +export class Viewers { + #divider: Divider; + #override = new Signal(undefined); + + /** + * The PROBE target: the live viewers' ceilings summed, or the {@link setTarget} override. + * Zero sends no target. + */ + readonly target: Getter; + + /** Divide `estimate`, normally a connection's receive estimate from PROBE. */ + constructor(estimate?: Getter) { + this.#divider = new Divider(estimate); + this.target = new Derived([this.#divider.entries, this.#override], (entries, override) => { + if (override !== undefined) return override; + let sum = 0; + for (const entry of entries) sum += entry.max; + return sum; }); + } - const reservation = makeReservation(this.#registry, id, rate); - this.#publish(); - return reservation; + /** + * Watch a broadcast receiving at most `max` bits per second, returning its viewer. + * + * `max` is a ceiling: what the largest rendition the player would switch to needs, + * not what it happens to be receiving. The claim lasts until {@link Viewer.close}: + * change the ceiling with {@link Viewer.update}, and close it once the broadcast + * stops being watched. + */ + watch(max: number): Viewer { + return makeViewer(this.#divider.claim(undefined, 0, max)); } /** - * Stop dividing. Existing reservations report `undefined` and further - * {@link reserve} calls still return a handle that never claims. + * Send `target` as the PROBE target instead of the viewers' sum, or `undefined` to follow them again. + * + * `0` turns probing off: the connection sends no target. */ + setTarget(target: number | undefined): void { + this.#override.set(target === undefined ? undefined : ceiling(target)); + } + + /** Stop dividing. Existing viewers report `undefined` and release their claims. */ close(): void { - if (!this.#alive.peek()) return; - this.#alive.set(false); - for (const entry of this.#entries.peek()) { - entry.rate.set(undefined); - } - this.#entries.set([]); - this.#signals.close(); + this.#divider.close(); } +} - #prune(): void { - const entries = this.#entries.peek(); - const live = entries.filter((entry) => hooks.demandReleased(entry.demand).peek() === undefined); - if (live.length !== entries.length) this.#entries.set(live); +let makeViewer: (reservation: Reservation) => Viewer; + +/** + * One watched broadcast's standing claim on {@link Viewers}, held for as long as it is watched. + * + * Close it to release the claim and lower the PROBE target. + */ +export class Viewer implements Disposable { + readonly #reservation: Reservation; + + private constructor(reservation: Reservation) { + this.#reservation = reservation; } - #publish(): void { - if (!this.#alive.peek()) return; - const estimate = this.#estimate?.peek(); - const entries = this.#entries.peek(); - const wants = wantsOf(entries); - for (const entry of entries) { - entry.rate.set(estimate == null ? undefined : shareOf(estimate, wants, entry)); - } + static { + makeViewer = (reservation) => new Viewer(reservation); } - #peek(id: number): number | undefined { - if (!this.#alive.peek()) return undefined; - const estimate = this.#estimate?.peek(); - if (estimate == null) return undefined; - const entries = this.#entries.peek(); - const entry = entries.find((candidate) => candidate.id === id); - if (!entry) return undefined; - return shareOf(estimate, wantsOf(entries), entry); + /** This viewer's slice of the receive estimate right now; see {@link Reservation.peek}. */ + peek(): number | undefined { + return this.#reservation.peek(); } - #update(id: number, max: number): void { - if (!this.#alive.peek()) return; - max = ceiling(max); - this.#entries.mutate((entries) => { - const entry = entries.find((candidate) => candidate.id === id); - if (entry) entry.max = max; - }); - this.#publish(); + /** + * This viewer's current slice of the receive estimate. + * + * `undefined` while the connection has no receive estimate or this viewer has been + * closed, telling a player to hold its current selection. + */ + get rate(): Getter { + return this.#reservation.rate; } - #release(id: number): void { - if (!this.#alive.peek()) return; - this.#entries.mutate((entries) => { - const index = entries.findIndex((entry) => entry.id === id); - if (index >= 0) entries.splice(index, 1); - }); - this.#publish(); + /** Change the ceiling, keeping the same claim, as when a catalog enables or disables a rendition. */ + update(max: number): void { + this.#reservation.update(max); + } + + /** Release the claim so other viewers take the room. Idempotent. */ + close(): void { + this.#reservation.close(); + } + + /** Calls {@link close}, so `using` releases the claim. */ + [Symbol.dispose](): void { + this.close(); } } diff --git a/js/net/src/bandwidth_api.ts b/js/net/src/bandwidth_api.ts index 7fc5892eab9..76e3316d3d0 100644 --- a/js/net/src/bandwidth_api.ts +++ b/js/net/src/bandwidth_api.ts @@ -3,4 +3,4 @@ * * @module */ -export { Allocator, type Handle, Reservation } from "./bandwidth.ts"; +export { Allocator, type Handle, Reservation, Viewer, Viewers } from "./bandwidth.ts"; diff --git a/js/net/src/connection/connect.ts b/js/net/src/connection/connect.ts index 62dba052534..a03ff19751a 100644 --- a/js/net/src/connection/connect.ts +++ b/js/net/src/connection/connect.ts @@ -1,8 +1,9 @@ import { Elapsed, Milli, Nano, sleep, timeout } from "@moq/clock"; import Session, { type Version as QmuxVersion } from "@moq/qmux"; -import { race } from "@moq/signals"; +import { type Getter, race } from "@moq/signals"; import type * as Auth from "../auth.ts"; import { vacant } from "../auth_session.ts"; +import type { Viewers } from "../bandwidth.ts"; import { ConnectTimeout, error, fromClose, ProtocolViolation, sessionCause } from "../error.ts"; import * as Ietf from "../ietf/index.ts"; import { IMPLEMENTATION } from "../implementation.ts"; @@ -250,6 +251,13 @@ export interface ConnectProps { */ implementation?: string; + /** + * The viewers whose ceilings summed the session sends as its PROBE target, so a peer + * that advertised `Increase` probes the connection up to it (moq-lite-05+). Omit to send + * no target. The registry is borrowed, so the same one can span reconnects. + */ + viewers?: Viewers; + /** * Maximum time for one connect, covering the dial and the MoQ handshake, which has no * deadline of its own (default: 30000ms). `0` waits forever. Past it, the connect rejects @@ -278,6 +286,8 @@ type SessionProps = { token?: Uint8Array; /** The implementation this side advertises in SETUP; empty sends nothing. */ implementation: string; + /** The PROBE target to send a peer that advertised `Increase`. */ + probeTarget?: Getter; }; // Save if WebSocket won the last race, so we won't give QUIC a head start next time. @@ -369,6 +379,7 @@ async function connectInner( extensions: Extensions.offered(props.extensions), token: presented.setup === undefined ? undefined : new TextEncoder().encode(presented.setup), implementation: props.implementation ?? IMPLEMENTATION, + probeTarget: props.viewers?.target, }); if (props.transport) { diff --git a/js/net/src/connection/pool.ts b/js/net/src/connection/pool.ts index 3c9f18757d0..3c0903b343b 100644 --- a/js/net/src/connection/pool.ts +++ b/js/net/src/connection/pool.ts @@ -9,7 +9,7 @@ import { Effect, type GetPromise, type Getter, Once, Signal } from "@moq/signals import type * as Announce from "../announce.ts"; import { Producer as AnnounceProducer } from "../announced.ts"; import type * as Auth from "../auth.ts"; -import type { Handle } from "../bandwidth.ts"; +import type { Handle, Viewers } from "../bandwidth.ts"; import * as Origin from "../origin.ts"; import * as Path from "../path.ts"; import { closeUnwanted } from "../util/announce.ts"; @@ -186,6 +186,15 @@ export class Connection { */ readonly allocator: Getter; + /** + * The receive-side registry for the current URL, or undefined while disabled or URL-less. + * + * Every handle on this URL shares the same instance, so players watching over one + * connection split its receive estimate instead of each selecting against all of it, + * and their ceilings summed are the PROBE target. Borrowed, not owned: it has no close. + */ + readonly viewers: Getter | undefined>; + /** * The origin for the current URL, or undefined while disabled or URL-less. * @@ -222,6 +231,7 @@ export class Connection { readonly #probe = new Signal | undefined>(undefined); readonly #origin = new Signal(undefined); readonly #allocator = new Signal(undefined); + readonly #viewers = new Signal | undefined>(undefined); readonly #auth = new Signal(undefined); readonly #error = new Signal(undefined); #signals: Effect; @@ -252,6 +262,7 @@ export class Connection { this.probe = new Follow(this.#probe); this.origin = this.#origin; this.allocator = this.#allocator; + this.viewers = this.#viewers; this.auth = this.#auth; this.transport = this.#signals.computed((effect) => effect.get(this.#established)?.transport); @@ -279,6 +290,7 @@ export class Connection { effect.set(this.#origin, lease.origin, undefined); effect.set(this.#allocator, lease.connection.allocator, undefined); + effect.set(this.#viewers, lease.connection.viewers, undefined); effect.set(this.#auth, lease.connection.auth, undefined); // Proxy the shared loop's outputs, so this handle reads like its own connection. @@ -330,6 +342,7 @@ export class Connection { if (!effect.get(this.enabled) || !effect.get(href)) return; effect.set(this.#origin, origin, undefined); effect.set(this.#allocator, loop.allocator, undefined); + effect.set(this.#viewers, loop.viewers, undefined); effect.set(this.#auth, loop.auth, undefined); }); signals.run((effect) => effect.set(this.#status, effect.get(loop.status), "disconnected")); diff --git a/js/net/src/connection/reload.ts b/js/net/src/connection/reload.ts index 92326220384..fecd3b33a3c 100644 --- a/js/net/src/connection/reload.ts +++ b/js/net/src/connection/reload.ts @@ -1,9 +1,9 @@ import { Instant, Milli, Nano, now, sleep } from "@moq/clock"; -import { Effect, type GetPromise, type Getter, Once, Signal } from "@moq/signals"; +import { Derived, Effect, type GetPromise, type Getter, Once, Signal } from "@moq/signals"; import type * as Announce from "../announced.ts"; import { Handle as AuthHandle } from "../auth.ts"; import { ended } from "../auth_session.ts"; -import { Allocator } from "../bandwidth.ts"; +import { Allocator, Viewers } from "../bandwidth.ts"; import { error, reason, SessionCode, SessionError } from "../error.ts"; import type { Consumer as OriginConsumer, Producer as OriginProducer } from "../origin.ts"; import * as Path from "../path.ts"; @@ -223,6 +223,15 @@ export class Reload { */ readonly allocator: Allocator; + /** + * Divides this connection's receive estimate among the broadcasts watched over it. + * + * The same instance across reconnects, so viewers survive a drop, and every session + * the loop dials sends their ceilings summed as its PROBE target. A live viewer + * requests PROBE; viewers report `undefined` while disconnected. + */ + readonly viewers: Viewers; + /** * The auth handle every session of the loop is built on, spanning reconnects. * @@ -408,6 +417,11 @@ export class Reload { this.allocator = new Allocator(this.#estimate); this.#signals.cleanup(() => this.allocator.close()); + // Lazy: the registry observes the estimate only while a viewer is live, and only + // that observation requests PROBE from the current session. + this.viewers = new Viewers(new Derived([this.probe], (probe) => probe?.estimatedRecvRate)); + this.#signals.cleanup(() => this.viewers.close()); + // The transport has no event for the send-rate estimate, so sample on our // own schedule and skip a tick while the previous snapshot is outstanding. this.#signals.run((effect) => { @@ -542,6 +556,7 @@ export class Reload { publish: this.publish, consume: this.consume, auth: this.auth, + viewers: this.viewers, signal, }); } finally { diff --git a/js/net/src/lite/connection.ts b/js/net/src/lite/connection.ts index e570afff863..d2b26fdedad 100644 --- a/js/net/src/lite/connection.ts +++ b/js/net/src/lite/connection.ts @@ -71,6 +71,8 @@ export interface ConnectionProps { token?: Uint8Array; /** The implementation our SETUP advertises (lite-05+). Defaults to {@link IMPLEMENTATION}; empty sends nothing. */ implementation?: string; + /** The PROBE target to send a peer that advertised `Increase`, in bits per second; zero sends none. */ + probeTarget?: Getter; } /** @@ -133,6 +135,8 @@ export class Connection implements Established { #token?: Uint8Array; // What our SETUP advertises; see {@link ConnectionProps.implementation}. #implementation: string; + // See {@link ConnectionProps.probeTarget}. + #probeTarget?: Getter; #peerImplementation = Promise.withResolvers(); /** The implementation the peer advertised; see {@link Established.peerImplementation}. */ @@ -169,6 +173,7 @@ export class Connection implements Established { client = true, token, implementation = IMPLEMENTATION, + probeTarget, }: ConnectionProps) { this.url = url; // Older versions carry the credential in the URL instead. @@ -225,6 +230,7 @@ export class Connection implements Established { ); this.#client = client; this.#implementation = implementation; + this.#probeTarget = probeTarget; // Only the lite-05+ Setup Stream carries it. if (!hasSetupStream(version)) this.#peerImplementation.resolve(undefined); registerWire(this, { @@ -288,7 +294,7 @@ export class Connection implements Established { const probes = new Effect((effect) => { if (!effect.get(this.#probe.used)) return; - effect.spawn(() => this.#subscriber.runProbe(effect.abort)); + effect.spawn(() => this.#subscriber.runProbe(effect.abort, this.#probeTarget)); }); // Fail loud on a publication our grant never covers, once the peer has answered the diff --git a/js/net/src/lite/subscriber.test.ts b/js/net/src/lite/subscriber.test.ts index e61a68f46f3..01c4d1e59a0 100644 --- a/js/net/src/lite/subscriber.test.ts +++ b/js/net/src/lite/subscriber.test.ts @@ -3,6 +3,7 @@ import { Manual, Milli, Nano } from "@moq/clock"; import { type Getter, Signal } from "@moq/signals"; import type { Grant } from "../auth.ts"; import type { AuthSession } from "../auth_session.ts"; +import { Viewers } from "../bandwidth.ts"; import type { Probe as ProbeStats } from "../connection/stats.ts"; import * as Epoch from "../epoch.ts"; import { @@ -25,6 +26,7 @@ import { type AnnounceBroadcast, AnnounceInit, AnnounceOk, encodeAnnounceBroadca import { Datagram as DatagramMessage } from "./datagram.ts"; import { Group } from "./group.ts"; import { Probe } from "./probe.ts"; +import { ProbeLevel, Setup } from "./setup.ts"; import { StreamId } from "./stream.ts"; import { encodeSubscribeResponse, @@ -2550,3 +2552,82 @@ test.each(["answer", "credit"] as const)("FETCH shares the TRACK deadline while installed.close(); } }); + +/** + * A PROBE stream to a peer whose SETUP advertised `level`: `sent` reads back what the + * subscriber wrote, and `finish` plays the peer's FIN. + */ +function probeTargetHarness(level: ProbeLevel) { + const version = Version.DRAFT_06; + let written!: ReadableStreamDefaultController; + const sent = new Reader( + new ReadableStream({ start: (controller) => (written = controller) }), + undefined, + version, + ); + let inbound!: ReadableStreamDefaultController; + const quic = { + createBidirectionalStream: async () => ({ + readable: new ReadableStream({ start: (controller) => (inbound = controller) }), + writable: new WritableStream({ + write: (chunk) => written.enqueue(new Uint8Array(chunk)), + close: () => written.close(), + }), + }), + } as unknown as WebTransport; + const peerSetup = new Signal(new Setup({ probe: level })); + const subscriber = new Subscriber(quic, version, HopSchema.parse(1n), new Signal({}), peerSetup); + return { + subscriber, + sent, + version, + finish: () => inbound.close(), + }; +} + +// 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 { subscriber, sent, version, finish } = probeTargetHarness(ProbeLevel.Increase); + const viewers = new Viewers(); + viewers.setTarget(0); + const running = subscriber.runProbe(undefined, viewers.target); + expect(await sent.u53()).toBe(StreamId.Probe); + + // Opted out: a viewer moves nothing onto the wire until the override clears. + const first = viewers.watch(1_000_000); + viewers.setTarget(undefined); + expect((await Probe.decode(sent, version)).bitrate).toBe(1_000_000); + + const second = viewers.watch(2_000_000); + expect((await Probe.decode(sent, version)).bitrate).toBe(3_000_000); + + first.close(); + expect((await Probe.decode(sent, version)).bitrate).toBe(2_000_000); + + // Dropping to zero retracts the target as unknown on the wire. + second.close(); + expect((await Probe.decode(sent, version)).bitrate).toBeUndefined(); + + finish(); + await running; + expect(await sent.done()).toBe(true); + 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); + 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); + + finish(); + await running; + expect(await sent.done()).toBe(true); + viewer.close(); + subscriber.close(); + viewers.close(); +}); diff --git a/js/net/src/lite/subscriber.ts b/js/net/src/lite/subscriber.ts index 7b3debc7861..4173a8637f4 100644 --- a/js/net/src/lite/subscriber.ts +++ b/js/net/src/lite/subscriber.ts @@ -1792,7 +1792,7 @@ export class Subscriber { return setup.probe; } - async runProbe(signal?: AbortSignal): Promise { + async runProbe(signal?: AbortSignal, target?: Getter): Promise { if (!this.#probe) return; if (this.version === Version.DRAFT_01 || this.version === Version.DRAFT_02) return; const scope = new Effect(); @@ -1805,9 +1805,12 @@ export class Subscriber { // input ends the session. Drop the estimates so consumers know they're stale. try { // Lite-05+ gates PROBE on the peer advertising Probe >= Report in its SETUP. + // Only a peer that probes up to a target is sent one; a Report-level peer ignores it. + let increase = false; if (hasSetupStream(this.version) && this.#peerSetup) { const level = await this.#peerProbeLevel(this.#peerSetup, scope); if (level === undefined || level < ProbeLevel.Report) return; + increase = level >= ProbeLevel.Increase; } if (this.#goingAway() || abort.aborted) return; const opening = Stream.open(this.#quic, { version: this.version }); @@ -1819,6 +1822,7 @@ export class Subscriber { } scope.cleanup(() => stream.close()); await scope.race(stream.writer.u53(StreamId.Probe)); + if (target && increase) this.#sendTarget(stream, target, scope); for (;;) { const probe = await scope.race(Probe.decodeMaybe(stream.reader, this.version)); if (!probe) break; @@ -1843,6 +1847,27 @@ export class Subscriber { } } + // Send `target` on the PROBE stream whenever it changes, in order, while `scope` lives. + // Nothing is sent while it is zero, until it retracts a target already sent. + #sendTarget(stream: Stream, target: Getter, scope: Effect): void { + let sent = 0; + let writing: Promise = Promise.resolve(); + scope.run((effect) => { + effect.get(target); + writing = writing + .then(async () => { + // The wire carries whole bits per second. + const next = Math.floor(target.peek()); + if (next === sent) return; + sent = next; + // Zero reads as unknown on the wire, which retracts the last target. + await new Probe({ bitrate: next > 0 ? next : undefined }).encode(stream.writer, this.version); + }) + // A failed write surfaces through the stream's reader, which ends the probe. + .catch(() => {}); + }); + } + /** * Ends every subscribed track: cleanly without declaring an end for a deliberate close, or * with `err` when the session died, since those tracks were cut off rather than ended. diff --git a/rs/moq-net/benches/bandwidth.rs b/rs/moq-net/benches/bandwidth.rs index 6b1a603639a..36fb170c845 100644 --- a/rs/moq-net/benches/bandwidth.rs +++ b/rs/moq-net/benches/bandwidth.rs @@ -3,11 +3,13 @@ //! - update: one reservation's ceiling moves and the session reads the new target. //! Swept over the reservations sharing the allocator, so an update that rescans //! every reservation shows up as a slope. +//! - viewers: one viewer's ceiling moves and the session reads the new PROBE target. +//! Swept over the viewers sharing the connection, for the same slope. //! //! Run with `cargo bench -p moq-net --features fuzz --bench bandwidth`. use criterion::{BenchmarkId, Criterion, criterion_group, criterion_main}; -use moq_net::bandwidth::{Allocator, Rate, Reservation}; +use moq_net::bandwidth::{Allocator, Rate, Reservation, Viewers}; use moq_net::{broadcast, fuzz, track}; /// Reservations sharing the allocator. @@ -46,5 +48,25 @@ fn bench_update(c: &mut Criterion) { group.finish(); } -criterion_group!(benches, bench_update); +fn bench_viewers(c: &mut Criterion) { + let mut group = c.benchmark_group("bandwidth/viewers"); + for count in RESERVATIONS { + group.bench_function(BenchmarkId::from_parameter(count), |b| { + let viewers = Viewers::default(); + let watched: Vec<_> = (0..count).map(|_| viewers.watch(Rate::from_kbps(1_000))).collect(); + let mut target = fuzz::ProbeTarget::viewers(&viewers); + target.poll().expect("the first poll reports the target"); + let touched = &watched[count / 2]; + let mut raised = false; + b.iter(|| { + raised = !raised; + touched.update(Rate::from_kbps(if raised { 2_000 } else { 1_000 })); + std::hint::black_box(target.poll().expect("the target moved")); + }); + }); + } + group.finish(); +} + +criterion_group!(benches, bench_update, bench_viewers); criterion_main!(benches); diff --git a/rs/moq-net/src/client.rs b/rs/moq-net/src/client.rs index 7a6b047d01b..f23e2a1b529 100644 --- a/rs/moq-net/src/client.rs +++ b/rs/moq-net/src/client.rs @@ -24,6 +24,7 @@ pub struct Client { extensions: setup::Extensions, auth: Option, allocator: Option, + viewers: Option, implementation: Option, } @@ -88,6 +89,22 @@ impl Client { self.allocator.clone().unwrap_or_default() } + /// Share `viewers` with every session this client dials. + /// + /// Each session sends what they add up to as its PROBE target, and its + /// [`Session::viewers`](crate::Session::viewers) watches into the same registry, so + /// a viewer taken on one session still counts after a reconnect. Without one, each + /// session starts an empty registry of its own. + pub fn with_viewers(mut self, viewers: crate::bandwidth::Viewers) -> Self { + self.viewers = Some(viewers); + self + } + + /// The registry the next session sends the target of. + fn viewers(&self) -> crate::bandwidth::Viewers { + self.viewers.clone().unwrap_or_default() + } + /// Restrict which protocol versions to offer, in preference order. /// Defaults to every version this crate supports. pub fn with_versions(mut self, versions: Versions) -> Self { @@ -316,11 +333,14 @@ impl Client { lite::Setup::default() }; + // One registry, which the subscriber sends and the session hands out. + let viewers = self.viewers(); let start = lite::start(lite::Config { runtime: runtime.clone(), stats: self.stats.clone(), client: true, limits: self.limits, + viewers: viewers.clone(), session: session.clone(), setup_stream: None, publish, @@ -344,7 +364,9 @@ impl Client { auth: start.auth, credential: start.credential, estimate: Some(start.estimate), + peer_target: Some(start.peer_target), bandwidth: self.allocator(), + viewers, peer_implementation: start.peer_implementation, }, )) @@ -418,7 +440,9 @@ impl Client { auth, credential, estimate: None, + peer_target: None, bandwidth: self.allocator(), + viewers: self.viewers(), peer_implementation, }, )); @@ -481,11 +505,14 @@ impl Client { } let stream = stream.with_version(v); + // One registry, which the subscriber sends and the session hands out. + let viewers = self.viewers(); let start = lite::start(lite::Config { runtime: runtime.clone(), stats: self.stats.clone(), client: true, limits: self.limits, + viewers: viewers.clone(), session: session.clone(), setup_stream: Some(stream), publish: publish.clone(), @@ -511,7 +538,9 @@ impl Client { auth: start.auth, credential: start.credential, estimate: Some(start.estimate), + peer_target: Some(start.peer_target), bandwidth: self.allocator(), + viewers, peer_implementation: start.peer_implementation, }, )) diff --git a/rs/moq-net/src/fuzz.rs b/rs/moq-net/src/fuzz.rs index 31d5bfaa0af..7696a5753fc 100644 --- a/rs/moq-net/src/fuzz.rs +++ b/rs/moq-net/src/fuzz.rs @@ -436,7 +436,7 @@ pub fn bump_publisher_bytes( registry.bump_publisher_bytes(path, tier, n); } -/// An allocator's probe target as its session follows it, for the bandwidth bench. +/// A probe target as its session follows it, for the bandwidth bench. pub struct ProbeTarget(crate::bandwidth::Target); impl ProbeTarget { @@ -445,6 +445,11 @@ impl ProbeTarget { Self(allocator.target()) } + /// Follow `viewers`' target, as the session sending it as PROBE does. + pub fn viewers(viewers: &crate::bandwidth::Viewers) -> Self { + Self(viewers.target()) + } + /// The target in bits per second once it moved, without parking. pub fn poll(&mut self) -> Option { match self.0.poll_changed(&kio::Waiter::noop()) { diff --git a/rs/moq-net/src/lite/publisher.rs b/rs/moq-net/src/lite/publisher.rs index 100b3626040..acafa9cade6 100644 --- a/rs/moq-net/src/lite/publisher.rs +++ b/rs/moq-net/src/lite/publisher.rs @@ -90,6 +90,8 @@ struct Shared { // untimed (see `wire_timestamp`). runtime: crate::time::Deadlines, estimate: kio::ProducerWeak, + /// The peer's latest PROBE target, which the session's sender probes up to. + peer_target: kio::Producer, } /// Largest millisecond duration every implementation can carry losslessly. @@ -128,6 +130,16 @@ fn cursor_floor(version: Version, start_group: Option, latest: Option) } impl Shared { + /// Record the peer's PROBE target, which only a session with a sender acts on. + fn set_peer_target(&self, target: crate::bandwidth::Rate) { + // An error means nothing follows the target, which is then moot. + if let Ok(mut current) = self.peer_target.write() + && *current != target + { + *current = target; + } + } + /// Watches whether the session still lets us serve `broadcast` to the peer: our /// grant, and the ceiling on what the peer may subscribe to. fn gate(&self, broadcast: &crate::Path) -> crate::auth::Gate { @@ -212,6 +224,7 @@ impl Publisher { lister: crate::broadcast::Owner::new(), runtime: config.runtime.clone(), estimate: config.estimate, + peer_target: kio::Producer::new(crate::bandwidth::Rate::ZERO), }), runtime: config.runtime, accept, @@ -221,6 +234,11 @@ impl Publisher { } impl Publisher { + /// The peer's latest PROBE target, or zero while it asks for none. + pub fn peer_target(&self) -> kio::Consumer { + self.shared.peer_target.consume() + } + pub fn poll(&mut self, waiter: &kio::Waiter) -> Poll> { if let Some(enforce) = &mut self.enforce && let Poll::Ready(res) = enforce.poll(&self.shared, waiter) @@ -721,7 +739,10 @@ impl ProbeServe { } fn poll(&mut self, waiter: &kio::Waiter) -> Poll> { - match ready!(self.poll_probe(waiter)) { + let res = ready!(self.poll_probe(waiter)); + // The stream carried the target, so it lapses with it. + self.shared.set_peer_target(crate::bandwidth::Rate::ZERO); + match res { Ok(()) => tracing::debug!("probe stream closed"), Err(err) => { tracing::warn!(%err, "probe stream error"); @@ -740,11 +761,18 @@ impl ProbeServe { // Deliver the previous estimate before weighing the next one. ready!(stream.writer.poll_flush(&mut cx))?; - // Report ignores target values, but consumes them so buffered bytes - // cannot hide the peer's FIN or a malformed complete message. + // The peer's target, recorded for the session's sender. Without one the + // session ignores it, as a Report-level publisher must, but it is still + // consumed so buffered bytes cannot hide the peer's FIN or a malformed + // complete message. loop { match stream.reader.poll_decode_maybe::(&mut cx) { - Poll::Ready(Ok(Some(_))) => ready!(self.budget.poll_yield(waiter)), + Poll::Ready(Ok(Some(probe))) => { + let target = probe.bitrate.map(crate::bandwidth::Rate::from_bps); + self.shared + .set_peer_target(target.unwrap_or(crate::bandwidth::Rate::ZERO)); + ready!(self.budget.poll_yield(waiter)) + } Poll::Ready(Ok(None)) => return Poll::Ready(Ok(())), Poll::Ready(Err(err)) => return Poll::Ready(Err(err)), Poll::Pending => break, diff --git a/rs/moq-net/src/lite/session.rs b/rs/moq-net/src/lite/session.rs index 41c53bf82b9..d69fbdf9a19 100644 --- a/rs/moq-net/src/lite/session.rs +++ b/rs/moq-net/src/lite/session.rs @@ -15,6 +15,8 @@ use super::{ pub(crate) struct SessionStart { pub recv_bandwidth: Option, + /// The peer's PROBE target, which the session's sender probes up to. + pub peer_target: kio::Consumer, /// The estimate PROBE reports, published by the session's supervisor. pub estimate: kio::Producer, /// The session's protocol machine over the boxed transport. @@ -198,6 +200,8 @@ pub struct Config { pub auth: crate::auth::Link, /// What the peer may make this session hold. pub limits: crate::session::Limits, + /// The viewers whose sum the session sends as its PROBE target. + pub viewers: bandwidth::Viewers, } /// Start a lite session. @@ -218,6 +222,7 @@ pub fn start(config: Config) -> Result { peer_setup, auth, limits, + viewers, } = config; let recv_bw = bandwidth::Producer::new(); @@ -330,6 +335,7 @@ pub fn start(config: Config) -> Result { client, subscriptions, }); + let peer_target = publisher.peer_target(); let mut subscriber = Subscriber::new(SubscriberConfig { runtime: runtime.clone(), session: session.clone(), @@ -346,6 +352,7 @@ pub fn start(config: Config) -> Result { auth: auth.clone(), }); subscriber.announces = announces; + subscriber.viewers = viewers; // SendSetup only logs a failure, so refuse a SETUP that cannot encode (one past the // size bound, such as a long implementation or path) here rather than leave the peer waiting. @@ -382,6 +389,7 @@ pub fn start(config: Config) -> Result { Ok(SessionStart { recv_bandwidth: recv_bw_consumer, + peer_target, estimate, driver, goaway: goaway_handle, @@ -994,6 +1002,7 @@ mod tests { stats: Default::default(), client: true, limits: Default::default(), + viewers: Default::default(), session: crate::driver::Transport::new(transport.clone()), setup_stream: None, publish: None, @@ -1039,6 +1048,7 @@ mod tests { stats: Default::default(), client: true, limits: Default::default(), + viewers: Default::default(), session: crate::driver::Transport::new(transport), setup_stream: None, publish: None, @@ -1119,6 +1129,7 @@ mod tests { stats: Default::default(), client: false, limits: Default::default(), + viewers: Default::default(), session: crate::driver::Transport::new(transport.clone()), setup_stream: None, publish: None, @@ -1206,6 +1217,7 @@ mod tests { stats: Default::default(), client: true, limits: Default::default(), + viewers: Default::default(), session: crate::driver::Transport::new(transport.clone()), setup_stream: None, publish: None, @@ -1287,6 +1299,7 @@ mod tests { client: false, auth: crate::auth::Link::new(version.has_auth()), limits: Default::default(), + viewers: Default::default(), }) .unwrap(); let _ = started.driver.poll(&kio::Waiter::noop()); @@ -1342,6 +1355,7 @@ mod tests { client: false, auth: crate::auth::Link::new(version.has_auth()), limits: Default::default(), + viewers: Default::default(), }) .unwrap(); let _ = started.driver.poll(&kio::Waiter::noop()); @@ -1375,6 +1389,7 @@ mod tests { peer_setup, auth: crate::auth::Link::new(version.has_auth()), limits: Default::default(), + viewers: Default::default(), }) .unwrap() } diff --git a/rs/moq-net/src/lite/setup.rs b/rs/moq-net/src/lite/setup.rs index a4d3830cb5e..8ae6edace1e 100644 --- a/rs/moq-net/src/lite/setup.rs +++ b/rs/moq-net/src/lite/setup.rs @@ -60,14 +60,21 @@ impl ProbeLevel { /// Both metrics are sampled rather than declared, so this only works for a /// transport whose figures exist by the time the session starts. QUIC and TCP /// both qualify: their RTT comes from the handshake, which has already happened. + /// + /// [`Increase`](Self::Increase) additionally needs a sender, a transport + /// [`Probe`](crate::transport::Probe), since the session probes to the peer's + /// target through it. Without one a peer's target could never be honored. #[cfg(feature = "async")] pub fn detect(session: &crate::driver::Transport) -> Self { use crate::transport::Metrics as _; use crate::transport::poll::Session as _; let metrics = session.metrics(); - match metrics.estimated_send_rate().is_some() || metrics.rtt().is_some() { - true => Self::Report, - false => Self::None, + if metrics.estimated_send_rate().is_none() && metrics.rtt().is_none() { + return Self::None; + } + match session.probe().is_some() { + true => Self::Increase, + false => Self::Report, } } @@ -536,18 +543,18 @@ mod tests { ); } - /// Probing to a local target never reaches the wire, so a sender alone promises the - /// peer nothing more than a report. + /// A sender probes to the peer's target as well as its own, so it promises the peer + /// `Increase`. Without one, `detect_reports_with_either_metric` stays at `Report`. #[test] #[cfg(feature = "async")] - fn a_sender_still_reports() { + fn a_sender_advertises_increase() { use crate::lite::test_transport::{SinkSession, SinkStats}; let stats = SinkStats::default().with_send_rate(1_000_000); let session = SinkSession::new(Default::default()).with_stats(stats).with_probe(); assert_eq!( ProbeLevel::detect(&crate::driver::Transport::new(session.clone())), - ProbeLevel::Report + ProbeLevel::Increase ); } diff --git a/rs/moq-net/src/lite/subscriber.rs b/rs/moq-net/src/lite/subscriber.rs index 3e02d35be12..127ff319e56 100644 --- a/rs/moq-net/src/lite/subscriber.rs +++ b/rs/moq-net/src/lite/subscriber.rs @@ -90,6 +90,8 @@ pub(super) struct Subscriber { auth: crate::auth::Link, /// Broadcasts the peer may have announced at once (`session::Limits::announces`). pub(super) announces: crate::session::Slots, + /// The viewers whose sum the PROBE stream sends as its target. + pub(super) viewers: bandwidth::Viewers, } #[derive(Clone)] @@ -128,6 +130,7 @@ impl Subscriber { going_away: config.going_away, auth: config.auth, announces: Default::default(), + viewers: Default::default(), } } @@ -1410,7 +1413,8 @@ impl DatagramRecv { } } -/// Opens a PROBE stream on demand while a consumer is interested. +/// Opens a PROBE stream on demand while a consumer is interested, and sends it the +/// viewers' target when the peer probes up to one. /// /// Loops forever: wait for a consumer, race the probe stream against the /// consumer leaving, then loop back. Transport errors stay per-stream; malformed @@ -1418,6 +1422,10 @@ impl DatagramRecv { struct RecvBandwidth { subscriber: Subscriber, state: BandwidthState, + /// The viewers' target, followed only once the peer advertised `Increase`. + target: Option, + /// The target last read from it. + wanted: bandwidth::Rate, } #[expect( @@ -1440,6 +1448,8 @@ impl RecvBandwidth { Self { subscriber, state: BandwidthState::Gate, + target: None, + wanted: bandwidth::Rate::ZERO, } } @@ -1450,11 +1460,16 @@ impl RecvBandwidth { if self.subscriber.recv_bandwidth.is_none() { return Poll::Ready(Ok(())); } - if self.subscriber.version.has_setup_stream() - && ready!(self.subscriber.peer_setup.poll_probe_level(waiter)) < lite::ProbeLevel::Report - { - tracing::debug!("peer does not support probing; skipping probe stream"); - return Poll::Ready(Ok(())); + if self.subscriber.version.has_setup_stream() { + let level = ready!(self.subscriber.peer_setup.poll_probe_level(waiter)); + if level < lite::ProbeLevel::Report { + tracing::debug!("peer does not support probing; skipping probe stream"); + return Poll::Ready(Ok(())); + } + // A Report-level peer ignores a target, so only a peer that probes is sent one. + if level >= lite::ProbeLevel::Increase { + self.target = Some(self.subscriber.viewers.target()); + } } self.state = BandwidthState::WaitUsed; } @@ -1480,7 +1495,12 @@ impl RecvBandwidth { Poll::Ready(Err(_)) => return Poll::Ready(Ok(())), Poll::Pending => {} } - match ready!(probe.poll(waiter)) { + if let Some(target) = &mut self.target { + while let Poll::Ready(rate) = target.poll_changed(waiter) { + self.wanted = rate; + } + } + match ready!(probe.poll(waiter, self.wanted)) { Ok(()) => tracing::debug!("probe stream closed"), Err(err) => { let err = lite::error::control(&mut self.subscriber.session.clone(), err); @@ -1497,11 +1517,13 @@ impl RecvBandwidth { } /// One PROBE stream: send the type, then feed the peer's estimates into the -/// bandwidth producer until it FINs. +/// bandwidth producer until it FINs, sending each new target along the way. struct ProbeStream { subscriber: Subscriber, session: Transport, state: ProbeState, + /// The target last sent; zero sends none. + sent: bandwidth::Rate, } enum ProbeState { @@ -1516,10 +1538,12 @@ impl ProbeStream { subscriber: subscriber.clone(), session: subscriber.session.clone(), state: ProbeState::Open, + sent: bandwidth::Rate::ZERO, } } - fn poll(&mut self, waiter: &kio::Waiter) -> Poll> { + /// Run the stream, sending `target` whenever it differs from the last one sent. + fn poll(&mut self, waiter: &kio::Waiter, target: bandwidth::Rate) -> Poll> { let mut cx = waiter.context(); loop { match &mut self.state { @@ -1542,6 +1566,16 @@ impl ProbeStream { self.state = ProbeState::Read { stream }; } ProbeState::Read { stream } => { + if target != self.sent { + // Zero reads as unknown on the wire, which retracts the last target. + let bitrate = (target > bandwidth::Rate::ZERO).then_some(target.as_bps()); + stream.writer.buffer(&lite::Probe { bitrate, rtt: None })?; + self.sent = target; + } + // Deliver the target without holding up the estimates behind it. + if let Poll::Ready(res) = stream.writer.poll_flush(&mut cx) { + res?; + } let bandwidth = self.subscriber.recv_bandwidth.as_ref().expect("gated by RecvBandwidth"); loop { let Some(probe) = ready!(stream.reader.poll_decode_maybe::(&mut cx))? else { diff --git a/rs/moq-net/src/model/bandwidth.rs b/rs/moq-net/src/model/bandwidth.rs index ecafcde5693..12e21889c93 100644 --- a/rs/moq-net/src/model/bandwidth.rs +++ b/rs/moq-net/src/model/bandwidth.rs @@ -10,6 +10,10 @@ //! The same reservations set the connection's probe target: their ceilings summed, //! which the session hands to its transport's [`Probe`](crate::transport::Probe) so //! the estimate can rise to fund them. +//! +//! The receive direction mirrors it: [Viewers] divides the receive estimate among the +//! broadcasts watched over one connection, and their ceilings summed are the PROBE +//! target the session asks its peer to probe up to. use std::{collections::BTreeMap, task::Poll}; @@ -109,7 +113,6 @@ impl Producer { } /// A handle that mints consumers without being one, so holding it is not demand. - #[cfg_attr(not(feature = "async"), allow(dead_code, reason = "async-only"))] pub fn weak(&self) -> Weak { Weak(self.state.weak()) } @@ -150,12 +153,10 @@ impl Default for Producer { /// Mints [`Consumer`]s on demand without counting as one, nor keeping the channel open. #[derive(Clone)] -#[cfg_attr(not(feature = "async"), allow(dead_code, reason = "async-only"))] pub struct Weak(kio::ProducerWeak); impl Weak { /// A new consumer, which reports the closure once the producer is gone. - #[cfg_attr(not(feature = "async"), allow(dead_code, reason = "async-only"))] pub fn consume(&self) -> Consumer { Consumer { inner: Inner::Whole(self.0.consume()), @@ -305,9 +306,11 @@ impl Allocator { pub fn reserve(&self, track: &track::Demand, max: Rate) -> Reservation { // Read the track before taking the registry lock, so the two are never held // at once and there's no order to get wrong. - let priority = track.priority(); - let demand = track.clone(); + self.claim(self.estimate.clone(), Some(track.clone()), track.priority(), max) + } + /// Claim up to `max` of `estimate`, active whenever `demand` is, or always without one. + fn claim(&self, estimate: Consumer, demand: Option, priority: i8, max: Rate) -> Reservation { let id = { // Nothing ever closes this channel: the allocator holds the only producer // and never aborts it, so it's open for as long as `self` is. @@ -319,7 +322,7 @@ impl Allocator { let closed: Vec = registry .entries .iter() - .filter(|(_, entry)| entry.demand.is_closed()) + .filter(|(_, entry)| entry.demand.as_ref().is_some_and(track::Demand::is_closed)) .map(|(id, _)| *id) .collect(); for id in closed { @@ -335,7 +338,7 @@ impl Allocator { Reservation { share: Share { - estimate: self.estimate.clone(), + estimate, registry: self.registry.consume(), id, }, @@ -434,6 +437,130 @@ impl std::fmt::Debug for Allocator { } } +/// Divides one connection's receive estimate among the broadcasts watched over it. +/// +/// The receive-side mirror of [`Allocator`]. Every player on a connection reads the +/// same receive estimate, so N players each selecting against all of it oversubscribe +/// the downlink N times over. [`watch`](Self::watch) a broadcast here and its +/// [`Viewer`] reports only its own slice, split max-min fair by each viewer's ceiling, +/// so the slices sum to the estimate instead of each matching it. Viewers carry no +/// priority: a viewer asking for less than an even cut takes all it asked for and +/// leaves the rest to the others. +/// +/// The viewers' ceilings summed are also the PROBE target the session sends its +/// peer, which probes the connection up to it when it advertised `Increase`, so the +/// estimate can rise to fund a larger rendition. The target never leaves this hop: +/// a relay probes its own downlink for its viewers, and never forwards them upstream. +/// +/// Holding a [`Viewer`] (or a [`Consumer`] read from one) requests PROBE, like +/// holding `Session::recv_bandwidth`. Take it from `Session::viewers` (with the +/// `async` feature) rather than building one, since only a session sends the target. +/// Clones share one registry. +#[derive(Clone, Default)] +pub struct Viewers { + /// The registry, whose own estimate is unused: each viewer reads one minted from + /// `estimate`, so holding the registry is not demand. + registry: Allocator, + /// Mints the receive estimate each viewer reads, or `None` when there is none. + estimate: Option, +} + +impl Viewers { + /// Divide the receive estimate `estimate` mints, with no session sending the target. + /// + /// For an estimate that outlives a session, such as one a reconnect loop feeds + /// from each session it dials. Hand the same registry to `Client::with_viewers` + /// (with the `async` feature) so every session it dials sends the target. + pub fn new(estimate: Weak) -> Self { + Self { + registry: Allocator::unlimited(), + estimate: Some(estimate), + } + } + + /// The same registry dividing the estimate `estimate` mints instead, or nothing when it is `None`. + #[cfg(feature = "async")] + pub(crate) fn with_estimate(&self, estimate: Option) -> Self { + Self { + registry: self.registry.clone(), + estimate, + } + } + + /// Watch a broadcast receiving at most `max`, returning its viewer. + /// + /// `max` is a ceiling: what the largest rendition the player would switch to + /// needs, not what it happens to be receiving. The claim lasts as long as the + /// returned [`Viewer`]: change the ceiling with [`update`](Viewer::update), and drop + /// it once the broadcast stops being watched. + pub fn watch(&self, max: Rate) -> Viewer { + let estimate = match &self.estimate { + Some(estimate) => estimate.consume(), + None => Consumer { + inner: Inner::Unavailable, + last: None, + probed: false, + }, + }; + Viewer(self.registry.claim(estimate, None, 0, max)) + } + + /// Send `target` as the PROBE target instead of the viewers' sum, or `None` to follow them again. + /// + /// `Some(Rate::ZERO)` turns probing off: the session sends no target. The override is + /// the registry's, so it holds for every clone and across the reconnects a persistent + /// registry spans. + pub fn set_target(&self, target: Option) { + self.registry.set_target(target); + } + + /// Follow the PROBE target, for the session that sends it to a peer that probes up to it. + /// + /// Holding it is what marks the viewers [`probed`](Consumer::probed). + #[cfg(any(feature = "async", test))] + pub(crate) fn target(&self) -> Target { + self.registry.target() + } +} + +// Hand-written so the config structs that carry a registry can still derive `Debug`. +impl std::fmt::Debug for Viewers { + fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { + f.debug_struct("Viewers") + .field("watched", &self.registry.registry.read().entries.len()) + .finish() + } +} + +/// One watched broadcast's standing claim on [`Viewers`], held for as long as it is watched. +/// +/// Holding it requests PROBE. Dropping it releases the claim and lowers the PROBE target. +#[must_use = "a dropped Viewer is released, so the broadcast claims nothing and the PROBE target drops"] +pub struct Viewer(Reservation); + +impl Viewer { + /// This viewer's slice of the receive estimate right now. + /// + /// `None` while the connection has no receive estimate, telling a player to hold its + /// current selection. + pub fn rate(&self) -> Option { + self.0.rate() + } + + /// A handle reading this viewer's current slice of the receive estimate. + /// + /// Cloneable and independent of the viewer: once the viewer is dropped these report + /// `None`. [`Consumer::probed`] reports whether the peer is asked to probe for it. + pub fn consume(&self) -> Consumer { + self.0.consume() + } + + /// Change the ceiling, keeping the same claim, as when a catalog enables or disables a rendition. + pub fn update(&self, max: Rate) { + self.0.update(max); + } +} + /// Every track registered with one [`Allocator`]. #[derive(Default)] struct Registry { @@ -465,7 +592,8 @@ impl Registry { /// One registered track's standing reservation. struct Entry { - demand: track::Demand, + /// The track whose demand gates the claim, or `None` for a claim that is always active. + demand: Option, priority: i8, max: Rate, } @@ -555,9 +683,10 @@ impl Share { // Its own track counts while idle too, so an unwatched sender reads the slice // it would get back: a rendition stopped for lack of bandwidth, whose viewers // then left, needs that to know when to resume. - .filter(|(want, demand)| match want.id == self.id { - true => !demand.is_closed(), - false => demand.is_used(), + .filter(|(want, demand)| match (demand, want.id == self.id) { + (None, _) => true, + (Some(demand), true) => !demand.is_closed(), + (Some(demand), false) => demand.is_used(), }) .map(|(want, _)| want) .collect(); @@ -600,15 +729,17 @@ impl Share { let wants: Vec = self .claims() .into_iter() - .filter(|(want, demand)| match demand.poll_state(waiter) { - track::DemandState::Active => true, - // An idle track claims nothing from its siblings, so an unwatched encoder's - // reservation goes to whoever is actually sending. Its own reader still - // sees the slice it would get back; see `grant`. - track::DemandState::Idle => want.id == self.id, - // Gone for good, and pruned by the next `register`. - track::DemandState::Closed => false, - }) + .filter( + |(want, demand)| match demand.as_ref().map(|demand| demand.poll_state(waiter)) { + None | Some(track::DemandState::Active) => true, + // An idle track claims nothing from its siblings, so an unwatched encoder's + // reservation goes to whoever is actually sending. Its own reader still + // sees the slice it would get back; see `grant`. + Some(track::DemandState::Idle) => want.id == self.id, + // Gone for good, and pruned by the next `register`. + Some(track::DemandState::Closed) => false, + }, + ) .map(|(want, _)| want) .collect(); @@ -620,7 +751,7 @@ impl Share { } /// Snapshot the registry so the tracks can be read without holding its lock. - fn claims(&self) -> Vec<(Want, track::Demand)> { + fn claims(&self) -> Vec<(Want, Option)> { self.registry .read() .entries @@ -716,7 +847,9 @@ impl Consumer { /// estimate can rise to fund it even while its sender is stopped. /// /// Only a session whose transport has a sender probes, and none does while - /// [`Allocator::set_target`] turns probing off. Without one the estimate + /// [`Allocator::set_target`] turns probing off. For a [`Viewer`]'s slice, whether + /// the session asks a peer that advertised `Increase` to probe for it, which + /// [`Viewers::set_target`] can turn off the same way. Without one the estimate /// stops learning once the connection is app-limited, so a sender that stops for /// lack of bandwidth could never see enough to resume. Always `false` for a whole /// estimate, which no reservation backs. [`poll_changed`](Self::poll_changed) @@ -1372,4 +1505,70 @@ mod tests { allocator.set_target(None); assert_eq!(target.poll_changed(&waiter), Poll::Ready(bps(4_000_000))); } + + /// Several broadcasts on one connection each read their own slice of the receive + /// estimate, max-min fair by ceiling, so together they never claim more than it. + #[test] + fn viewers_split_the_estimate_max_min_fair() { + let estimate = Producer::new(); + let viewers = Viewers::new(estimate.weak()); + let small = viewers.watch(bps(1_000_000)); + let large = viewers.watch(bps(8_000_000)); + assert_eq!(small.rate(), None, "no estimate yet: hold the selection"); + + estimate.set(Some(bps(6_000_000))).unwrap(); + assert_eq!(small.rate(), Some(bps(1_000_000))); + assert_eq!(large.rate(), Some(bps(5_000_000))); + + let third = viewers.watch(bps(4_000_000)); + let grants = [&small, &large, &third].map(|viewer| viewer.rate().unwrap()); + assert_eq!(grants, [bps(1_000_000), bps(2_500_000), bps(2_500_000)]); + assert!(grants.iter().map(|rate| rate.as_bps()).sum::() <= 6_000_000); + + // A viewer that leaves hands its slice back. + drop(third); + assert_eq!(large.rate(), Some(bps(5_000_000))); + } + + /// The PROBE target sums every live viewer's ceiling until overridden. + #[test] + fn the_viewers_target_sums_their_ceilings() { + let viewers = Viewers::default(); + let mut target = viewers.target(); + let waiter = kio::Waiter::noop(); + assert_eq!(target.poll_changed(&waiter), Poll::Ready(Rate::ZERO)); + + let first = viewers.watch(bps(3_000_000)); + let second = viewers.clone().watch(bps(2_000_000)); + assert_eq!(target.poll_changed(&waiter), Poll::Ready(bps(5_000_000))); + first.update(bps(1_000_000)); + assert_eq!(target.poll_changed(&waiter), Poll::Ready(bps(3_000_000))); + + viewers.set_target(Some(Rate::ZERO)); + assert_eq!(target.poll_changed(&waiter), Poll::Ready(Rate::ZERO)); + viewers.set_target(None); + assert_eq!(target.poll_changed(&waiter), Poll::Ready(bps(3_000_000))); + + drop(second); + assert_eq!(target.poll_changed(&waiter), Poll::Ready(bps(1_000_000))); + drop(first); + assert_eq!(target.poll_changed(&waiter), Poll::Ready(Rate::ZERO)); + } + + /// A held viewer is what requests the receive estimate (and so PROBE); the registry + /// alone is not, so a session holding one opens no PROBE stream. + #[test] + fn a_viewer_requests_the_estimate() { + let estimate = Producer::new(); + let viewers = Viewers::new(estimate.weak()); + assert!(!estimate.is_used()); + + let viewer = viewers.watch(bps(1_000_000)); + assert!(estimate.is_used()); + let grant = viewer.consume(); + drop(viewer); + assert!(estimate.is_used(), "a grant read from the viewer still wants it"); + drop(grant); + assert!(!estimate.is_used()); + } } diff --git a/rs/moq-net/src/server.rs b/rs/moq-net/src/server.rs index 0eb8d2b6d3c..8ce9a25cc4a 100644 --- a/rs/moq-net/src/server.rs +++ b/rs/moq-net/src/server.rs @@ -184,11 +184,14 @@ impl Server { lite::Setup::default() }; + // One registry, which the subscriber sends and the session hands out. + let viewers = crate::bandwidth::Viewers::default(); let start = lite::start(lite::Config { runtime: runtime.clone(), stats: self.stats.clone(), client: false, limits: self.limits, + viewers: viewers.clone(), session: session.clone(), setup_stream: None, publish, @@ -212,7 +215,9 @@ impl Server { auth: start.auth, credential: start.credential, estimate: Some(start.estimate), + peer_target: Some(start.peer_target), bandwidth: crate::bandwidth::Allocator::default(), + viewers, peer_implementation: start.peer_implementation, }, )) @@ -550,7 +555,9 @@ impl PausedIetf { auth, credential, estimate: None, + peer_target: None, bandwidth: crate::bandwidth::Allocator::default(), + viewers: Default::default(), peer_implementation, }, )) @@ -594,11 +601,14 @@ impl PausedNegotiated { let stream = stream.with_version(version); // Pre-lite-05: no Setup Stream, so nothing to advertise or seed. + // One registry, which the subscriber sends and the session hands out. + let viewers = crate::bandwidth::Viewers::default(); let start = lite::start(lite::Config { runtime: runtime.clone(), stats: server.stats.clone(), client: false, limits: server.limits, + viewers: viewers.clone(), session: session.clone(), setup_stream: Some(stream), publish, @@ -622,7 +632,9 @@ impl PausedNegotiated { auth: start.auth, credential: start.credential, estimate: Some(start.estimate), + peer_target: Some(start.peer_target), bandwidth: crate::bandwidth::Allocator::default(), + viewers, peer_implementation: start.peer_implementation, }, )) diff --git a/rs/moq-net/src/session.rs b/rs/moq-net/src/session.rs index 7af1a79edea..5ce8e84cab5 100644 --- a/rs/moq-net/src/session.rs +++ b/rs/moq-net/src/session.rs @@ -169,6 +169,8 @@ pub struct Session { /// unused: [`bandwidth`](Self::bandwidth) mints one per call, so holding the /// session doesn't keep the sampler running. bandwidth: bandwidth::Allocator, + /// The registry whose viewers this session sends its peer as the PROBE target. + viewers: bandwidth::Viewers, goaway: Arc, auth: auth::Handle, credential: Option, @@ -236,6 +238,18 @@ impl Session { self.recv_bandwidth.as_ref().map(bandwidth::Weak::consume) } + /// Divides [`recv_bandwidth`](Self::recv_bandwidth) among the broadcasts watched over this session. + /// + /// The session sends what the viewers add up to as its PROBE target, so a peer that + /// advertised `Increase` probes the connection up to it. Holding a viewer requests + /// PROBE. Clones share one registry: a + /// [`Client::with_viewers`](crate::Client::with_viewers) registry's when the session + /// was dialed with one, so viewers outlive a reconnect. Viewers report `None` when + /// the version has no PROBE. + pub fn viewers(&self) -> bandwidth::Viewers { + self.viewers.with_estimate(self.recv_bandwidth.clone()) + } + /// Returns a snapshot of the current connection statistics. /// /// Cheap and non-blocking: this reads the latest sample the session's @@ -392,6 +406,10 @@ pub(super) struct Handles { pub estimate: Option>, /// The reservations the session probes for. pub bandwidth: bandwidth::Allocator, + /// The viewers whose sum the session sends as its PROBE target. + pub viewers: bandwidth::Viewers, + /// The peer's PROBE target, for a protocol that carries one (moq-lite PROBE). + pub peer_target: Option>, /// What the peer's SETUP advertised as its implementation. pub peer_implementation: crate::setup::PeerImplementation, } @@ -412,6 +430,8 @@ impl Session { estimate, stats: context, bandwidth, + viewers, + peer_target, peer_implementation, } = handles; let goaway = Arc::new(goaway); @@ -436,7 +456,12 @@ impl Session { }; // Without a sender there is nothing to hand the target to, so don't follow it. - let probe = session.probe().map(|probe| (probe, bandwidth.target())); + let probe = session.probe().map(|sender| Probing { + sender, + local: bandwidth.target(), + peer: peer_target, + targets: (bandwidth::Rate::ZERO, bandwidth::Rate::ZERO), + }); let close = kio::Producer::new(None); let closed = kio::Producer::new(None); @@ -475,6 +500,7 @@ impl Session { send_bandwidth, recv_bandwidth, bandwidth, + viewers, goaway, auth: auth.handle().clone(), credential, @@ -520,8 +546,8 @@ pub(crate) struct Supervisor { send_bandwidth: Option, /// Published on change while a consumer exists; see [`Self::poll_sampler`]. estimate: Option>, - /// The transport's sender and the target it is handed, when it has one. - probe: Option<(crate::transport::Probe, bandwidth::Target)>, + /// The transport's sender and the targets it probes up to, when it has one. + probe: Option, /// When the last sample was taken. sampled: Option, mode: SamplerMode, @@ -533,6 +559,52 @@ pub(crate) struct Supervisor { auth: auth::Link, } +/// A transport's sender and the two targets it probes up to, whichever is larger. +/// +/// The directions never mix: these are both rates this side sends at, its own +/// reservations' and what the peer asks to receive. What this side wants to receive +/// goes to the peer instead, as its PROBE target. +struct Probing { + sender: crate::transport::Probe, + /// This side's reservations. + local: bandwidth::Target, + /// The peer's PROBE target, when the protocol carries one. `None` once it is gone. + peer: Option>, + /// The last local and peer targets read. + targets: (bandwidth::Rate, bandwidth::Rate), +} + +impl Probing { + fn poll(&mut self, waiter: &kio::Waiter) { + while let Poll::Ready(local) = self.local.poll_changed(waiter) { + self.targets.0 = local; + } + // Loop until pending, so the waiter stays armed for the next change. + while let Some(peer) = &self.peer { + let last = self.targets.1; + let polled = peer.poll(waiter, |rate| match **rate != last { + true => Poll::Ready(**rate), + false => Poll::Pending, + }); + match polled.map(|res| res.ok()) { + Poll::Ready(Some(rate)) => self.targets.1 = rate, + // The protocol stopped reading the peer; nothing it asked for still holds. + Poll::Ready(None) => { + self.targets.1 = bandwidth::Rate::ZERO; + self.peer = None; + } + Poll::Pending => break, + } + } + // The peer's target is untrusted, but only sets how high to probe: each probe + // scales the current estimate and stays under congestion control. + let target = self.targets.0.max(self.targets.1); + if self.sender.target() != target { + self.sender.set_target(target); + } + } +} + /// A [`Session::close`] waiting for the protocol to deliver what it queued. enum Drain { /// Nobody asked for one. @@ -661,10 +733,8 @@ impl Supervisor { self.poll_sampler(waiter); - if let Some((probe, target)) = &mut self.probe { - while let Poll::Ready(target) = target.poll_changed(waiter) { - probe.set_target(target); - } + if let Some(probe) = &mut self.probe { + probe.poll(waiter); } Poll::Pending diff --git a/rs/moq-net/tests/integration/main.rs b/rs/moq-net/tests/integration/main.rs index da3b6acc2b0..9bfdd1bb0bb 100644 --- a/rs/moq-net/tests/integration/main.rs +++ b/rs/moq-net/tests/integration/main.rs @@ -71,6 +71,7 @@ mod tracks; mod tracks_ietf; mod unannounce_release; mod untimed; +mod viewer_target; mod wide_hop; mod wide_sequence; mod widened_max_age; diff --git a/rs/moq-net/tests/integration/support/harness.rs b/rs/moq-net/tests/integration/support/harness.rs index 52cac7f185a..5f2bfa57977 100644 --- a/rs/moq-net/tests/integration/support/harness.rs +++ b/rs/moq-net/tests/integration/support/harness.rs @@ -92,6 +92,8 @@ pub struct MockConnectOptions { pub cost: Option, /// What both transports report as their connection statistics. pub stats: MockStats, + /// Whether both transports have a sender that probes up to a target. + pub probe: bool, /// The context the server records under. pub server_stats: moq_net::stats::Session, /// Count server driver polls into this counter when supplied. @@ -125,6 +127,7 @@ impl MockConnectOptions { server_extensions: Default::default(), cost: None, stats: MockStats::default(), + probe: false, server_stats: Default::default(), server_polls: None, client_discovers_all: true, @@ -165,6 +168,8 @@ pub async fn connect_mock(opts: MockConnectOptions) -> MockPair { client_transport.set_latency(opts.latency); client_transport.set_stats(opts.stats); server_transport.set_stats(opts.stats); + client_transport.set_probe(opts.probe); + server_transport.set_probe(opts.probe); let transports = (client_transport.clone(), server_transport.clone()); let mut client = Client::new() diff --git a/rs/moq-net/tests/integration/support/mock.rs b/rs/moq-net/tests/integration/support/mock.rs index 0b3265cdcc7..fa4773fd587 100644 --- a/rs/moq-net/tests/integration/support/mock.rs +++ b/rs/moq-net/tests/integration/support/mock.rs @@ -456,6 +456,10 @@ struct Side { panic_on_stats: AtomicBool, /// The wire counters [`poll::Session::wire`] exposes, which a test updates as a transport would. wire: moq_net::transport::Wire, + /// Whether [`poll::Session::probe`] reports a sender; see [`MockSession::set_probe`]. + probing: AtomicBool, + /// The sender's target, which the session sets. + probe: moq_net::transport::Probe, } /// The connection statistics a [`MockSession`] reports. Unavailable by default. @@ -652,6 +656,13 @@ impl poll::Session for MockSession { fn wire(&self) -> Option { Some(self.side.wire.clone()) } + + fn probe(&self) -> Option { + self.side + .probing + .load(Ordering::Relaxed) + .then(|| self.side.probe.clone()) + } } #[allow(dead_code, reason = "only some test binaries steer delivery")] @@ -685,6 +696,16 @@ impl MockSession { *self.side.stats.lock().unwrap() = stats; } + /// Report a sender from now on, which a session reads once as it starts. + pub fn set_probe(&self, probing: bool) { + self.side.probing.store(probing, Ordering::Relaxed); + } + + /// The target the session hands this side's sender, or zero without one. + pub fn probe_target(&self) -> moq_net::bandwidth::Rate { + self.side.probe.target() + } + /// How many times the stats were read. pub fn stats_reads(&self) -> usize { self.side.stats_reads.load(Ordering::Relaxed) @@ -881,6 +902,8 @@ pub fn create_mock_session_pair(config: memory::Config) -> (MockSession, MockSes stats_reads: Default::default(), panic_on_stats: Default::default(), wire: Default::default(), + probing: Default::default(), + probe: Default::default(), }), accept_uni: Default::default(), accept_bi: Default::default(), diff --git a/rs/moq-net/tests/integration/viewer_target.rs b/rs/moq-net/tests/integration/viewer_target.rs new file mode 100644 index 00000000000..8b2f6872838 --- /dev/null +++ b/rs/moq-net/tests/integration/viewer_target.rs @@ -0,0 +1,134 @@ +#![cfg(feature = "async")] + +//! A session sends its viewers' sum to the peer as the PROBE target, and a sending +//! session probes to the larger of its own reservations and the peer's target. + +use crate::support; + +use std::time::Duration; + +use moq_net::{Version, bandwidth::Rate, broadcast, track}; +use support::harness::{MockConnectOptions, MockPair, connect_mock}; +use support::mock::{MockSession, MockStats}; + +/// The versions whose SETUP carries the probe level a target is gated on. +const VERSIONS: [&str; 2] = ["moq-lite-06", "moq-lite-07-wip"]; + +const STATS: MockStats = MockStats { + estimated_send_rate: Some(10_000_000), + rtt: Some(Duration::from_millis(40)), +}; + +/// A connected pair, each side with a sender when `probe`. +async fn pair(version: &str, probe: bool) -> MockPair { + let mut options = MockConnectOptions::new(version.parse::().unwrap()); + options.stats = STATS; + options.probe = probe; + connect_mock(options).await +} + +fn mbps(n: u64) -> Rate { + Rate::from_mbps(n) +} + +/// Run until `transport`'s sender is handed `target`. +async fn probes_to(transport: &MockSession, target: Rate) { + while transport.probe_target() != target { + moq_clock::sleep(Duration::from_millis(1)).await; + } +} + +/// A track to reserve for, plus the broadcast keeping it alive. +fn reservable() -> (broadcast::Producer, track::Producer) { + let broadcast = broadcast::Info::default().produce(); + let track = broadcast.create_track("t", None).unwrap(); + (broadcast, track) +} + +#[moq_clock::test] +async fn viewers_sum_into_the_peers_target() { + for version in VERSIONS { + let pair = pair(version, true).await; + let viewers = pair.client.viewers(); + + let first = viewers.watch(mbps(3)); + probes_to(&pair.server_transport, mbps(3)).await; + let second = viewers.watch(mbps(2)); + probes_to(&pair.server_transport, mbps(5)).await; + first.update(mbps(1)); + probes_to(&pair.server_transport, mbps(3)).await; + + drop(second); + probes_to(&pair.server_transport, mbps(1)).await; + // The last viewer releases the PROBE stream, and the target lapses with it. + drop(first); + probes_to(&pair.server_transport, Rate::ZERO).await; + } +} + +#[moq_clock::test] +async fn the_sender_probes_to_the_larger_target() { + for version in VERSIONS { + let pair = pair(version, true).await; + let (_broadcast, track) = reservable(); + let reserved = pair.server.allocator().reserve(&track.demand(), mbps(4)); + probes_to(&pair.server_transport, mbps(4)).await; + + let viewer = pair.client.viewers().watch(mbps(6)); + probes_to(&pair.server_transport, mbps(6)).await; + viewer.update(mbps(2)); + probes_to(&pair.server_transport, mbps(4)).await; + drop(reserved); + probes_to(&pair.server_transport, mbps(2)).await; + } +} + +/// A session that publishes and watches probes its uplink for what it sends, never +/// for what it watches, and its peer the other way around. +#[moq_clock::test] +async fn the_directions_stay_apart() { + for version in VERSIONS { + let pair = pair(version, true).await; + let (_broadcast, track) = reservable(); + let _sent = pair.client.allocator().reserve(&track.demand(), mbps(1)); + let _watched = pair.client.viewers().watch(mbps(6)); + + probes_to(&pair.client_transport, mbps(1)).await; + probes_to(&pair.server_transport, mbps(6)).await; + moq_clock::sleep(Duration::from_secs(1)).await; + assert_eq!(pair.client_transport.probe_target(), mbps(1), "{version}"); + assert_eq!(pair.server_transport.probe_target(), mbps(6), "{version}"); + } +} + +#[moq_clock::test] +async fn opting_out_sends_no_target() { + for version in VERSIONS { + let pair = pair(version, true).await; + let viewers = pair.client.viewers(); + viewers.set_target(Some(Rate::ZERO)); + let viewer = viewers.watch(mbps(6)); + let mut grant = viewer.consume(); + // The estimate arrives, so the PROBE stream is up and the target would have too. + assert_eq!(grant.changed().await.unwrap(), Some(mbps(6)), "{version}"); + moq_clock::sleep(Duration::from_secs(1)).await; + assert_eq!(pair.server_transport.probe_target(), Rate::ZERO, "{version}"); + assert!(!grant.probed(), "{version}: opted out, nothing probes for it"); + + viewers.set_target(None); + probes_to(&pair.server_transport, mbps(6)).await; + assert!(grant.probed(), "{version}"); + } +} + +/// A peer without a sender advertises `Report`, so its viewers are never probed for. +#[moq_clock::test] +async fn a_peer_without_a_sender_is_sent_no_target() { + for version in VERSIONS { + let pair = pair(version, false).await; + let viewer = pair.client.viewers().watch(mbps(6)); + let mut grant = viewer.consume(); + assert_eq!(grant.changed().await.unwrap(), Some(mbps(6)), "{version}"); + assert!(!grant.probed(), "{version}"); + } +} diff --git a/rs/moq-tokio/src/client.rs b/rs/moq-tokio/src/client.rs index 7e45b517dd6..cf0ccda0749 100644 --- a/rs/moq-tokio/src/client.rs +++ b/rs/moq-tokio/src/client.rs @@ -244,6 +244,12 @@ impl Client { self } + /// Share `viewers` with every session this client dials. + pub(crate) fn with_viewers(mut self, viewers: moq_net::bandwidth::Viewers) -> Self { + self.moq = self.moq.with_viewers(viewers); + self + } + /// Price the links this client dials; see [`moq_net::Client::with_cost`]. pub fn with_cost(mut self, cost: u64) -> Self { self.moq = self.moq.with_cost(cost); diff --git a/rs/moq-tokio/src/connection.rs b/rs/moq-tokio/src/connection.rs index 8886a1045ab..2fbe4a0aec4 100644 --- a/rs/moq-tokio/src/connection.rs +++ b/rs/moq-tokio/src/connection.rs @@ -936,6 +936,8 @@ pub struct Connection { bandwidth: moq_net::bandwidth::Allocator, /// Persistent recv-bitrate estimate, fed by the loop from each live session. recv_bandwidth: moq_net::bandwidth::Weak, + /// Divides `recv_bandwidth`, and every session the loop dials sends its viewers' target. + viewers: moq_net::bandwidth::Viewers, /// The last status returned by [`status`](Self::status), for change detection. /// Per-clone: a clone starts from its parent's cursor and diverges from there. last_reported: Option, @@ -980,7 +982,8 @@ impl Connection { let send_bandwidth = send_bw.consume(); let recv_bandwidth = recv_bw.weak(); let bandwidth = moq_net::bandwidth::Allocator::new(send_bandwidth.clone()); - let client = client.with_allocator(bandwidth.clone()); + let viewers = moq_net::bandwidth::Viewers::new(recv_bandwidth.clone()); + let client = client.with_allocator(bandwidth.clone()).with_viewers(viewers.clone()); let closed: CloseGuard = Default::default(); let task_closed = closed.clone(); @@ -1028,6 +1031,7 @@ impl Connection { send_bandwidth, recv_bandwidth, bandwidth, + viewers, last_reported: None, } } @@ -1562,6 +1566,15 @@ impl Connection { self.recv_bandwidth.consume() } + /// Divides [`recv_bandwidth`](Self::recv_bandwidth) among the broadcasts watched over + /// this connection, mirroring [`moq_net::Session::viewers`]. + /// + /// Persistent like the estimate: every session the loop dials sends these viewers' + /// target, so they survive reconnects. Viewers report `None` while disconnected. + pub fn viewers(&self) -> moq_net::bandwidth::Viewers { + self.viewers.clone() + } + /// Poll whether the connection loop has stopped. /// /// `Ready(Err)` if it permanently gave up (reconnect timeout exceeded, an auth From edc77a487814556bf726b9b53c1bcba0081e8ad0 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 28 Oct 2026 05:37:31 -0700 Subject: [PATCH 03/20] chore(quest): finish viewer targets Move the browser's peer-target half to padding, its sender, and the peer-target clamp to the rate grant. Co-Authored-By: Claude Opus 5.5 --- .../m2/performance-survey/bandwidth-grants.md | 7 +- quest/m2/probe/README.md | 7 +- quest/m2/probe/padding.md | 16 +++- quest/m2/probe/players.md | 9 +- quest/m2/probe/viewer-target.md | 87 ------------------- quest/m2/probe/viewer-upswitch.md | 9 +- quest/m2/rate-grant.md | 6 ++ 7 files changed, 33 insertions(+), 108 deletions(-) delete mode 100644 quest/m2/probe/viewer-target.md diff --git a/quest/m2/performance-survey/bandwidth-grants.md b/quest/m2/performance-survey/bandwidth-grants.md index bb35a35399b..848d77ff533 100644 --- a/quest/m2/performance-survey/bandwidth-grants.md +++ b/quest/m2/performance-survey/bandwidth-grants.md @@ -50,9 +50,10 @@ registrations, which the sweep must count as well. Consider calculating a shared allocation once per relevant change, but retain strict priority, max-min fairness, rounding, ties, immediate peek behavior and closed-demand removal. An idle sender still sees the share it would regain -without shrinking its active siblings' grants; that is intended. Cover both languages in this quest. Coordinate with -[viewer targets](/quest/m2/probe/viewer-target.md), which changes how the same -allocator feeds probes. +without shrinking its active siblings' grants; that is intended. Cover both languages in this quest. Viewer grants +(`bandwidth::Viewers`, `Bandwidth.Viewers`, [moq-dev/moq#7090](https://github.com/moq-dev/moq/pull/7090)) divide the receive estimate +through the same registry and `Share::grant`, so the fix covers them too; the +`bandwidth/viewers` bench sweeps their count. Follow the [survey's benchmark contract](/quest/m2/performance-survey/README.md): measure the baseline before optimizing, retain paired evidence, verify equivalent diff --git a/quest/m2/probe/README.md b/quest/m2/probe/README.md index 39d4029a866..77aaa420205 100644 --- a/quest/m2/probe/README.md +++ b/quest/m2/probe/README.md @@ -29,7 +29,7 @@ publisher-local padding handle: target and the peer's PROBE target. PROBE `Increase` is the wire signal; retransmission or padding is the mechanism. The send target (`bandwidth::Allocator`'s reservations) owns the local half and - [viewer targets](/quest/m2/probe/viewer-target.md) the peer's. + viewer targets (`bandwidth::Viewers`, [moq-dev/moq#7090](https://github.com/moq-dev/moq/pull/7090)) the peer's. - **Viewers are in scope.** The viewer up-switch joined the epic, since a viewer's target is the same session target sent the other way. - **moq-net stays catalog-agnostic, and each hop is independent.** A relay @@ -63,8 +63,8 @@ Decided with the maintainer on 2026-10-20: probes with padding. - The target then split: m1 keeps the send target native rung recovery needs, and viewer handles, viewer grants, the peer's - PROBE target, and `Increase` came back here as - [viewer targets](/quest/m2/probe/viewer-target.md), beside their consumers. + PROBE target, and `Increase` came back here as viewer targets, beside their + consumers, and landed in [moq-dev/moq#7090](https://github.com/moq-dev/moq/pull/7090). The `js/net` send target moved to [padding](/quest/m2/probe/padding.md), its only sender. @@ -85,7 +85,6 @@ This README's own work, once the children land: - [Native rung disable](/quest/m1/simulcast-rung-disable.md) - OBS stops sending the top renditions its grant cannot fund, as the Rust/FFI publishers do, and a shaped uplink through moq-ffi proves the resume - [Padding probes](/quest/m2/probe/padding.md) - a browser probes with a lowest-priority padding stream on an ALR schedule - [JS rung disable](/quest/m2/probe/rung-disable-js.md) - `@moq/publish` applies the native rung rule, recovering through padding -- [Viewer targets](/quest/m2/probe/viewer-target.md) - a session sends its viewer handles as its PROBE target, probes to the peer's, splits the receive estimate into viewer grants, and advertises `Increase` where a sender exists - [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 diff --git a/quest/m2/probe/padding.md b/quest/m2/probe/padding.md index a41a5c36937..15e59c33dc5 100644 --- a/quest/m2/probe/padding.md +++ b/quest/m2/probe/padding.md @@ -9,9 +9,8 @@ sends a short probe cluster at about twice the estimate, capped at the target, about every five seconds, with a follow-up probe when one validates. When the path has room the estimate rises; when it doesn't, padding stays within its overhead and media frame-delay budgets. Such sessions on lite-07 or IETF -draft-18 and later then have a sender, so -[viewer targets](/quest/m2/probe/viewer-target.md) can advertise PROBE -`Increase` for them. +draft-18 and later then have a sender, so they advertise PROBE `Increase` and +probe to the larger of their send target and the peer's PROBE target. ## Plan @@ -33,6 +32,14 @@ Decided with the maintainer on 2026-10-17 (see the (`js/net/src/connection/reload.ts`). Moved here in review of [#6102](https://github.com/moq-dev/moq/pull/6102), so m1 ships no browser target without a sender. +- **The peer's target.** Viewer targets landed first ([moq-dev/moq#7090](https://github.com/moq-dev/moq/pull/7090)), so + `js/net` still advertises `Report` and its publisher's `runProbe` reads and + drops a peer's PROBE target. With padding, keep the latest target from each + PROBE stream (zero once the stream ends), pad to the larger of it and the send + target, and advertise `Increase` from `probeLevel` only where padding runs, + mirroring Rust's `ProbeLevel::detect` and the session's `Probing` in + `rs/moq-net/src/session.rs`. The two directions never mix: a viewer's own + target goes to its peer, never into what it pads. - **WebRTC's schedule.** Model it on GoogCC's `ProbeController` ALR probing. Rejected: [#5863](https://github.com/moq-dev/moq/pull/5863)'s exponential backoff to 60 s, which leaves a rendition waiting up to a minute after the @@ -63,6 +70,9 @@ Tests, on `@moq/clock`'s `Manual`: - The padding writer over a fake WebTransport: padding goes out at the lowest priority on lite-07 and IETF draft-18, while lite-05, lite-06, and drafts 14 to 17 pad nothing and negotiate `Report`. +- A peer's PROBE target raises what padding probes to, a session that also + watches never pads for its own viewers, and the target lapses when the + PROBE stream ends. - In Chrome through a shaped link: with padding the estimate rises past the media, without it it stays frozen. On a path held below the target, report media frame delay and deadline misses against budgets set before tuning: diff --git a/quest/m2/probe/players.md b/quest/m2/probe/players.md index eadf39e9eef..f73be05729d 100644 --- a/quest/m2/probe/players.md +++ b/quest/m2/probe/players.md @@ -16,8 +16,9 @@ Decided with the maintainer on 2026-10-17 (see the already reads the catalog, which keeps moq-net catalog-agnostic, and only an enabled rendition is one it could switch to. Targets are on by default. -- The handle comes from the [viewer targets](/quest/m2/probe/viewer-target.md) quest; this - quest only decides its `max`. +- The handle is a `Bandwidth.Viewer` from `connection.viewers` in `@moq/net` + (`Session::viewers` or `moq_tokio::Connection::viewers` in Rust), landed in + [moq-dev/moq#7090](https://github.com/moq-dev/moq/pull/7090); this quest only decides its `max`. - Settle what a rendition without a catalog bitrate contributes. - A probe that reaches the target must make the rendition selectable. Selection discounts the estimate (0.8x in `js/watch/src/video/source.ts`) @@ -28,7 +29,3 @@ enabled rendition is one it could switch to. Targets are on by default. Tests with mocked catalogs: the target tracks the highest enabled rendition through enable and disable flips, ignores disabled ones, drops when unwatched, and yields to an application override. - -## Required - -- [Viewer targets](/quest/m2/probe/viewer-target.md) - the per-broadcast viewer handle diff --git a/quest/m2/probe/viewer-target.md b/quest/m2/probe/viewer-target.md deleted file mode 100644 index 695490903f1..00000000000 --- a/quest/m2/probe/viewer-target.md +++ /dev/null @@ -1,87 +0,0 @@ -# [M] Viewer probe targets and grants - -## Goal - -A moq-net session and a `js/net` connection each keep a receive target: the -sum of their viewer handles, sent to the peer as the PROBE target. A sending -session probes to the larger of its own send target -(`bandwidth::Allocator`'s; in `js/net`, the one [padding](/quest/m2/probe/padding.md) adds) and the -peer's PROBE target, and advertises PROBE `Increase` where it has a -sender. The two directions never mix: a session that publishes and watches -doesn't probe its uplink for what it watches. - -Each viewer handle also reads a grant: its share of the session's receive -estimate, so several broadcasts watched over one connection each select -against their own share instead of the whole downlink. - -## Plan - -Split from the send target by the maintainer on -2026-10-20: m1 native rung recovery needs only the send target, while these -handles' consumers ([players](/quest/m2/probe/players.md) and the -[viewer up-switch](/quest/m2/probe/viewer-upswitch.md)) are in m2. - -Decided with the maintainer on 2026-10-17 (see the -[epic](/quest/m2/probe/README.md)): - -- **A viewer handle per broadcast.** The subscriber session hands out a - reservation-like handle carrying a `max`, one per watched broadcast; the - session sums the live handles and sends the sum as its PROBE target. - Updating or dropping a handle changes the sum. Rejected: one target the - application sums, which pushes the multi-broadcast case onto every app. - Players hold these handles. -- **Viewer grants.** Decided with the maintainer on 2026-10-19: a viewer - handle carries a grant the way a publisher `Reservation` does, splitting the - receive estimate across live handles max-min fair by `max`, the split the - send `Allocator` applies within one priority tier - (`rs/moq-net/src/model/bandwidth.rs`). A handle asking for less than an even - cut takes all of it and leaves the rest to the others. Today every - `` on a pooled connection selects against 0.8x the whole - `estimatedRecvRate`, so N watchers over-select about N times. Rejected: each - watcher measuring its own subscription's rate, which stays app-limited and - can't see headroom, and dividing the estimate by the watcher count, which - ignores each handle's `max`. - Handles carry no priority: subscription priorities are per track and fixed - by kind, so no per-broadcast priority exists to divide by. Add one when a - player needs to favor one broadcast over another. -- **Peer target.** A sending session probes to the larger of its own target - and the peer's PROBE target. Each hop is independent: a relay never forwards - a viewer's target upstream, and the PROBE target stays per connection, with - no per-track wire field. moq-net reads no catalog. A peer's target is - untrusted, but it only sets how high to probe: each probe scales the - current estimate (BBR's 1.25x phase, padding's 2x cluster) and stays under - congestion control. Repeated cycles can still walk the estimate up to the - path's capacity, so a huge target costs the redundant bytes of probing that - far, held to native probing's overhead budget (redundant bytes at most - 10% of unique bytes, [moq-dev/moq#6635](https://github.com/moq-dev/moq/pull/6635)); a peer that subscribes to more media can already cost the - sender that much. Clamp it to the session's rate cap where one exists - ([rate grant](/quest/m2/rate-grant.md)) rather than adding a constant. -- **`Increase` only with a sender.** SETUP advertises `Increase` only when - the session has a sender behind the seam the send target defines: native - probing on moq-quic, padding in the browser. A browser session on a version - [padding](/quest/m2/probe/padding.md) refuses (lite-05, lite-06) has none, so it keeps `Report`. -- **Automatic, opt-out.** Targets are on by default; an application can - override them or disable probing. - -Notes for the implementer: - -- Rust sessions request PROBE today only while an owned `recv_bandwidth()` - consumer is held (`doc/concept/standard.md`). If the viewer handle subsumes - that, migrate those callers in the same change; a held consumer never - silently stops requesting PROBE. -- Wire: none. PROBE already carries a target and SETUP the `Increase` level - (`drafts/draft-lcurley-moq-lite.md`, `drafts/draft-lcurley-moq-probe.md`). - Report the public API in the PR, mirrored across Rust and JS, and carry it - through moq-ffi and the bindings per the cross-package sync table. - -Tests with mocked time, Rust and JS: viewer handles sum into the PROBE target -sent to the peer; the session probes to the larger of its reservations and -the peer's target; a session that publishes and watches keeps the two -directions apart; viewer grants split the receive estimate max-min fair by -`max` and never sum above it; `Increase` is advertised only with a sender, and never by a browser session -on a version padding refuses; -opting out sends no target. - -The sum fans out over viewer handles, so add a benchmark sweeping their count, -wired into the benchmark CI, so an update that rescans every handle shows up -as a slope. diff --git a/quest/m2/probe/viewer-upswitch.md b/quest/m2/probe/viewer-upswitch.md index 7d84f3a3129..3a6ef603302 100644 --- a/quest/m2/probe/viewer-upswitch.md +++ b/quest/m2/probe/viewer-upswitch.md @@ -19,14 +19,14 @@ estimate. Decided with the maintainer on 2026-10-17: this joined the [probe epic](/quest/m2/probe/README.md). [Players](/quest/m2/probe/players.md) -set the viewer target, the [session](/quest/m2/probe/viewer-target.md) sends it as -its PROBE target, and the relay's sender probes the downlink up to it; this +set the viewer target, the session sends it as its PROBE target +([moq-dev/moq#7090](https://github.com/moq-dev/moq/pull/7090)), and the relay's sender probes the downlink up to it; this quest makes selection act on the estimate that rises. The relay runs moq-quic, whose native probing ([moq-dev/moq#6635](https://github.com/moq-dev/moq/pull/6635)) is that sender. -Selection reads its broadcast's viewer grant from the -[viewer targets](/quest/m2/probe/viewer-target.md) quest, not the connection's whole +Selection reads its broadcast's viewer grant (`Bandwidth.Viewer.rate`), not +the connection's whole `estimatedRecvRate`, so several watchers on one pooled connection don't each select against the full downlink (decided with the maintainer on 2026-10-19). @@ -37,7 +37,6 @@ and audio, or selection stops discounting a probed estimate. ## Required -- [Viewer targets](/quest/m2/probe/viewer-target.md) - the viewer handle the session sends as its PROBE target, and the relay probing up to it - [Players set viewer targets](/quest/m2/probe/players.md) - `@moq/watch` asks for its highest enabled rendition ## Closes diff --git a/quest/m2/rate-grant.md b/quest/m2/rate-grant.md index 1295b89c771..bcc07265ed0 100644 --- a/quest/m2/rate-grant.md +++ b/quest/m2/rate-grant.md @@ -33,6 +33,12 @@ negotiated IETF AUTH extension and `drafts/draft-lcurley-moq-auth.md` unchanged: extending cap reporting to IETF is outside this quest. Keeping that boundary avoids expanding the agreed lite-only wire change. +A sending session also clamps the peer's PROBE target to the cap it enforces +on that peer, as viewer targets decided rather than adding a constant: a target +past the cap only buys probing overhead the peer can never receive. The session +takes the larger of its own and the peer's target in `Probing` +(`rs/moq-net/src/session.rs`, [moq-dev/moq#7090](https://github.com/moq-dev/moq/pull/7090)); clamp the peer's half there. + Tests: a capped session's grant carries the rates; the publisher's video target never exceeds the cap minus overhead; a raised cap lets it climb back. From 52354fb540474cf3b47b574c6254858a6163908a Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 28 Oct 2026 05:53:54 -0700 Subject: [PATCH 04/20] docs(net): the client advertises Increase with a sender Co-Authored-By: Claude Opus 5.5 --- rs/moq-net/src/client.rs | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/rs/moq-net/src/client.rs b/rs/moq-net/src/client.rs index f23e2a1b529..a3df54311ca 100644 --- a/rs/moq-net/src/client.rs +++ b/rs/moq-net/src/client.rs @@ -311,11 +311,12 @@ impl Client { ) -> Result<(Session, crate::Driver), Error> { let (publish, subscribe) = self.origins(peer_hop); - // Advertise our capabilities (we report what the transport measures; we - // don't pad) plus the request path on URI-less transports, and the - // direction we intend to use so the server can reject a token that lacks - // the matching scope during the handshake instead of silently carrying - // no media. Versions without a Setup Stream have nothing to advertise. + // Advertise our capabilities (we report what the transport measures, and + // probe to the peer's target only with a sender) plus the request path on + // URI-less transports, and the direction we intend to use so the server + // can reject a token that lacks the matching scope during the handshake + // instead of silently carrying no media. Versions without a Setup Stream + // have nothing to advertise. let our_setup = if version.has_setup_stream() { lite::Setup { probe: lite::ProbeLevel::detect(&session), From b10c63c96d757edef46a8a8cb0bc2057ff83a5f7 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Fri, 30 Oct 2026 21:12:15 -0700 Subject: [PATCH 05/20] feat(ffi): viewers divide the receive estimate MoqSession::viewers returns a MoqViewers registry; MoqViewers::watch returns a MoqViewer reading its slice, and the session sends the viewers' summed ceilings as its PROBE target. Co-Authored-By: Claude Opus 5.5 --- rs/moq-ffi/CHANGELOG.md | 3 ++ rs/moq-ffi/src/bandwidth.rs | 90 ++++++++++++++++++++++++++++++++++ rs/moq-ffi/src/session.rs | 17 +++++++ rs/moq-ffi/src/session/dial.rs | 13 ++++- 4 files changed, 122 insertions(+), 1 deletion(-) diff --git a/rs/moq-ffi/CHANGELOG.md b/rs/moq-ffi/CHANGELOG.md index 89a1c5367a4..e941ca6dac7 100644 --- a/rs/moq-ffi/CHANGELOG.md +++ b/rs/moq-ffi/CHANGELOG.md @@ -9,6 +9,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Added +- `MoqSession::viewers` returns a `MoqViewers` that divides the receive estimate + among watched broadcasts: `MoqViewers::watch` returns a `MoqViewer` reading its + slice, and the viewers' ceilings summed are the PROBE target sent to the peer. - `MoqAudioEncoder::track_init` returns the init that publishes its packets, and `MoqAudioEncoder::set_bitrate` retunes it live. - `MoqAudioDecoderOutput::delay_us` fixes the audio playout delay, and diff --git a/rs/moq-ffi/src/bandwidth.rs b/rs/moq-ffi/src/bandwidth.rs index bc0d22e1f61..999ffc90bb5 100644 --- a/rs/moq-ffi/src/bandwidth.rs +++ b/rs/moq-ffi/src/bandwidth.rs @@ -88,6 +88,73 @@ impl MoqReservation { } } +/// Divides one connection's receive estimate among the broadcasts watched over it, +/// mirroring [`moq_net::bandwidth::Viewers`]. +/// +/// Minted by [`MoqSession::viewers`](crate::session::MoqSession::viewers). Handles from +/// one session share a registry, and the session sends what its viewers' ceilings add +/// up to as its PROBE target, so a peer that probes raises the estimate toward it. +#[derive(uniffi::Object)] +pub struct MoqViewers { + inner: moq_net::bandwidth::Viewers, +} + +impl MoqViewers { + pub(crate) fn new(inner: moq_net::bandwidth::Viewers) -> Self { + Self { inner } + } +} + +#[uniffi::export] +impl MoqViewers { + /// Watch a broadcast receiving at most `max_bps`, returning its viewer. + /// + /// `max_bps` is a ceiling: what the largest rendition the player would switch to + /// needs, not what it is receiving. The claim lasts as long as the returned handle; + /// drop it once the broadcast stops being watched. Holding one requests the receive + /// estimate, like [`MoqSession::recv_bandwidth`](crate::session::MoqSession::recv_bandwidth). + pub fn watch(&self, max_bps: u64) -> Arc { + let _guard = crate::ffi::enter(); + Arc::new(MoqViewer { + inner: self.inner.watch(moq_net::bandwidth::Rate::from_bps(max_bps)), + }) + } + + /// Send `target_bps` as the PROBE target instead of the viewers' sum, or `None` to + /// follow them again. `Some(0)` sends no target. + pub fn set_target(&self, target_bps: Option) { + let _guard = crate::ffi::enter(); + self.inner + .set_target(target_bps.map(moq_net::bandwidth::Rate::from_bps)); + } +} + +/// One watched broadcast's standing claim on a [`MoqViewers`]. +/// +/// [`rate`](Self::rate) is [`moq_net::bandwidth::Viewer::rate`]: `None` means no +/// receive estimate, so hold the current selection. +#[derive(uniffi::Object)] +pub struct MoqViewer { + inner: moq_net::bandwidth::Viewer, +} + +#[uniffi::export] +impl MoqViewer { + /// This viewer's slice of the receive estimate right now, in bits per second. + /// + /// `None` means no estimate: hold the current selection. `Some(0)` is a real zero rate. + pub fn rate(&self) -> Option { + let _guard = crate::ffi::enter(); + self.inner.rate().map(moq_net::bandwidth::Rate::as_bps) + } + + /// Change the ceiling, keeping the same claim. + pub fn update(&self, max_bps: u64) { + let _guard = crate::ffi::enter(); + self.inner.update(moq_net::bandwidth::Rate::from_bps(max_bps)); + } +} + #[cfg(test)] mod tests { use super::*; @@ -203,6 +270,29 @@ mod tests { assert_eq!(reserved.rate(), Some(1_000_000)); } + /// Two viewers split a 3 Mbps receive estimate max-min fair by ceiling. + #[test] + fn viewers_split_the_receive_estimate() { + let estimate = moq_net::bandwidth::Producer::new(); + let viewers = MoqViewers::new(moq_net::bandwidth::Viewers::new(estimate.weak())); + + let first = viewers.watch(4_000_000); + let second = viewers.watch(1_000_000); + assert_eq!(first.rate(), None); + + estimate + .set(Some(moq_net::bandwidth::Rate::from_bps(3_000_000))) + .unwrap(); + assert_eq!(first.rate(), Some(2_000_000)); + assert_eq!(second.rate(), Some(1_000_000)); + + second.update(4_000_000); + assert_eq!(first.rate(), Some(1_500_000)); + + drop(second); + assert_eq!(first.rate(), Some(3_000_000)); + } + #[cfg(all(feature = "video", not(target_arch = "wasm32")))] #[test] fn a_share_wakes_a_parked_thread() { diff --git a/rs/moq-ffi/src/session.rs b/rs/moq-ffi/src/session.rs index aa7bbbdeec2..2665dfc4d2f 100644 --- a/rs/moq-ffi/src/session.rs +++ b/rs/moq-ffi/src/session.rs @@ -1311,6 +1311,23 @@ impl MoqSession { self.allocator.clone() } + /// The session's viewers, used to divide the connection's receive estimate among + /// the broadcasts watched over it. + /// + /// Every call returns a handle to the same registry, and the session sends what its + /// viewers add up to as its PROBE target. A client handle survives reconnects: a + /// viewer reads `None` while disconnected and resumes on the next connection. + pub fn viewers(&self) -> Arc { + Arc::new(crate::bandwidth::MoqViewers::new(match &self.inner { + #[cfg(not(target_arch = "wasm32"))] + Inner::Connection(connection) => connection.viewers(), + #[cfg(not(target_arch = "wasm32"))] + Inner::Session(session) => session.viewers(), + #[cfg(target_arch = "wasm32")] + Inner::Dial(dial) => dial.viewers(), + })) + } + /// Follow the grant the peer gave this session. /// /// Every call returns an independent consumer. A client session's grant follows each diff --git a/rs/moq-ffi/src/session/dial.rs b/rs/moq-ffi/src/session/dial.rs index 10efb740cb0..66717ac2d59 100644 --- a/rs/moq-ffi/src/session/dial.rs +++ b/rs/moq-ffi/src/session/dial.rs @@ -50,6 +50,8 @@ pub(crate) struct Dial { bandwidth: moq_net::bandwidth::Allocator, /// The session's receive estimate, forwarded while a consumer holds it. recv: moq_net::bandwidth::Weak, + /// Persistent from before the handshake: divides `recv`, and the session sends its target. + viewers: moq_net::bandwidth::Viewers, /// Persistent from before the handshake, so a grant consumer taken while dialing follows /// the session; ended with the dial. auth: moq_net::auth::Handle, @@ -66,12 +68,17 @@ impl Dial { let send = moq_net::bandwidth::Producer::new(); let recv = moq_net::bandwidth::Producer::new(); let bandwidth = moq_net::bandwidth::Allocator::new(send.consume()); + let viewers = moq_net::bandwidth::Viewers::new(recv.weak()); let auth = moq_net::auth::Handle::new(); - let client = client.with_allocator(bandwidth.clone()).with_auth(auth.clone()); + let client = client + .with_allocator(bandwidth.clone()) + .with_viewers(viewers.clone()) + .with_auth(auth.clone()); let dial = Self { state: state.clone(), bandwidth, recv: recv.weak(), + viewers, auth: auth.clone(), }; @@ -196,6 +203,10 @@ impl Dial { self.recv.consume() } + pub fn viewers(&self) -> moq_net::bandwidth::Viewers { + self.viewers.clone() + } + /// The auth handle every session of this dial is built on. pub fn auth(&self) -> moq_net::auth::Handle { self.auth.clone() From 5bf755c6b4714747da057a2ec38428a3de9a480b Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Fri, 30 Oct 2026 21:25:06 -0700 Subject: [PATCH 06/20] feat(moq-c): viewers in the C ABI moq_session_viewers, moq_viewers_watch/set_target/close and moq_viewer_rate/update/close mirror the allocator and reservation calls. Co-Authored-By: Claude Opus 5.5 --- rs/moq-c/README.md | 7 +++ rs/moq-c/src/bandwidth.rs | 129 +++++++++++++++++++++++++++++++++++++- rs/moq-c/src/session.rs | 11 ++++ rs/moq-c/src/test.rs | 39 ++++++++++++ 4 files changed, 183 insertions(+), 3 deletions(-) diff --git a/rs/moq-c/README.md b/rs/moq-c/README.md index af18306b768..02c2cb01131 100644 --- a/rs/moq-c/README.md +++ b/rs/moq-c/README.md @@ -39,6 +39,13 @@ int32_t moq_allocator_close(uint32_t allocator); int32_t moq_reservation_rate(uint32_t reservation, uint64_t *bps, bool *present); int32_t moq_reservation_update(uint32_t reservation, uint64_t max_bps); int32_t moq_reservation_close(uint32_t reservation); +int32_t moq_session_viewers(uint32_t session); +int32_t moq_viewers_watch(uint32_t viewers, uint64_t max_bps); +int32_t moq_viewers_set_target(uint32_t viewers, uint64_t target_bps, bool present); +int32_t moq_viewers_close(uint32_t viewers); +int32_t moq_viewer_rate(uint32_t viewer, uint64_t *bps, bool *present); +int32_t moq_viewer_update(uint32_t viewer, uint64_t max_bps); +int32_t moq_viewer_close(uint32_t viewer); // Server int32_t moq_server_listen(const moq_server_config *config, moq_status_callback on_request, void *user_data); diff --git a/rs/moq-c/src/bandwidth.rs b/rs/moq-c/src/bandwidth.rs index 40666ceed13..b83435d6793 100644 --- a/rs/moq-c/src/bandwidth.rs +++ b/rs/moq-c/src/bandwidth.rs @@ -1,16 +1,19 @@ -//! Session bandwidth allocator and per-track reservation, mirroring -//! [`moq_net::bandwidth`]. +//! Session bandwidth allocator and per-track reservation, and the receive-side +//! viewers, mirroring [`moq_net::bandwidth`]. use std::sync::Arc; use crate::{Error, Id, NonZeroSlab, State, ffi}; -/// Allocators minted from a session, plus the reservations taken against them. +/// Allocators minted from a session, plus the reservations taken against them, and +/// the same for the receive side's viewers. #[derive(Default)] pub(crate) struct Bandwidth { allocators: NonZeroSlab, reservations: NonZeroSlab>, consumers: NonZeroSlab>, + viewers: NonZeroSlab, + viewer: NonZeroSlab, } impl Bandwidth { @@ -45,6 +48,10 @@ impl Bandwidth { self.reservations.remove(id).ok_or(Error::NotFound)?; Ok(()) } + + pub fn insert_viewers(&mut self, viewers: moq_net::bandwidth::Viewers) -> Result { + self.viewers.insert(viewers) + } } /// The session's bandwidth allocator. Clones share one reservation registry. @@ -139,6 +146,122 @@ pub extern "C" fn moq_reservation_close(reservation: u32) -> i32 { }) } +/// The session's viewers, dividing the receive estimate among watched broadcasts. +/// +/// Clones share one registry, and the session sends the viewers' ceilings summed as its +/// PROBE target. Returns a non-zero handle, or a negative error if the session is unknown. +#[unsafe(no_mangle)] +pub extern "C" fn moq_session_viewers(session: u32) -> i32 { + ffi::enter(move || { + let session = ffi::parse_id(session)?; + let mut state = State::lock(); + let viewers = state.session.viewers(session)?; + state.bandwidth.insert_viewers(viewers) + }) +} + +/// Release a viewers handle. Viewers watched through it stay until each is closed (or +/// the session's viewers are gone). +#[unsafe(no_mangle)] +pub extern "C" fn moq_viewers_close(viewers: u32) -> i32 { + ffi::enter(move || { + let viewers = ffi::parse_id(viewers)?; + State::lock().bandwidth.viewers.remove(viewers).ok_or(Error::NotFound)?; + Ok(()) + }) +} + +/// Watch a broadcast receiving at most `max_bps`, returning a viewer handle. +/// +/// `max_bps` is a ceiling: what the largest rendition you would switch to needs, not +/// what you are receiving. Holding the viewer requests the receive estimate, like a +/// [`moq_session_recv_bandwidth`] consumer. Close it with [`moq_viewer_close`] once the +/// broadcast stops being watched. +#[unsafe(no_mangle)] +pub extern "C" fn moq_viewers_watch(viewers: u32, max_bps: u64) -> i32 { + ffi::enter(move || { + let viewers = ffi::parse_id(viewers)?; + let mut state = State::lock(); + let viewer = state + .bandwidth + .viewers + .get(viewers) + .ok_or(Error::NotFound)? + .watch(moq_net::bandwidth::Rate::from_bps(max_bps)); + state.bandwidth.viewer.insert(viewer) + }) +} + +/// Send `target_bps` as the PROBE target instead of the viewers' sum. +/// +/// `present` false follows the viewers again. `present` true and `target_bps` 0 sends +/// no target. +#[unsafe(no_mangle)] +pub extern "C" fn moq_viewers_set_target(viewers: u32, target_bps: u64, present: bool) -> i32 { + ffi::enter(move || { + let viewers = ffi::parse_id(viewers)?; + State::lock() + .bandwidth + .viewers + .get(viewers) + .ok_or(Error::NotFound)? + .set_target(present.then(|| moq_net::bandwidth::Rate::from_bps(target_bps))); + Ok(()) + }) +} + +/// This viewer's slice of the receive estimate right now, in bits per second. +/// +/// `present` is false when there is no estimate: keep the current rendition. `present` +/// true and `bps` 0 is a real zero rate. +/// +/// # Safety +/// - `bps` and `present` must be valid pointers. +#[unsafe(no_mangle)] +pub unsafe extern "C" fn moq_viewer_rate(viewer: u32, bps: *mut u64, present: *mut bool) -> i32 { + ffi::enter(move || { + let viewer = ffi::parse_id(viewer)?; + let bps = unsafe { bps.as_mut() }.ok_or(Error::InvalidPointer)?; + let present = unsafe { present.as_mut() }.ok_or(Error::InvalidPointer)?; + let rate = State::lock() + .bandwidth + .viewer + .get(viewer) + .ok_or(Error::NotFound)? + .rate(); + *bps = rate.map_or(0, moq_net::bandwidth::Rate::as_bps); + *present = rate.is_some(); + Ok(()) + }) +} + +/// Change the viewer's ceiling, keeping the same claim. +#[unsafe(no_mangle)] +pub extern "C" fn moq_viewer_update(viewer: u32, max_bps: u64) -> i32 { + ffi::enter(move || { + let viewer = ffi::parse_id(viewer)?; + State::lock() + .bandwidth + .viewer + .get(viewer) + .ok_or(Error::NotFound)? + .update(moq_net::bandwidth::Rate::from_bps(max_bps)); + Ok(()) + }) +} + +/// Release a viewer, handing its share back to the others and lowering the PROBE target. +#[unsafe(no_mangle)] +pub extern "C" fn moq_viewer_close(viewer: u32) -> i32 { + ffi::enter(move || { + let viewer = ffi::parse_id(viewer)?; + // Released outside the lock. + let viewer = State::lock().bandwidth.viewer.remove(viewer).ok_or(Error::NotFound)?; + drop(viewer); + Ok(()) + }) +} + /// One owned estimate and, optionally, its single outstanding changed call. struct Consumer { inner: std::sync::Mutex>, diff --git a/rs/moq-c/src/session.rs b/rs/moq-c/src/session.rs index 7841b8552e7..d0b1f8fbab2 100644 --- a/rs/moq-c/src/session.rs +++ b/rs/moq-c/src/session.rs @@ -294,6 +294,17 @@ impl Session { } } + /// The session's viewers, whose summed ceilings it sends as its PROBE target. A dialed + /// session's survive reconnects, reading no estimate while offline. + /// + /// Errors with [`Error::Offline`] for an accepted session still in SETUP. + pub fn viewers(&self, id: Id) -> Result { + match self.link(id)? { + Link::Dialed { connection, .. } => Ok(connection.viewers()), + Link::Accepted(accepted) => Ok(accepted.as_ref().ok_or(Error::Offline)?.session.viewers()), + } + } + /// Mint receive-estimate demand only when the caller asks for a consumer. pub fn recv_bandwidth(&self, id: Id) -> Result, Error> { match self.link(id)? { diff --git a/rs/moq-c/src/test.rs b/rs/moq-c/src/test.rs index 54434728ffa..1038bd10ae1 100644 --- a/rs/moq-c/src/test.rs +++ b/rs/moq-c/src/test.rs @@ -6421,6 +6421,45 @@ fn bandwidth_reservations_split_the_estimate() { assert_eq!(moq_origin_close(origin), 0); } +/// Two viewers split a 3 Mbps receive estimate max-min fair by ceiling, and closing +/// one hands its share back. +#[test] +fn viewers_split_the_receive_estimate() { + let estimate = moq_net::bandwidth::Producer::new(); + let viewers = { + let mut state = State::lock(); + let viewers = moq_net::bandwidth::Viewers::new(estimate.weak()); + id(i32::from(state.bandwidth.insert_viewers(viewers).unwrap())) + }; + let viewer_rate = |viewer: u32| { + let mut bps = 0; + let mut present = false; + assert_eq!(unsafe { moq_viewer_rate(viewer, &mut bps, &mut present) }, 0); + present.then_some(bps) + }; + + let first = id(moq_viewers_watch(viewers, 4_000_000)); + let second = id(moq_viewers_watch(viewers, 1_000_000)); + assert_eq!(viewer_rate(first), None); + + estimate + .set(Some(moq_net::bandwidth::Rate::from_bps(3_000_000))) + .unwrap(); + assert_eq!(viewer_rate(first), Some(2_000_000)); + assert_eq!(viewer_rate(second), Some(1_000_000)); + + assert_eq!(moq_viewer_update(second, 4_000_000), 0); + assert_eq!(viewer_rate(first), Some(1_500_000)); + assert_eq!(moq_viewers_set_target(viewers, 0, true), 0); + assert_eq!(moq_viewers_set_target(viewers, 0, false), 0); + + assert_eq!(moq_viewer_close(second), 0); + assert_eq!(viewer_rate(first), Some(3_000_000)); + assert_eq!(moq_viewer_close(first), 0); + assert!(moq_viewer_close(first) < 0); + assert_eq!(moq_viewers_close(viewers), 0); +} + /// Two allocator handles share one registry. #[test] fn bandwidth_handles_share_the_registry() { From 4beec47b9a0a10a0956ee46e70690dcb57e2bba7 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Fri, 30 Oct 2026 21:25:06 -0700 Subject: [PATCH 07/20] feat(bindings): carry viewers through every binding Session.viewers() in py, swift, kt, dart and go wraps MoqViewers; the C and C++ packages pick it up from the generator. doc/lib documents each. Co-Authored-By: Claude Opus 5.5 --- dart/moq/lib/src/aliases.dart | 7 + dart/moq/lib/src/client.dart | 10 + dart/moq/test/moq_test.dart | 11 + dart/moq_ffi/lib/src/moq.dart | 286 ++++++++++++++++++ doc/lib/c/index.md | 1 + doc/lib/cpp/index.md | 15 + doc/lib/dart/index.md | 1 + doc/lib/go/index.md | 1 + doc/lib/kt/index.md | 1 + doc/lib/py/index.md | 1 + doc/lib/swift/index.md | 1 + go/wrapper/README.md | 8 + go/wrapper/bandwidth_test.go | 43 +++ go/wrapper/session.go | 57 ++++ .../kotlin/dev/moq/Aliases.kt | 4 + .../jvmAndAndroidMain/kotlin/dev/moq/Moq.kt | 11 + .../kotlin/dev/moq/SmokeTest.kt | 18 ++ py/moq-rs/README.md | 1 + py/moq-rs/moq/__init__.py | 13 +- py/moq-rs/moq/session.py | 58 ++++ py/moq-rs/tests/test_server.py | 25 ++ swift/Sources/Moq/Bandwidth.swift | 48 +++ swift/Sources/Moq/Client.swift | 10 + swift/Tests/MoqTests/SmokeTests.swift | 15 + 24 files changed, 645 insertions(+), 1 deletion(-) diff --git a/dart/moq/lib/src/aliases.dart b/dart/moq/lib/src/aliases.dart index 58085dabb41..05434fdac82 100644 --- a/dart/moq/lib/src/aliases.dart +++ b/dart/moq/lib/src/aliases.dart @@ -159,6 +159,13 @@ typedef BandwidthConsumer = MoqBandwidthConsumer; /// One track's standing claim on an [Allocator]. typedef Reservation = MoqReservation; +/// Divides one connection's receive estimate among the broadcasts watched over it. +typedef Viewers = MoqViewers; + +/// One watched broadcast's standing claim on [Viewers]; holding it requests +/// PROBE, disposing it releases the claim. +typedef Viewer = MoqViewer; + /// A snapshot of transport connection statistics. typedef ConnectionStats = MoqConnectionStats; diff --git a/dart/moq/lib/src/client.dart b/dart/moq/lib/src/client.dart index f8bda830179..9d68ec0e7cb 100644 --- a/dart/moq/lib/src/client.dart +++ b/dart/moq/lib/src/client.dart @@ -247,6 +247,16 @@ final class Moq { /// the room back. Allocator allocator() => session.allocator(); + /// The session's viewers, dividing the connection's receive estimate among + /// the broadcasts watched over it. + /// + /// Every call returns a handle to the same registry, and the session sends + /// what its viewers' ceilings add up to as its PROBE target. [Viewers.watch] + /// a broadcast with the ceiling of the largest rendition the player would + /// switch to, read its slice with [Viewer.rate], and dispose the [Viewer] + /// once the broadcast stops being watched. + Viewers viewers() => session.viewers(); + /// Follow the grant the peer gave this session. /// /// Listen to [GrantConsumerUpdates.updates] for the current grant and each diff --git a/dart/moq/test/moq_test.dart b/dart/moq/test/moq_test.dart index a772ace5575..dd6f12eda2c 100644 --- a/dart/moq/test/moq_test.dart +++ b/dart/moq/test/moq_test.dart @@ -211,6 +211,17 @@ void main() { final serverSession = await accepted; expect(client.allocator(), isA()); + final viewers = client.viewers(); + expect(viewers, isA()); + final viewer = viewers.watch(maxBps: 4000000); + expect(viewer, isA()); + // A slice never exceeds its ceiling, whether or not QUIC has an estimate yet. + viewer.update(maxBps: 1000000); + expect(viewer.rate() ?? 0, lessThanOrEqualTo(1000000)); + viewers.setTarget(targetBps: 0); + viewers.setTarget(targetBps: null); + viewer.dispose(); + final announcement = client.announced().updates().firstWhere( (event) => event is AnnounceEventStart, ); diff --git a/dart/moq_ffi/lib/src/moq.dart b/dart/moq_ffi/lib/src/moq.dart index 4c0bd31cb45..29ccbc397dd 100644 --- a/dart/moq_ffi/lib/src/moq.dart +++ b/dart/moq_ffi/lib/src/moq.dart @@ -8,7 +8,9 @@ import "dart:ffi"; import "dart:io" show Platform, File, Directory; import "dart:isolate"; import "dart:typed_data"; + import "package:ffi/ffi.dart"; + import "uniffi_runtime.dart"; export "uniffi_runtime.dart"; @@ -9378,6 +9380,173 @@ class FfiConverterMoqReservation { } } +abstract class MoqViewerInterface { + int? rate(); + void update({required int maxBps}); +} + +final _MoqViewerFinalizer = Finalizer>((ptr) { + rustCall((status) => uniffi_moq_ffi_fn_free_moqviewer(ptr, status)); +}); + +class MoqViewer implements MoqViewerInterface { + late final Pointer _ptr; + bool _isDisposed = false; + MoqViewer._(this._ptr) { + _MoqViewerFinalizer.attach(this, _ptr, detach: this); + } + factory MoqViewer.lift(Pointer ptr) { + return MoqViewer._(ptr); + } + Pointer uniffiClonePointer() { + if (_isDisposed) { + throw StateError("Object has already been disposed"); + } + return rustCall( + (status) => uniffi_moq_ffi_fn_clone_moqviewer(_ptr, status), + ); + } + + void dispose() { + if (_isDisposed) { + return; + } + _isDisposed = true; + _MoqViewerFinalizer.detach(this); + rustCall((status) => uniffi_moq_ffi_fn_free_moqviewer(_ptr, status)); + } + + int? rate() { + return rustCallWithLifter( + (status) => + uniffi_moq_ffi_fn_method_moqviewer_rate(uniffiClonePointer(), status), + FfiConverterOptionalUInt64.lift, + null, + ); + } + + void update({required int maxBps}) { + return rustCall((status) { + uniffi_moq_ffi_fn_method_moqviewer_update( + uniffiClonePointer(), + FfiConverterUInt64.lower(maxBps), + status, + ); + }, null); + } +} + +class FfiConverterMoqViewer { + static MoqViewer lift(Pointer ptr) { + return MoqViewer.lift(ptr); + } + + static Pointer lower(MoqViewer value) { + return value.uniffiClonePointer(); + } + + static int allocationSize(MoqViewer value) { + return 8; + } + + static LiftRetVal read(Uint8List buf) { + final handle = buf.buffer.asByteData(buf.offsetInBytes).getInt64(0); + final pointer = Pointer.fromAddress(handle); + return LiftRetVal(MoqViewer.lift(pointer), 8); + } + + static int write(MoqViewer value, Uint8List buf) { + final handle = lower(value); + buf.buffer.asByteData(buf.offsetInBytes).setInt64(0, handle.address); + return 8; + } +} + +abstract class MoqViewersInterface { + void setTarget({required int? targetBps}); + MoqViewer watch({required int maxBps}); +} + +final _MoqViewersFinalizer = Finalizer>((ptr) { + rustCall((status) => uniffi_moq_ffi_fn_free_moqviewers(ptr, status)); +}); + +class MoqViewers implements MoqViewersInterface { + late final Pointer _ptr; + bool _isDisposed = false; + MoqViewers._(this._ptr) { + _MoqViewersFinalizer.attach(this, _ptr, detach: this); + } + factory MoqViewers.lift(Pointer ptr) { + return MoqViewers._(ptr); + } + Pointer uniffiClonePointer() { + if (_isDisposed) { + throw StateError("Object has already been disposed"); + } + return rustCall( + (status) => uniffi_moq_ffi_fn_clone_moqviewers(_ptr, status), + ); + } + + void dispose() { + if (_isDisposed) { + return; + } + _isDisposed = true; + _MoqViewersFinalizer.detach(this); + rustCall((status) => uniffi_moq_ffi_fn_free_moqviewers(_ptr, status)); + } + + void setTarget({required int? targetBps}) { + return rustCall((status) { + uniffi_moq_ffi_fn_method_moqviewers_set_target( + uniffiClonePointer(), + FfiConverterOptionalUInt64.lower(targetBps), + status, + ); + }, null); + } + + MoqViewer watch({required int maxBps}) { + return rustCallWithLifter( + (status) => uniffi_moq_ffi_fn_method_moqviewers_watch( + uniffiClonePointer(), + FfiConverterUInt64.lower(maxBps), + status, + ), + FfiConverterMoqViewer.lift, + null, + ); + } +} + +class FfiConverterMoqViewers { + static MoqViewers lift(Pointer ptr) { + return MoqViewers.lift(ptr); + } + + static Pointer lower(MoqViewers value) { + return value.uniffiClonePointer(); + } + + static int allocationSize(MoqViewers value) { + return 8; + } + + static LiftRetVal read(Uint8List buf) { + final handle = buf.buffer.asByteData(buf.offsetInBytes).getInt64(0); + final pointer = Pointer.fromAddress(handle); + return LiftRetVal(MoqViewers.lift(pointer), 8); + } + + static int write(MoqViewers value, Uint8List buf) { + final handle = lower(value); + buf.buffer.asByteData(buf.offsetInBytes).setInt64(0, handle.address); + return 8; + } +} + abstract class MoqBroadcastConsumerInterface { UniffiRustFuture fetchGroup({ required String name, @@ -13588,6 +13757,7 @@ abstract class MoqSessionInterface { UniffiRustFuture stateChanged({required int after}); MoqConnectionStats stats(); MoqTokens? tokens(); + MoqViewers viewers(); } final _MoqSessionFinalizer = Finalizer>((ptr) { @@ -13754,6 +13924,17 @@ class MoqSession implements MoqSessionInterface { null, ); } + + MoqViewers viewers() { + return rustCallWithLifter( + (status) => uniffi_moq_ffi_fn_method_moqsession_viewers( + uniffiClonePointer(), + status, + ), + FfiConverterMoqViewers.lift, + null, + ); + } } class FfiConverterMoqSession { @@ -17305,6 +17486,73 @@ external void uniffi_moq_ffi_fn_method_moqreservation_update( Pointer uniffiStatus, ); +@Native Function(Pointer, Pointer)>( + assetId: _uniffiAssetId, +) +external Pointer uniffi_moq_ffi_fn_clone_moqviewer( + Pointer handle, + Pointer uniffiStatus, +); + +@Native, Pointer)>( + assetId: _uniffiAssetId, +) +external void uniffi_moq_ffi_fn_free_moqviewer( + Pointer handle, + Pointer uniffiStatus, +); + +@Native, Pointer)>( + assetId: _uniffiAssetId, +) +external RustBuffer uniffi_moq_ffi_fn_method_moqviewer_rate( + Pointer ptr, + Pointer uniffiStatus, +); + +@Native, Uint64, Pointer)>( + assetId: _uniffiAssetId, +) +external void uniffi_moq_ffi_fn_method_moqviewer_update( + Pointer ptr, + int max_bps, + Pointer uniffiStatus, +); + +@Native Function(Pointer, Pointer)>( + assetId: _uniffiAssetId, +) +external Pointer uniffi_moq_ffi_fn_clone_moqviewers( + Pointer handle, + Pointer uniffiStatus, +); + +@Native, Pointer)>( + assetId: _uniffiAssetId, +) +external void uniffi_moq_ffi_fn_free_moqviewers( + Pointer handle, + Pointer uniffiStatus, +); + +@Native, RustBuffer, Pointer)>( + assetId: _uniffiAssetId, +) +external void uniffi_moq_ffi_fn_method_moqviewers_set_target( + Pointer ptr, + RustBuffer target_bps, + Pointer uniffiStatus, +); + +@Native Function(Pointer, Uint64, Pointer)>( + assetId: _uniffiAssetId, +) +external Pointer uniffi_moq_ffi_fn_method_moqviewers_watch( + Pointer ptr, + int max_bps, + Pointer uniffiStatus, +); + @Native Function(Pointer, Pointer)>( assetId: _uniffiAssetId, ) @@ -19257,6 +19505,14 @@ external RustBuffer uniffi_moq_ffi_fn_method_moqsession_tokens( Pointer uniffiStatus, ); +@Native Function(Pointer, Pointer)>( + assetId: _uniffiAssetId, +) +external Pointer uniffi_moq_ffi_fn_method_moqsession_viewers( + Pointer ptr, + Pointer uniffiStatus, +); + @Native Function(Pointer, Pointer)>( assetId: _uniffiAssetId, ) @@ -19974,6 +20230,18 @@ external int uniffi_moq_ffi_checksum_method_moqreservation_rate(); @Native(assetId: _uniffiAssetId) external int uniffi_moq_ffi_checksum_method_moqreservation_update(); +@Native(assetId: _uniffiAssetId) +external int uniffi_moq_ffi_checksum_method_moqviewer_rate(); + +@Native(assetId: _uniffiAssetId) +external int uniffi_moq_ffi_checksum_method_moqviewer_update(); + +@Native(assetId: _uniffiAssetId) +external int uniffi_moq_ffi_checksum_method_moqviewers_set_target(); + +@Native(assetId: _uniffiAssetId) +external int uniffi_moq_ffi_checksum_method_moqviewers_watch(); + @Native(assetId: _uniffiAssetId) external int uniffi_moq_ffi_checksum_method_moqbroadcastconsumer_fetch_group(); @@ -20423,6 +20691,9 @@ external int uniffi_moq_ffi_checksum_method_moqsession_stats(); @Native(assetId: _uniffiAssetId) external int uniffi_moq_ffi_checksum_method_moqsession_tokens(); +@Native(assetId: _uniffiAssetId) +external int uniffi_moq_ffi_checksum_method_moqsession_viewers(); + @Native(assetId: _uniffiAssetId) external int uniffi_moq_ffi_checksum_method_moqtokens_answered(); @@ -20670,6 +20941,18 @@ void _checkApiChecksums() { if (uniffi_moq_ffi_checksum_method_moqreservation_update() != 9626) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } + if (uniffi_moq_ffi_checksum_method_moqviewer_rate() != 64505) { + throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); + } + if (uniffi_moq_ffi_checksum_method_moqviewer_update() != 13024) { + throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); + } + if (uniffi_moq_ffi_checksum_method_moqviewers_set_target() != 23388) { + throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); + } + if (uniffi_moq_ffi_checksum_method_moqviewers_watch() != 62773) { + throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); + } if (uniffi_moq_ffi_checksum_method_moqbroadcastconsumer_fetch_group() != 18633) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); @@ -21137,6 +21420,9 @@ void _checkApiChecksums() { if (uniffi_moq_ffi_checksum_method_moqsession_tokens() != 2396) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } + if (uniffi_moq_ffi_checksum_method_moqsession_viewers() != 51586) { + throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); + } if (uniffi_moq_ffi_checksum_method_moqtokens_answered() != 11571) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } diff --git a/doc/lib/c/index.md b/doc/lib/c/index.md index ea47e0561af..a99806d6338 100644 --- a/doc/lib/c/index.md +++ b/doc/lib/c/index.md @@ -110,6 +110,7 @@ inside. The header is the reference: each function carries a doc comment. - **JSON windows.** `moq_publish_json_window` publishes a sliding run of records: `moq_publish_json_window_push` appends at the back, `moq_publish_json_window_pop` drops from the front, and `moq_publish_json_window_cut` closes the open group at a natural boundary. The catalog has no window mode, so a reader names the track. `moq_consume_json_window_event` fills `moq_json_window_event` with a push (the record at `start`, in `json`), a pop of `[start, end)`, or a skip of `[start, end)` that this reader joined too late to receive. Set `checkpoint_records` to bound what each new group restates for a window you never pop. - **Decoded reads.** `moq_decode_audio` and `moq_decode_video` deliver read ids in order: a frame, a gap where media was lost, or an end where the publisher stopped its encoder. Check `kind` on what `moq_decode_audio_read` or `moq_decode_video_read` writes. Free each id with `moq_decode_audio_read_free` or `moq_decode_video_read_free` promptly: a held video frame holds a decoder buffer, and the decoder stalls. A decoder reads everything the track still holds unless a live player sets `start` to `MOQ_DECODE_START_LATEST`, which joins at the newest group and skips the cached backlog. - **Stats.** `moq_session_stats()` fills `moq_connection_stats` with `rtt_us`, `estimated_send_rate_bps`, and the byte and packet counters (`bytes_sent`, `bytes_received`, `bytes_lost`, `packets_sent`, `packets_received`, `packets_lost`). Each has a `_valid` flag, false when the transport does not report it, which is not the same as zero. `moq_session_snapshot()` adds the negotiated `protocol`. A failed dial or dropped connection reaches the session's `on_state` with its `failure` code, and `moq_error()` gives the reason during that callback. Hold the handle returned by `moq_session_recv_bandwidth()` to request receive estimates. `moq_bandwidth_consumer_peek()` reads the estimate and `moq_bandwidth_consumer_changed()` waits for a change. `moq_bandwidth_consumer_close()` releases demand; the last consumer stops PROBE. Stats snapshots do not request it. +- **Viewers.** `moq_session_viewers()` returns a handle that divides the receive estimate among the broadcasts you watch, max-min fair by each one's ceiling. `moq_viewers_watch()` returns a viewer claiming up to `max_bps`, the bitrate of the largest rendition you would switch to; `moq_viewer_rate()` reads its share in bits per second, with `present` false while there is no estimate (keep the current rendition), and `moq_viewer_update()` changes the ceiling. Holding a viewer requests the estimate like a `moq_session_recv_bandwidth()` consumer, and `moq_viewer_close()` releases the claim. The session sends the summed ceilings as its PROBE target; `moq_viewers_set_target()` with `present` true overrides that, a `0` target sends none, and `present` false follows the viewers again. `moq_viewers_close()` releases the registry handle; viewers watched through it stay until each is closed. - **Demand.** A watcher from `moq_publish_track_demand()` (or the media, video, and audio variants) calls back `MOQ_DEMAND_USED` or `MOQ_DEMAND_UNUSED`, again whenever the wanted group moves. `moq_publish_demand_wanted()` reads that group: start a new one once it passes your largest. Set `refresh` in `moq_track_info` to have a joining subscriber ask for a new group once the newest has grown past `refresh` times its first frame. - **Disabled renditions.** A rendition with `enabled: false` has no frames coming until its publisher re-enables it. Select an enabled rendition from the latest catalog before opening a decoder. Keep one already playing while every rendition of its kind is disabled: the convenience decoders accept a disabled configuration, and a re-enable, such as an unmute, then plays without a resubscribe. Among the video renditions you can decode, prefer the highest `preference`; `0` is the default and `-1` marks a compatibility transcode. diff --git a/doc/lib/cpp/index.md b/doc/lib/cpp/index.md index e9829e1fdbc..0dfa95e78c1 100644 --- a/doc/lib/cpp/index.md +++ b/doc/lib/cpp/index.md @@ -203,6 +203,21 @@ A rendition with `enabled: false` has no frames coming until its publisher re-en Hold the owned `BandwidthConsumer` returned by `session->recv_bandwidth()` to receive bandwidth estimates. `rate()` reads the current estimate in bits per second and `rate_changed()` waits for a new one. Releasing the last consumer stops PROBE; the session and stats snapshots do not request it. Client consumers survive reconnects and report no estimate while disconnected. +## Viewers + +`session->viewers()` divides the receive estimate among the broadcasts you watch, max-min fair by each one's ceiling. `watch(max_bps)` returns a `Viewer` claiming up to a ceiling, the bitrate of the largest rendition you would switch to; its `rate()` reads that viewer's share in bits per second, `std::nullopt` while there is no estimate (keep the current rendition), and `update(max_bps)` changes the ceiling. Holding a viewer requests the estimate like `recv_bandwidth()`, and releasing it releases the claim. The session sends the summed ceilings as its PROBE target; `set_target(bps)` overrides that, `0` sends none, and `std::nullopt` follows the viewers again. Client viewers survive reconnects and read `std::nullopt` while disconnected. + +```cpp +auto viewers = session->viewers(); +auto camera = viewers->watch(4'000'000); // what its largest rendition needs +auto screen = viewers->watch(1'000'000); +if (auto bps = camera->rate()) { + // Switch to the largest rendition that fits in *bps. +} +camera->update(2'500'000); // the catalog disabled the top rendition +screen.reset(); // stopped watching: its share returns to camera +``` + ## Compressed tracks `moq::TrackInfo::compress` on a raw track sends each group DEFLATE-compressed to opt-in `moq-lite-07-wip` peers; other peers, and every reader here, get the original frames. diff --git a/doc/lib/dart/index.md b/doc/lib/dart/index.md index 40eb22f5287..bd69b79bd82 100644 --- a/doc/lib/dart/index.md +++ b/doc/lib/dart/index.md @@ -149,6 +149,7 @@ shows which module holds each. - **Closing.** `await moq.close()` drains for up to one second and reports its result. `session.shutdown()` requests the drain synchronously; `await session.closed()` waits for its result. `session.cancel(code: 0)` closes at once. Finish or abort live tracks first. Awaiting cancellation of an announcement, grant, or request subscription releases its pending native read. Announcements and grants also release their consumer; server listeners leave their shared server usable. Application delivery requires explicitly selecting `moq-lite-07-wip` on both peers; older Lite versions (including default lite-06) and IETF wait only for transport ACKs. - **Ending cleanly.** When the input ends, finish every track, then call `finish()` on its `CatalogProducer` to finish the catalog, which ends the content. The broadcast stays announced and keeps serving the finished tracks, so a subscriber still catching up can drain them, until `broadcast.close()` takes it offline; disposing its `Publication` does not. How long to keep it up is yours to decide. A track still open at the close, or released without a finish, ends with `Unroutable`, which readers take as the publisher leaving. - **Stats.** `session.stats()` reports `rtt`, `estimatedSendRateBps`, and the byte and packet counters (`bytesSent`, `bytesReceived`, `bytesLost`, `packetsSent`, `packetsReceived`, `packetsLost`). A field is `null` when the transport does not report it, which is not the same as zero. `version` names the negotiated protocol. Connect returns a connecting session; read its coherent `state()` snapshot and wait with that snapshot's revision to observe first-dial failures and reconnects. Each watcher keeps its own revision. Hold the owned `BandwidthConsumer` returned by `session.recvBandwidth()` to receive bandwidth estimates. `rate()` reads the current estimate in bits per second and `rateChanged()` waits for a new one. Release the consumer or call `cancel()` when finished; releasing the last consumer stops PROBE; the session and stats snapshots do not request it. Client consumers survive reconnects and report no estimate while disconnected. +- **Viewers.** `client.viewers()` divides the connection's receive estimate among the broadcasts you watch, max-min fair by each one's ceiling. `watch(maxBps: ...)` returns a `Viewer` claiming up to what the largest rendition the player would switch to needs; `rate()` reads its slice in bits per second, `null` while there is no estimate, so hold the current selection. `update(maxBps: ...)` changes the ceiling, such as when the catalog enables or disables a rendition. Holding a viewer requests PROBE, and the session sends the viewers' summed ceilings as the PROBE target; `dispose()` it once the broadcast stops being watched. `setTarget(targetBps: ...)` sends another target, `0` sends none, and `null` follows the viewers again. Client viewers survive reconnects and read `null` while disconnected. - **Authorization.** On `moq-lite-07-wip` (opt in with `ConnectOptions(versions: ...)`) and on moq-transport draft-18+ with the [MoQ Auth extension](/draft/moq-auth), listen to `moq.grants().updates()` for the `Grant` the relay sent back and each change, `null` until it answers and while a client session reconnects. - **Tokens.** Pass `ConnectOptions(tokens: [...])` instead of putting the credential in the URL. The first is the connection credential, sent in SETUP and, while an offered version can't carry it there (lite before 07), as the URL's `?jwt=`; each other token widens the grant over AUTH. `moq.tokens().set_(tokens: [...])` replaces them before they expire: the next dial presents them, a live AUTH session at once, and after an authorization refusal the session redials only if they changed. `await tokens().answered()` returns once the relay accepts them and throws its refusal with the relay's code. A `?jwt=` already in the URL stays the connection credential, which is how to reach a relay older than this release. - **Errors.** Read diagnostic payloads from `reason` and structured protocol failures from `details`. diff --git a/doc/lib/go/index.md b/doc/lib/go/index.md index adae42878ff..7123ee87fb7 100644 --- a/doc/lib/go/index.md +++ b/doc/lib/go/index.md @@ -135,6 +135,7 @@ shows which module holds each. - **Closing.** `client.Close()` drains for up to one second and returns an error on failure. `session.Shutdown()` requests that drain immediately; `session.Closed(ctx)` waits for its result, and `session.Cancel(code)` closes at once. Finish or abort live tracks first. Application delivery requires explicitly selecting `moq-lite-07-wip` on both peers; older Lite versions (including default lite-06) and IETF wait only for transport ACKs. - **Ending cleanly.** When the input ends, finish every track, then call `Finish()` on its `media.CatalogProducer` to finish the catalog, which ends the content. The broadcast stays announced and keeps serving the finished tracks, so a subscriber still catching up can drain them, until `broadcast.Close()` takes it offline. How long to keep it up is yours to decide. A track still open at the close, or released without a finish, ends with `Unroutable`, which readers take as the publisher leaving. - **Stats.** `Session().Stats()` reports `RTT`, `EstimatedSendRateBps`, and the byte and packet counters (`BytesSent`, `BytesReceived`, `BytesLost`, `PacketsSent`, `PacketsReceived`, `PacketsLost`). A field is nil when the transport does not report it, which is not the same as zero. `Version` names the negotiated protocol. `Dial` returns a connecting session; read `Session().State()` and wait with `StateChanged(ctx, state.Revision)` to observe first-dial failures and reconnects. Hold the owned `BandwidthConsumer` returned by `Session().RecvBandwidth()` to receive bandwidth estimates. `Rate()` reads the current estimate in bits per second and `RateChanged(ctx)` waits for a new one. Calling `Close()` on the last consumer stops PROBE; the session and stats snapshots do not request it. Client consumers survive reconnects and report no estimate while disconnected. +- **Viewers.** `Session().Viewers()` divides the connection's receive estimate among the broadcasts you watch, max-min fair by each one's ceiling. `Watch(maxBps)` returns a `Viewer` claiming up to what the largest rendition the player would switch to needs; `Rate()` reads its slice in bits per second, nil while there is no estimate, so hold the current selection. `Update(maxBps)` changes the ceiling, such as when the catalog enables or disables a rendition. Holding a viewer requests PROBE, and the session sends the viewers' summed ceilings as the PROBE target; `Close()` it once the broadcast stops being watched, from the goroutine that last used it. `SetTarget(&bps)` sends another target, zero sends none, and nil follows the viewers again. Client viewers survive reconnects and read nil while disconnected. - **Authorization.** On `moq-lite-07-wip` (opt in with `ClientConfig.Versions`) and on moq-transport draft-18+ with the [MoQ Auth extension](/draft/moq-auth), `Session().Grants()` returns a `GrantConsumer`: `Grant()` is the `Grant` the relay sent back, nil until it answers and while a client session reconnects, and `Changed(ctx)` waits for the next one. `Close()` it when done. - **Tokens.** Set `ClientConfig.Tokens` instead of putting the credential in the URL. The first is the connection credential, sent in SETUP and, while an offered version can't carry it there (lite before 07), as the URL's `?jwt=`; each other token widens the grant over AUTH. `Session().Tokens().Set(...)` replaces a client session's tokens before they expire: the next dial presents them, a live AUTH session at once, and after an authorization refusal the session redials only if they changed. `Answered(ctx)` returns nil once the relay accepts them, or its refusal with the relay's code. A `?jwt=` already in the URL stays the connection credential, which is how to reach a relay older than this release. - **Errors.** Read diagnostic payloads from `Reason` and structured protocol failures from `Details`. diff --git a/doc/lib/kt/index.md b/doc/lib/kt/index.md index 15da4c2e82b..21f296ec0fd 100644 --- a/doc/lib/kt/index.md +++ b/doc/lib/kt/index.md @@ -106,6 +106,7 @@ shows which module holds each. - **Closing.** `moq.shutdown()` requests a drain immediately; suspending `moq.session.closed()` waits up to one second and reports its result. `Moq.close()`, and so `use { }`, cancels at once. Finish or abort live tracks first. Application delivery requires explicitly selecting `moq-lite-07-wip` on both peers; older Lite versions (including default lite-06) and IETF wait only for transport ACKs. - **Ending cleanly.** When the input ends, finish every track, then call `finish()` on its `CatalogProducer` to finish the catalog, which ends the content. The broadcast stays announced and keeps serving the finished tracks, so a subscriber still catching up can drain them, until `broadcast.end()` takes it offline. How long to keep it up is yours to decide. A track still open at the end, or released without a finish, ends with `Unroutable`, which readers take as the publisher leaving. - **Stats.** `session.stats()` reports `rtt`, `estimatedSendRateBps`, and the byte and packet counters (`bytesSent`, `bytesReceived`, `bytesLost`, `packetsSent`, `packetsReceived`, `packetsLost`). A field is `null` when the transport does not report it, which is not the same as zero. `version` names the negotiated protocol. Connect returns a connecting session; read its coherent `state()` snapshot and wait with that snapshot's revision to observe first-dial failures and reconnects. Each watcher keeps its own revision. Hold the owned `BandwidthConsumer` returned by `session.recvBandwidth()` to receive bandwidth estimates. `rate()` reads the current estimate in bits per second and `rateChanged()` waits for a new one. Release the consumer or call `cancel()` when finished; releasing the last consumer stops PROBE; the session and stats snapshots do not request it. Client consumers survive reconnects and report no estimate while disconnected. +- **Viewers.** `moq.viewers()` divides the connection's receive estimate among the broadcasts you watch, max-min fair by each one's ceiling. `watch(maxBps)` returns a `Viewer` claiming up to what the largest rendition the player would switch to needs; `rate()` reads its slice in bits per second, `null` while there is no estimate, so hold the current selection. `update(maxBps)` changes the ceiling, such as when the catalog enables or disables a rendition. Holding a viewer requests PROBE, and the session sends the viewers' summed ceilings as the PROBE target; `close()` it, or leave `use { }`, once the broadcast stops being watched. `setTarget(bps)` sends another target, `0` sends none, and `null` follows the viewers again. Client viewers survive reconnects and read `null` while disconnected. - **Authorization.** On `moq-lite-07-wip` (opt in with `ClientConfig(versions = ...)`) and on moq-transport draft-18+ with the [MoQ Auth extension](/draft/moq-auth), collect `moq.grants().updates()` for the `Grant` the relay sent back and each change, `null` until it answers and while a client session reconnects. Ending the collection cancels the consumer. - **Tokens.** Pass `ClientConfig(tokens = listOf(...))` instead of putting the credential in the URL. The first is the connection credential, sent in SETUP and, while an offered version can't carry it there (lite before 07), as the URL's `?jwt=`; each other token widens the grant over AUTH. `moq.tokens().set(listOf(...))` replaces them before they expire: the next dial presents them, a live AUTH session at once, and after an authorization refusal the session redials only if they changed. Suspending `tokens().answered()` returns once the relay accepts them and throws its refusal with the relay's code. A `?jwt=` already in the URL stays the connection credential, which is how to reach a relay older than this release. - **Errors.** Read diagnostic payloads from `reason` and structured protocol failures from `details`. diff --git a/doc/lib/py/index.md b/doc/lib/py/index.md index 32672b11dd4..9546b07de49 100644 --- a/doc/lib/py/index.md +++ b/doc/lib/py/index.md @@ -123,6 +123,7 @@ shows which module holds each. - **Closing.** `session.shutdown()` requests a drain immediately; `await session.closed()` waits up to one second and reports its result. `cancel(code)` closes at once. Finish or abort live tracks first. Application delivery requires explicitly selecting `moq-lite-07-wip` on both peers; older Lite versions (including default lite-06) and IETF wait only for transport ACKs. - **Ending cleanly.** When the input ends, finish every track, then call `finish()` on its `moq.media.CatalogProducer` to finish the catalog, which ends the content. The broadcast stays announced and keeps serving the finished tracks, so a subscriber still catching up can drain them, until `broadcast.close()` takes it offline. How long to keep it up is yours to decide. A track still open at the close, or released without a finish, ends with `Unroutable`, which readers take as the publisher leaving. - **Stats.** `session.stats()` reports `rtt`, `estimated_send_rate_bps`, and the byte and packet counters (`bytes_sent`, `bytes_received`, `bytes_lost`, `packets_sent`, `packets_received`, `packets_lost`). A field is `None` when the transport does not report it, which is not the same as zero. `version` names the negotiated protocol. Connect returns a connecting session; read its coherent `state()` snapshot and wait with that snapshot's revision to observe first-dial failures and reconnects. Each watcher keeps its own revision. Hold the owned `BandwidthConsumer` returned by `session.recv_bandwidth()` to receive bandwidth estimates. `rate()` reads the current estimate in bits per second and `rate_changed()` waits for a new one. Release the consumer or call `cancel()` when finished; releasing the last consumer stops PROBE; the session and stats snapshots do not request it. Client consumers survive reconnects and report no estimate while disconnected. +- **Viewers.** `session.viewers()` divides the receive estimate among the broadcasts you watch. `watch(max_bps)` returns a `Viewer` claiming up to a ceiling, the bitrate of the largest rendition you would switch to; its `rate()` reads that viewer's fair share in bits per second, `None` while there is no estimate (keep the current rendition), and `update(max_bps)` changes the ceiling. Holding a viewer requests the estimate like `recv_bandwidth()`, and dropping it releases the claim. The session sends the summed ceilings as its PROBE target; `set_target(bps)` overrides that, `0` sends none, and `None` follows the viewers again. - **Authorization.** On `moq-lite-07-wip` (opt in with `versions=`) and on moq-transport draft-18+ with the [MoQ Auth extension](/draft/moq-auth), `async for grant in session.grants()` yields the `Grant` the relay sent back and each change, `None` until it answers and while a client session reconnects. `grants().grant()` reads it once; cancelling or leaving an `async with` releases the wait. - **Tokens.** Pass `tokens=[...]` instead of putting the credential in the URL. The first is the connection credential, sent in SETUP and, while an offered version can't carry it there (lite before 07), as the URL's `?jwt=`; each other token widens the grant over AUTH. `session.tokens().set([...])` replaces a client session's tokens before they expire: the next dial presents them, a live AUTH session at once, and after an authorization refusal the session redials only if they changed. `await tokens.answered()` returns once the relay accepts them and raises its refusal with the relay's code. A `?jwt=` already in the URL stays the connection credential, which is how to reach a relay older than this release. - **Errors.** Read diagnostic payloads from `reason` and structured protocol failures from `details`. diff --git a/doc/lib/swift/index.md b/doc/lib/swift/index.md index 074caacbdbc..cf4a1432f54 100644 --- a/doc/lib/swift/index.md +++ b/doc/lib/swift/index.md @@ -106,6 +106,7 @@ shows which module holds each. - **Closing.** `session.shutdown()` requests a drain immediately; `try await session.closed()` waits up to one second and reports its result. `session.cancel(code:)` closes at once. Finish or abort live tracks first. Application delivery requires explicitly selecting `moq-lite-07-wip` on both peers; older Lite versions (including default lite-06) and IETF wait only for transport ACKs. - **Ending cleanly.** When the input ends, finish every track, then call `try finish()` on its `Media.CatalogProducer` to finish the catalog, which ends the content. The broadcast stays announced and keeps serving the finished tracks, so a subscriber still catching up can drain them, until `broadcast.close()` takes it offline. How long to keep it up is yours to decide. A track still open at the close, or released without a finish, ends with `Unroutable`, which readers take as the publisher leaving. - **Stats.** `session.stats()` reports `rtt`, `estimatedSendRateBps`, and the byte and packet counters (`bytesSent`, `bytesReceived`, `bytesLost`, `packetsSent`, `packetsReceived`, `packetsLost`). A field is `nil` when the transport does not report it, which is not the same as zero. `version` names the negotiated protocol. Connect returns a connecting session; read its coherent `state()` snapshot and wait with that snapshot's revision to observe first-dial failures and reconnects. Each watcher keeps its own revision. Hold the owned `BandwidthConsumer` returned by `session.recvBandwidth()` to receive bandwidth estimates. `rate()` reads the current estimate in bits per second and `rateChanged()` waits for a new one. Release the consumer or call `cancel()` when finished; releasing the last consumer stops PROBE; the session and stats snapshots do not request it. Client consumers survive reconnects and report no estimate while disconnected. +- **Viewers.** `session.viewers()` divides the receive estimate among the broadcasts you watch. `watch(maxBps:)` returns a `Viewer` claiming up to a ceiling, the bitrate of the largest rendition you would switch to; its `rate()` reads that viewer's fair share in bits per second, `nil` while there is no estimate (keep the current rendition), and `update(maxBps:)` changes the ceiling. Holding a viewer requests the estimate like `recvBandwidth()`, and releasing it releases the claim. The session sends the summed ceilings as its PROBE target; `setTarget(targetBps:)` overrides that, `0` sends none, and `nil` follows the viewers again. - **Authorization.** On `moq-lite-07-wip` (opt in with `Client(versions:)`) and on moq-transport draft-18+ with the [MoQ Auth extension](/draft/moq-auth), `for try await grant in session.grants()` yields the `Grant` the relay sent back and each change, `nil` until it answers and while a client session reconnects. Cancelling the iterating task cancels the native wait. - **Tokens.** Pass `Client(tokens: [...])` instead of putting the credential in the URL. The first is the connection credential, sent in SETUP and, while an offered version can't carry it there (lite before 07), as the URL's `?jwt=`; each other token widens the grant over AUTH. `try session.tokens()?.set([...])` replaces them before they expire: the next dial presents them, a live AUTH session at once, and after an authorization refusal the session redials only if they changed. `try await tokens.answered()` returns once the relay accepts them and throws its refusal with the relay's code. A `?jwt=` already in the URL stays the connection credential, which is how to reach a relay older than this release. - **Errors.** Diagnostic cases use the `reason:` argument label; match their associated value to inspect it. Protocol errors carry `details`. diff --git a/go/wrapper/README.md b/go/wrapper/README.md index 2cd23e980d3..641c69f1cee 100644 --- a/go/wrapper/README.md +++ b/go/wrapper/README.md @@ -78,6 +78,14 @@ return its share and automatic probe ceiling immediately, even while the track stays subscribed. A later update can resume the same claim. While the track stays open, dropping the Go reference alone leaves release to garbage collection. +A player divides the receive estimate among the broadcasts it watches with +`Client.Session().Viewers()`. `Watch(maxBps)` claims up to what the largest +rendition it would switch to needs; the viewer's `Rate()` is its slice, nil +while there is no estimate, and `Update(maxBps)` changes the ceiling. The +session sends the viewers' summed ceilings as its PROBE target, which +`SetTarget` overrides. Holding a viewer requests PROBE, so `Close()` it once +the broadcast stops being watched. + Incoming server requests expose the query-free `Path()` before `Accept()`. It is consistent across transports and returns an empty string for the root or missing path. `Query()` returns the encoded query and may contain credentials. diff --git a/go/wrapper/bandwidth_test.go b/go/wrapper/bandwidth_test.go index 5783bed2e4c..d6d0c6c34e5 100644 --- a/go/wrapper/bandwidth_test.go +++ b/go/wrapper/bandwidth_test.go @@ -86,3 +86,46 @@ func TestReservationUpdateReleasesSubscribedTrack(t *testing.T) { } runtime.KeepAlive(retired) } + +// Viewers are wired through the session: watch, update, override the target, +// and release a viewer without disturbing the registry. The moq-ffi tests +// cover how the estimate divides. +func TestViewersWatchUpdateAndClose(t *testing.T) { + ctx, cancel := context.WithTimeout(context.Background(), testTimeout) + defer cancel() + relay := startRelay(t, ctx, "127.0.0.1:0") + defer relay.server.Close() + client, err := moq.Dial(ctx, "https://"+relay.addr, moq.ClientConfig{ + TLS: moq.ClientTLS{Insecure: true}, + Once: true, + }) + if err != nil { + t.Fatal(err) + } + defer client.Close() + waitConnects(t, ctx, client.Session(), 1) + + viewers := client.Session().Viewers() + first := viewers.Watch(4_000_000) + second := viewers.Watch(1_000_000) + // Whether QUIC has a receive estimate yet varies, but a slice never exceeds its ceiling. + if rate := second.Rate(); rate != nil && *rate > 1_000_000 { + t.Fatalf("rate = %d, above its 1000000 ceiling", *rate) + } + second.Update(500_000) + if rate := second.Rate(); rate != nil && *rate > 500_000 { + t.Fatalf("rate = %d, above its 500000 ceiling", *rate) + } + zero := uint64(0) + viewers.SetTarget(&zero) + viewers.SetTarget(nil) + + // Closing one viewer leaves the others and the registry usable. + second.Close() + first.Update(2_000_000) + if rate := first.Rate(); rate != nil && *rate > 2_000_000 { + t.Fatalf("rate = %d, above its 2000000 ceiling", *rate) + } + first.Close() + client.Session().Viewers().Watch(1).Close() +} diff --git a/go/wrapper/session.go b/go/wrapper/session.go index 119ab1317f3..4db6b361539 100644 --- a/go/wrapper/session.go +++ b/go/wrapper/session.go @@ -176,6 +176,63 @@ func (r *Reservation) Update(maxBps uint64) { r.inner.Update(maxBps) } +// Viewers returns the session's viewers, dividing the connection's receive +// estimate among the broadcasts watched over it. Every call returns a handle to +// the same registry, and the session sends what its viewers' ceilings add up to +// as its PROBE target. A client handle survives reconnects: a viewer reads nil +// while disconnected and resumes on the next connection. +func (s *Session) Viewers() *Viewers { + return &Viewers{inner: s.inner.Viewers()} +} + +// Viewers divides one connection's receive estimate among the broadcasts +// watched over it, max-min fair by each viewer's ceiling. +type Viewers struct { + inner *ffi.MoqViewers +} + +// Watch claims up to maxBps for a broadcast, returning its viewer. maxBps is a +// ceiling: what the largest rendition the player would switch to needs, not what +// it is receiving. Holding the viewer requests the receive estimate, like +// Session.RecvBandwidth; Close it once the broadcast stops being watched. +func (v *Viewers) Watch(maxBps uint64) *Viewer { + return &Viewer{inner: v.inner.Watch(maxBps)} +} + +// SetTarget sends targetBps as the PROBE target instead of the viewers' sum, or +// nil to follow them again. Zero sends no target. +func (v *Viewers) SetTarget(targetBps *uint64) { + v.inner.SetTarget(targetBps) +} + +// Viewer is one watched broadcast's standing claim on Viewers. +// +// Rate is a snapshot: nil means no receive estimate, so hold the current +// selection, and 0 is a real zero rate. +type Viewer struct { + inner *ffi.MoqViewer +} + +// Rate returns this viewer's slice of the receive estimate right now, in bits +// per second. +func (v *Viewer) Rate() *uint64 { + return v.inner.Rate() +} + +// Update changes the ceiling, keeping the same claim, as when a catalog enables +// or disables a rendition. +func (v *Viewer) Update(maxBps uint64) { + v.inner.Update(maxBps) +} + +// Close releases the claim, handing its share to the other viewers, lowering +// the PROBE target, and ending its receive-estimate demand without waiting for +// garbage collection. Call it from the goroutine that last used the viewer; +// the viewer is unusable afterwards. +func (v *Viewer) Close() { + v.inner.Destroy() +} + // Publish returns the origin used to advertise local broadcasts to the remote. func (s *Session) Publish() *OriginProducer { return &OriginProducer{inner: s.inner.Publish()} diff --git a/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Aliases.kt b/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Aliases.kt index 65a254f477a..643669a7ba9 100644 --- a/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Aliases.kt +++ b/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Aliases.kt @@ -165,6 +165,10 @@ typealias Allocator = uniffi.moq.MoqAllocator typealias BandwidthConsumer = uniffi.moq.MoqBandwidthConsumer /** One track's standing claim on an [Allocator]. */ typealias Reservation = uniffi.moq.MoqReservation +/** Divides one connection's receive estimate among the broadcasts watched over it. */ +typealias Viewers = uniffi.moq.MoqViewers +/** One watched broadcast's standing claim on [Viewers]; holding it requests PROBE, closing it releases the claim. */ +typealias Viewer = uniffi.moq.MoqViewer /** A snapshot of transport connection statistics. */ typealias ConnectionStats = uniffi.moq.MoqConnectionStats /** Follows the grant a session's peer gave it; cancel it to release a pending wait. */ diff --git a/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Moq.kt b/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Moq.kt index 66528ce225f..26303b32871 100644 --- a/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Moq.kt +++ b/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Moq.kt @@ -63,6 +63,17 @@ class Moq internal constructor( */ fun allocator(): Allocator = session.allocator() + /** + * The session's viewers, dividing the connection's receive estimate among the broadcasts + * watched over it. + * + * Every call returns a handle to the same registry, and the session sends what its viewers' + * ceilings add up to as its PROBE target. [Viewers.watch] a broadcast with the ceiling of + * the largest rendition the player would switch to, read its slice with [Viewer.rate], and + * [Viewer.close] it once the broadcast stops being watched. + */ + fun viewers(): Viewers = session.viewers() + /** * Follow the grant the peer gave this session. * diff --git a/kt/moq/src/jvmAndAndroidTest/kotlin/dev/moq/SmokeTest.kt b/kt/moq/src/jvmAndAndroidTest/kotlin/dev/moq/SmokeTest.kt index 122e13032a1..c03baca1bea 100644 --- a/kt/moq/src/jvmAndAndroidTest/kotlin/dev/moq/SmokeTest.kt +++ b/kt/moq/src/jvmAndAndroidTest/kotlin/dev/moq/SmokeTest.kt @@ -519,6 +519,24 @@ class SmokeTest { } } + @Test + fun `viewers watch, update, and release before the session connects`() = runTest { + Server.listen(ServerConfig(bind = "127.0.0.1:0", tls = ServerTls(generate = listOf("localhost")))).use { server -> + Moq.connect("https://${server.localAddr}", ClientConfig(tls = ClientTls(insecure = true))).use { moq -> + val viewers: Viewers = moq.viewers() + // The server never accepts, so there is no receive estimate to divide. + val viewer: Viewer = viewers.watch(4_000_000uL) + viewer.use { + assertNull(it.rate()) + it.update(1_000_000uL) + assertNull(it.rate()) + } + viewers.setTarget(0uL) + viewers.setTarget(null) + } + } + } + @Test fun `closing a server releases its port`() = runTest { val first = Server.listen(ServerConfig(bind = "127.0.0.1:0", tls = ServerTls(generate = listOf("localhost")))) diff --git a/py/moq-rs/README.md b/py/moq-rs/README.md index f2e5aa39b7c..7fdc4143f87 100644 --- a/py/moq-rs/README.md +++ b/py/moq-rs/README.md @@ -163,6 +163,7 @@ client = moq.Client( - `.stats() → ConnectionStats`. Snapshot RTT, bandwidth estimates, and byte/packet counters. - `.state()` and `await .state_changed(after)`. Read one lifecycle snapshot and wait with its revision; first-dial failures and reconnects share the same session. - `.allocator() → Allocator`. Divide the send estimate between encoders and app-owned tracks. + - `.viewers() → Viewers`. Divide the receive estimate between watched broadcasts: `.watch(max_bps) → Viewer` claims up to a ceiling, `Viewer.rate()` reads its slice (`None` while there is no estimate), and dropping the viewer releases it. The summed ceilings are the PROBE target; `.set_target(bps)` overrides it (`0` sends none, `None` follows the viewers again). - `.grants() → GrantConsumer`. On `moq-lite-07-wip` and on moq-transport draft-18+ with the MoQ Auth extension, `.grant()` reads the peer's `Grant` and `async for grant in session.grants()` follows it. - `.tokens() → Tokens | None`. A client session's credentials: `.set([...])` replaces them without reconnecting and `await .answered()` raises the relay's refusal. diff --git a/py/moq-rs/moq/__init__.py b/py/moq-rs/moq/__init__.py index 8f5a72b486e..b62b309f9af 100644 --- a/py/moq-rs/moq/__init__.py +++ b/py/moq-rs/moq/__init__.py @@ -41,7 +41,16 @@ TrackRequests, ) from .server import Request, Server, Transport -from .session import Allocator, BandwidthConsumer, GrantConsumer, Reservation, Session, Tokens +from .session import ( + Allocator, + BandwidthConsumer, + GrantConsumer, + Reservation, + Session, + Tokens, + Viewer, + Viewers, +) from .subscribe import ( BroadcastConsumer, GroupConsumer, @@ -147,6 +156,8 @@ "VideoEncoderOutput", "VideoDecodedFrame", "VideoPixelFormat", + "Viewer", + "Viewers", "WebSocketConfig", "connect", "is_auth", diff --git a/py/moq-rs/moq/session.py b/py/moq-rs/moq/session.py index 33619e8ff04..6757cda985b 100644 --- a/py/moq-rs/moq/session.py +++ b/py/moq-rs/moq/session.py @@ -11,6 +11,8 @@ MoqReservation, MoqSession, MoqTokens, + MoqViewer, + MoqViewers, ) from ._records import _strs @@ -131,6 +133,16 @@ def allocator(self) -> Allocator: """ return Allocator(self._inner.allocator()) + def viewers(self) -> Viewers: + """The session's viewers, dividing the receive estimate among watched broadcasts. + + Every call returns a handle to the same registry, and the session sends + what its viewers' ceilings add up to as its PROBE target. A client handle + survives reconnects: a viewer reads ``None`` while disconnected and + resumes on the next connection. + """ + return Viewers(self._inner.viewers()) + class GrantConsumer: """Follows the grant a session's peer gave it, returned by :meth:`Session.grants`. @@ -269,3 +281,49 @@ def rate(self) -> int | None: def update(self, max_bps: int) -> None: """Change the ceiling, keeping the same claim.""" self._inner.update(max_bps) + + +class Viewers: + """Divides one connection's receive estimate among the broadcasts watched over it. + + Minted by :meth:`Session.viewers`. Handles from one session share a registry. + """ + + def __init__(self, inner: MoqViewers) -> None: + self._inner = inner + + def watch(self, max_bps: int) -> Viewer: + """Watch a broadcast receiving at most ``max_bps``, returning its viewer. + + ``max_bps`` is a ceiling: what the largest rendition the player would + switch to needs, not what it is receiving. Drop the viewer once the + broadcast stops being watched. Holding one requests the receive + estimate, like :meth:`Session.recv_bandwidth`. + """ + return Viewer(self._inner.watch(max_bps)) + + def set_target(self, target_bps: int | None) -> None: + """Send ``target_bps`` as the PROBE target instead of the viewers' sum. + + ``None`` follows the viewers again, and ``0`` sends no target. + """ + self._inner.set_target(target_bps) + + +class Viewer: + """One watched broadcast's standing claim on :class:`Viewers`. + + :meth:`rate` is a snapshot: ``None`` means no receive estimate, so hold the + current selection, and ``0`` is a real zero rate. + """ + + def __init__(self, inner: MoqViewer) -> None: + self._inner = inner + + def rate(self) -> int | None: + """This viewer's slice of the receive estimate right now, in bits per second.""" + return self._inner.rate() + + def update(self, max_bps: int) -> None: + """Change the ceiling, keeping the same claim.""" + self._inner.update(max_bps) diff --git a/py/moq-rs/tests/test_server.py b/py/moq-rs/tests/test_server.py index c8f3f7f664c..902ded322ba 100644 --- a/py/moq-rs/tests/test_server.py +++ b/py/moq-rs/tests/test_server.py @@ -212,6 +212,31 @@ async def test_session_state_names_a_failing_first_dial(): session.cancel(0) +async def test_viewer_holds_without_an_estimate(): + """A viewer on a session that has not connected reads no estimate.""" + import socket + + with socket.socket(socket.AF_INET, socket.SOCK_DGRAM) as silent: + silent.bind(("127.0.0.1", 0)) + host, port = silent.getsockname() + client = moq.Client( + f"https://{host}:{port}", + tls=moq.ClientTls(insecure=True), + bind="127.0.0.1:0", + websocket=moq.WebSocketConfig(enabled=False), + ) + async with client: + session = client.session + assert session is not None + viewers = session.viewers() + viewer = viewers.watch(1_000_000) + viewer.update(2_000_000) + viewers.set_target(0) + viewers.set_target(None) + assert viewer.rate() is None + session.cancel(0) + + async def test_server_close_releases_port(): """Exiting the context manager releases the listening socket before it returns, so the same address binds again with no retry.""" diff --git a/swift/Sources/Moq/Bandwidth.swift b/swift/Sources/Moq/Bandwidth.swift index 917b4199046..1dd203be3a3 100644 --- a/swift/Sources/Moq/Bandwidth.swift +++ b/swift/Sources/Moq/Bandwidth.swift @@ -58,3 +58,51 @@ public final class Reservation: Sendable { ffi.update(maxBps: maxBps) } } + +/// Divides one connection's receive estimate among the broadcasts watched over it. +/// +/// Minted by `Session.viewers`. Handles from the same session share one registry. +public final class Viewers: Sendable { + let ffi: MoqViewers + + init(_ ffi: MoqViewers) { + self.ffi = ffi + } + + /// Watch a broadcast receiving at most `maxBps`, returning its viewer. + /// + /// `maxBps` is a ceiling: what the largest rendition the player would switch to + /// needs, not what it is receiving. Drop the viewer once the broadcast stops being + /// watched. Holding one requests the receive estimate, like `Session.recvBandwidth()`. + public func watch(maxBps: UInt64) -> Viewer { + Viewer(ffi.watch(maxBps: maxBps)) + } + + /// Send `targetBps` as the PROBE target instead of the viewers' sum, or `nil` to + /// follow them again. `0` sends no target. + public func setTarget(targetBps: UInt64?) { + ffi.setTarget(targetBps: targetBps) + } +} + +/// One watched broadcast's standing claim on `Viewers`. +/// +/// `rate()` is a snapshot: `nil` means no receive estimate, so hold the current +/// selection, and `0` is a real zero rate. +public final class Viewer: Sendable { + let ffi: MoqViewer + + init(_ ffi: MoqViewer) { + self.ffi = ffi + } + + /// This viewer's slice of the receive estimate right now, in bits per second. + public func rate() -> UInt64? { + ffi.rate() + } + + /// Change the ceiling, keeping the same claim. + public func update(maxBps: UInt64) { + ffi.update(maxBps: maxBps) + } +} diff --git a/swift/Sources/Moq/Client.swift b/swift/Sources/Moq/Client.swift index 1a5ec39a438..d62009403a6 100644 --- a/swift/Sources/Moq/Client.swift +++ b/swift/Sources/Moq/Client.swift @@ -174,4 +174,14 @@ public final class Session: Sendable { public func allocator() -> Allocator { Allocator(ffi.allocator()) } + + /// The session's viewers, dividing the receive estimate among watched broadcasts. + /// + /// Every call returns a handle to the same registry, and the session sends what + /// its viewers' ceilings add up to as its PROBE target. A client handle survives + /// reconnects: a viewer reads `nil` while disconnected and resumes on the next + /// connection. + public func viewers() -> Viewers { + Viewers(ffi.viewers()) + } } diff --git a/swift/Tests/MoqTests/SmokeTests.swift b/swift/Tests/MoqTests/SmokeTests.swift index d672f32f4d0..1d62ecaaf2c 100644 --- a/swift/Tests/MoqTests/SmokeTests.swift +++ b/swift/Tests/MoqTests/SmokeTests.swift @@ -92,6 +92,21 @@ final class SmokeTests: XCTestCase { } } + /// A viewer on a session that has not connected reads no estimate. + func testViewerHoldsWithoutAnEstimate() async throws { + let client = try Client(bind: "127.0.0.1:0", tls: ClientTls(insecure: true), once: true) + defer { client.cancel() } + let session = try await client.connect(to: "https://127.0.0.1:1") + defer { session.cancel(code: 0) } + + let viewers = session.viewers() + let viewer = viewers.watch(maxBps: 1_000_000) + viewer.update(maxBps: 2_000_000) + viewers.setTarget(targetBps: 0) + viewers.setTarget(targetBps: nil) + XCTAssertNil(viewer.rate()) + } + /// A value the native side cannot use throws from the constructor, not the dial. func testInvalidConfigThrowsConfig() { XCTAssertThrowsError(try Client(versions: ["moq-lite-99"])) { error in From cfb197dc5e79a42b412c0a9eb1d5bb844529afdc Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Fri, 30 Oct 2026 21:25:22 -0700 Subject: [PATCH 08/20] chore(quest): players name the FFI viewer handles Co-Authored-By: Claude Opus 5.5 --- quest/m2/probe/players.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/quest/m2/probe/players.md b/quest/m2/probe/players.md index f73be05729d..ade697532c7 100644 --- a/quest/m2/probe/players.md +++ b/quest/m2/probe/players.md @@ -17,7 +17,9 @@ already reads the catalog, which keeps moq-net catalog-agnostic, and only an enabled rendition is one it could switch to. Targets are on by default. - The handle is a `Bandwidth.Viewer` from `connection.viewers` in `@moq/net` - (`Session::viewers` or `moq_tokio::Connection::viewers` in Rust), landed in + (`Session::viewers` or `moq_tokio::Connection::viewers` in Rust, and + `MoqSession::viewers` through moq-ffi and every binding, decided with the + maintainer on 2026-10-31), landed in [moq-dev/moq#7090](https://github.com/moq-dev/moq/pull/7090); this quest only decides its `max`. - Settle what a rendition without a catalog bitrate contributes. - A probe that reaches the target must make the rendition selectable. From 37814ed72a01a45931df04794ce16bfcb4c011d6 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sat, 31 Oct 2026 00:17:35 -0700 Subject: [PATCH 09/20] fix(moq-c): box the session task's inner future Unoptimized builds copy the select future into every wrapper's frame (Background::watch twice, isolate, run, the task), which with this branch's larger connection loop overflowed the 2 MiB runtime thread in a_failing_dial_reports_its_failure. Boxing it drops the dial's stack need from over 2 MiB to under 768 KiB. Co-Authored-By: Claude Opus 5.5 --- rs/moq-c/src/session.rs | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) diff --git a/rs/moq-c/src/session.rs b/rs/moq-c/src/session.rs index d0b1f8fbab2..1b7d744e7d5 100644 --- a/rs/moq-c/src/session.rs +++ b/rs/moq-c/src/session.rs @@ -157,14 +157,16 @@ impl Session { let _publish = publish; let _consume = consume; - // A panic ends only this session, reported through the terminal callback. - let res = ffi::run(publish_driver.watch(consume_driver.watch(async move { + // A panic ends only this session, reported through the terminal callback. Boxed so + // each wrapper holds a pointer: unoptimized builds otherwise copy the future into + // every layer's frame, overflowing the runtime thread's stack. + let res = ffi::run(publish_driver.watch(consume_driver.watch(Box::pin(async move { tokio::select! { // close() requested: drain what the session queued, then close it. _ = closed => reconnect.clone().close().await.map_err(map_connect_error), res = Self::report(callback, &reconnect, &monitor) => res, } - }))) + })))) .await; // The terminal callback waits for the close to reach the peer, so a caller that exits // on it doesn't leave the peer to time the connection out. @@ -221,13 +223,14 @@ impl Session { let _publish = publish; let _consume = consume; - // A panic ends only this session, reported through the terminal callback. - let mut res = ffi::run(publish_driver.watch(consume_driver.watch(async move { + // A panic ends only this session, reported through the terminal callback. Boxed + // like the dialed session's. + let mut res = ffi::run(publish_driver.watch(consume_driver.watch(Box::pin(async move { tokio::select! { _ = closed => Ok(()), res = Self::serve(id, callback, request) => res, } - }))) + })))) .await; let entry = State::lock().session.task.remove(id); From ad189e49ffb44f8c54c250e1f23e4c953250f743 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sat, 31 Oct 2026 02:05:37 -0700 Subject: [PATCH 10/20] fix(net): keep a newer PROBE stream's target, coalesce blocked targets A publisher clears the peer's target when a PROBE stream ends only if that stream set it last, so a superseded stream's late reset no longer erases its successor's target. Subscribers in both languages hold one target in flight while the writer is blocked and send the latest once it drains. Co-Authored-By: Claude Opus 5.5 --- js/net/src/lite/subscriber.ts | 25 ++++++++---- rs/moq-net/src/lite/publisher.rs | 65 +++++++++++++++++++++++++++---- rs/moq-net/src/lite/subscriber.rs | 19 +++++---- 3 files changed, 86 insertions(+), 23 deletions(-) diff --git a/js/net/src/lite/subscriber.ts b/js/net/src/lite/subscriber.ts index b9dcb88eed3..a2be47c9842 100644 --- a/js/net/src/lite/subscriber.ts +++ b/js/net/src/lite/subscriber.ts @@ -1889,23 +1889,32 @@ export class Subscriber { } // Send `target` on the PROBE stream whenever it changes, in order, while `scope` lives. - // Nothing is sent while it is zero, until it retracts a target already sent. + // Nothing is sent while it is zero, until it retracts a target already sent. One write is + // in flight at a time, and the next sends the latest target, so a peer that stops reading + // holds one target however often it changes. #sendTarget(stream: Stream, target: Getter, scope: Effect): void { let sent = 0; - let writing: Promise = Promise.resolve(); - scope.run((effect) => { - effect.get(target); - writing = writing - .then(async () => { + let writing = false; + const write = async () => { + writing = true; + try { + for (;;) { // The wire carries whole bits per second. const next = Math.floor(target.peek()); if (next === sent) return; sent = next; // Zero reads as unknown on the wire, which retracts the last target. await new Probe({ bitrate: next > 0 ? next : undefined }).encode(stream.writer, this.version); - }) + } + } catch { // A failed write surfaces through the stream's reader, which ends the probe. - .catch(() => {}); + } finally { + writing = false; + } + }; + scope.run((effect) => { + effect.get(target); + if (!writing) void write(); }); } diff --git a/rs/moq-net/src/lite/publisher.rs b/rs/moq-net/src/lite/publisher.rs index 39651c13021..2d48127a6f5 100644 --- a/rs/moq-net/src/lite/publisher.rs +++ b/rs/moq-net/src/lite/publisher.rs @@ -1,7 +1,5 @@ use crate::driver::Transport; use crate::transport::poll::Session as _; -#[cfg(test)] -use std::sync::atomic::AtomicU64; use crate::{SessionError, announce, frame, group, origin, track}; use rangemap::{RangeMap, RangeSet}; @@ -10,7 +8,7 @@ use std::{ ops::{Bound, ControlFlow, Range}, sync::{ Arc, Mutex, - atomic::{AtomicUsize, Ordering}, + atomic::{AtomicU64, AtomicUsize, Ordering}, }, task::{Poll, ready}, time::Duration, @@ -92,6 +90,11 @@ struct Shared { estimate: kio::ProducerWeak, /// The peer's latest PROBE target, which the session's sender probes up to. peer_target: kio::Producer, + /// The PROBE stream that set `peer_target` last, so a superseded stream ending + /// after its replacement already sent a target cannot clear it. + peer_target_owner: Mutex, + /// Numbers each PROBE stream for `peer_target_owner`, from 1. + probe_streams: AtomicU64, } /// Largest millisecond duration every implementation can carry losslessly. @@ -130,8 +133,23 @@ fn cursor_floor(version: Version, start_group: Option, latest: Option) } impl Shared { - /// Record the peer's PROBE target, which only a session with a sender acts on. - fn set_peer_target(&self, target: crate::bandwidth::Rate) { + /// Record the peer's PROBE target from stream `owner`, which only a session with a + /// sender acts on. The latest stream to send one wins. + fn set_peer_target(&self, owner: u64, target: crate::bandwidth::Rate) { + let mut current = self.peer_target_owner.lock().unwrap(); + *current = owner; + self.write_peer_target(target); + } + + /// Lapse the peer's PROBE target with stream `owner`, unless a later stream set it. + fn clear_peer_target(&self, owner: u64) { + let current = self.peer_target_owner.lock().unwrap(); + if *current == owner { + self.write_peer_target(crate::bandwidth::Rate::ZERO); + } + } + + fn write_peer_target(&self, target: crate::bandwidth::Rate) { // An error means nothing follows the target, which is then moot. if let Ok(mut current) = self.peer_target.write() && *current != target @@ -225,6 +243,8 @@ impl Publisher { runtime: config.runtime.clone(), estimate: config.estimate, peer_target: kio::Producer::new(crate::bandwidth::Rate::ZERO), + peer_target_owner: Mutex::new(0), + probe_streams: AtomicU64::new(0), }), runtime: config.runtime, accept, @@ -673,6 +693,8 @@ struct ProbeServe { due: crate::time::Deadline, /// A peer streaming targets still lets the session's other tasks run. budget: kio::coop::Budget, + /// This stream's number, owning the peer's target while it sent the latest one. + id: u64, } impl ProbeServe { @@ -724,6 +746,7 @@ impl ProbeServe { fn new(shared: Arc, runtime: crate::time::Deadlines, stream: Stream) -> Self { Self { + id: shared.probe_streams.fetch_add(1, Ordering::Relaxed) + 1, estimate: shared.estimate.consume(), seen: None, shared, @@ -737,8 +760,9 @@ impl ProbeServe { fn poll(&mut self, waiter: &kio::Waiter) -> Poll> { let res = ready!(self.poll_probe(waiter)); - // The stream carried the target, so it lapses with it. - self.shared.set_peer_target(crate::bandwidth::Rate::ZERO); + // The stream carried the target, so it lapses with it, unless a newer stream's + // target arrived before this one's end. + self.shared.clear_peer_target(self.id); match res { Ok(()) => tracing::debug!("probe stream closed"), Err(err) => { @@ -766,7 +790,7 @@ impl ProbeServe { Poll::Ready(Ok(Some(probe))) => { let target = probe.bitrate.map(crate::bandwidth::Rate::from_bps); self.shared - .set_peer_target(target.unwrap_or(crate::bandwidth::Rate::ZERO)); + .set_peer_target(self.id, target.unwrap_or(crate::bandwidth::Rate::ZERO)); ready!(self.budget.poll_yield(waiter)) } Poll::Ready(Ok(None)) => return Poll::Ready(Ok(())), @@ -7637,6 +7661,31 @@ mod tests { ProbeServe::new(publisher.shared.clone(), publisher.runtime.clone(), stream) } + /// A subscriber that drops its PROBE stream and opens another can see the new + /// stream's target land before the old stream's end: that end must not clear it. + #[moq_clock::test] + async fn a_superseded_probe_stream_keeps_its_successors_target() { + use crate::bandwidth::Rate; + let version = Version::Lite06; + let session = ScriptedSession::new(Vec::new()); + let mut transport = crate::driver::Transport::new(session.clone()); + let stream = Stream::open(&mut transport, version).await.unwrap(); + let estimate = kio::Producer::default(); + let old = probe_server(crate::driver::Transport::new(session), stream, version, &estimate); + let stream = Stream::open(&mut transport, version).await.unwrap(); + let new = ProbeServe::new(old.shared.clone(), crate::time::sim(), stream); + let shared = old.shared.clone(); + let target = shared.peer_target.consume(); + + shared.set_peer_target(old.id, Rate::from_bps(1_000_000)); + shared.set_peer_target(new.id, Rate::from_bps(2_000_000)); + shared.clear_peer_target(old.id); + assert_eq!(*target.read(), Rate::from_bps(2_000_000)); + + shared.clear_peer_target(new.id); + assert_eq!(*target.read(), Rate::ZERO); + } + #[moq_clock::test] async fn malformed_complete_goaway_closes_the_session() { use kio::Task; diff --git a/rs/moq-net/src/lite/subscriber.rs b/rs/moq-net/src/lite/subscriber.rs index ba24375b8bf..f9105e09b38 100644 --- a/rs/moq-net/src/lite/subscriber.rs +++ b/rs/moq-net/src/lite/subscriber.rs @@ -1484,15 +1484,20 @@ impl ProbeStream { stream.writer.buffer(&lite::ControlType::Probe)?; wait!(Send => stream.writer.poll_flush(waiter))?; Poll::Ready(wait!(Read => { - if target != self.sent { - // Zero reads as unknown on the wire, which retracts the last target. - let bitrate = (target > bandwidth::Rate::ZERO).then_some(target.as_bps()); - stream.writer.buffer(&lite::Probe { bitrate, rtt: None })?; - self.sent = target; - } - // Deliver the target without holding up the estimates behind it. + // Deliver the target without holding up the estimates behind it. Only a flushed + // writer takes the next one, so a peer that stops reading holds one target, and + // the latest is sent once it drains. if let Poll::Ready(res) = stream.writer.poll_flush(waiter) { res?; + if target != self.sent { + // Zero reads as unknown on the wire, which retracts the last target. + let bitrate = (target > bandwidth::Rate::ZERO).then_some(target.as_bps()); + stream.writer.buffer(&lite::Probe { bitrate, rtt: None })?; + self.sent = target; + if let Poll::Ready(res) = stream.writer.poll_flush(waiter) { + res?; + } + } } let bandwidth = self.subscriber.recv_bandwidth.as_ref().expect("gated by RecvBandwidth"); // Each estimate wakes every reader, so a peer streaming them must not hold From 165fa95bc199c0f5106fe28627ca7e9b0e1be6f3 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sat, 31 Oct 2026 02:08:05 -0700 Subject: [PATCH 11/20] fix(net): ignore a superseded PROBE stream's late targets Only a stream at least as new as the target's owner may set it, so an old stream's buffered targets can't reclaim ownership and then clear it. Co-Authored-By: Claude Opus 5.5 --- rs/moq-net/src/lite/publisher.rs | 16 +++++++++++----- 1 file changed, 11 insertions(+), 5 deletions(-) diff --git a/rs/moq-net/src/lite/publisher.rs b/rs/moq-net/src/lite/publisher.rs index 2d48127a6f5..8ab7550e1e4 100644 --- a/rs/moq-net/src/lite/publisher.rs +++ b/rs/moq-net/src/lite/publisher.rs @@ -90,10 +90,10 @@ struct Shared { estimate: kio::ProducerWeak, /// The peer's latest PROBE target, which the session's sender probes up to. peer_target: kio::Producer, - /// The PROBE stream that set `peer_target` last, so a superseded stream ending - /// after its replacement already sent a target cannot clear it. + /// The newest PROBE stream to set `peer_target`, so a superseded stream whose + /// buffered targets or end arrive after its replacement's target can't touch it. peer_target_owner: Mutex, - /// Numbers each PROBE stream for `peer_target_owner`, from 1. + /// Numbers each PROBE stream for `peer_target_owner` in accept order, from 1. probe_streams: AtomicU64, } @@ -134,9 +134,12 @@ fn cursor_floor(version: Version, start_group: Option, latest: Option) impl Shared { /// Record the peer's PROBE target from stream `owner`, which only a session with a - /// sender acts on. The latest stream to send one wins. + /// sender acts on. The newest stream to send one wins; an older one is ignored. fn set_peer_target(&self, owner: u64, target: crate::bandwidth::Rate) { let mut current = self.peer_target_owner.lock().unwrap(); + if owner < *current { + return; + } *current = owner; self.write_peer_target(target); } @@ -7662,7 +7665,8 @@ mod tests { } /// A subscriber that drops its PROBE stream and opens another can see the new - /// stream's target land before the old stream's end: that end must not clear it. + /// stream's target land before the old stream's buffered targets and end: neither + /// may replace or clear it. #[moq_clock::test] async fn a_superseded_probe_stream_keeps_its_successors_target() { use crate::bandwidth::Rate; @@ -7679,6 +7683,8 @@ mod tests { shared.set_peer_target(old.id, Rate::from_bps(1_000_000)); shared.set_peer_target(new.id, Rate::from_bps(2_000_000)); + shared.set_peer_target(old.id, Rate::from_bps(3_000_000)); + assert_eq!(*target.read(), Rate::from_bps(2_000_000)); shared.clear_peer_target(old.id); assert_eq!(*target.read(), Rate::from_bps(2_000_000)); From 116a553643d848fa2a7d092b808ca4f7f65a4bdd Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sat, 31 Oct 2026 02:10:53 -0700 Subject: [PATCH 12/20] fix(net): follow the newest target among open PROBE streams Ordering streams by when their type decoded can misorder a replacement and the stream it replaced. Track each open stream's latest target instead: the peer's target is the newest write among open streams, and a stream's end falls back to the others', so a superseded stream's late targets and end settle on its replacement's target in any delivery order. Co-Authored-By: Claude Opus 5.5 --- rs/moq-net/src/lite/publisher.rs | 68 +++++++++++++++++++++----------- 1 file changed, 44 insertions(+), 24 deletions(-) diff --git a/rs/moq-net/src/lite/publisher.rs b/rs/moq-net/src/lite/publisher.rs index 8ab7550e1e4..92b57dd6285 100644 --- a/rs/moq-net/src/lite/publisher.rs +++ b/rs/moq-net/src/lite/publisher.rs @@ -90,13 +90,23 @@ struct Shared { estimate: kio::ProducerWeak, /// The peer's latest PROBE target, which the session's sender probes up to. peer_target: kio::Producer, - /// The newest PROBE stream to set `peer_target`, so a superseded stream whose - /// buffered targets or end arrive after its replacement's target can't touch it. - peer_target_owner: Mutex, - /// Numbers each PROBE stream for `peer_target_owner` in accept order, from 1. + /// Each open PROBE stream's latest target, which `peer_target` follows. + peer_targets: Mutex, + /// Numbers each PROBE stream for `peer_targets`. probe_streams: AtomicU64, } +/// The latest target each open PROBE stream sent, so the peer's target is the newest +/// one written by a stream still open. A superseded stream's late targets and end then +/// settle on its replacement's target whatever order they arrive in, with no need to +/// know which stream the peer opened first. +#[derive(Default)] +struct PeerTargets { + /// By stream: when its target was written, counted by `writes`, and the target. + streams: HashMap, + writes: u64, +} + /// Largest millisecond duration every implementation can carry losslessly. pub(super) const MAX_SAFE_DELAY_MS: u64 = (1_u64 << 53) - 1; @@ -133,23 +143,29 @@ fn cursor_floor(version: Version, start_group: Option, latest: Option) } impl Shared { - /// Record the peer's PROBE target from stream `owner`, which only a session with a - /// sender acts on. The newest stream to send one wins; an older one is ignored. - fn set_peer_target(&self, owner: u64, target: crate::bandwidth::Rate) { - let mut current = self.peer_target_owner.lock().unwrap(); - if owner < *current { - return; - } - *current = owner; + /// Record the PROBE target stream `stream` sent, which only a session with a sender + /// acts on. The latest write wins while several streams are open. + fn set_peer_target(&self, stream: u64, target: crate::bandwidth::Rate) { + let mut targets = self.peer_targets.lock().unwrap(); + targets.writes += 1; + let order = targets.writes; + targets.streams.insert(stream, (order, target)); self.write_peer_target(target); } - /// Lapse the peer's PROBE target with stream `owner`, unless a later stream set it. - fn clear_peer_target(&self, owner: u64) { - let current = self.peer_target_owner.lock().unwrap(); - if *current == owner { - self.write_peer_target(crate::bandwidth::Rate::ZERO); + /// Lapse the target stream `stream` sent as it ends, falling back to the newest one + /// another open stream sent, or zero. + fn clear_peer_target(&self, stream: u64) { + let mut targets = self.peer_targets.lock().unwrap(); + if targets.streams.remove(&stream).is_none() { + return; } + let newest = targets + .streams + .values() + .max_by_key(|(order, _)| *order) + .map_or(crate::bandwidth::Rate::ZERO, |(_, target)| *target); + self.write_peer_target(newest); } fn write_peer_target(&self, target: crate::bandwidth::Rate) { @@ -246,7 +262,7 @@ impl Publisher { runtime: config.runtime.clone(), estimate: config.estimate, peer_target: kio::Producer::new(crate::bandwidth::Rate::ZERO), - peer_target_owner: Mutex::new(0), + peer_targets: Default::default(), probe_streams: AtomicU64::new(0), }), runtime: config.runtime, @@ -696,7 +712,7 @@ struct ProbeServe { due: crate::time::Deadline, /// A peer streaming targets still lets the session's other tasks run. budget: kio::coop::Budget, - /// This stream's number, owning the peer's target while it sent the latest one. + /// This stream's key in the session's `peer_targets`. id: u64, } @@ -763,8 +779,8 @@ impl ProbeServe { fn poll(&mut self, waiter: &kio::Waiter) -> Poll> { let res = ready!(self.poll_probe(waiter)); - // The stream carried the target, so it lapses with it, unless a newer stream's - // target arrived before this one's end. + // The stream carried the target, so it lapses with it, back to another open + // stream's target if a replacement already sent one. self.shared.clear_peer_target(self.id); match res { Ok(()) => tracing::debug!("probe stream closed"), @@ -7665,8 +7681,8 @@ mod tests { } /// A subscriber that drops its PROBE stream and opens another can see the new - /// stream's target land before the old stream's buffered targets and end: neither - /// may replace or clear it. + /// stream's target land before the old stream's buffered targets and end, in any + /// order: once the old stream ends, the new stream's target stands. #[moq_clock::test] async fn a_superseded_probe_stream_keeps_its_successors_target() { use crate::bandwidth::Rate; @@ -7683,10 +7699,14 @@ mod tests { shared.set_peer_target(old.id, Rate::from_bps(1_000_000)); shared.set_peer_target(new.id, Rate::from_bps(2_000_000)); + // The old stream's buffered target lands late, winning while it is open. shared.set_peer_target(old.id, Rate::from_bps(3_000_000)); - assert_eq!(*target.read(), Rate::from_bps(2_000_000)); + assert_eq!(*target.read(), Rate::from_bps(3_000_000)); shared.clear_peer_target(old.id); assert_eq!(*target.read(), Rate::from_bps(2_000_000)); + // A stream that never sent a target ends without touching the others'. + shared.clear_peer_target(old.id + new.id + 1); + assert_eq!(*target.read(), Rate::from_bps(2_000_000)); shared.clear_peer_target(new.id); assert_eq!(*target.read(), Rate::ZERO); From a25f126b15c29b6e2ee69cd3326ce2e384c491b5 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sat, 31 Oct 2026 03:10:56 -0700 Subject: [PATCH 13/20] style(net): format the viewer demand test Co-Authored-By: Claude Opus 5.5 --- rs/moq-net/src/model/bandwidth.rs | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/rs/moq-net/src/model/bandwidth.rs b/rs/moq-net/src/model/bandwidth.rs index a7c56634c25..1e4ff607dfb 100644 --- a/rs/moq-net/src/model/bandwidth.rs +++ b/rs/moq-net/src/model/bandwidth.rs @@ -1606,7 +1606,10 @@ mod tests { assert!(estimate.demand().wanted()); let grant = viewer.consume(); drop(viewer); - assert!(estimate.demand().wanted(), "a grant read from the viewer still wants it"); + assert!( + estimate.demand().wanted(), + "a grant read from the viewer still wants it" + ); drop(grant); assert!(!estimate.demand().wanted()); } From 25daac03fff81c2d676ce416036a70bc48c9a364 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sat, 31 Oct 2026 08:33:03 -0700 Subject: [PATCH 14/20] fix(net): address PR review on viewers and PROBE targets - A closed registry's claim registers nothing, so its target stays zero. - ReloadProps excludes viewers: a reload owns the registry its sessions feed. - A failed PROBE target write ends the probe instead of leaving reads blocked. Co-Authored-By: Claude Opus 5.5 --- js/net/src/bandwidth.test.ts | 10 ++++++++++ js/net/src/bandwidth.ts | 9 ++++++--- js/net/src/connection/reload.test.ts | 9 +++++++++ js/net/src/connection/reload.ts | 5 ++++- js/net/src/lite/subscriber.test.ts | 24 ++++++++++++++++++++++-- js/net/src/lite/subscriber.ts | 4 +++- 6 files changed, 54 insertions(+), 7 deletions(-) diff --git a/js/net/src/bandwidth.test.ts b/js/net/src/bandwidth.test.ts index 9ace1ed10b1..6109a30fd04 100644 --- a/js/net/src/bandwidth.test.ts +++ b/js/net/src/bandwidth.test.ts @@ -369,6 +369,16 @@ test("the viewers' target sums their ceilings until overridden", () => { viewers.close(); }); +test("a closed viewers registry claims nothing", () => { + const viewers = new Viewers(new Signal(1_000_000)); + viewers.close(); + + const viewer = viewers.watch(2_000_000); + expect(viewers.target.peek()).toBe(0); + expect(viewer.peek()).toBeUndefined(); + viewer.close(); +}); + // Observing a connection's receive estimate is what requests PROBE, so a registry with // nobody watching must not hold that demand. test("an idle viewers registry does not observe the estimate", async () => { diff --git a/js/net/src/bandwidth.ts b/js/net/src/bandwidth.ts index 2dedb218655..b9cc428baa0 100644 --- a/js/net/src/bandwidth.ts +++ b/js/net/src/bandwidth.ts @@ -175,9 +175,12 @@ class Divider { const id = this.#nextId++; const rate = new Signal(undefined); - this.entries.mutate((entries) => { - entries.push({ id, demand, priority, max, rate }); - }); + // A closed registry hands back an inert reservation, so its target stays zero. + if (this.#alive.peek()) { + this.entries.mutate((entries) => { + entries.push({ id, demand, priority, max, rate }); + }); + } const reservation = makeReservation(this.#registry, id, rate); this.#publish(); diff --git a/js/net/src/connection/reload.test.ts b/js/net/src/connection/reload.test.ts index 071d8d427a5..750f36b5c99 100644 --- a/js/net/src/connection/reload.test.ts +++ b/js/net/src/connection/reload.test.ts @@ -2,6 +2,7 @@ import { expect, spyOn, test } from "bun:test"; import { Instant, Manual, Milli, Nano, yieldNow } from "@moq/clock"; import { Effect, Signal } from "@moq/signals"; import * as Announce from "../announced.ts"; +import { Viewers } from "../bandwidth.ts"; import type { Producer as BroadcastProducer } from "../broadcast.ts"; import { ConnectTimeout, SessionCode, SessionError, StreamCode, toTransport } from "../error.ts"; import { Route } from "../hop.ts"; @@ -87,6 +88,14 @@ test("ReloadProps excludes transport", () => { expect(props.enabled).toBeUndefined(); }); +test("ReloadProps excludes viewers", () => { + const withViewers = { viewers: new Viewers() }; + // @ts-expect-error a reload owns its viewers registry + const props: ReloadProps = withViewers; + expect(props.enabled).toBeUndefined(); + withViewers.viewers.close(); +}); + test("closing mid-connect aborts the pending attempt", async () => { const original = globalThis.WebTransport; let closes = 0; diff --git a/js/net/src/connection/reload.ts b/js/net/src/connection/reload.ts index fecd3b33a3c..681b34cfc34 100644 --- a/js/net/src/connection/reload.ts +++ b/js/net/src/connection/reload.ts @@ -83,7 +83,7 @@ export type ReloadDelay = { */ export type ReloadProps = Omit< ConnectProps, - "url" | "signal" | "transport" | "implementation" | "extensions" | "tokens" + "url" | "signal" | "transport" | "implementation" | "extensions" | "tokens" | "viewers" > & { /** See {@link ConnectProps.tokens}; pass a `Signal` to replace them before they expire. */ tokens?: readonly string[] | Signal; @@ -94,6 +94,9 @@ export type ReloadProps = Omit< /** A one-shot transport cannot be reused by the reconnect loop. */ transport?: never; + /** A reload owns its {@link Reload.viewers}, fed by its own sessions' estimates. */ + viewers?: never; + /** Whether to reload the connection when it disconnects (default: true). */ enabled?: boolean | Signal; diff --git a/js/net/src/lite/subscriber.test.ts b/js/net/src/lite/subscriber.test.ts index 00dc2ddaae7..019c316b881 100644 --- a/js/net/src/lite/subscriber.test.ts +++ b/js/net/src/lite/subscriber.test.ts @@ -2722,7 +2722,7 @@ test.each(["answer", "credit"] as const)("FETCH shares the TRACK deadline while * A PROBE stream to a peer whose SETUP advertised `level`: `sent` reads back what the * subscriber wrote, and `finish` plays the peer's FIN. */ -function probeTargetHarness(level: ProbeLevel) { +function probeTargetHarness(level: ProbeLevel, options?: { failTarget?: boolean }) { const version = Version.DRAFT_06; let written!: ReadableStreamDefaultController; const sent = new Reader( @@ -2731,11 +2731,16 @@ function probeTargetHarness(level: ProbeLevel) { version, ); let inbound!: ReadableStreamDefaultController; + let writes = 0; const quic = { createBidirectionalStream: async () => ({ readable: new ReadableStream({ start: (controller) => (inbound = controller) }), writable: new WritableStream({ - write: (chunk) => written.enqueue(new Uint8Array(chunk)), + write: (chunk) => { + // Only the stream type precedes the first target. + if (options?.failTarget && writes++ > 0) throw new Error("write failed"); + written.enqueue(new Uint8Array(chunk)); + }, close: () => written.close(), }), }), @@ -2781,6 +2786,21 @@ test("the PROBE stream sends the viewers' target to an Increase peer", async () viewers.close(); }); +// The writer and reader are independent: a failed target write ends the probe even while +// the peer keeps its side open. +test("a failed PROBE target write ends the probe", async () => { + const { subscriber, sent } = probeTargetHarness(ProbeLevel.Increase, { failTarget: 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 running; + 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/js/net/src/lite/subscriber.ts b/js/net/src/lite/subscriber.ts index 230662ba3ae..047ff392512 100644 --- a/js/net/src/lite/subscriber.ts +++ b/js/net/src/lite/subscriber.ts @@ -1912,7 +1912,9 @@ export class Subscriber { await new Probe({ bitrate: next > 0 ? next : undefined }).encode(stream.writer, this.version); } } catch { - // A failed write surfaces through the stream's reader, which ends the probe. + // The writer and reader are independent, so a failed write does not end the + // reads: end the probe here, which also closes the stream. + scope.close(); } finally { writing = false; } From 217e617c73e74198616176fc5ff470f01c2332e0 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sun, 1 Nov 2026 15:49:02 -0800 Subject: [PATCH 15/20] fix(net): reset a stalled PROBE target write when the probe ends Closing the probe stream queued its FIN behind a target write the peer was not draining, so the stream outlived the probe. The probe now resets the stream while a target write is in flight. Also clarifies that the receive consumer reads the estimate and a viewer reads its share, and applies ktfmt (main's new Kotlin format gate) to the viewers wrapper and smoke test. Co-Authored-By: Claude Opus 5.5 --- doc/concept/standard.md | 4 +- js/net/src/lite/subscriber.test.ts | 43 +++++++++++++++++-- js/net/src/lite/subscriber.ts | 5 +++ .../jvmAndAndroidMain/kotlin/dev/moq/Moq.kt | 4 +- .../kotlin/dev/moq/SmokeTest.kt | 33 ++++++++------ 5 files changed, 69 insertions(+), 20 deletions(-) diff --git a/doc/concept/standard.md b/doc/concept/standard.md index 1bbff72cc9a..1dd7d50f5bd 100644 --- a/doc/concept/standard.md +++ b/doc/concept/standard.md @@ -49,8 +49,8 @@ ignores unknown parameters: [cluster](/draft/moq-cluster) routing hop lists, before a `SUBSCRIBE_NAMESPACE` is synced, and [probe](/draft/moq-probe) for bandwidth estimation. Rust sessions request PROBE only while an owned `recv_bandwidth()` consumer or a `viewers()` viewer is held. -Read estimates through its `peek()` or `changed()` methods; session statistics do -not request PROBE. The viewers' ceilings, summed, are the PROBE target, sent only +The consumer reads the estimate, and a viewer reads its share of it; session +statistics do not request PROBE. The viewers' ceilings, summed, are the PROBE target, sent only to a peer advertising `Increase`, which a native session over moq-quic with BBR3 does and a browser session does not yet. Both libraries offer solicit and auth unless a side's diff --git a/js/net/src/lite/subscriber.test.ts b/js/net/src/lite/subscriber.test.ts index e614794c65e..0a029eafe94 100644 --- a/js/net/src/lite/subscriber.test.ts +++ b/js/net/src/lite/subscriber.test.ts @@ -2956,7 +2956,7 @@ test.each(["answer", "credit"] as const)("FETCH shares the TRACK deadline while * A PROBE stream to a peer whose SETUP advertised `level`: `sent` reads back what the * subscriber wrote, and `finish` plays the peer's FIN. */ -function probeTargetHarness(level: ProbeLevel, options?: { failTarget?: boolean }) { +function probeTargetHarness(level: ProbeLevel, options?: { failTarget?: boolean; stallTarget?: boolean }) { const version = Version.DRAFT_06; let written!: ReadableStreamDefaultController; const sent = new Reader( @@ -2966,13 +2966,29 @@ function probeTargetHarness(level: ProbeLevel, options?: { failTarget?: boolean ); let inbound!: ReadableStreamDefaultController; let writes = 0; + let stall!: () => void; + const stalled = new Promise((resolve) => (stall = resolve)); + let reset!: (reason: unknown) => void; + const aborted = new Promise((resolve) => (reset = resolve)); const quic = { createBidirectionalStream: async () => ({ readable: new ReadableStream({ start: (controller) => (inbound = controller) }), writable: new WritableStream({ - write: (chunk) => { + write: async (chunk, controller) => { // Only the stream type precedes the first target. - if (options?.failTarget && writes++ > 0) throw new Error("write failed"); + 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) { + stall(); + await new Promise((_, reject) => { + controller.signal.addEventListener("abort", () => { + reset(controller.signal.reason); + reject(controller.signal.reason); + }); + }); + } + } written.enqueue(new Uint8Array(chunk)); }, close: () => written.close(), @@ -2985,6 +3001,8 @@ function probeTargetHarness(level: ProbeLevel, options?: { failTarget?: boolean subscriber, sent, version, + stalled, + aborted, finish: () => inbound.close(), }; } @@ -3035,6 +3053,25 @@ test("a failed PROBE target write ends the probe", async () => { viewers.close(); }); +// Ending the probe resets a stream whose target write the peer never drained, rather than +// queueing a close behind that write and holding the stream open. +test("ending the probe resets a stalled PROBE target write", async () => { + const { subscriber, sent, stalled, aborted } = probeTargetHarness(ProbeLevel.Increase, { stallTarget: true }); + const viewers = new Viewers(); + const viewer = viewers.watch(1_000_000); + const stop = new AbortController(); + const running = subscriber.runProbe(stop.signal, viewers.target); + expect(await sent.u53()).toBe(StreamId.Probe); + await stalled; + + stop.abort(); + await running; + expect(await aborted).toBeDefined(); + 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/js/net/src/lite/subscriber.ts b/js/net/src/lite/subscriber.ts index 7bc93c46cd7..c27760a5469 100644 --- a/js/net/src/lite/subscriber.ts +++ b/js/net/src/lite/subscriber.ts @@ -1989,6 +1989,11 @@ export class Subscriber { effect.get(target); if (!writing) void write(); }); + // A close queues behind a write the peer is not reading, which would hold the stream + // open past the probe; a reset rejects that write and frees the stream. + scope.cleanup(() => { + if (writing) stream.abort(new StreamError(StreamCode.Cancel, { message: "probe ended" })); + }); } /** diff --git a/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Moq.kt b/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Moq.kt index 361b4c0ab1a..384948bd994 100644 --- a/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Moq.kt +++ b/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Moq.kt @@ -67,8 +67,8 @@ internal constructor( * watched over it. * * Every call returns a handle to the same registry, and the session sends what its viewers' - * ceilings add up to as its PROBE target. [Viewers.watch] a broadcast with the ceiling of - * the largest rendition the player would switch to, read its slice with [Viewer.rate], and + * ceilings add up to as its PROBE target. [Viewers.watch] a broadcast with the ceiling of the + * largest rendition the player would switch to, read its slice with [Viewer.rate], and * [Viewer.close] it once the broadcast stops being watched. */ fun viewers(): Viewers = session.viewers() diff --git a/kt/moq/src/jvmAndAndroidTest/kotlin/dev/moq/SmokeTest.kt b/kt/moq/src/jvmAndAndroidTest/kotlin/dev/moq/SmokeTest.kt index 0e13fc60757..c39208a25da 100644 --- a/kt/moq/src/jvmAndAndroidTest/kotlin/dev/moq/SmokeTest.kt +++ b/kt/moq/src/jvmAndAndroidTest/kotlin/dev/moq/SmokeTest.kt @@ -599,20 +599,27 @@ class SmokeTest { @Test fun `viewers watch, update, and release before the session connects`() = runTest { - Server.listen(ServerConfig(bind = "127.0.0.1:0", tls = ServerTls(generate = listOf("localhost")))).use { server -> - Moq.connect("https://${server.localAddr}", ClientConfig(tls = ClientTls(insecure = true))).use { moq -> - val viewers: Viewers = moq.viewers() - // The server never accepts, so there is no receive estimate to divide. - val viewer: Viewer = viewers.watch(4_000_000uL) - viewer.use { - assertNull(it.rate()) - it.update(1_000_000uL) - assertNull(it.rate()) - } - viewers.setTarget(0uL) - viewers.setTarget(null) + Server.listen( + ServerConfig(bind = "127.0.0.1:0", tls = ServerTls(generate = listOf("localhost"))) + ) + .use { server -> + Moq.connect( + "https://${server.localAddr}", + ClientConfig(tls = ClientTls(insecure = true)), + ) + .use { moq -> + val viewers: Viewers = moq.viewers() + // The server never accepts, so there is no receive estimate to divide. + val viewer: Viewer = viewers.watch(4_000_000uL) + viewer.use { + assertNull(it.rate()) + it.update(1_000_000uL) + assertNull(it.rate()) + } + viewers.setTarget(0uL) + viewers.setTarget(null) + } } - } } @Test From 4a4e510fbf025aefcccf90cf03d3061dea8d117d Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 3 Nov 2026 16:28:22 -0800 Subject: [PATCH 16/20] feat(net): bound viewer probe targets; local override covers local reservations Viewer ceilings and PROBE target overrides that would sum above what every PROBE encoding carries (2^53 - 1 bps) are refused at the public API instead of failing the PROBE write and ending receive estimates: - moq-net: `Viewers::watch`, `Viewers::set_target`, and `Viewer::update` return `Result`, failing with `Error::BoundsExceeded`, and `Viewers::MAX_TARGET` names the limit. The registry enforces it under its lock, so a refused call changes nothing. - moq-ffi: the same calls return `MoqError::OutOfRange`; moq-c returns `MOQ_ERROR_OUT_OF_RANGE` (-45). Python, Swift, Kotlin, Dart, and Go carry the error; Go's `Watch`, `Update`, and `SetTarget` return it. - js/net: `Viewers.watch`, `setTarget`, and `Viewer.update` throw a `RangeError` past `Viewers.MAX_TARGET`, summing in the same order the target does so rounding cannot slip past it. `Allocator::set_target` docs now say a zero override stops probing for the local reservations only, since the session probes to the larger of that and the peer's PROBE target; an integration test covers it. Co-Authored-By: Claude Opus 5.5 --- c/moq/MIGRATE.md | 4 + cpp/moq/MIGRATE.md | 4 + dart/moq/MIGRATE.md | 4 + dart/moq/test/moq_test.dart | 5 + dart/moq_ffi/MIGRATE.md | 4 + dart/moq_ffi/lib/src/moq.dart | 72 ++++++- doc/lib/c/index.md | 2 +- doc/lib/cpp/index.md | 8 +- doc/lib/dart/index.md | 2 +- doc/lib/go/index.md | 2 +- doc/lib/js/net.md | 2 +- doc/lib/kt/index.md | 2 +- doc/lib/py/index.md | 2 +- doc/lib/swift/index.md | 2 +- go/wrapper/MIGRATE.md | 4 + go/wrapper/README.md | 3 +- go/wrapper/bandwidth_test.go | 37 +++- go/wrapper/errors.go | 2 + go/wrapper/errors_test.go | 1 + go/wrapper/session.go | 24 ++- js/net/api/index.api.md | 1 + js/net/src/bandwidth.test.ts | 29 ++- js/net/src/bandwidth.ts | 60 +++++- kt/moq-ffi/MIGRATE.md | 4 + kt/moq/MIGRATE.md | 4 + .../kotlin/dev/moq/SmokeTest.kt | 2 + py/moq-ffi/MIGRATE.md | 4 + py/moq-rs/MIGRATE.md | 4 + py/moq-rs/moq/session.py | 13 +- py/moq-rs/tests/test_server.py | 5 + rs/moq-c/src/bandwidth.rs | 28 ++- rs/moq-c/src/error.rs | 8 + rs/moq-c/src/test.rs | 7 + rs/moq-ffi/CHANGELOG.md | 2 + rs/moq-ffi/MIGRATE.md | 4 + rs/moq-ffi/src/bandwidth.rs | 61 +++++- rs/moq-ffi/src/error.rs | 7 + rs/moq-net/MIGRATE.md | 5 + rs/moq-net/benches/bandwidth.rs | 6 +- rs/moq-net/src/model/bandwidth.rs | 188 ++++++++++++++---- rs/moq-net/tests/integration/viewer_target.rs | 39 +++- swift/MIGRATE.md | 4 + swift/Sources/Moq/Bandwidth.swift | 20 +- swift/Tests/MoqTests/SmokeTests.swift | 14 +- 44 files changed, 578 insertions(+), 127 deletions(-) diff --git a/c/moq/MIGRATE.md b/c/moq/MIGRATE.md index a880800ee85..ed80a88cb82 100644 --- a/c/moq/MIGRATE.md +++ b/c/moq/MIGRATE.md @@ -4,6 +4,10 @@ How to update your code for each breaking change, newest first. ## Unreleased +### Viewer targets are bounded ([#7090](https://github.com/moq-dev/moq/pull/7090)) + +Viewer ceilings and PROBE target overrides are refused with the new `MOQ_ERROR_OUT_OF_RANGE` once they would sum above 2^53 - 1 bps, the most a PROBE target carries; nothing changes on a refusal. `moq_viewers_watch`, `moq_viewers_set_target`, and `moq_viewer_update` return it. Handle the new variant wherever you match the error exhaustively. Regenerate bindings and rebuild the matching native library together. + ### Media setup refusals are typed Audio and video subscribe setup now reports `MOQ_ERROR_UNSUPPORTED_CONFIG` when the decoder refuses a codec, layout, or description. Handle this variant to try another rendition instead of inspecting an audio/video error message or `Unsupported`. Decoder faults, such as a backend that fails to open, and later peer and decode failures keep their existing errors. Regenerate bindings and rebuild the matching native library together. diff --git a/cpp/moq/MIGRATE.md b/cpp/moq/MIGRATE.md index 64741d2fcf5..8314b7a1cb6 100644 --- a/cpp/moq/MIGRATE.md +++ b/cpp/moq/MIGRATE.md @@ -2,6 +2,10 @@ ## Unreleased +### Viewer targets are bounded ([#7090](https://github.com/moq-dev/moq/pull/7090)) + +Viewer ceilings and PROBE target overrides are refused with the new `moq::Error::kOutOfRange` once they would sum above 2^53 - 1 bps, the most a PROBE target carries; nothing changes on a refusal. `Viewers::watch` and `set_target` and `Viewer::update` return a `moq::expected` carrying it. Handle the new variant wherever you match the error exhaustively. Regenerate bindings and rebuild the matching native library together. + ### Media setup refusals are typed Audio and video subscribe setup now reports `moq::Error::kUnsupportedConfig` when the decoder refuses a codec, layout, or description. Handle this variant to try another rendition instead of inspecting an audio/video error message or `Unsupported`. Decoder faults, such as a backend that fails to open, and later peer and decode failures keep their existing errors. Regenerate bindings and rebuild the matching native library together. diff --git a/dart/moq/MIGRATE.md b/dart/moq/MIGRATE.md index 55789a0a84a..65e68b07773 100644 --- a/dart/moq/MIGRATE.md +++ b/dart/moq/MIGRATE.md @@ -4,6 +4,10 @@ How to update your code for each breaking change, newest first. ## Unreleased +### Viewer targets are bounded ([#7090](https://github.com/moq-dev/moq/pull/7090)) + +Viewer ceilings and PROBE target overrides are refused with the new `OutOfRangeMoqException` once they would sum above 2^53 - 1 bps, the most a PROBE target carries; nothing changes on a refusal. `Viewers.watch` and `setTarget` and `Viewer.update` throw it. Handle the new variant wherever you match the error exhaustively. Regenerate bindings and rebuild the matching native library together. + ### Media setup refusals are typed Audio and video subscribe setup now reports `UnsupportedConfigMoqException` when the decoder refuses a codec, layout, or description. Handle this variant to try another rendition instead of inspecting an audio/video error message or `Unsupported`. Decoder faults, such as a backend that fails to open, and later peer and decode failures keep their existing errors. Regenerate bindings and rebuild the matching native library together. diff --git a/dart/moq/test/moq_test.dart b/dart/moq/test/moq_test.dart index bd560999da8..1124c71e377 100644 --- a/dart/moq/test/moq_test.dart +++ b/dart/moq/test/moq_test.dart @@ -230,6 +230,11 @@ void main() { expect(viewer.rate() ?? 0, lessThanOrEqualTo(1000000)); viewers.setTarget(targetBps: 0); viewers.setTarget(targetBps: null); + // Past what a PROBE target carries: refused. + expect( + () => viewers.watch(maxBps: 1 << 53), + throwsA(isA()), + ); viewer.dispose(); final announcement = client.announced().updates().firstWhere( diff --git a/dart/moq_ffi/MIGRATE.md b/dart/moq_ffi/MIGRATE.md index 1f0d514839c..df3475adb81 100644 --- a/dart/moq_ffi/MIGRATE.md +++ b/dart/moq_ffi/MIGRATE.md @@ -2,6 +2,10 @@ ## Unreleased +### Viewer targets are bounded ([#7090](https://github.com/moq-dev/moq/pull/7090)) + +Viewer ceilings and PROBE target overrides are refused with the new `OutOfRangeMoqException` once they would sum above 2^53 - 1 bps, the most a PROBE target carries; nothing changes on a refusal. `MoqViewers.watch` and `setTarget` and `MoqViewer.update` throw it. Handle the new variant wherever you match the error exhaustively. Regenerate bindings and rebuild the matching native library together. + ### Media setup refusals are typed Audio and video subscribe setup now reports `UnsupportedConfigMoqException` when the decoder refuses a codec, layout, or description. Handle this variant to try another rendition instead of inspecting an audio/video error message or `Unsupported`. Decoder faults, such as a backend that fails to open, and later peer and decode failures keep their existing errors. Regenerate bindings and rebuild the matching native library together. diff --git a/dart/moq_ffi/lib/src/moq.dart b/dart/moq_ffi/lib/src/moq.dart index 30456df7566..1be1b373204 100644 --- a/dart/moq_ffi/lib/src/moq.dart +++ b/dart/moq_ffi/lib/src/moq.dart @@ -5771,6 +5771,12 @@ class FfiConverterMoqException { lifted.value, lifted.bytesRead - subview.offsetInBytes + 4, ); + case 35: + final lifted = OutOfRangeMoqException.read(subview); + return LiftRetVal( + lifted.value, + lifted.bytesRead - subview.offsetInBytes + 4, + ); default: throw UniffiInternalError( UniffiInternalError.unexpectedEnumCase, @@ -6974,6 +6980,44 @@ class UnsupportedConfigMoqException extends MoqException { } } +class OutOfRangeMoqException extends MoqException { + final String reason; + OutOfRangeMoqException(String this.reason); + OutOfRangeMoqException._(String this.reason); + static LiftRetVal read(Uint8List buf) { + int new_offset = buf.offsetInBytes; + final reason_lifted = FfiConverterString.read( + Uint8List.view(buf.buffer, new_offset), + ); + final reason = reason_lifted.value; + new_offset += reason_lifted.bytesRead; + return LiftRetVal(OutOfRangeMoqException._(reason), new_offset); + } + + @override + RustBuffer lower() { + final buf = Uint8List(allocationSize()); + write(buf); + return toRustBuffer(buf); + } + + @override + int allocationSize() { + return FfiConverterString.allocationSize(reason) + 4; + } + + @override + int write(Uint8List buf) { + buf.buffer.asByteData(buf.offsetInBytes).setInt32(0, 35); + int new_offset = buf.offsetInBytes + 4; + new_offset += FfiConverterString.write( + reason, + Uint8List.view(buf.buffer, new_offset), + ); + return new_offset; + } +} + class MoqExceptionErrorHandler extends UniffiRustCallStatusErrorHandler { @override Exception lift(RustBuffer errorBuf) { @@ -10112,9 +10156,15 @@ class MoqViewer implements MoqViewerInterface { if (_isDisposed) { return; } + final status = calloc(); _isDisposed = true; _MoqViewerFinalizer.detach(this); - rustCall((status) => uniffi_moq_ffi_fn_free_moqviewer(_ptr, status)); + try { + uniffi_moq_ffi_fn_free_moqviewer(_ptr, status); + checkCallStatus(NullRustCallStatusErrorHandler(), status); + } finally { + calloc.free(status); + } } int? rate() { @@ -10133,7 +10183,7 @@ class MoqViewer implements MoqViewerInterface { FfiConverterUInt64.lower(maxBps), status, ); - }, null); + }, moqExceptionErrorHandler); } } @@ -10194,9 +10244,15 @@ class MoqViewers implements MoqViewersInterface { if (_isDisposed) { return; } + final status = calloc(); _isDisposed = true; _MoqViewersFinalizer.detach(this); - rustCall((status) => uniffi_moq_ffi_fn_free_moqviewers(_ptr, status)); + try { + uniffi_moq_ffi_fn_free_moqviewers(_ptr, status); + checkCallStatus(NullRustCallStatusErrorHandler(), status); + } finally { + calloc.free(status); + } } void setTarget({required int? targetBps}) { @@ -10206,7 +10262,7 @@ class MoqViewers implements MoqViewersInterface { FfiConverterOptionalUInt64.lower(targetBps), status, ); - }, null); + }, moqExceptionErrorHandler); } MoqViewer watch({required int maxBps}) { @@ -10217,7 +10273,7 @@ class MoqViewers implements MoqViewersInterface { status, ), FfiConverterMoqViewer.lift, - null, + moqExceptionErrorHandler, ); } } @@ -22217,13 +22273,13 @@ void _checkApiChecksums() { if (uniffi_moq_ffi_checksum_method_moqviewer_rate() != 64505) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } - if (uniffi_moq_ffi_checksum_method_moqviewer_update() != 13024) { + if (uniffi_moq_ffi_checksum_method_moqviewer_update() != 27767) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } - if (uniffi_moq_ffi_checksum_method_moqviewers_set_target() != 23388) { + if (uniffi_moq_ffi_checksum_method_moqviewers_set_target() != 46661) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } - if (uniffi_moq_ffi_checksum_method_moqviewers_watch() != 62773) { + if (uniffi_moq_ffi_checksum_method_moqviewers_watch() != 18224) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } if (uniffi_moq_ffi_checksum_method_moqbroadcastconsumer_closed() != 12232) { diff --git a/doc/lib/c/index.md b/doc/lib/c/index.md index ad32fa7203b..297d11c57b9 100644 --- a/doc/lib/c/index.md +++ b/doc/lib/c/index.md @@ -115,7 +115,7 @@ inside. The header is the reference: each function carries a doc comment. - **JSON windows.** `moq_publish_json_window` publishes a sliding run of records: `moq_publish_json_window_push` appends at the back, `moq_publish_json_window_pop` drops from the front, and `moq_publish_json_window_cut` closes the open group at a natural boundary. The catalog has no window mode, so a reader names the track. `moq_consume_json_window_event` fills `moq_json_window_event` with a push (the record at `start`, in `json`), a pop of `[start, end)`, or a skip of `[start, end)` that this reader joined too late to receive. Set `checkpoint_records` to bound what each new group restates for a window you never pop. - **Decoded reads.** `moq_decode_audio` and `moq_decode_video` deliver read ids in order: a frame, a gap where media was lost, or an end where the publisher stopped its encoder. Check `kind` on what `moq_decode_audio_read` or `moq_decode_video_read` writes. Free each id with `moq_decode_audio_read_free` or `moq_decode_video_read_free` promptly: a held video frame holds a decoder buffer, and the decoder stalls. A decoder reads everything the track still holds unless a live player sets `start` to `MOQ_DECODE_START_LATEST`, which joins at the newest group and skips the cached backlog. A decoder setup refusal reports `MOQ_ERROR_UNSUPPORTED_CONFIG` on its terminal callback, so the caller can try another rendition; later peer or decode failures retain their own error codes. - **Stats.** `moq_session_stats()` fills `moq_connection_stats` with `rtt_us`, `estimated_send_rate_bps`, and the byte and packet counters (`bytes_sent`, `bytes_received`, `bytes_lost`, `packets_sent`, `packets_received`, `packets_lost`). Each has a `_valid` flag, false when the transport does not report it, which is not the same as zero. `moq_session_snapshot()` adds the negotiated `protocol`. A failed dial or dropped connection reaches the session's `on_state` with its `failure` code, and `moq_error()` gives the reason during that callback. Hold the handle returned by `moq_session_recv_bandwidth()` to request receive estimates. `moq_bandwidth_consumer_peek()` reads the estimate and `moq_bandwidth_consumer_changed()` waits for a change. `moq_bandwidth_consumer_close()` releases demand; the last consumer stops PROBE. Stats snapshots do not request it. -- **Viewers.** `moq_session_viewers()` returns a handle that divides the receive estimate among the broadcasts you watch, max-min fair by each one's ceiling. `moq_viewers_watch()` returns a viewer claiming up to `max_bps`, the bitrate of the largest rendition you would switch to; `moq_viewer_rate()` reads its share in bits per second, with `present` false while there is no estimate (keep the current rendition), and `moq_viewer_update()` changes the ceiling. Holding a viewer requests the estimate like a `moq_session_recv_bandwidth()` consumer, and `moq_viewer_close()` releases the claim. The session sends the summed ceilings as its PROBE target; `moq_viewers_set_target()` with `present` true overrides that, a `0` target sends none, and `present` false follows the viewers again. `moq_viewers_close()` releases the registry handle; viewers watched through it stay until each is closed. +- **Viewers.** `moq_session_viewers()` returns a handle that divides the receive estimate among the broadcasts you watch, max-min fair by each one's ceiling. `moq_viewers_watch()` returns a viewer claiming up to `max_bps`, the bitrate of the largest rendition you would switch to; `moq_viewer_rate()` reads its share in bits per second, with `present` false while there is no estimate (keep the current rendition), and `moq_viewer_update()` changes the ceiling. Holding a viewer requests the estimate like a `moq_session_recv_bandwidth()` consumer, and `moq_viewer_close()` releases the claim. The session sends the summed ceilings as its PROBE target; `moq_viewers_set_target()` with `present` true overrides that, a `0` target sends none, and `present` false follows the viewers again. `moq_viewers_watch()`, `moq_viewer_update()`, and `moq_viewers_set_target()` return `MOQ_ERROR_OUT_OF_RANGE`, changing nothing, when the ceilings or the target would pass 2^53 - 1 bps, the most a PROBE target carries. `moq_viewers_close()` releases the registry handle; viewers watched through it stay until each is closed. - **Demand.** A watcher from `moq_publish_track_demand()` (or the media, video, and audio variants) calls back `MOQ_DEMAND_WANTED` or `MOQ_DEMAND_UNWANTED`, again whenever the wanted group moves. `moq_publish_demand_wanted()` reads that group: start a new one once it passes your largest. Set `refresh` in `moq_track_info` to have a joining subscriber ask for a new group once the newest has grown past `refresh` times its first frame. A producer publishes everything you write, subscribed or not, so a late subscriber can fetch the recent past. Capturing only while the watcher reports `MOQ_DEMAND_WANTED` is an opt-in that saves the encode but leaves nothing from before the first subscriber. - **Disabled renditions.** A rendition with `enabled: false` has no frames coming until its publisher re-enables it. Query the latest catalog with `moq_consume_audio_enabled` or `moq_consume_video_enabled` before selecting a rendition and opening a decoder. Keep one already playing while every rendition of its kind is disabled: the convenience decoders accept a disabled configuration, and a re-enable, such as an unmute, then plays without a resubscribe. Among the video renditions you can decode, prefer the highest `preference`; `0` is the default and `-1` marks a compatibility transcode. diff --git a/doc/lib/cpp/index.md b/doc/lib/cpp/index.md index 82eb07a5bc6..f067ce9ae1e 100644 --- a/doc/lib/cpp/index.md +++ b/doc/lib/cpp/index.md @@ -215,16 +215,16 @@ Hold the owned `BandwidthConsumer` returned by `session->recv_bandwidth()` to re ## Viewers -`session->viewers()` divides the receive estimate among the broadcasts you watch, max-min fair by each one's ceiling. `watch(max_bps)` returns a `Viewer` claiming up to a ceiling, the bitrate of the largest rendition you would switch to; its `rate()` reads that viewer's share in bits per second, `std::nullopt` while there is no estimate (keep the current rendition), and `update(max_bps)` changes the ceiling. Holding a viewer requests the estimate like `recv_bandwidth()`, and releasing it releases the claim. The session sends the summed ceilings as its PROBE target; `set_target(bps)` overrides that, `0` sends none, and `std::nullopt` follows the viewers again. Client viewers survive reconnects and read `std::nullopt` while disconnected. +`session->viewers()` divides the receive estimate among the broadcasts you watch, max-min fair by each one's ceiling. `watch(max_bps)` returns a `Viewer` claiming up to a ceiling, the bitrate of the largest rendition you would switch to; its `rate()` reads that viewer's share in bits per second, `std::nullopt` while there is no estimate (keep the current rendition), and `update(max_bps)` changes the ceiling. Holding a viewer requests the estimate like `recv_bandwidth()`, and releasing it releases the claim. The session sends the summed ceilings as its PROBE target; `set_target(bps)` overrides that, `0` sends none, and `std::nullopt` follows the viewers again. `watch`, `update`, and `set_target` return `moq::Error::kOutOfRange` when the ceilings or the target would pass 2^53 - 1 bps, the most a PROBE target carries. Client viewers survive reconnects and read `std::nullopt` while disconnected. ```cpp auto viewers = session->viewers(); -auto camera = viewers->watch(4'000'000); // what its largest rendition needs -auto screen = viewers->watch(1'000'000); +auto camera = ok(viewers->watch(4'000'000)); // what its largest rendition needs +auto screen = ok(viewers->watch(1'000'000)); if (auto bps = camera->rate()) { // Switch to the largest rendition that fits in *bps. } -camera->update(2'500'000); // the catalog disabled the top rendition +ok(camera->update(2'500'000)); // the catalog disabled the top rendition screen.reset(); // stopped watching: its share returns to camera ``` diff --git a/doc/lib/dart/index.md b/doc/lib/dart/index.md index 6b644e77435..7daa1b36442 100644 --- a/doc/lib/dart/index.md +++ b/doc/lib/dart/index.md @@ -156,7 +156,7 @@ shows which module holds each. - **Closing.** `await moq.close()` drains for up to one second and reports its result. `session.shutdown()` requests the drain synchronously; `await session.closed()` waits for its result. `session.cancel(code: 0)` closes at once. Finish or abort live tracks first. Awaiting cancellation of an announcement, grant, or request subscription releases its pending native read. Announcements and grants also release their consumer; server listeners leave their shared server usable. moq-lite-05 and newer wait for the peer to receive finished tails; older Lite versions and IETF wait only for transport ACKs. - **Ending cleanly.** When the input ends, finish every track, then call `finish()` on its `CatalogProducer` to finish the catalog, which ends the content. The broadcast stays announced and keeps serving the finished tracks, so a subscriber still catching up can drain them, until `broadcast.close()` takes it offline; disposing its `Publication` does not. How long to keep it up is yours to decide. A track still open at the close, or released without a finish, ends with `Unroutable` (`Internal` over moq-transport, which has no such code). Readers follow a publisher's runs by announcement, not by that error: see [identity and recovery](/concept/identity). - **Stats.** `session.stats()` reports `rtt`, `estimatedSendRateBps`, and the byte and packet counters (`bytesSent`, `bytesReceived`, `bytesLost`, `packetsSent`, `packetsReceived`, `packetsLost`). A field is `null` when the transport does not report it, which is not the same as zero. `version` names the negotiated protocol. Connect returns a connecting session; read its coherent `state()` snapshot and wait with that snapshot's revision to observe first-dial failures and reconnects. Each watcher keeps its own revision. Hold the owned `BandwidthConsumer` returned by `session.recvBandwidth()` to receive bandwidth estimates. `rate()` reads the current estimate in bits per second and `rateChanged()` waits for a new one. Release the consumer or call `cancel()` when finished; releasing the last consumer stops PROBE; the session and stats snapshots do not request it. Client consumers survive reconnects and report no estimate while disconnected. -- **Viewers.** `client.viewers()` divides the connection's receive estimate among the broadcasts you watch, max-min fair by each one's ceiling. `watch(maxBps: ...)` returns a `Viewer` claiming up to what the largest rendition the player would switch to needs; `rate()` reads its slice in bits per second, `null` while there is no estimate, so hold the current selection. `update(maxBps: ...)` changes the ceiling, such as when the catalog enables or disables a rendition. Holding a viewer requests PROBE, and the session sends the viewers' summed ceilings as the PROBE target; `dispose()` it once the broadcast stops being watched. `setTarget(targetBps: ...)` sends another target, `0` sends none, and `null` follows the viewers again. Client viewers survive reconnects and read `null` while disconnected. +- **Viewers.** `client.viewers()` divides the connection's receive estimate among the broadcasts you watch, max-min fair by each one's ceiling. `watch(maxBps: ...)` returns a `Viewer` claiming up to what the largest rendition the player would switch to needs; `rate()` reads its slice in bits per second, `null` while there is no estimate, so hold the current selection. `update(maxBps: ...)` changes the ceiling, such as when the catalog enables or disables a rendition. Holding a viewer requests PROBE, and the session sends the viewers' summed ceilings as the PROBE target; `dispose()` it once the broadcast stops being watched. `setTarget(targetBps: ...)` sends another target, `0` sends none, and `null` follows the viewers again. Ceilings or a target past 2^53 - 1 bps, the most a PROBE target carries, throw `OutOfRangeMoqException`. Client viewers survive reconnects and read `null` while disconnected. - **Authorization.** On `moq-lite-07-wip` (opt in with `ConnectOptions(versions: ...)`) and on moq-transport draft-18+ with the [MoQ Auth extension](/draft/moq-auth), listen to `moq.grants().updates()` for the `Grant` the relay sent back and each change, `null` until it answers and while a client session reconnects. - **Tokens.** Pass `ConnectOptions(tokens: [...])` instead of putting the credential in the URL. The first is the connection credential, sent in SETUP and, while an offered version can't carry it there (lite before 07), as the URL's `?jwt=`; each other token widens the grant over AUTH. `moq.tokens().set_(tokens: [...])` replaces them before they expire: the next dial presents them, a live AUTH session at once, and after an authorization refusal the session redials only if they changed. `await tokens().answered()` returns once the relay accepts them and throws its refusal with the relay's code. A `?jwt=` already in the URL stays the connection credential, which is how to reach a relay older than this release. - **Errors.** Read diagnostic payloads from `reason` and structured protocol failures from `details`. diff --git a/doc/lib/go/index.md b/doc/lib/go/index.md index 2c3c6c84834..96af0410a80 100644 --- a/doc/lib/go/index.md +++ b/doc/lib/go/index.md @@ -137,7 +137,7 @@ shows which module holds each. - **Closing.** `client.Close()` drains for up to one second and returns an error on failure. `session.Shutdown()` requests that drain immediately; `session.Closed(ctx)` waits for its result, and `session.Cancel(code)` closes at once. Finish or abort live tracks first. moq-lite-05 and newer wait for the peer to receive finished tails; older Lite versions and IETF wait only for transport ACKs. - **Ending cleanly.** When the input ends, finish every track, then call `Finish()` on its `media.CatalogProducer` to finish the catalog, which ends the content. The broadcast stays announced and keeps serving the finished tracks, so a subscriber still catching up can drain them, until `broadcast.Close()` takes it offline. How long to keep it up is yours to decide. A track still open at the close, or released without a finish, ends with `Unroutable` (`Internal` over moq-transport, which has no such code). Readers follow a publisher's runs by announcement, not by that error: see [identity and recovery](/concept/identity). - **Stats.** `Session().Stats()` reports `RTT`, `EstimatedSendRateBps`, and the byte and packet counters (`BytesSent`, `BytesReceived`, `BytesLost`, `PacketsSent`, `PacketsReceived`, `PacketsLost`). A field is nil when the transport does not report it, which is not the same as zero. `Version` names the negotiated protocol. `Dial` returns a connecting session; read `Session().State()` and wait with `StateChanged(ctx, state.Revision)` to observe first-dial failures and reconnects. Hold the owned `BandwidthConsumer` returned by `Session().RecvBandwidth()` to receive bandwidth estimates. `Rate()` reads the current estimate in bits per second and `RateChanged(ctx)` waits for a new one. Calling `Close()` on the last consumer stops PROBE; the session and stats snapshots do not request it. Client consumers survive reconnects and report no estimate while disconnected. -- **Viewers.** `Session().Viewers()` divides the connection's receive estimate among the broadcasts you watch, max-min fair by each one's ceiling. `Watch(maxBps)` returns a `Viewer` claiming up to what the largest rendition the player would switch to needs; `Rate()` reads its slice in bits per second, nil while there is no estimate, so hold the current selection. `Update(maxBps)` changes the ceiling, such as when the catalog enables or disables a rendition. Holding a viewer requests PROBE, and the session sends the viewers' summed ceilings as the PROBE target; `Close()` it once the broadcast stops being watched, from the goroutine that last used it. `SetTarget(&bps)` sends another target, zero sends none, and nil follows the viewers again. Client viewers survive reconnects and read nil while disconnected. +- **Viewers.** `Session().Viewers()` divides the connection's receive estimate among the broadcasts you watch, max-min fair by each one's ceiling. `Watch(maxBps)` returns a `Viewer` claiming up to what the largest rendition the player would switch to needs; `Rate()` reads its slice in bits per second, nil while there is no estimate, so hold the current selection. `Update(maxBps)` changes the ceiling, such as when the catalog enables or disables a rendition. Holding a viewer requests PROBE, and the session sends the viewers' summed ceilings as the PROBE target; `Close()` it once the broadcast stops being watched, from the goroutine that last used it. `SetTarget(&bps)` sends another target, zero sends none, and nil follows the viewers again. `Watch`, `Update`, and `SetTarget` return `moq.ErrOutOfRange` when the ceilings or the target would pass 2^53 - 1 bps, the most a PROBE target carries. Client viewers survive reconnects and read nil while disconnected. - **Authorization.** On `moq-lite-07-wip` (opt in with `ClientConfig.Versions`) and on moq-transport draft-18+ with the [MoQ Auth extension](/draft/moq-auth), `Session().Grants()` returns a `GrantConsumer`: `Grant()` is the `Grant` the relay sent back, nil until it answers and while a client session reconnects, and `Changed(ctx)` waits for the next one. `Close()` it when done. - **Tokens.** Set `ClientConfig.Tokens` instead of putting the credential in the URL. The first is the connection credential, sent in SETUP and, while an offered version can't carry it there (lite before 07), as the URL's `?jwt=`; each other token widens the grant over AUTH. `Session().Tokens().Set(...)` replaces a client session's tokens before they expire: the next dial presents them, a live AUTH session at once, and after an authorization refusal the session redials only if they changed. `Answered(ctx)` returns nil once the relay accepts them, or its refusal with the relay's code. A `?jwt=` already in the URL stays the connection credential, which is how to reach a relay older than this release. - **Errors.** Read diagnostic payloads from `Reason` and structured protocol failures from `Details`. diff --git a/doc/lib/js/net.md b/doc/lib/js/net.md index 3ae62d1dde1..1a3913e0485 100644 --- a/doc/lib/js/net.md +++ b/doc/lib/js/net.md @@ -47,7 +47,7 @@ publication.announce(); - **Connections share by URL and versions.** `new Connection({ url })` pools and reconnects with backoff, which the elements use. An ordered `versions` list, spelled like `moq-lite-06` as in Rust, applies to both WebTransport and WebSocket; equivalent lists share, while a different order or an omitted list gets its own pool entry. Supplying your own transport options or origin selects a private loop. Receive estimates are on demand: observe `connection.probe` reactively or subscribe while you need them; `peek()` alone opens no PROBE stream. - **GOAWAY moves the session.** The connection dials the replacement at once while the old session keeps serving its groups, up to `goaway.handover` (default 10s, or the relay's deadline when that is sooner). New requests keep opening on the old session until the replacement's route outranks it, which is a restart when the instance did not cross: an unpinned announced request follows the replacement, while a blind or instance-pinned request stays on its accepted stream. When `moq-lite-07-wip` is offered the instance crosses, the replacement serves the same stream, and open subscriptions move across without missing a group. An empty GOAWAY redials the same URL. A redirect stays on the same host unless `goaway.redirect` is `"follow"`, which also presents the tokens on the connection's `auth` handle to the new host. A one-shot session from `Connection.connect` never moves on its own; its `draining` settles with the GOAWAY, so you can connect again and close it. Its URI is the peer's to choose and `goaway.redirect` does not apply, so validate it before dialing it or presenting tokens to it. - **One send estimate per connection.** `Bandwidth.Allocator` divides it by track priority, max-min fair within a tier. An idle track claims nothing, though its reservation still reads the share it would get. Publishers reserve against it so their targets sum to the estimate. A connection samples the estimate from its transport only while a reservation reads it, so receive-only and lingering connections do no stats work, and the first reservation after none reads `undefined` until one fresh snapshot lands. A transport that cannot report one is never sampled and reads `undefined`: the WebSocket fallback, WebRTC, and WebTransport without `getStats()` (shipping Chromium and Safari). -- **One receive estimate per connection.** `connection.viewers` divides it among watched broadcasts, max-min fair by each viewer's ceiling, so several players on one pooled connection don't each select against the whole downlink. Holding a viewer requests PROBE, and the viewers' ceilings, summed, are the PROBE target a relay advertising `Increase` probes the downlink up to. `setTarget(0)` opts out. +- **One receive estimate per connection.** `connection.viewers` divides it among watched broadcasts, max-min fair by each viewer's ceiling, so several players on one pooled connection don't each select against the whole downlink. Holding a viewer requests PROBE, and the viewers' ceilings, summed, are the PROBE target a relay advertising `Increase` probes the downlink up to. `setTarget(0)` opts out. `watch`, `update`, and `setTarget` throw a `RangeError` when the ceilings or the target would pass `Viewers.MAX_TARGET` (`Number.MAX_SAFE_INTEGER`), the most a PROBE target carries. - **List a broadcast's tracks.** `for await (const event of broadcast.tracks())` reports each track the broadcast lists (`added`, with its `Track.Info`), one `synced`, then `added` and `removed` as tracks come and go, until the broadcast ends; leaving the loop stops listing. Over a session it needs `moq-lite-07-wip`, syncs at once with what this side holds, and the peer's tracks follow as `added`. A track served only on request is never listed. See [discovery](/concept/moq-lite#discovery). - **One track per name.** Concurrent subscriptions share one request and producer. `createTrack` on a name with a request still queued answers it. The application owns sequence numbers: the broadcast keeps nothing of an ended track, so a track that replaces it, created or requested, starts at 0. A name always means the same content, so the replacement continues past its predecessor's groups by writing its first group with an explicit sequence. Sequences are `bigint`, so every ID the wire carries fits, past 2^53 included: `track.createGroup(5n)`, `{ absolute: 10n }`. Frame indices and relative anchors stay `number`. - **Timing is per track, with no default.** A track that declares a `timescale` carries a `timestamp` on every frame; one without is [untimed](/concept/moq-lite#subscriptions) and its frames carry none. Omitting it means untimed, as in Rust. Nothing stamps a frame for you: the publisher passes the timestamp, and the `Timed` type (`{ value, at }`) carries one into the `@moq/json` producers. diff --git a/doc/lib/kt/index.md b/doc/lib/kt/index.md index 573b15279b9..6836623c556 100644 --- a/doc/lib/kt/index.md +++ b/doc/lib/kt/index.md @@ -111,7 +111,7 @@ shows which module holds each. - **Closing.** `moq.shutdown()` requests a drain immediately; suspending `moq.session.closed()` waits up to one second and reports its result. `Moq.close()`, and so `use { }`, cancels at once. Finish or abort live tracks first. moq-lite-05 and newer wait for the peer to receive finished tails; older Lite versions and IETF wait only for transport ACKs. - **Ending cleanly.** When the input ends, finish every track, then call `finish()` on its `CatalogProducer` to finish the catalog, which ends the content. The broadcast stays announced and keeps serving the finished tracks, so a subscriber still catching up can drain them, until `broadcast.end()` takes it offline. How long to keep it up is yours to decide. A track still open at the end, or released without a finish, ends with `Unroutable` (`Internal` over moq-transport, which has no such code). Readers follow a publisher's runs by announcement, not by that error: see [identity and recovery](/concept/identity). - **Stats.** `session.stats()` reports `rtt`, `estimatedSendRateBps`, and the byte and packet counters (`bytesSent`, `bytesReceived`, `bytesLost`, `packetsSent`, `packetsReceived`, `packetsLost`). A field is `null` when the transport does not report it, which is not the same as zero. `version` names the negotiated protocol. Connect returns a connecting session; read its coherent `state()` snapshot and wait with that snapshot's revision to observe first-dial failures and reconnects. Each watcher keeps its own revision. Hold the owned `BandwidthConsumer` returned by `session.recvBandwidth()` to receive bandwidth estimates. `rate()` reads the current estimate in bits per second and `rateChanged()` waits for a new one. Release the consumer or call `cancel()` when finished; releasing the last consumer stops PROBE; the session and stats snapshots do not request it. Client consumers survive reconnects and report no estimate while disconnected. -- **Viewers.** `moq.viewers()` divides the connection's receive estimate among the broadcasts you watch, max-min fair by each one's ceiling. `watch(maxBps)` returns a `Viewer` claiming up to what the largest rendition the player would switch to needs; `rate()` reads its slice in bits per second, `null` while there is no estimate, so hold the current selection. `update(maxBps)` changes the ceiling, such as when the catalog enables or disables a rendition. Holding a viewer requests PROBE, and the session sends the viewers' summed ceilings as the PROBE target; `close()` it, or leave `use { }`, once the broadcast stops being watched. `setTarget(bps)` sends another target, `0` sends none, and `null` follows the viewers again. Client viewers survive reconnects and read `null` while disconnected. +- **Viewers.** `moq.viewers()` divides the connection's receive estimate among the broadcasts you watch, max-min fair by each one's ceiling. `watch(maxBps)` returns a `Viewer` claiming up to what the largest rendition the player would switch to needs; `rate()` reads its slice in bits per second, `null` while there is no estimate, so hold the current selection. `update(maxBps)` changes the ceiling, such as when the catalog enables or disables a rendition. Holding a viewer requests PROBE, and the session sends the viewers' summed ceilings as the PROBE target; `close()` it, or leave `use { }`, once the broadcast stops being watched. `setTarget(bps)` sends another target, `0` sends none, and `null` follows the viewers again. Ceilings or a target past 2^53 - 1 bps, the most a PROBE target carries, throw `MoqException.OutOfRange`. Client viewers survive reconnects and read `null` while disconnected. - **Authorization.** On `moq-lite-07-wip` (opt in with `ClientConfig(versions = ...)`) and on moq-transport draft-18+ with the [MoQ Auth extension](/draft/moq-auth), collect `moq.grants().updates()` for the `Grant` the relay sent back and each change, `null` until it answers and while a client session reconnects. Ending the collection cancels the consumer. - **Tokens.** Pass `ClientConfig(tokens = listOf(...))` instead of putting the credential in the URL. The first is the connection credential, sent in SETUP and, while an offered version can't carry it there (lite before 07), as the URL's `?jwt=`; each other token widens the grant over AUTH. `moq.tokens().set(listOf(...))` replaces them before they expire: the next dial presents them, a live AUTH session at once, and after an authorization refusal the session redials only if they changed. Suspending `tokens().answered()` returns once the relay accepts them and throws its refusal with the relay's code. A `?jwt=` already in the URL stays the connection credential, which is how to reach a relay older than this release. - **Errors.** Read diagnostic payloads from `reason` and structured protocol failures from `details`. diff --git a/doc/lib/py/index.md b/doc/lib/py/index.md index 65f584ee9d7..bdff311139a 100644 --- a/doc/lib/py/index.md +++ b/doc/lib/py/index.md @@ -125,7 +125,7 @@ shows which module holds each. - **Closing.** `session.shutdown()` requests a drain immediately; `await session.closed()` waits up to one second and reports its result. `cancel(code)` closes at once. Finish or abort live tracks first. moq-lite-05 and newer wait for the peer to receive finished tails; older Lite versions and IETF wait only for transport ACKs. - **Ending cleanly.** When the input ends, finish every track, then call `finish()` on its `moq.media.CatalogProducer` to finish the catalog, which ends the content. The broadcast stays announced and keeps serving the finished tracks, so a subscriber still catching up can drain them, until `broadcast.close()` takes it offline. How long to keep it up is yours to decide. A track still open at the close, or released without a finish, ends with `Unroutable` (`Internal` over moq-transport, which has no such code). Readers follow a publisher's runs by announcement, not by that error: see [identity and recovery](/concept/identity). - **Stats.** `session.stats()` reports `rtt`, `estimated_send_rate_bps`, and the byte and packet counters (`bytes_sent`, `bytes_received`, `bytes_lost`, `packets_sent`, `packets_received`, `packets_lost`). A field is `None` when the transport does not report it, which is not the same as zero. `version` names the negotiated protocol. Connect returns a connecting session; read its coherent `state()` snapshot and wait with that snapshot's revision to observe first-dial failures and reconnects. Each watcher keeps its own revision. Hold the owned `BandwidthConsumer` returned by `session.recv_bandwidth()` to receive bandwidth estimates. `rate()` reads the current estimate in bits per second and `rate_changed()` waits for a new one. Release the consumer or call `cancel()` when finished; releasing the last consumer stops PROBE; the session and stats snapshots do not request it. Client consumers survive reconnects and report no estimate while disconnected. -- **Viewers.** `session.viewers()` divides the receive estimate among the broadcasts you watch. `watch(max_bps)` returns a `Viewer` claiming up to a ceiling, the bitrate of the largest rendition you would switch to; its `rate()` reads that viewer's fair share in bits per second, `None` while there is no estimate (keep the current rendition), and `update(max_bps)` changes the ceiling. Holding a viewer requests the estimate like `recv_bandwidth()`, and dropping it releases the claim. The session sends the summed ceilings as its PROBE target; `set_target(bps)` overrides that, `0` sends none, and `None` follows the viewers again. +- **Viewers.** `session.viewers()` divides the receive estimate among the broadcasts you watch. `watch(max_bps)` returns a `Viewer` claiming up to a ceiling, the bitrate of the largest rendition you would switch to; its `rate()` reads that viewer's fair share in bits per second, `None` while there is no estimate (keep the current rendition), and `update(max_bps)` changes the ceiling. Holding a viewer requests the estimate like `recv_bandwidth()`, and dropping it releases the claim. The session sends the summed ceilings as its PROBE target; `set_target(bps)` overrides that, `0` sends none, and `None` follows the viewers again. Ceilings or a target past 2^53 - 1 bps, the most a PROBE target carries, raise `moq.Error.OutOfRange`. - **Authorization.** On `moq-lite-07-wip` (opt in with `versions=`) and on moq-transport draft-18+ with the [MoQ Auth extension](/draft/moq-auth), `async for grant in session.grants()` yields the `Grant` the relay sent back and each change, `None` until it answers and while a client session reconnects. `grants().grant()` reads it once; cancelling or leaving an `async with` releases the wait. - **Tokens.** Pass `tokens=[...]` instead of putting the credential in the URL. The first is the connection credential, sent in SETUP and, while an offered version can't carry it there (lite before 07), as the URL's `?jwt=`; each other token widens the grant over AUTH. `session.tokens().set([...])` replaces a client session's tokens before they expire: the next dial presents them, a live AUTH session at once, and after an authorization refusal the session redials only if they changed. `await tokens.answered()` returns once the relay accepts them and raises its refusal with the relay's code. A `?jwt=` already in the URL stays the connection credential, which is how to reach a relay older than this release. - **Errors.** Read diagnostic payloads from `reason` and structured protocol failures from `details`. diff --git a/doc/lib/swift/index.md b/doc/lib/swift/index.md index 4551478e823..3cf2b0ef1d8 100644 --- a/doc/lib/swift/index.md +++ b/doc/lib/swift/index.md @@ -111,7 +111,7 @@ shows which module holds each. - **Closing.** `session.shutdown()` requests a drain immediately; `try await session.closed()` waits up to one second and reports its result. `session.cancel(code:)` closes at once. Finish or abort live tracks first. moq-lite-05 and newer wait for the peer to receive finished tails; older Lite versions and IETF wait only for transport ACKs. - **Ending cleanly.** When the input ends, finish every track, then call `try finish()` on its `Media.CatalogProducer` to finish the catalog, which ends the content. The broadcast stays announced and keeps serving the finished tracks, so a subscriber still catching up can drain them, until `broadcast.close()` takes it offline. How long to keep it up is yours to decide. A track still open at the close, or released without a finish, ends with `Unroutable` (`Internal` over moq-transport, which has no such code). Readers follow a publisher's runs by announcement, not by that error: see [identity and recovery](/concept/identity). - **Stats.** `session.stats()` reports `rtt`, `estimatedSendRateBps`, and the byte and packet counters (`bytesSent`, `bytesReceived`, `bytesLost`, `packetsSent`, `packetsReceived`, `packetsLost`). A field is `nil` when the transport does not report it, which is not the same as zero. `version` names the negotiated protocol. Connect returns a connecting session; read its coherent `state()` snapshot and wait with that snapshot's revision to observe first-dial failures and reconnects. Each watcher keeps its own revision. Hold the owned `BandwidthConsumer` returned by `session.recvBandwidth()` to receive bandwidth estimates. `rate()` reads the current estimate in bits per second and `rateChanged()` waits for a new one. Release the consumer or call `cancel()` when finished; releasing the last consumer stops PROBE; the session and stats snapshots do not request it. Client consumers survive reconnects and report no estimate while disconnected. -- **Viewers.** `session.viewers()` divides the receive estimate among the broadcasts you watch. `watch(maxBps:)` returns a `Viewer` claiming up to a ceiling, the bitrate of the largest rendition you would switch to; its `rate()` reads that viewer's fair share in bits per second, `nil` while there is no estimate (keep the current rendition), and `update(maxBps:)` changes the ceiling. Holding a viewer requests the estimate like `recvBandwidth()`, and releasing it releases the claim. The session sends the summed ceilings as its PROBE target; `setTarget(targetBps:)` overrides that, `0` sends none, and `nil` follows the viewers again. +- **Viewers.** `session.viewers()` divides the receive estimate among the broadcasts you watch. `watch(maxBps:)` returns a `Viewer` claiming up to a ceiling, the bitrate of the largest rendition you would switch to; its `rate()` reads that viewer's fair share in bits per second, `nil` while there is no estimate (keep the current rendition), and `update(maxBps:)` changes the ceiling. Holding a viewer requests the estimate like `recvBandwidth()`, and releasing it releases the claim. The session sends the summed ceilings as its PROBE target; `setTarget(targetBps:)` overrides that, `0` sends none, and `nil` follows the viewers again. `watch`, `update`, and `setTarget` throw `MoqError.OutOfRange` when the ceilings or the target would pass 2^53 - 1 bps, the most a PROBE target carries. - **Authorization.** On `moq-lite-07-wip` (opt in with `Client(versions:)`) and on moq-transport draft-18+ with the [MoQ Auth extension](/draft/moq-auth), `for try await grant in session.grants()` yields the `Grant` the relay sent back and each change, `nil` until it answers and while a client session reconnects. Cancelling the iterating task cancels the native wait. - **Tokens.** Pass `Client(tokens: [...])` instead of putting the credential in the URL. The first is the connection credential, sent in SETUP and, while an offered version can't carry it there (lite before 07), as the URL's `?jwt=`; each other token widens the grant over AUTH. `try session.tokens()?.set([...])` replaces them before they expire: the next dial presents them, a live AUTH session at once, and after an authorization refusal the session redials only if they changed. `try await tokens.answered()` returns once the relay accepts them and throws its refusal with the relay's code. A `?jwt=` already in the URL stays the connection credential, which is how to reach a relay older than this release. - **Errors.** Diagnostic cases use the `reason:` argument label; match their associated value to inspect it. Protocol errors carry `details`. diff --git a/go/wrapper/MIGRATE.md b/go/wrapper/MIGRATE.md index d3188ea7fff..38f5c307234 100644 --- a/go/wrapper/MIGRATE.md +++ b/go/wrapper/MIGRATE.md @@ -4,6 +4,10 @@ How to update your code for each breaking change, newest first. ## Unreleased +### Viewer targets are bounded ([#7090](https://github.com/moq-dev/moq/pull/7090)) + +Viewer ceilings and PROBE target overrides are refused with the new `ErrOutOfRange` once they would sum above 2^53 - 1 bps, the most a PROBE target carries; nothing changes on a refusal. `Viewers.Watch` returns `(*Viewer, error)`, and `Viewers.SetTarget` and `Viewer.Update` return an `error`. Handle the new variant wherever you match the error exhaustively. Regenerate bindings and rebuild the matching native library together. + ### Media setup refusals are typed Audio and video subscribe setup now reports `ErrUnsupportedConfig` when the decoder refuses a codec, layout, or description. Handle this variant to try another rendition instead of inspecting an audio/video error message or `Unsupported`. Decoder faults, such as a backend that fails to open, and later peer and decode failures keep their existing errors. Regenerate bindings and rebuild the matching native library together. diff --git a/go/wrapper/README.md b/go/wrapper/README.md index 48e4321a07b..999d54ea876 100644 --- a/go/wrapper/README.md +++ b/go/wrapper/README.md @@ -85,7 +85,8 @@ A player divides the receive estimate among the broadcasts it watches with rendition it would switch to needs; the viewer's `Rate()` is its slice, nil while there is no estimate, and `Update(maxBps)` changes the ceiling. The session sends the viewers' summed ceilings as its PROBE target, which -`SetTarget` overrides. Holding a viewer requests PROBE, so `Close()` it once +`SetTarget` overrides. Ceilings or a target summing above 2^53 - 1 fail with +`moq.ErrOutOfRange`. Holding a viewer requests PROBE, so `Close()` it once the broadcast stops being watched. Incoming server requests expose the query-free `Path()` before `Accept()`. It diff --git a/go/wrapper/bandwidth_test.go b/go/wrapper/bandwidth_test.go index d6d0c6c34e5..5475fc39850 100644 --- a/go/wrapper/bandwidth_test.go +++ b/go/wrapper/bandwidth_test.go @@ -2,6 +2,7 @@ package moq_test import ( "context" + "errors" "math" "runtime" "testing" @@ -106,26 +107,48 @@ func TestViewersWatchUpdateAndClose(t *testing.T) { waitConnects(t, ctx, client.Session(), 1) viewers := client.Session().Viewers() - first := viewers.Watch(4_000_000) - second := viewers.Watch(1_000_000) + first, err := viewers.Watch(4_000_000) + if err != nil { + t.Fatal(err) + } + second, err := viewers.Watch(1_000_000) + if err != nil { + t.Fatal(err) + } // Whether QUIC has a receive estimate yet varies, but a slice never exceeds its ceiling. if rate := second.Rate(); rate != nil && *rate > 1_000_000 { t.Fatalf("rate = %d, above its 1000000 ceiling", *rate) } - second.Update(500_000) + if err := second.Update(500_000); err != nil { + t.Fatal(err) + } if rate := second.Rate(); rate != nil && *rate > 500_000 { t.Fatalf("rate = %d, above its 500000 ceiling", *rate) } zero := uint64(0) - viewers.SetTarget(&zero) - viewers.SetTarget(nil) + if err := viewers.SetTarget(&zero); err != nil { + t.Fatal(err) + } + if err := viewers.SetTarget(nil); err != nil { + t.Fatal(err) + } + // Past what a PROBE target carries: refused. + if _, err := viewers.Watch(1 << 53); !errors.Is(err, moq.ErrOutOfRange) { + t.Fatalf("Watch(2^53) = %v, want ErrOutOfRange", err) + } // Closing one viewer leaves the others and the registry usable. second.Close() - first.Update(2_000_000) + if err := first.Update(2_000_000); err != nil { + t.Fatal(err) + } if rate := first.Rate(); rate != nil && *rate > 2_000_000 { t.Fatalf("rate = %d, above its 2000000 ceiling", *rate) } first.Close() - client.Session().Viewers().Watch(1).Close() + last, err := client.Session().Viewers().Watch(1) + if err != nil { + t.Fatal(err) + } + last.Close() } diff --git a/go/wrapper/errors.go b/go/wrapper/errors.go index 022bd5d3d98..73057fa29c9 100644 --- a/go/wrapper/errors.go +++ b/go/wrapper/errors.go @@ -91,6 +91,8 @@ var ( ErrLog = ffi.ErrMoqErrorLog // ErrConfig is returned when Dial or Listen is given a value the native side cannot use. ErrConfig = ffi.ErrMoqErrorConfig + // ErrOutOfRange is returned when a number is outside the range the call accepts, such as viewer ceilings summing above 2^53 - 1. + ErrOutOfRange = ffi.ErrMoqErrorOutOfRange ) // IsShutdown reports whether err is the expected result of a graceful shutdown diff --git a/go/wrapper/errors_test.go b/go/wrapper/errors_test.go index 4cb2e38cd22..80c84dfd720 100644 --- a/go/wrapper/errors_test.go +++ b/go/wrapper/errors_test.go @@ -96,6 +96,7 @@ func TestErrorSentinels(t *testing.T) { {"NotFound", ffi.NewMoqErrorNotFound(), moq.ErrNotFound}, {"Unsupported", ffi.NewMoqErrorUnsupported(), moq.ErrUnsupported}, {"UnsupportedConfig", ffi.NewMoqErrorUnsupportedConfig("description"), moq.ErrUnsupportedConfig}, + {"OutOfRange", ffi.NewMoqErrorOutOfRange("viewer"), moq.ErrOutOfRange}, {"InvalidPattern", ffi.NewMoqErrorInvalidPattern(""), moq.ErrInvalidPattern}, {"InvalidInstance", ffi.NewMoqErrorInvalidInstance(""), moq.ErrInvalidInstance}, {"UnresolvableBroadcast", ffi.NewMoqErrorUnresolvableBroadcast(""), moq.ErrUnresolvableBroadcast}, diff --git a/go/wrapper/session.go b/go/wrapper/session.go index ba3e342bf75..a266e194b01 100644 --- a/go/wrapper/session.go +++ b/go/wrapper/session.go @@ -195,14 +195,21 @@ type Viewers struct { // ceiling: what the largest rendition the player would switch to needs, not what // it is receiving. Holding the viewer requests the receive estimate, like // Session.RecvBandwidth; Close it once the broadcast stops being watched. -func (v *Viewers) Watch(maxBps uint64) *Viewer { - return &Viewer{inner: v.inner.Watch(maxBps)} +// Errors with ErrOutOfRange, watching nothing, when the ceilings would sum +// above 2^53 - 1. +func (v *Viewers) Watch(maxBps uint64) (*Viewer, error) { + inner, err := v.inner.Watch(maxBps) + if err != nil { + return nil, err + } + return &Viewer{inner: inner}, nil } // SetTarget sends targetBps as the PROBE target instead of the viewers' sum, or -// nil to follow them again. Zero sends no target. -func (v *Viewers) SetTarget(targetBps *uint64) { - v.inner.SetTarget(targetBps) +// nil to follow them again. Zero sends no target. Errors with ErrOutOfRange, +// keeping the previous override, above 2^53 - 1. +func (v *Viewers) SetTarget(targetBps *uint64) error { + return v.inner.SetTarget(targetBps) } // Viewer is one watched broadcast's standing claim on Viewers. @@ -220,9 +227,10 @@ func (v *Viewer) Rate() *uint64 { } // Update changes the ceiling, keeping the same claim, as when a catalog enables -// or disables a rendition. -func (v *Viewer) Update(maxBps uint64) { - v.inner.Update(maxBps) +// or disables a rendition. Errors with ErrOutOfRange, keeping the previous +// ceiling, when the ceilings would sum above 2^53 - 1. +func (v *Viewer) Update(maxBps uint64) error { + return v.inner.Update(maxBps) } // Close releases the claim, handing its share to the other viewers, lowering diff --git a/js/net/api/index.api.md b/js/net/api/index.api.md index 3b64d316f3e..739ad855b00 100644 --- a/js/net/api/index.api.md +++ b/js/net/api/index.api.md @@ -81,6 +81,7 @@ export namespace Bandwidth { } export class Viewers { constructor(estimate?: Signals.Getter); + static readonly MAX_TARGET: number; close(): void; setTarget(target: number | undefined): void; readonly target: Signals.Getter; diff --git a/js/net/src/bandwidth.test.ts b/js/net/src/bandwidth.test.ts index fc7623ff88c..beef3e4821d 100644 --- a/js/net/src/bandwidth.test.ts +++ b/js/net/src/bandwidth.test.ts @@ -393,6 +393,33 @@ test("viewers split the receive estimate max-min fair", () => { viewers.close(); }); +// The PROBE stream encodes at most MAX_TARGET, so a viewer, update, or override past it is +// refused and leaves the target as it was. +test("viewer targets stay encodable", () => { + const viewers = new Viewers(); + const max = Viewers.MAX_TARGET; + + expect(() => viewers.watch(max + 1)).toThrow(RangeError); + const first = viewers.watch(max - 1); + expect(() => viewers.watch(2)).toThrow(RangeError); + const second = viewers.watch(1); + expect(viewers.target.peek()).toBe(max); + + expect(() => second.update(2)).toThrow(RangeError); + expect(viewers.target.peek()).toBe(max); + first.update(1); + second.update(max - 1); + expect(viewers.target.peek()).toBe(max); + + viewers.setTarget(1_000_000); + expect(() => viewers.setTarget(max + 1)).toThrow(RangeError); + expect(viewers.target.peek()).toBe(1_000_000); + + first.close(); + second.close(); + viewers.close(); +}); + test("the viewers' target sums their ceilings until overridden", () => { const viewers = new Viewers(new Signal(1_000_000)); expect(viewers.target.peek()).toBe(0); @@ -404,7 +431,7 @@ test("the viewers' target sums their ceilings until overridden", () => { second.update(4_000_000); expect(viewers.target.peek()).toBe(5_000_000); - // Zero turns probing off; clearing the override follows the viewers again. + // Zero sends no target; clearing the override follows the viewers again. viewers.setTarget(0); expect(viewers.target.peek()).toBe(0); viewers.setTarget(10_000_000); diff --git a/js/net/src/bandwidth.ts b/js/net/src/bandwidth.ts index cd29fdb865e..143582cf438 100644 --- a/js/net/src/bandwidth.ts +++ b/js/net/src/bandwidth.ts @@ -191,12 +191,21 @@ function ceiling(max: number): number { return max; } +/** The ceilings summed in order, the way {@link Viewers.target} sums them. */ +function total(entries: readonly { max: number }[]): number { + let sum = 0; + for (const entry of entries) sum += entry.max; + return sum; +} + /** * The registry behind {@link Allocator} and {@link Viewers}: divides one estimate * among its claims, publishing each claim's slice. */ class Divider { #estimate: Getter | undefined; + /** The most the ceilings may sum to, or `undefined` for no limit. */ + #limit: number | undefined; readonly entries = new Signal([]); /** Whether a live claim reads the estimate; see {@link reserved}. */ readonly reserved = new Signal(false); @@ -208,8 +217,9 @@ class Divider { #version = 0; #division: Division | undefined; - constructor(estimate?: Getter) { + constructor(estimate?: Getter, limit?: number) { this.#estimate = estimate; + this.#limit = limit; this.#registry = { peek: (id) => this.#peek(id), @@ -246,6 +256,8 @@ class Divider { max = ceiling(max); this.#prune(); + if (this.#limit !== undefined && this.#alive.peek()) this.#fits([...this.entries.peek(), { max }]); + const id = this.#nextId++; const rate = new Signal(undefined); // A closed registry hands back an inert reservation, so its target stays zero. @@ -327,9 +339,20 @@ class Divider { return shareOf(this.#plan(estimate, entries), entry); } + /** Throw when `entries`' ceilings sum above the limit. */ + #fits(entries: readonly { max: number }[]): void { + const sum = total(entries); + if (sum > (this.#limit ?? Number.POSITIVE_INFINITY)) { + throw new RangeError(`ceilings sum to ${sum}, above the limit of ${this.#limit}`); + } + } + #update(id: number, max: number): void { if (!this.#alive.peek()) return; max = ceiling(max); + if (this.#limit !== undefined) { + this.#fits(this.entries.peek().map((entry) => (entry.id === id ? { max } : entry))); + } this.#mutate((entries) => { const entry = entries.find((candidate) => candidate.id === id); if (entry) entry.max = max; @@ -471,6 +494,13 @@ export class Allocator implements Handle { * connection's receive estimate is what requests PROBE. */ export class Viewers { + /** + * The largest PROBE target: the most the viewers' ceilings, summed, or an override may be. + * + * `Number.MAX_SAFE_INTEGER` bits per second, the largest integer the PROBE stream encodes. + */ + static readonly MAX_TARGET = Number.MAX_SAFE_INTEGER; + #divider: Divider; #override = new Signal(undefined); @@ -482,13 +512,10 @@ export class Viewers { /** Divide `estimate`, normally a connection's receive estimate from PROBE. */ constructor(estimate?: Getter) { - this.#divider = new Divider(estimate); - this.target = new Derived([this.#divider.entries, this.#override], (entries, override) => { - if (override !== undefined) return override; - let sum = 0; - for (const entry of entries) sum += entry.max; - return sum; - }); + this.#divider = new Divider(estimate, Viewers.MAX_TARGET); + this.target = new Derived([this.#divider.entries, this.#override], (entries, override) => + override !== undefined ? override : total(entries), + ); } /** @@ -498,6 +525,8 @@ export class Viewers { * not what it happens to be receiving. The claim lasts until {@link Viewer.close}: * change the ceiling with {@link Viewer.update}, and close it once the broadcast * stops being watched. + * + * @throws {RangeError} watching nothing, when the ceilings would sum above {@link Viewers.MAX_TARGET}. */ watch(max: number): Viewer { return makeViewer(this.#divider.claim(undefined, 0, max)); @@ -506,10 +535,15 @@ export class Viewers { /** * Send `target` as the PROBE target instead of the viewers' sum, or `undefined` to follow them again. * - * `0` turns probing off: the connection sends no target. + * `0` sends no target, so the peer stops probing for these viewers. + * + * @throws {RangeError} keeping the previous override, for a target above {@link Viewers.MAX_TARGET}. */ setTarget(target: number | undefined): void { - this.#override.set(target === undefined ? undefined : ceiling(target)); + if (target !== undefined && ceiling(target) > Viewers.MAX_TARGET) { + throw new RangeError(`PROBE target ${target} is above the limit of ${Viewers.MAX_TARGET}`); + } + this.#override.set(target); } /** Stop dividing. Existing viewers report `undefined` and release their claims. */ @@ -551,7 +585,11 @@ export class Viewer implements Disposable { return this.#reservation.rate; } - /** Change the ceiling, keeping the same claim, as when a catalog enables or disables a rendition. */ + /** + * Change the ceiling, keeping the same claim, as when a catalog enables or disables a rendition. + * + * @throws {RangeError} keeping the previous ceiling, when the ceilings would sum above {@link Viewers.MAX_TARGET}. + */ update(max: number): void { this.#reservation.update(max); } diff --git a/kt/moq-ffi/MIGRATE.md b/kt/moq-ffi/MIGRATE.md index 9525d9ce6a6..2f15dab034f 100644 --- a/kt/moq-ffi/MIGRATE.md +++ b/kt/moq-ffi/MIGRATE.md @@ -2,6 +2,10 @@ ## Unreleased +### Viewer targets are bounded ([#7090](https://github.com/moq-dev/moq/pull/7090)) + +Viewer ceilings and PROBE target overrides are refused with the new `MoqException.OutOfRange` once they would sum above 2^53 - 1 bps, the most a PROBE target carries; nothing changes on a refusal. `MoqViewers.watch` and `setTarget` and `MoqViewer.update` throw it. Handle the new variant wherever you match the error exhaustively. Regenerate bindings and rebuild the matching native library together. + ### Media setup refusals are typed Audio and video subscribe setup now reports `MoqException.UnsupportedConfig` when the decoder refuses a codec, layout, or description. Handle this variant to try another rendition instead of inspecting an audio/video error message or `Unsupported`. Decoder faults, such as a backend that fails to open, and later peer and decode failures keep their existing errors. Regenerate bindings and rebuild the matching native library together. diff --git a/kt/moq/MIGRATE.md b/kt/moq/MIGRATE.md index cef72975bb2..886456f825a 100644 --- a/kt/moq/MIGRATE.md +++ b/kt/moq/MIGRATE.md @@ -4,6 +4,10 @@ How to update your code for each breaking change, newest first. ## Unreleased +### Viewer targets are bounded ([#7090](https://github.com/moq-dev/moq/pull/7090)) + +Viewer ceilings and PROBE target overrides are refused with the new `MoqException.OutOfRange` once they would sum above 2^53 - 1 bps, the most a PROBE target carries; nothing changes on a refusal. `Viewers.watch` and `setTarget` and `Viewer.update` throw it. Handle the new variant wherever you match the error exhaustively. Regenerate bindings and rebuild the matching native library together. + ### Media setup refusals are typed Audio and video subscribe setup now reports `MoqException.UnsupportedConfig` when the decoder refuses a codec, layout, or description. Handle this variant to try another rendition instead of inspecting an audio/video error message or `Unsupported`. Decoder faults, such as a backend that fails to open, and later peer and decode failures keep their existing errors. Regenerate bindings and rebuild the matching native library together. diff --git a/kt/moq/src/jvmAndAndroidTest/kotlin/dev/moq/SmokeTest.kt b/kt/moq/src/jvmAndAndroidTest/kotlin/dev/moq/SmokeTest.kt index 7bc2fbd3799..31b6c21613a 100644 --- a/kt/moq/src/jvmAndAndroidTest/kotlin/dev/moq/SmokeTest.kt +++ b/kt/moq/src/jvmAndAndroidTest/kotlin/dev/moq/SmokeTest.kt @@ -702,6 +702,8 @@ class SmokeTest { } viewers.setTarget(0uL) viewers.setTarget(null) + // Past what a PROBE target carries: refused. + assertFailsWith { viewers.watch(1uL shl 53) } } } } diff --git a/py/moq-ffi/MIGRATE.md b/py/moq-ffi/MIGRATE.md index 042afc06407..ab1806ded62 100644 --- a/py/moq-ffi/MIGRATE.md +++ b/py/moq-ffi/MIGRATE.md @@ -2,6 +2,10 @@ ## Unreleased +### Viewer targets are bounded ([#7090](https://github.com/moq-dev/moq/pull/7090)) + +Viewer ceilings and PROBE target overrides are refused with the new `MoqError.OutOfRange` once they would sum above 2^53 - 1 bps, the most a PROBE target carries; nothing changes on a refusal. `MoqViewers.watch` and `set_target` and `MoqViewer.update` raise it. Handle the new variant wherever you match the error exhaustively. Regenerate bindings and rebuild the matching native library together. + ### Media setup refusals are typed Audio and video subscribe setup now reports `UnsupportedConfig` when the decoder refuses a codec, layout, or description. Handle this variant to try another rendition instead of inspecting an audio/video error message or `Unsupported`. Decoder faults, such as a backend that fails to open, and later peer and decode failures keep their existing errors. Regenerate bindings and rebuild the matching native library together. diff --git a/py/moq-rs/MIGRATE.md b/py/moq-rs/MIGRATE.md index a85cd9a2c75..a607e133781 100644 --- a/py/moq-rs/MIGRATE.md +++ b/py/moq-rs/MIGRATE.md @@ -4,6 +4,10 @@ How to update your code for each breaking change, newest first. ## Unreleased +### Viewer targets are bounded ([#7090](https://github.com/moq-dev/moq/pull/7090)) + +Viewer ceilings and PROBE target overrides are refused with the new `moq.Error.OutOfRange` once they would sum above 2^53 - 1 bps, the most a PROBE target carries; nothing changes on a refusal. `Viewers.watch` and `set_target` and `Viewer.update` raise it. Handle the new variant wherever you match the error exhaustively. Regenerate bindings and rebuild the matching native library together. + ### Media setup refusals are typed Audio and video subscribe setup now reports `UnsupportedConfig` when the decoder refuses a codec, layout, or description. Handle this variant to try another rendition instead of inspecting an audio/video error message or `Unsupported`. Decoder faults, such as a backend that fails to open, and later peer and decode failures keep their existing errors. Regenerate bindings and rebuild the matching native library together. diff --git a/py/moq-rs/moq/session.py b/py/moq-rs/moq/session.py index 3fff8a20b65..67f1b7ee2ab 100644 --- a/py/moq-rs/moq/session.py +++ b/py/moq-rs/moq/session.py @@ -299,14 +299,17 @@ def watch(self, max_bps: int) -> Viewer: ``max_bps`` is a ceiling: what the largest rendition the player would switch to needs, not what it is receiving. Drop the viewer once the broadcast stops being watched. Holding one requests the receive - estimate, like :meth:`Session.recv_bandwidth`. + estimate, like :meth:`Session.recv_bandwidth`. Raises + ``moq.Error.OutOfRange``, watching nothing, when the ceilings would sum + above ``2**53 - 1``. """ return Viewer(self._inner.watch(max_bps)) def set_target(self, target_bps: int | None) -> None: """Send ``target_bps`` as the PROBE target instead of the viewers' sum. - ``None`` follows the viewers again, and ``0`` sends no target. + ``None`` follows the viewers again, and ``0`` sends no target. Raises + ``moq.Error.OutOfRange``, keeping the previous override, above ``2**53 - 1``. """ self._inner.set_target(target_bps) @@ -326,7 +329,11 @@ def rate(self) -> int | None: return self._inner.rate() def update(self, max_bps: int) -> None: - """Change the ceiling, keeping the same claim.""" + """Change the ceiling, keeping the same claim. + + Raises ``moq.Error.OutOfRange``, keeping the previous ceiling, when the + ceilings would sum above ``2**53 - 1``. + """ self._inner.update(max_bps) diff --git a/py/moq-rs/tests/test_server.py b/py/moq-rs/tests/test_server.py index 2389a87d2c9..1deab09e91d 100644 --- a/py/moq-rs/tests/test_server.py +++ b/py/moq-rs/tests/test_server.py @@ -234,6 +234,11 @@ async def test_viewer_holds_without_an_estimate(): viewers.set_target(0) viewers.set_target(None) assert viewer.rate() is None + # Past what a PROBE target carries: refused. + with pytest.raises(moq.Error.OutOfRange): + viewers.watch(2**53) + with pytest.raises(moq.Error.OutOfRange): + viewers.set_target(2**53) session.cancel(0) diff --git a/rs/moq-c/src/bandwidth.rs b/rs/moq-c/src/bandwidth.rs index 8317e12874f..19a1d2170ca 100644 --- a/rs/moq-c/src/bandwidth.rs +++ b/rs/moq-c/src/bandwidth.rs @@ -176,7 +176,8 @@ pub extern "C" fn moq_viewers_close(viewers: u32) -> i32 { /// `max_bps` is a ceiling: what the largest rendition you would switch to needs, not /// what you are receiving. Holding the viewer requests the receive estimate, like a /// [`moq_session_recv_bandwidth`] consumer. Close it with [`moq_viewer_close`] once the -/// broadcast stops being watched. +/// broadcast stops being watched. Returns [`MOQ_ERROR_OUT_OF_RANGE`](crate::MOQ_ERROR_OUT_OF_RANGE), +/// watching nothing, when the ceilings would sum above `2^53 - 1`. #[unsafe(no_mangle)] pub extern "C" fn moq_viewers_watch(viewers: u32, max_bps: u64) -> i32 { ffi::enter(move || { @@ -187,7 +188,8 @@ pub extern "C" fn moq_viewers_watch(viewers: u32, max_bps: u64) -> i32 { .viewers .get(viewers) .ok_or(Error::NotFound)? - .watch(moq_net::bandwidth::Rate::from_bps(max_bps)); + .watch(moq_net::bandwidth::Rate::from_bps(max_bps)) + .map_err(out_of_range)?; state.bandwidth.viewer.insert(viewer) }) } @@ -195,7 +197,8 @@ pub extern "C" fn moq_viewers_watch(viewers: u32, max_bps: u64) -> i32 { /// Send `target_bps` as the PROBE target instead of the viewers' sum. /// /// `present` false follows the viewers again. `present` true and `target_bps` 0 sends -/// no target. +/// no target. Returns [`MOQ_ERROR_OUT_OF_RANGE`](crate::MOQ_ERROR_OUT_OF_RANGE), keeping the +/// previous override, for a target above `2^53 - 1`. #[unsafe(no_mangle)] pub extern "C" fn moq_viewers_set_target(viewers: u32, target_bps: u64, present: bool) -> i32 { ffi::enter(move || { @@ -205,8 +208,8 @@ pub extern "C" fn moq_viewers_set_target(viewers: u32, target_bps: u64, present: .viewers .get(viewers) .ok_or(Error::NotFound)? - .set_target(present.then(|| moq_net::bandwidth::Rate::from_bps(target_bps))); - Ok(()) + .set_target(present.then(|| moq_net::bandwidth::Rate::from_bps(target_bps))) + .map_err(out_of_range) }) } @@ -236,6 +239,9 @@ pub unsafe extern "C" fn moq_viewer_rate(viewer: u32, bps: *mut u64, present: *m } /// Change the viewer's ceiling, keeping the same claim. +/// +/// Returns [`MOQ_ERROR_OUT_OF_RANGE`](crate::MOQ_ERROR_OUT_OF_RANGE), keeping the previous +/// ceiling, when the ceilings would sum above `2^53 - 1`. #[unsafe(no_mangle)] pub extern "C" fn moq_viewer_update(viewer: u32, max_bps: u64) -> i32 { ffi::enter(move || { @@ -245,11 +251,19 @@ pub extern "C" fn moq_viewer_update(viewer: u32, max_bps: u64) -> i32 { .viewer .get(viewer) .ok_or(Error::NotFound)? - .update(moq_net::bandwidth::Rate::from_bps(max_bps)); - Ok(()) + .update(moq_net::bandwidth::Rate::from_bps(max_bps)) + .map_err(out_of_range) }) } +/// A viewer ceiling or target refused for passing the PROBE target's limit. +fn out_of_range(err: moq_net::Error) -> Error { + Error::OutOfRange(format!( + "{err}: viewer targets sum to at most {} bps", + moq_net::bandwidth::Viewers::MAX_TARGET.as_bps() + )) +} + /// Release a viewer, handing its share back to the others and lowering the PROBE target. #[unsafe(no_mangle)] pub extern "C" fn moq_viewer_close(viewer: u32) -> i32 { diff --git a/rs/moq-c/src/error.rs b/rs/moq-c/src/error.rs index f9a59d5ea19..6aa26d80431 100644 --- a/rs/moq-c/src/error.rs +++ b/rs/moq-c/src/error.rs @@ -84,6 +84,8 @@ pub const MOQ_ERROR_EXPIRED: i32 = -42; pub const MOQ_ERROR_UNSUPPORTED_CATALOG: i32 = -43; /// The rendition's codec, layout, or description was refused during setup; another rendition may work. pub const MOQ_ERROR_UNSUPPORTED_CONFIG: i32 = -44; +/// A number is outside the range the call accepts. +pub const MOQ_ERROR_OUT_OF_RANGE: i32 = -45; /// Whether a protocol code is from the session or stream registry. #[repr(C)] @@ -347,6 +349,11 @@ pub enum Error { /// resolved through an origin, so there is nothing to resolve the reference against. #[error("unresolvable broadcast reference: {0}")] UnresolvableBroadcast(String), + + /// A number was outside the range the call accepts, such as viewer ceilings summing + /// above what a PROBE target carries. + #[error("out of range: {0}")] + OutOfRange(String), } impl From for Error { @@ -538,6 +545,7 @@ impl ffi::ReturnCode for Error { Error::JsonTrack(_) => MOQ_ERROR_JSON_TRACK, Error::InvalidConfig(_) => MOQ_ERROR_INVALID_CONFIG, Error::UnresolvableBroadcast(_) => MOQ_ERROR_UNRESOLVABLE_BROADCAST, + Error::OutOfRange(_) => MOQ_ERROR_OUT_OF_RANGE, } } } diff --git a/rs/moq-c/src/test.rs b/rs/moq-c/src/test.rs index cb44288b7f0..d962a8bc590 100644 --- a/rs/moq-c/src/test.rs +++ b/rs/moq-c/src/test.rs @@ -7073,6 +7073,13 @@ fn viewers_split_the_receive_estimate() { assert_eq!(moq_viewers_set_target(viewers, 0, true), 0); assert_eq!(moq_viewers_set_target(viewers, 0, false), 0); + // Past what a PROBE target carries: refused, and nothing changes. + let max = moq_net::bandwidth::Viewers::MAX_TARGET.as_bps(); + assert_eq!(moq_viewers_watch(viewers, max), crate::MOQ_ERROR_OUT_OF_RANGE); + assert_eq!(moq_viewer_update(second, max), crate::MOQ_ERROR_OUT_OF_RANGE); + assert_eq!(moq_viewers_set_target(viewers, max + 1, true), crate::MOQ_ERROR_OUT_OF_RANGE); + assert_eq!(viewer_rate(first), Some(1_500_000)); + assert_eq!(moq_viewer_close(second), 0); assert_eq!(viewer_rate(first), Some(3_000_000)); assert_eq!(moq_viewer_close(first), 0); diff --git a/rs/moq-ffi/CHANGELOG.md b/rs/moq-ffi/CHANGELOG.md index e1f58ea3fba..517f618517b 100644 --- a/rs/moq-ffi/CHANGELOG.md +++ b/rs/moq-ffi/CHANGELOG.md @@ -12,6 +12,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - `MoqSession::viewers` returns a `MoqViewers` that divides the receive estimate among watched broadcasts: `MoqViewers::watch` returns a `MoqViewer` reading its slice, and the viewers' ceilings summed are the PROBE target sent to the peer. + Ceilings or a target past 2^53 - 1 bps are refused with the new + `MoqError::OutOfRange`. - `MoqAudioEncoder::track_init` returns the init that publishes its packets, and `MoqAudioEncoder::set_bitrate` retunes it live. - `MoqAudioDecoderOutput::delay_us` fixes the audio playout delay, and diff --git a/rs/moq-ffi/MIGRATE.md b/rs/moq-ffi/MIGRATE.md index b28fde7454e..c6146df3bb1 100644 --- a/rs/moq-ffi/MIGRATE.md +++ b/rs/moq-ffi/MIGRATE.md @@ -5,6 +5,10 @@ These are the UniFFI names; each language wrapper has its own `MIGRATE.md` in it ## Unreleased +### Viewer targets are bounded ([#7090](https://github.com/moq-dev/moq/pull/7090)) + +Viewer ceilings and PROBE target overrides are refused with the new `MoqError::OutOfRange` once they would sum above 2^53 - 1 bps, the most a PROBE target carries; nothing changes on a refusal. `MoqViewers::watch` and `set_target` and `MoqViewer::update` return a `Result`. Handle the new variant wherever you match the error exhaustively. Regenerate bindings and rebuild the matching native library together. + ### Media setup refusals are typed Audio and video subscribe setup now reports `UnsupportedConfig` when the decoder refuses a codec, layout, or description. Handle this variant to try another rendition instead of inspecting an audio/video error message or `Unsupported`. Decoder faults, such as a backend that fails to open, and later peer and decode failures keep their existing errors. Regenerate bindings and rebuild the matching native library together. diff --git a/rs/moq-ffi/src/bandwidth.rs b/rs/moq-ffi/src/bandwidth.rs index 9630399ce3d..4e35614e33e 100644 --- a/rs/moq-ffi/src/bandwidth.rs +++ b/rs/moq-ffi/src/bandwidth.rs @@ -113,19 +113,38 @@ impl MoqViewers { /// needs, not what it is receiving. The claim lasts as long as the returned handle; /// drop it once the broadcast stops being watched. Holding one requests the receive /// estimate, like [`MoqSession::recv_bandwidth`](crate::session::MoqSession::recv_bandwidth). - pub fn watch(&self, max_bps: u64) -> Arc { + /// + /// Errors with [`MoqError::OutOfRange`], watching nothing, when the ceilings would sum + /// above [`moq_net::bandwidth::Viewers::MAX_TARGET`] (`2^53 - 1`). + pub fn watch(&self, max_bps: u64) -> Result, MoqError> { let _guard = crate::ffi::enter(); - Arc::new(MoqViewer { - inner: self.inner.watch(moq_net::bandwidth::Rate::from_bps(max_bps)), - }) + let inner = self + .inner + .watch(moq_net::bandwidth::Rate::from_bps(max_bps)) + .map_err(out_of_range)?; + Ok(Arc::new(MoqViewer { inner })) } /// Send `target_bps` as the PROBE target instead of the viewers' sum, or `None` to /// follow them again. `Some(0)` sends no target. - pub fn set_target(&self, target_bps: Option) { + /// + /// Errors with [`MoqError::OutOfRange`], keeping the previous override, for a target + /// above `2^53 - 1`. + pub fn set_target(&self, target_bps: Option) -> Result<(), MoqError> { let _guard = crate::ffi::enter(); self.inner - .set_target(target_bps.map(moq_net::bandwidth::Rate::from_bps)); + .set_target(target_bps.map(moq_net::bandwidth::Rate::from_bps)) + .map_err(out_of_range) + } +} + +/// A viewer ceiling or target refused for passing the PROBE target's limit. +fn out_of_range(err: moq_net::Error) -> MoqError { + MoqError::OutOfRange { + reason: format!( + "{err}: viewer targets sum to at most {} bps", + moq_net::bandwidth::Viewers::MAX_TARGET.as_bps() + ), } } @@ -149,9 +168,14 @@ impl MoqViewer { } /// Change the ceiling, keeping the same claim. - pub fn update(&self, max_bps: u64) { + /// + /// Errors with [`MoqError::OutOfRange`], keeping the previous ceiling, when the + /// ceilings would sum above `2^53 - 1`. + pub fn update(&self, max_bps: u64) -> Result<(), MoqError> { let _guard = crate::ffi::enter(); - self.inner.update(moq_net::bandwidth::Rate::from_bps(max_bps)); + self.inner + .update(moq_net::bandwidth::Rate::from_bps(max_bps)) + .map_err(out_of_range) } } @@ -354,8 +378,8 @@ mod tests { let estimate = moq_net::bandwidth::Producer::new(); let viewers = MoqViewers::new(moq_net::bandwidth::Viewers::new(estimate.weak())); - let first = viewers.watch(4_000_000); - let second = viewers.watch(1_000_000); + let first = viewers.watch(4_000_000).unwrap(); + let second = viewers.watch(1_000_000).unwrap(); assert_eq!(first.rate(), None); estimate @@ -364,13 +388,28 @@ mod tests { assert_eq!(first.rate(), Some(2_000_000)); assert_eq!(second.rate(), Some(1_000_000)); - second.update(4_000_000); + second.update(4_000_000).unwrap(); assert_eq!(first.rate(), Some(1_500_000)); drop(second); assert_eq!(first.rate(), Some(3_000_000)); } + /// Ceilings and overrides past what a PROBE target carries are refused as out of range. + #[test] + fn viewer_targets_past_the_limit_are_out_of_range() { + let viewers = MoqViewers::new(moq_net::bandwidth::Viewers::default()); + let max = moq_net::bandwidth::Viewers::MAX_TARGET.as_bps(); + let refused = |res: Result<(), MoqError>| matches!(res, Err(MoqError::OutOfRange { .. })); + + assert!(refused(viewers.watch(u64::MAX).map(drop))); + let viewer = viewers.watch(max).unwrap(); + assert!(refused(viewers.watch(1).map(drop))); + assert!(refused(viewer.update(max + 1))); + assert!(refused(viewers.set_target(Some(max + 1)))); + viewers.set_target(Some(max)).unwrap(); + } + /// A rung follows its reservation's grant down, but never disables while no session /// probes for it, since nothing could then raise the grant to resume it. A missing /// grant holds the target. diff --git a/rs/moq-ffi/src/error.rs b/rs/moq-ffi/src/error.rs index 096ac68e331..96ad7ffe6a2 100644 --- a/rs/moq-ffi/src/error.rs +++ b/rs/moq-ffi/src/error.rs @@ -408,6 +408,13 @@ pub enum MoqError { /// A diagnostic message describing the refusal. reason: String, }, + /// A number was outside the range the call accepts, such as viewer ceilings summing + /// above what a PROBE target carries. + #[error("out of range: {reason}")] + OutOfRange { + /// A diagnostic message describing the refusal. + reason: String, + }, } impl From for MoqError { diff --git a/rs/moq-net/MIGRATE.md b/rs/moq-net/MIGRATE.md index 9409ae7227c..e99587877e6 100644 --- a/rs/moq-net/MIGRATE.md +++ b/rs/moq-net/MIGRATE.md @@ -4,6 +4,11 @@ How to update your code for each breaking change, newest first. ## Unreleased +### A zero `Allocator::set_target` leaves the peer's PROBE target ([#7090](https://github.com/moq-dev/moq/pull/7090)) + +A session with a sender now probes to the larger of its allocator's target and the PROBE target its peer sends, so `Allocator::set_target(Some(Rate::ZERO))` stops probing for this side's reservations only. A peer that advertises a target still raises the probe; a reservation's `Consumer::probed` stays `false`, since nothing probes for it. +The new `Viewers::watch`, `Viewers::set_target`, and `Viewer::update` return `Result` and refuse ceilings summing above `Viewers::MAX_TARGET` with `Error::BoundsExceeded`. + ### `group::on_track` is `track::Info::rescale` ([#7702](https://github.com/moq-dev/moq/pull/7702)) The free function `moq_net::group::on_track(timestamp, timescale)` is removed. diff --git a/rs/moq-net/benches/bandwidth.rs b/rs/moq-net/benches/bandwidth.rs index 1b7429c6abb..0904c0bbbb0 100644 --- a/rs/moq-net/benches/bandwidth.rs +++ b/rs/moq-net/benches/bandwidth.rs @@ -72,14 +72,16 @@ fn bench_viewers(c: &mut Criterion) { for count in RESERVATIONS { group.bench_function(BenchmarkId::from_parameter(count), |b| { let viewers = Viewers::default(); - let watched: Vec<_> = (0..count).map(|_| viewers.watch(Rate::from_kbps(1_000))).collect(); + let watched: Vec<_> = (0..count).map(|_| viewers.watch(Rate::from_kbps(1_000)).expect("within the limit")).collect(); let mut target = fuzz::ProbeTarget::viewers(&viewers); target.poll().expect("the first poll reports the target"); let touched = &watched[count / 2]; let mut raised = false; b.iter(|| { raised = !raised; - touched.update(Rate::from_kbps(if raised { 2_000 } else { 1_000 })); + touched + .update(Rate::from_kbps(if raised { 2_000 } else { 1_000 })) + .expect("within the limit"); std::hint::black_box(target.poll().expect("the target moved")); }); }); diff --git a/rs/moq-net/src/model/bandwidth.rs b/rs/moq-net/src/model/bandwidth.rs index 64e313dca7f..14997098b5f 100644 --- a/rs/moq-net/src/model/bandwidth.rs +++ b/rs/moq-net/src/model/bandwidth.rs @@ -25,7 +25,7 @@ use std::{ task::{Poll, Wake, Waker}, }; -use crate::{Error, Result, track}; +use crate::{BoundsExceeded, Error, Result, track}; /// A rate, in bits per second. /// @@ -267,15 +267,26 @@ impl Allocator { /// Probe up to `target` instead of the sum of the reservations, or `None` to follow them again. /// - /// `Some(Rate::ZERO)` turns probing off. The override is the registry's, so it holds - /// for every clone and across the reconnects a persistent allocator spans. + /// The override covers these reservations only: `Some(Rate::ZERO)` stops probing for + /// them, but a session still probes up to the PROBE target its peer sends, since it + /// probes to the larger of the two. The override is the registry's, so it holds for + /// every clone and across the reconnects a persistent allocator spans. pub fn set_target(&self, target: Option) { + if self.retarget(target).is_err() { + unreachable!("an allocator's registry has no limit") + } + } + + /// Override the target, refusing one above the registry's limit. + fn retarget(&self, target: Option) -> Result<()> { let Ok(mut registry) = self.registry.write() else { unreachable!("the allocator holds its own registry producer") }; + registry.fits(target.map_or(0, |target| u128::from(target.as_bps())))?; if registry.target != target { registry.target = target; } + Ok(()) } /// Follow the probe target, for the session that probes on the reservations' behalf. @@ -352,11 +363,23 @@ impl Allocator { pub fn reserve(&self, track: &track::Demand, max: Rate) -> Reservation { // Read the track before taking the registry lock, so the two are never held // at once and there's no order to get wrong. - self.claim(self.estimate.clone(), Some(track.clone()), track.priority(), max) + let claimed = self.claim(self.estimate.clone(), Some(track.clone()), track.priority(), max); + let Ok(reservation) = claimed else { + unreachable!("an allocator's registry has no limit") + }; + reservation } /// Claim up to `max` of `estimate`, active whenever `demand` is, or always without one. - fn claim(&self, estimate: Consumer, demand: Option, priority: i8, max: Rate) -> Reservation { + /// + /// Errors without claiming when the ceilings would sum above the registry's limit. + fn claim( + &self, + estimate: Consumer, + demand: Option, + priority: i8, + max: Rate, + ) -> Result { let (id, grants) = { // Nothing ever closes this channel: the allocator holds the only producer // and never aborts it, so it's open for as long as `self` is. @@ -374,6 +397,7 @@ impl Allocator { for id in closed { registry.remove(id); } + registry.fits(registry.reserved + u128::from(max.as_bps()))?; let id = registry.next_id; registry.next_id += 1; @@ -383,7 +407,7 @@ impl Allocator { (id, registry.grants.clone()) }; - Reservation { + Ok(Reservation { share: Share { estimate, registry: self.registry.consume(), @@ -391,7 +415,7 @@ impl Allocator { id, }, registry: self.registry.downgrade(), - } + }) } } @@ -441,18 +465,28 @@ impl Reservation { /// Does nothing once every [`Allocator`] is gone, since there is then nothing left /// dividing anything; a reader learns that from its [`consumer`](Self::consume). pub fn update(&self, max: Rate) { + if self.resize(max).is_err() { + unreachable!("an allocator's registry has no limit") + } + } + + /// Change the ceiling, refusing one that would sum above the registry's limit. + fn resize(&self, max: Rate) -> Result<()> { let Some(registry) = self.registry.upgrade() else { - return; + return Ok(()); }; let Ok(mut registry) = registry.write() else { - return; + return Ok(()); }; let registry = &mut *registry; if let Some(entry) = registry.entries.get_mut(&self.share.id) { - registry.reserved = registry.reserved - u128::from(entry.max.as_bps()) + u128::from(max.as_bps()); + let reserved = registry.reserved - u128::from(entry.max.as_bps()) + u128::from(max.as_bps()); + within(registry.limit, reserved)?; + registry.reserved = reserved; registry.generation += 1; entry.max = max; } + Ok(()) } } @@ -501,11 +535,15 @@ impl std::fmt::Debug for Allocator { /// estimate can rise to fund a larger rendition. The target never leaves this hop: /// a relay probes its own downlink for its viewers, and never forwards them upstream. /// +/// The ceilings may sum to at most [`MAX_TARGET`](Self::MAX_TARGET), which every PROBE +/// encoding carries: a viewer or override that would pass it is refused with +/// [`Error::BoundsExceeded`]. +/// /// Holding a [`Viewer`] (or a [`Consumer`] read from one) requests PROBE, like /// holding `Session::recv_bandwidth`. Take it from `Session::viewers` (with the /// `async` feature) rather than building one, since only a session sends the target. /// Clones share one registry. -#[derive(Clone, Default)] +#[derive(Clone)] pub struct Viewers { /// The registry, whose own estimate is unused: each viewer reads one minted from /// `estimate`, so holding the registry is not demand. @@ -515,6 +553,12 @@ pub struct Viewers { } impl Viewers { + /// The largest PROBE target: the most the viewers' ceilings, summed, or an override may be. + /// + /// `2^53 - 1` bits per second, the largest integer a JavaScript peer decodes exactly, + /// and well inside the wire's varint. + pub const MAX_TARGET: Rate = Rate::from_bps((1 << 53) - 1); + /// Divide the receive estimate `estimate` mints, with no session sending the target. /// /// For an estimate that outlives a session, such as one a reconnect loop feeds @@ -522,8 +566,8 @@ impl Viewers { /// (with the `async` feature) so every session it dials sends the target. pub fn new(estimate: Weak) -> Self { Self { - registry: Allocator::unlimited(), estimate: Some(estimate), + ..Self::default() } } @@ -542,7 +586,12 @@ impl Viewers { /// needs, not what it happens to be receiving. The claim lasts as long as the /// returned [`Viewer`]: change the ceiling with [`update`](Viewer::update), and drop /// it once the broadcast stops being watched. - pub fn watch(&self, max: Rate) -> Viewer { + /// + /// # Errors + /// + /// [`Error::BoundsExceeded`], watching nothing, when the ceilings would sum above + /// [`MAX_TARGET`](Self::MAX_TARGET). + pub fn watch(&self, max: Rate) -> Result { let estimate = match &self.estimate { Some(estimate) => estimate.consume(), None => Consumer { @@ -551,16 +600,21 @@ impl Viewers { probed: false, }, }; - Viewer(self.registry.claim(estimate, None, 0, max)) + Ok(Viewer(self.registry.claim(estimate, None, 0, max)?)) } /// Send `target` as the PROBE target instead of the viewers' sum, or `None` to follow them again. /// - /// `Some(Rate::ZERO)` turns probing off: the session sends no target. The override is - /// the registry's, so it holds for every clone and across the reconnects a persistent - /// registry spans. - pub fn set_target(&self, target: Option) { - self.registry.set_target(target); + /// `Some(Rate::ZERO)` sends no target, so the peer stops probing for these viewers. The + /// override is the registry's, so it holds for every clone and across the reconnects a + /// persistent registry spans. + /// + /// # Errors + /// + /// [`Error::BoundsExceeded`], keeping the previous override, for a target above + /// [`MAX_TARGET`](Self::MAX_TARGET). + pub fn set_target(&self, target: Option) -> Result<()> { + self.registry.retarget(target) } /// Follow the PROBE target, for the session that sends it to a peer that probes up to it. @@ -572,6 +626,20 @@ impl Viewers { } } +/// No receive estimate to divide, with the PROBE target's limit. +impl Default for Viewers { + fn default() -> Self { + let registry = Allocator::unlimited(); + if let Ok(mut state) = registry.registry.write() { + state.limit = Some(Self::MAX_TARGET); + } + Self { + registry, + estimate: None, + } + } +} + // Hand-written so the config structs that carry a registry can still derive `Debug`. impl std::fmt::Debug for Viewers { fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { @@ -605,8 +673,13 @@ impl Viewer { } /// Change the ceiling, keeping the same claim, as when a catalog enables or disables a rendition. - pub fn update(&self, max: Rate) { - self.0.update(max); + /// + /// # Errors + /// + /// [`Error::BoundsExceeded`], keeping the previous ceiling, when the ceilings would + /// sum above [`Viewers::MAX_TARGET`]. + pub fn update(&self, max: Rate) -> Result<()> { + self.0.resize(max) } } @@ -621,6 +694,8 @@ struct Registry { reserved: u128, /// The application's override of `reserved` as the probe target. target: Option, + /// The most `reserved` and `target` may each be, or `None` for no limit. + limit: Option, /// How many sessions probe for these reservations, each through its [`Target`]. probes: usize, /// Bumped whenever an entry is added, moved or removed, so a [`Plan`] knows the @@ -638,6 +713,11 @@ impl Registry { } } + /// Refuse `total` when it is above the registry's limit. + fn fits(&self, total: u128) -> Result<()> { + within(self.limit, total) + } + /// What the session probes up to. fn target(&self) -> Rate { self.target @@ -645,6 +725,14 @@ impl Registry { } } +/// Refuse `total` when it is above `limit`. +fn within(limit: Option, total: u128) -> Result<()> { + match limit { + Some(limit) if total > u128::from(limit.as_bps()) => Err(Error::BoundsExceeded(BoundsExceeded)), + _ => Ok(()), + } +} + /// One registered track's standing reservation. struct Entry { /// The track whose demand gates the claim, or `None` for a claim that is always active. @@ -728,8 +816,9 @@ impl Share { self.grants.grant(&self.registry, estimate, self.id) } - /// Whether a session probes for this share's registry, toward a target above zero, - /// which turns probing off. + /// Whether a session probes for this share's registry, toward a target above zero. + /// A zero target stops probing for these claims, though the session may still probe + /// for its peer's target. fn probed(&self) -> bool { let registry = self.registry.read(); registry.probes > 0 && registry.target() > Rate::ZERO @@ -1058,9 +1147,9 @@ impl Consumer { /// Whether a session probes the connection for this slice's reservation, so the /// estimate can rise to fund it even while its sender is stopped. /// - /// Only a session whose transport has a sender probes, and none does while - /// [`Allocator::set_target`] turns probing off. For a [`Viewer`]'s slice, whether - /// the session asks a peer that advertised `Increase` to probe for it, which + /// Only a session whose transport has a sender probes, and none does for it while + /// [`Allocator::set_target`] overrides the target to zero. For a [`Viewer`]'s slice, + /// whether the session asks a peer that advertised `Increase` to probe for it, which /// [`Viewers::set_target`] can turn off the same way. Without one the estimate /// stops learning once the connection is app-limited, so a sender that stops for /// lack of bandwidth could never see enough to resume. Always `false` for a whole @@ -1825,15 +1914,15 @@ mod tests { fn viewers_split_the_estimate_max_min_fair() { let estimate = Producer::new(); let viewers = Viewers::new(estimate.weak()); - let small = viewers.watch(bps(1_000_000)); - let large = viewers.watch(bps(8_000_000)); + let small = viewers.watch(bps(1_000_000)).unwrap(); + let large = viewers.watch(bps(8_000_000)).unwrap(); assert_eq!(small.rate(), None, "no estimate yet: hold the selection"); estimate.set(Some(bps(6_000_000))).unwrap(); assert_eq!(small.rate(), Some(bps(1_000_000))); assert_eq!(large.rate(), Some(bps(5_000_000))); - let third = viewers.watch(bps(4_000_000)); + let third = viewers.watch(bps(4_000_000)).unwrap(); let grants = [&small, &large, &third].map(|viewer| viewer.rate().unwrap()); assert_eq!(grants, [bps(1_000_000), bps(2_500_000), bps(2_500_000)]); assert!(grants.iter().map(|rate| rate.as_bps()).sum::() <= 6_000_000); @@ -1851,15 +1940,15 @@ mod tests { let waiter = kio::Waiter::noop(); assert_eq!(target.poll_changed(&waiter), Poll::Ready(Rate::ZERO)); - let first = viewers.watch(bps(3_000_000)); - let second = viewers.clone().watch(bps(2_000_000)); + let first = viewers.watch(bps(3_000_000)).unwrap(); + let second = viewers.clone().watch(bps(2_000_000)).unwrap(); assert_eq!(target.poll_changed(&waiter), Poll::Ready(bps(5_000_000))); - first.update(bps(1_000_000)); + first.update(bps(1_000_000)).unwrap(); assert_eq!(target.poll_changed(&waiter), Poll::Ready(bps(3_000_000))); - viewers.set_target(Some(Rate::ZERO)); + viewers.set_target(Some(Rate::ZERO)).unwrap(); assert_eq!(target.poll_changed(&waiter), Poll::Ready(Rate::ZERO)); - viewers.set_target(None); + viewers.set_target(None).unwrap(); assert_eq!(target.poll_changed(&waiter), Poll::Ready(bps(3_000_000))); drop(second); @@ -1868,6 +1957,35 @@ mod tests { assert_eq!(target.poll_changed(&waiter), Poll::Ready(Rate::ZERO)); } + /// The viewers' ceilings sum to at most what every PROBE encoding carries: a viewer, + /// update, or override past it is refused and leaves the target as it was. + #[test] + fn viewer_targets_stay_encodable() { + let viewers = Viewers::default(); + let mut target = viewers.target(); + let waiter = kio::Waiter::noop(); + let max = Viewers::MAX_TARGET.as_bps(); + let bounds = |res: Result<()>| matches!(res, Err(Error::BoundsExceeded(_))); + + assert!(bounds(viewers.watch(bps(max + 1)).map(drop))); + let first = viewers.watch(bps(max - 1)).unwrap(); + assert!(bounds(viewers.watch(bps(2)).map(drop)), "the sum would pass the limit"); + let second = viewers.watch(bps(1)).unwrap(); + assert_eq!(target.poll_changed(&waiter), Poll::Ready(Viewers::MAX_TARGET)); + + assert!(bounds(second.update(bps(2)))); + first.update(bps(1)).unwrap(); + assert_eq!(target.poll_changed(&waiter), Poll::Ready(bps(2))); + second.update(bps(max - 1)).unwrap(); + assert_eq!(target.poll_changed(&waiter), Poll::Ready(Viewers::MAX_TARGET)); + + viewers.set_target(Some(bps(1_000_000))).unwrap(); + assert!(bounds(viewers.set_target(Some(bps(max + 1))))); + assert_eq!(target.poll_changed(&waiter), Poll::Ready(bps(1_000_000))); + viewers.set_target(Some(Viewers::MAX_TARGET)).unwrap(); + assert_eq!(target.poll_changed(&waiter), Poll::Ready(Viewers::MAX_TARGET)); + } + /// A held viewer is what requests the receive estimate (and so PROBE); the registry /// alone is not, so a session holding one opens no PROBE stream. #[test] @@ -1876,7 +1994,7 @@ mod tests { let viewers = Viewers::new(estimate.weak()); assert!(!estimate.demand().wanted()); - let viewer = viewers.watch(bps(1_000_000)); + let viewer = viewers.watch(bps(1_000_000)).unwrap(); assert!(estimate.demand().wanted()); let grant = viewer.consume(); drop(viewer); diff --git a/rs/moq-net/tests/integration/viewer_target.rs b/rs/moq-net/tests/integration/viewer_target.rs index 4eb8cf3b03b..b8a22bc1140 100644 --- a/rs/moq-net/tests/integration/viewer_target.rs +++ b/rs/moq-net/tests/integration/viewer_target.rs @@ -51,11 +51,11 @@ async fn viewers_sum_into_the_peers_target() { let pair = pair(version, true).await; let viewers = pair.client.viewers(); - let first = viewers.watch(mbps(3)); + let first = viewers.watch(mbps(3)).unwrap(); probes_to(&pair.server_transport, mbps(3)).await; - let second = viewers.watch(mbps(2)); + let second = viewers.watch(mbps(2)).unwrap(); probes_to(&pair.server_transport, mbps(5)).await; - first.update(mbps(1)); + first.update(mbps(1)).unwrap(); probes_to(&pair.server_transport, mbps(3)).await; drop(second); @@ -74,15 +74,34 @@ async fn the_sender_probes_to_the_larger_target() { let reserved = pair.server.allocator().reserve(&track.demand(), mbps(4)); probes_to(&pair.server_transport, mbps(4)).await; - let viewer = pair.client.viewers().watch(mbps(6)); + let viewer = pair.client.viewers().watch(mbps(6)).unwrap(); probes_to(&pair.server_transport, mbps(6)).await; - viewer.update(mbps(2)); + viewer.update(mbps(2)).unwrap(); probes_to(&pair.server_transport, mbps(4)).await; drop(reserved); probes_to(&pair.server_transport, mbps(2)).await; } } +/// The sender's override covers its own reservations only: zeroing it stops probing +/// for them, while the peer's target still sets how high to probe. +#[moq_net::kio::test] +async fn a_local_override_leaves_the_peers_target() { + for version in VERSIONS { + let pair = pair(version, true).await; + let (_broadcast, track) = reservable(); + let allocator = pair.server.allocator(); + let reserved = allocator.reserve(&track.demand(), mbps(4)); + allocator.set_target(Some(Rate::ZERO)); + + let viewer = pair.client.viewers().watch(mbps(2)).unwrap(); + probes_to(&pair.server_transport, mbps(2)).await; + assert!(!reserved.consume().probed(), "{version}: nothing probes for the reservation"); + drop(viewer); + probes_to(&pair.server_transport, Rate::ZERO).await; + } +} + /// A session that publishes and watches probes its uplink for what it sends, never /// for what it watches, and its peer the other way around. #[moq_net::kio::test] @@ -91,7 +110,7 @@ async fn the_directions_stay_apart() { let pair = pair(version, true).await; let (_broadcast, track) = reservable(); let _sent = pair.client.allocator().reserve(&track.demand(), mbps(1)); - let _watched = pair.client.viewers().watch(mbps(6)); + let _watched = pair.client.viewers().watch(mbps(6)).unwrap(); probes_to(&pair.client_transport, mbps(1)).await; probes_to(&pair.server_transport, mbps(6)).await; @@ -106,8 +125,8 @@ async fn opting_out_sends_no_target() { for version in VERSIONS { let pair = pair(version, true).await; let viewers = pair.client.viewers(); - viewers.set_target(Some(Rate::ZERO)); - let viewer = viewers.watch(mbps(6)); + viewers.set_target(Some(Rate::ZERO)).unwrap(); + let viewer = viewers.watch(mbps(6)).unwrap(); let mut grant = viewer.consume(); // The estimate arrives, so the PROBE stream is up and the target would have too. assert_eq!(grant.changed().await.unwrap(), Some(mbps(6)), "{version}"); @@ -115,7 +134,7 @@ async fn opting_out_sends_no_target() { assert_eq!(pair.server_transport.probe_target(), Rate::ZERO, "{version}"); assert!(!grant.probed(), "{version}: opted out, nothing probes for it"); - viewers.set_target(None); + viewers.set_target(None).unwrap(); probes_to(&pair.server_transport, mbps(6)).await; assert!(grant.probed(), "{version}"); } @@ -126,7 +145,7 @@ async fn opting_out_sends_no_target() { async fn a_peer_without_a_sender_is_sent_no_target() { for version in VERSIONS { let pair = pair(version, false).await; - let viewer = pair.client.viewers().watch(mbps(6)); + let viewer = pair.client.viewers().watch(mbps(6)).unwrap(); let mut grant = viewer.consume(); assert_eq!(grant.changed().await.unwrap(), Some(mbps(6)), "{version}"); assert!(!grant.probed(), "{version}"); diff --git a/swift/MIGRATE.md b/swift/MIGRATE.md index de2bfe1db11..ae6cfa04ec6 100644 --- a/swift/MIGRATE.md +++ b/swift/MIGRATE.md @@ -4,6 +4,10 @@ How to update your code for each breaking change, newest first. ## Unreleased +### Viewer targets are bounded ([#7090](https://github.com/moq-dev/moq/pull/7090)) + +Viewer ceilings and PROBE target overrides are refused with the new `MoqError.OutOfRange` once they would sum above 2^53 - 1 bps, the most a PROBE target carries; nothing changes on a refusal. `Viewers.watch(maxBps:)` and `setTarget(targetBps:)` and `Viewer.update(maxBps:)` throw it, so call them with `try`. Handle the new variant wherever you match the error exhaustively. Regenerate bindings and rebuild the matching native library together. + ### Media setup refusals are typed Audio and video subscribe setup now reports `UnsupportedConfig` when the decoder refuses a codec, layout, or description. Handle this variant to try another rendition instead of inspecting an audio/video error message or `Unsupported`. Decoder faults, such as a backend that fails to open, and later peer and decode failures keep their existing errors. Regenerate bindings and rebuild the matching native library together. diff --git a/swift/Sources/Moq/Bandwidth.swift b/swift/Sources/Moq/Bandwidth.swift index e54529a7f70..69b1313d297 100644 --- a/swift/Sources/Moq/Bandwidth.swift +++ b/swift/Sources/Moq/Bandwidth.swift @@ -74,14 +74,17 @@ public final class Viewers: Sendable { /// `maxBps` is a ceiling: what the largest rendition the player would switch to /// needs, not what it is receiving. Drop the viewer once the broadcast stops being /// watched. Holding one requests the receive estimate, like `Session.recvBandwidth()`. - public func watch(maxBps: UInt64) -> Viewer { - Viewer(ffi.watch(maxBps: maxBps)) + /// Throws `MoqError.OutOfRange`, watching nothing, when the ceilings would sum above + /// `2^53 - 1`. + public func watch(maxBps: UInt64) throws -> Viewer { + Viewer(try ffi.watch(maxBps: maxBps)) } /// Send `targetBps` as the PROBE target instead of the viewers' sum, or `nil` to - /// follow them again. `0` sends no target. - public func setTarget(targetBps: UInt64?) { - ffi.setTarget(targetBps: targetBps) + /// follow them again. `0` sends no target. Throws `MoqError.OutOfRange`, keeping the + /// previous override, above `2^53 - 1`. + public func setTarget(targetBps: UInt64?) throws { + try ffi.setTarget(targetBps: targetBps) } } @@ -101,9 +104,10 @@ public final class Viewer: Sendable { ffi.rate() } - /// Change the ceiling, keeping the same claim. - public func update(maxBps: UInt64) { - ffi.update(maxBps: maxBps) + /// Change the ceiling, keeping the same claim. Throws `MoqError.OutOfRange`, keeping + /// the previous ceiling, when the ceilings would sum above `2^53 - 1`. + public func update(maxBps: UInt64) throws { + try ffi.update(maxBps: maxBps) } } diff --git a/swift/Tests/MoqTests/SmokeTests.swift b/swift/Tests/MoqTests/SmokeTests.swift index b2fca9aa330..0d9131a52a8 100644 --- a/swift/Tests/MoqTests/SmokeTests.swift +++ b/swift/Tests/MoqTests/SmokeTests.swift @@ -120,11 +120,17 @@ final class SmokeTests: XCTestCase { defer { session.cancel(code: 0) } let viewers = session.viewers() - let viewer = viewers.watch(maxBps: 1_000_000) - viewer.update(maxBps: 2_000_000) - viewers.setTarget(targetBps: 0) - viewers.setTarget(targetBps: nil) + let viewer = try viewers.watch(maxBps: 1_000_000) + try viewer.update(maxBps: 2_000_000) + try viewers.setTarget(targetBps: 0) + try viewers.setTarget(targetBps: nil) XCTAssertNil(viewer.rate()) + // Past what a PROBE target carries: refused. + XCTAssertThrowsError(try viewers.watch(maxBps: 1 << 53)) { error in + guard case MoqError.OutOfRange = error else { + return XCTFail("expected OutOfRange, got \(error)") + } + } } /// A value the native side cannot use throws from the constructor, not the dial. From d862400f7a07719f09ff09aa3a9333d19d8d8054 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 3 Nov 2026 16:29:56 -0800 Subject: [PATCH 17/20] quest: record the 2026-11-03 viewer-target decisions; unblock the follow-ups Main's viewer-followups quest required the viewer-target quest this PR finishes and deletes. Co-Authored-By: Claude Opus 5.5 --- quest/m2/probe/README.md | 13 +++++++++++++ quest/m2/probe/viewer-followups.md | 6 +----- 2 files changed, 14 insertions(+), 5 deletions(-) diff --git a/quest/m2/probe/README.md b/quest/m2/probe/README.md index 1aacb0ceeb3..0fae738bad5 100644 --- a/quest/m2/probe/README.md +++ b/quest/m2/probe/README.md @@ -69,6 +69,19 @@ Decided with the maintainer on 2026-10-20: The `js/net` send target moved to [padding](/quest/m2/probe/padding.md), its only sender. +Decided with the maintainer on 2026-11-03, in review of +[moq-dev/moq#7090](https://github.com/moq-dev/moq/pull/7090): + +- **A local override covers local reservations only.** ✅ Keep the larger of + the two targets: `Allocator::set_target(Some(0))` stops probing for this + side's reservations, and the peer's PROBE target still sets how high to + probe. Rejected: a local zero that also disables peer-driven probing. +- **Unencodable viewer targets are refused at the public API.** ✅ Viewer + ceilings and overrides that would sum above 2^53 - 1 bps fail + (`Error::BoundsExceeded` in Rust, `MoqError::OutOfRange` through moq-ffi, a + `RangeError` in JS) and change nothing. Rejected: saturating the advertised + target, which silently changes what an oversized target means. + This README's own work, once the children land: - An end-to-end shaped-uplink test, at least nightly: a Chrome publisher diff --git a/quest/m2/probe/viewer-followups.md b/quest/m2/probe/viewer-followups.md index fd94679b999..7b3812a2d15 100644 --- a/quest/m2/probe/viewer-followups.md +++ b/quest/m2/probe/viewer-followups.md @@ -16,7 +16,7 @@ left are closed: ## 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](/quest/m2/probe/viewer-target.md). +which finishes viewer targets. - Pooled reconnect: the `Reload`/pool `viewers` wiring (`js/net/src/connection/reload.ts`) is covered only by type checks and @@ -37,7 +37,3 @@ 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. - -## Required - -- [Viewer probe targets and grants](/quest/m2/probe/viewer-target.md) - its PR, [moq-dev/moq#7090](https://github.com/moq-dev/moq/pull/7090), adds the handles and PROBE wiring these test From 36980cbd470a419bc3da739fb6cfab84b6eef10e Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 3 Nov 2026 16:30:11 -0800 Subject: [PATCH 18/20] style: rustfmt the viewer limit changes Co-Authored-By: Claude Opus 5.5 --- rs/moq-c/src/test.rs | 5 ++++- rs/moq-net/benches/bandwidth.rs | 4 +++- rs/moq-net/src/model/bandwidth.rs | 8 +------- rs/moq-net/tests/integration/viewer_target.rs | 5 ++++- 4 files changed, 12 insertions(+), 10 deletions(-) diff --git a/rs/moq-c/src/test.rs b/rs/moq-c/src/test.rs index d962a8bc590..fa820a4f7ef 100644 --- a/rs/moq-c/src/test.rs +++ b/rs/moq-c/src/test.rs @@ -7077,7 +7077,10 @@ fn viewers_split_the_receive_estimate() { let max = moq_net::bandwidth::Viewers::MAX_TARGET.as_bps(); assert_eq!(moq_viewers_watch(viewers, max), crate::MOQ_ERROR_OUT_OF_RANGE); assert_eq!(moq_viewer_update(second, max), crate::MOQ_ERROR_OUT_OF_RANGE); - assert_eq!(moq_viewers_set_target(viewers, max + 1, true), crate::MOQ_ERROR_OUT_OF_RANGE); + assert_eq!( + moq_viewers_set_target(viewers, max + 1, true), + crate::MOQ_ERROR_OUT_OF_RANGE + ); assert_eq!(viewer_rate(first), Some(1_500_000)); assert_eq!(moq_viewer_close(second), 0); diff --git a/rs/moq-net/benches/bandwidth.rs b/rs/moq-net/benches/bandwidth.rs index 0904c0bbbb0..7440f750bf0 100644 --- a/rs/moq-net/benches/bandwidth.rs +++ b/rs/moq-net/benches/bandwidth.rs @@ -72,7 +72,9 @@ fn bench_viewers(c: &mut Criterion) { for count in RESERVATIONS { group.bench_function(BenchmarkId::from_parameter(count), |b| { let viewers = Viewers::default(); - let watched: Vec<_> = (0..count).map(|_| viewers.watch(Rate::from_kbps(1_000)).expect("within the limit")).collect(); + let watched: Vec<_> = (0..count) + .map(|_| viewers.watch(Rate::from_kbps(1_000)).expect("within the limit")) + .collect(); let mut target = fuzz::ProbeTarget::viewers(&viewers); target.poll().expect("the first poll reports the target"); let touched = &watched[count / 2]; diff --git a/rs/moq-net/src/model/bandwidth.rs b/rs/moq-net/src/model/bandwidth.rs index 14997098b5f..46017b658ad 100644 --- a/rs/moq-net/src/model/bandwidth.rs +++ b/rs/moq-net/src/model/bandwidth.rs @@ -373,13 +373,7 @@ impl Allocator { /// Claim up to `max` of `estimate`, active whenever `demand` is, or always without one. /// /// Errors without claiming when the ceilings would sum above the registry's limit. - fn claim( - &self, - estimate: Consumer, - demand: Option, - priority: i8, - max: Rate, - ) -> Result { + fn claim(&self, estimate: Consumer, demand: Option, priority: i8, max: Rate) -> Result { let (id, grants) = { // Nothing ever closes this channel: the allocator holds the only producer // and never aborts it, so it's open for as long as `self` is. diff --git a/rs/moq-net/tests/integration/viewer_target.rs b/rs/moq-net/tests/integration/viewer_target.rs index b8a22bc1140..583fcb5b934 100644 --- a/rs/moq-net/tests/integration/viewer_target.rs +++ b/rs/moq-net/tests/integration/viewer_target.rs @@ -96,7 +96,10 @@ async fn a_local_override_leaves_the_peers_target() { let viewer = pair.client.viewers().watch(mbps(2)).unwrap(); probes_to(&pair.server_transport, mbps(2)).await; - assert!(!reserved.consume().probed(), "{version}: nothing probes for the reservation"); + assert!( + !reserved.consume().probed(), + "{version}: nothing probes for the reservation" + ); drop(viewer); probes_to(&pair.server_transport, Rate::ZERO).await; } From 246e7929f209732912260693942aa51d18401c80 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 3 Nov 2026 16:47:31 -0800 Subject: [PATCH 19/20] fix(net): a closed JS viewers registry retracts its target override Also say plainly that Session::viewers reads its own session's estimate, like Session::allocator; the reconnecting handle follows each new one. Co-Authored-By: Claude Opus 5.5 --- js/net/src/bandwidth.test.ts | 5 +++++ js/net/src/bandwidth.ts | 9 ++++++++- rs/moq-net/src/session.rs | 7 +++++-- 3 files changed, 18 insertions(+), 3 deletions(-) diff --git a/js/net/src/bandwidth.test.ts b/js/net/src/bandwidth.test.ts index beef3e4821d..df068984ac2 100644 --- a/js/net/src/bandwidth.test.ts +++ b/js/net/src/bandwidth.test.ts @@ -449,7 +449,12 @@ test("the viewers' target sums their ceilings until overridden", () => { test("a closed viewers registry claims nothing", () => { const viewers = new Viewers(new Signal(1_000_000)); + // Closing retracts an override too, and a later one is ignored. + viewers.setTarget(1_000_000); viewers.close(); + expect(viewers.target.peek()).toBe(0); + viewers.setTarget(1_000_000); + expect(viewers.target.peek()).toBe(0); const viewer = viewers.watch(2_000_000); expect(viewers.target.peek()).toBe(0); diff --git a/js/net/src/bandwidth.ts b/js/net/src/bandwidth.ts index 143582cf438..27811ff8682 100644 --- a/js/net/src/bandwidth.ts +++ b/js/net/src/bandwidth.ts @@ -503,6 +503,7 @@ export class Viewers { #divider: Divider; #override = new Signal(undefined); + #closed = false; /** * The PROBE target: the live viewers' ceilings summed, or the {@link setTarget} override. @@ -540,14 +541,20 @@ export class Viewers { * @throws {RangeError} keeping the previous override, for a target above {@link Viewers.MAX_TARGET}. */ setTarget(target: number | undefined): void { + if (this.#closed) return; if (target !== undefined && ceiling(target) > Viewers.MAX_TARGET) { throw new RangeError(`PROBE target ${target} is above the limit of ${Viewers.MAX_TARGET}`); } this.#override.set(target); } - /** Stop dividing. Existing viewers report `undefined` and release their claims. */ + /** + * Stop dividing. Existing viewers report `undefined` and release their claims, and the + * target drops to zero for good, override included. + */ close(): void { + this.#closed = true; + this.#override.set(undefined); this.#divider.close(); } } diff --git a/rs/moq-net/src/session.rs b/rs/moq-net/src/session.rs index cd6b28b2177..2ed971dfe3c 100644 --- a/rs/moq-net/src/session.rs +++ b/rs/moq-net/src/session.rs @@ -246,8 +246,11 @@ impl Session { /// advertised `Increase` probes the connection up to it. Holding a viewer requests /// PROBE. Clones share one registry: a /// [`Client::with_viewers`](crate::Client::with_viewers) registry's when the session - /// was dialed with one, so viewers outlive a reconnect. Viewers report `None` when - /// the version has no PROBE. + /// was dialed with one, so their claims outlive a reconnect, like + /// [`allocator`](Self::allocator)'s. Viewers taken here read this session's + /// estimate, and report `None` once it ends or when the version has no PROBE; take + /// them from the reconnecting handle (`moq_tokio::Connection::viewers`) to read + /// each new session's. pub fn viewers(&self) -> bandwidth::Viewers { self.viewers.with_estimate(self.recv_bandwidth.clone()) } From 219e46c779810ac8350c16674907c758f4676ec9 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 3 Nov 2026 22:15:33 -0800 Subject: [PATCH 20/20] fix(signals): a Derived's one-shot reader re-arms before its sources see it leave `Derived.changed(fn)` released its source subscriptions before calling `fn`. A source that counts its listeners, such as a connection's PROBE estimate, then saw its last one leave and published "unwanted" before an Effect reading through the Derived scheduled its rerun. A reload's viewers read the estimate that way, so with no other observer every PROBE report closed and reopened the PROBE stream. Call `fn` first, as `Observed` and `Follow` already do, so the reader's replacement subscription coalesces the gap away. Co-Authored-By: Claude Opus 5.5 --- js/net/src/util/observed.test.ts | 24 +++++++++++++++++++++++- js/signals/src/index.ts | 18 +++++++++++++++--- 2 files changed, 38 insertions(+), 4 deletions(-) diff --git a/js/net/src/util/observed.test.ts b/js/net/src/util/observed.test.ts index 8dcad772018..71cce5837dd 100644 --- a/js/net/src/util/observed.test.ts +++ b/js/net/src/util/observed.test.ts @@ -1,5 +1,5 @@ import { expect, test } from "bun:test"; -import { Effect, type Getter, Signal } from "@moq/signals"; +import { Derived, Effect, type Getter, Signal } from "@moq/signals"; import { Follow, Observed } from "./observed"; const flush = async () => { @@ -36,6 +36,28 @@ test("reactive one-shot observers preserve demand across a value update", async stop(); }); +// A reload's viewers read the session's PROBE estimate through a Follow and a Derived; a +// gap in demand there would close and reopen the PROBE stream on every report. +test("a reactive reader through a Derived preserves demand across a value update", async () => { + const value = new Observed(1); + const demand: boolean[] = []; + const stop = value.wanted.subscribe((wanted) => demand.push(wanted)); + const derived = new Derived([new Follow(new Signal | undefined>(value))], (value) => + value === undefined ? undefined : value * 2, + ); + const effect = new Effect((effect) => { + effect.get(derived); + }); + await flush(); + value.set(2); + await flush(); + expect(demand).toEqual([true]); + effect.close(); + await flush(); + expect(demand).toEqual([true, false]); + stop(); +}); + test("forwarded demand switches sources and releases its old source", async () => { const first = new Observed(1); const second = new Observed(2); diff --git a/js/signals/src/index.ts b/js/signals/src/index.ts index dce31400c80..1eb72ecacf6 100644 --- a/js/signals/src/index.ts +++ b/js/signals/src/index.ts @@ -1271,11 +1271,23 @@ export class Derived[], T> implements G // Calls `fn` with the derived value the first time it changes, then unsubscribes. #once(fn: Subscriber): Dispose { + let active = true; const dispose = this.subscribe((value) => { - dispose(); - fn(value); + if (!active) return; + active = false; + // Call `fn` before letting go of the sources: a reactive reader schedules its next + // run there, so its replacement subscription coalesces away the gap a source that + // counts its listeners (such as demand for an estimate) would otherwise see. + try { + fn(value); + } finally { + dispose(); + } }); - return dispose; + return () => { + active = false; + dispose(); + }; } // Subscribes to every source, recomputing on any notification.