From 2ff35d96caa298a7931e79d6a2962c74590107b4 Mon Sep 17 00:00:00 2001 From: Luke Curley <432854+kixelated@users.noreply.github.com> Date: Mon, 19 Oct 2026 18:35:25 -0700 Subject: [PATCH 01/14] chore(quest): claim lite refresh wire Co-Authored-By: GPT-6.1-Sol From 6e620f6cf5415d10f214646066a8e08871d9e8d3 Mon Sep 17 00:00:00 2001 From: Luke Curley <432854+kixelated@users.noreply.github.com> Date: Mon, 19 Oct 2026 18:48:34 -0700 Subject: [PATCH 02/14] feat(lite): carry refresh demand through relays Co-Authored-By: GPT-6.1-Sol --- drafts/draft-lcurley-moq-lite.md | 18 ++++++ js/net/bench/refresh.ts | 71 ++++++++++++++++++++++ js/net/src/internal.ts | 12 ++++ js/net/src/lite/publisher.ts | 4 ++ js/net/src/lite/refresh.test.ts | 80 +++++++++++++++++++++++++ js/net/src/lite/subscribe.test.ts | 9 +++ js/net/src/lite/subscribe.ts | 14 +++++ js/net/src/lite/subscriber.ts | 19 +++++- js/net/src/lite/track.test.ts | 9 +++ js/net/src/lite/track.ts | 16 ++++- js/net/src/resume.ts | 6 ++ js/net/src/track.ts | 5 ++ rs/moq-net/src/fuzz.rs | 2 + rs/moq-net/src/lite/publisher.rs | 56 +++++++++++++++++ rs/moq-net/src/lite/subscribe.rs | 47 +++++++++++++++ rs/moq-net/src/lite/subscriber.rs | 40 ++++++++++++- rs/moq-net/src/lite/track.rs | 39 ++++++++++++ rs/moq-net/src/test_interop.rs | 1 + rs/moq-net/tests/integration/main.rs | 1 + rs/moq-net/tests/integration/refresh.rs | 68 +++++++++++++++++++++ sh/gh/nightly.sh | 2 +- 21 files changed, 512 insertions(+), 7 deletions(-) create mode 100644 js/net/bench/refresh.ts create mode 100644 js/net/src/lite/refresh.test.ts create mode 100644 rs/moq-net/tests/integration/refresh.rs diff --git a/drafts/draft-lcurley-moq-lite.md b/drafts/draft-lcurley-moq-lite.md index 941072fbbe6..1fe61998429 100644 --- a/drafts/draft-lcurley-moq-lite.md +++ b/drafts/draft-lcurley-moq-lite.md @@ -1198,6 +1198,7 @@ SUBSCRIBE_UPDATE Message { Group End (i) Frame Start (i) Frame End (i) + Wanted Group (i) } ~~~ @@ -1205,6 +1206,13 @@ See [SUBSCRIBE](#subscribe) for information about each field. Moving `Frame Start` forward within a group that is already being delivered does not retract frames the publisher has already sent; like `Group Start`, it only bounds what the publisher sends from here on. +**Wanted Group**: +A live-edge join requesting this group or later, encoded as the sequence plus one; `0` means no request. +A publisher MUST ignore a request at or below its largest group, and otherwise evaluate it as a new SUBSCRIBE under the Track's Refresh ratio. +A relay sends a request when local demand wants a group beyond its largest, and MUST NOT send another until its largest reaches the requested group. +The pending request ends with the subscription. +A new SUBSCRIBE itself counts as a join and needs no Wanted Group field. + ## TRACK TRACK is sent by a subscriber to request a Track's immutable publisher properties. It is the first message on a Track Stream (0x6). @@ -1239,6 +1247,7 @@ TRACK_INFO Message { Publisher Priority (8) Publisher Max Age (i) Timescale (i) + Refresh (i) } ~~~ @@ -1271,6 +1280,13 @@ The number of timestamp units per second for frame timestamps on this Track, or lite-05 and lite-06 have no untimed encoding: there it MUST be non-zero, and a subscriber that receives 0 MUST reset the stream with a protocol violation. Common values include `1000` (milliseconds), `1000000` (microseconds), `48000` (audio sample rate), and `90000` (RTP video clock). +**Refresh**: +An optional unsigned 32-bit byte ratio, encoded as the ratio plus one; `0` disables refresh. +On a live-edge join, a publisher asks for a group beyond every sequence already produced when the newest group's bytes after its first frame exceed the ratio times that first frame's bytes. +Joins coalesce until the requested group arrives. +A relay preserves the ratio and evaluates joins against its own cache, forwarding demand in SUBSCRIBE_UPDATE. +Lite-05/06 omit Refresh and Wanted Group; a Track received on those versions never refreshes. + ## SUBSCRIBE_OK {#subscribe-ok} A SUBSCRIBE_OK message confirms a subscription and resolves its absolute start position. It is the first message the publisher sends on the Subscribe Stream, once the start position is known. @@ -1586,6 +1602,8 @@ The `Message Length` describes the payload size on the wire. ## moq-lite-07 +- Added TRACK_INFO `Refresh` and SUBSCRIBE_UPDATE `Wanted Group`, carrying ratio-based refresh demand through relays. + - A publisher must not start a timed Group's frame 0 earlier than a lower-sequence Group's. Receivers do not check it, since a received timestamp may be a send time. - Added the reliable ordered RTCDataChannel binding, with one Qmux Record per binary message and no datagrams. diff --git a/js/net/bench/refresh.ts b/js/net/bench/refresh.ts new file mode 100644 index 00000000000..c26c3a3079c --- /dev/null +++ b/js/net/bench/refresh.ts @@ -0,0 +1,71 @@ +/** Sweep unrelated tracks and joined readers for a refresh crossing one lite hop. */ +import { Manual, Nano } from "@moq/clock"; +import { accept } from "../src/connection/accept.ts"; +import { connect } from "../src/connection/connect.ts"; +import { ALPN_07_WIP } from "../src/lite/version.ts"; +import { createMockTransportPair } from "../src/mock.ts"; +import { Producer } from "../src/origin.ts"; +import * as Path from "../src/path.ts"; + +console.debug = () => {}; +console.log("tracks,joined,refresh_us"); +for (const tracks of [1, 8, 32]) + for (const joined of [1, 8, 32]) { + const clock = new Manual(); + const restore = clock.install(); + const source = new Producer(); + const destination = new Producer(); + const broadcast = source.createBroadcast(Path.from("room")); + broadcast.announce(); + const producers = Array.from({ length: tracks }, (_, i) => broadcast.createTrack(`data${i}`, { refresh: 1 })); + const pair = createMockTransportPair(ALPN_07_WIP); + const url = new URL("https://localhost/refresh"); + const peers = await Promise.all([ + connect({ url, transport: pair.client, consume: destination }), + accept({ url, transport: pair.server, publish: source.consume() }), + ]); + try { + const announcements = destination.announced(); + while ((await announcements.next())?.kind !== "start") {} + const request = destination.request(Path.from("room")); + while (!request.active.peek()) await request.active.changed(); + const remote = request.active.peek()!; + const consumers = producers.map((_, i) => remote.track(`data${i}`)); + const baseline = consumers.map((track) => track.subscribe()); + for (let i = 0; i < tracks; i++) { + const group = producers[i].appendGroup(); + group.writeFrame({ payload: new Uint8Array(3) }); + group.close(); + const received = (await baseline[i].recvGroup())!; + await received.readFrame(); + received.close(); + } + const samples: number[] = []; + for (let round = 0; round < 9; round++) { + const group = producers[0].appendGroup(); + group.writeFrame({ payload: new Uint8Array(3) }); + group.writeFrame({ payload: new Uint8Array(4) }); + group.close(); + const received = (await baseline[0].recvGroup())!; + await received.readFrame(); + await received.readFrame(); + received.close(); + const start = performance.now(); + const joins = Array.from({ length: joined }, () => consumers[0].subscribe()); + const wanted = producers[0].demand().wanted; + while (wanted.peek() !== group.sequence + 1) await wanted.changed(); + if (round > 0) samples.push((performance.now() - start) * 1000); + for (const join of joins) join.close(); + } + samples.sort((a, b) => a - b); + console.log(`${tracks},${joined},${samples[4].toFixed(2)}`); + for (const sub of baseline) sub.close(); + request.close(); + } finally { + destination.close(); + source.close(); + for (const peer of peers) peer.abort(); + await clock.advanceAsync(Nano(0)); + restore(); + } + } diff --git a/js/net/src/internal.ts b/js/net/src/internal.ts index 1b7f06d4800..dc231a5c227 100644 --- a/js/net/src/internal.ts +++ b/js/net/src/internal.ts @@ -283,6 +283,8 @@ export type RecvDatagram = * buffer of its own. Implemented by `resume.ts`, the counterpart of the Rust `Inner::Resume`. */ export interface ResumeSource { + /** Re-evaluate a live-edge join at the serving copy. */ + join(): void; /** The next group not in `delivered`, in arrival or sequence order, without waiting. */ tryGroup(ordered: boolean, delivered: Delivered): Recv; /** @@ -349,6 +351,10 @@ export const hooks: { * that floor, a pending tail owes nothing below it. Mirrors the Rust `start_at`; assigned by * `track.ts`. */ + /** Re-evaluate a live-edge join at this subscriber's copy. */ + joinSubscriber: (subscriber: Subscriber) => void; + /** Re-evaluate a live-edge join at a producer. */ + joinProducer: (producer: Producer) => void; startTrack: (producer: Producer, served: { start: number; requested?: number }) => void; // pending: /quest/m1/public-model/ingest.md /** @@ -488,6 +494,12 @@ export const hooks: { endTrack: () => { throw new Error("track.ts not loaded"); }, + joinProducer: () => { + throw new Error("track.ts not loaded"); + }, + joinSubscriber: () => { + throw new Error("track.ts not loaded"); + }, startTrack: () => { throw new Error("track.ts not loaded"); }, diff --git a/js/net/src/lite/publisher.ts b/js/net/src/lite/publisher.ts index f4ec22d7f59..77c364e3db3 100644 --- a/js/net/src/lite/publisher.ts +++ b/js/net/src/lite/publisher.ts @@ -806,6 +806,9 @@ export class Publisher { writer: stream.writer, version: this.version, apply: (update) => { + const largest = hooks.peekLargest(track).largest?.group; + if (update.wantedGroup !== undefined && (largest === undefined || update.wantedGroup > largest)) + hooks.joinSubscriber(track); const end = exclusiveGroupEnd(update.endGroup); track.update({ priority: update.priority, @@ -1350,6 +1353,7 @@ export class Publisher { const info = await wireOf(front).resolveTrackInfo(track, release.signal); return new TrackInfoMessage({ priority: info.priority, + refresh: info.refresh, // Publisher Max Age: the publisher's retention bound, advertised so // relays re-serve with the same window. maxAge: info.maxAge, diff --git a/js/net/src/lite/refresh.test.ts b/js/net/src/lite/refresh.test.ts new file mode 100644 index 00000000000..2e76ec5fb26 --- /dev/null +++ b/js/net/src/lite/refresh.test.ts @@ -0,0 +1,80 @@ +import { expect, spyOn, test } from "bun:test"; +import { Manual, Nano } from "@moq/clock"; +import { accept } from "../connection/accept.ts"; +import { connect } from "../connection/connect.ts"; +import { createMockTransportPair } from "../mock.ts"; +import { Producer } from "../origin.ts"; +import * as Path from "../path.ts"; +import { SubscribeUpdate } from "./subscribe.ts"; +import { ALPN_06, ALPN_07_WIP } from "./version.ts"; + +test.each([ALPN_06, ALPN_07_WIP])("refresh joins reach a browser publisher on %s", async (alpn) => { + const clock = new Manual(); + const restore = clock.install(); + const source = new Producer(); + const b = new Producer(); + const broadcast = source.createBroadcast(Path.from("room")); + broadcast.announce(); + const producer = broadcast.createTrack("data", { refresh: 1 }); + const transports = [createMockTransportPair(alpn)]; + const peers = []; + const updates: number[] = []; + const encode = SubscribeUpdate.prototype.encode; + const spy = spyOn(SubscribeUpdate.prototype, "encode").mockImplementation(function ( + this: SubscribeUpdate, + writer, + version, + ) { + if (this.wantedGroup !== undefined) updates.push(this.wantedGroup); + return encode.call(this, writer, version); + }); + try { + for (const [index, [upstream, downstream]] of [[source, b]].entries()) { + const pair = transports[index]; + const url = new URL("https://localhost/refresh"); + peers.push( + ...(await Promise.all([ + connect({ url, transport: pair.client, consume: downstream }), + accept({ url, transport: pair.server, publish: upstream.consume() }), + ])), + ); + } + const announcements = b.announced(); + while ((await announcements.next())?.kind !== "start") {} + const request = b.request(Path.from("room")); + while (request.active.peek() === undefined) await request.active.changed(); + const remote = request.active.peek()!.track("data"); + expect((await remote.info()).refresh).toBe(alpn === ALPN_07_WIP ? 1 : undefined); + const baseline = remote.subscribe(); + const group = producer.appendGroup(); + group.writeFrame({ payload: new Uint8Array(3) }); + group.writeFrame({ payload: new Uint8Array(3) }); + const received = await baseline.recvGroup(); + expect((await received!.readFrame())!.payload.length).toBe(3); + expect((await received!.readFrame())!.payload.length).toBe(3); + const joins = [remote.subscribe()]; + await clock.advanceAsync(Nano(0)); + expect(producer.demand().wanted.peek()).toBe(0); + updates.length = 0; + group.writeFrame({ payload: new Uint8Array(1) }); + expect((await received!.readFrame())!.payload.length).toBe(1); + for (let i = 0; i < 8; i++) joins.push(remote.subscribe()); + await clock.advanceAsync(Nano(0)); + if (alpn === ALPN_07_WIP) { + while (producer.demand().wanted.peek() !== 1) await producer.demand().wanted.changed(); + } + expect(producer.demand().wanted.peek()).toBe(alpn === ALPN_07_WIP ? 1 : 0); + // Concurrent local joins coalesce into one upstream update. + expect(updates.length).toBe(alpn === ALPN_07_WIP ? 1 : 0); + for (const join of joins) join.close(); + received!.close(); + baseline.close(); + group.close(); + } finally { + spy.mockRestore(); + for (const origin of [b, source]) origin.close(); + for (const peer of peers) peer.abort(); + await clock.advanceAsync(Nano(0)); + restore(); + } +}); diff --git a/js/net/src/lite/subscribe.test.ts b/js/net/src/lite/subscribe.test.ts index 16f77f46796..79496e96400 100644 --- a/js/net/src/lite/subscribe.test.ts +++ b/js/net/src/lite/subscribe.test.ts @@ -312,3 +312,12 @@ test.each([Version.DRAFT_03, Version.DRAFT_05, Version.DRAFT_06])( expect(decoded.order).toBe("descending"); }, ); + +test("wanted group survives lite-07 and disappears on legacy wires", async () => { + for (const version of [Version.DRAFT_05, Version.DRAFT_06, Version.DRAFT_07]) { + const update = new SubscribeUpdate({ priority: 7, wantedGroup: 3 }); + const encoded = await encodeMessage(version, update); + const decoded = await SubscribeUpdate.decode(new Reader(undefined, encoded, version), version); + expect(decoded.wantedGroup).toBe(version === Version.DRAFT_07 ? 3 : undefined); + } +}); diff --git a/js/net/src/lite/subscribe.ts b/js/net/src/lite/subscribe.ts index f9be30b4785..a0b4610b63d 100644 --- a/js/net/src/lite/subscribe.ts +++ b/js/net/src/lite/subscribe.ts @@ -189,6 +189,8 @@ export function emptyRange({ startGroup, endGroup }: { startGroup?: number; endG } export class SubscribeUpdate { + /** A join requesting this group or later, judged against the local refresh ratio. */ + wantedGroup?: number; priority: number; /** See {@link Subscribe.order}. */ order: Order; @@ -203,6 +205,7 @@ export class SubscribeUpdate { constructor(props: { priority: number; + wantedGroup?: number; order?: Order; maxDelay?: number; startGroup?: number; @@ -210,6 +213,9 @@ export class SubscribeUpdate { startFrame?: number; endFrame?: number; }) { + if (props.wantedGroup !== undefined && (!Number.isSafeInteger(props.wantedGroup) || props.wantedGroup < 0)) + throw new RangeError("wanted group must be a safe non-negative integer"); + this.wantedGroup = props.wantedGroup; this.priority = props.priority; this.order = props.order ?? "descending"; this.maxDelay = props.maxDelay ?? 0; @@ -232,6 +238,8 @@ export class SubscribeUpdate { await encodeStartGroup(w, version, this.startGroup); await w.u53(this.endGroup !== undefined ? this.endGroup + 1 : 0); await encodeFrameBounds(w, version, this); + if (version === Version.DRAFT_07) + await w.u62(this.wantedGroup === undefined ? 0n : BigInt(this.wantedGroup) + 1n); break; } } @@ -249,7 +257,11 @@ export class SubscribeUpdate { const endGroup = (await r.u53()) || undefined; const end = endGroup !== undefined ? endGroup - 1 : undefined; const frames = await decodeFrameBounds(r, version, startGroup, end); + const wanted = version === Version.DRAFT_07 ? await r.u62() : 0n; + if (wanted > BigInt(Number.MAX_SAFE_INTEGER) + 1n) + throw new RangeError("wanted group exceeds safe integer"); return new SubscribeUpdate({ + wantedGroup: wanted === 0n ? undefined : Number(wanted - 1n), priority, order, maxDelay, @@ -262,6 +274,8 @@ export class SubscribeUpdate { } async encode(w: Writer, version: Version): Promise { + if (this.wantedGroup !== undefined && (!Number.isSafeInteger(this.wantedGroup) || this.wantedGroup < 0)) + throw new RangeError("wanted group must be a safe non-negative integer"); return Message.encode(w, (w) => this.#encode(w, version)); } diff --git a/js/net/src/lite/subscriber.ts b/js/net/src/lite/subscriber.ts index 08732d797f2..496e8cbb6a5 100644 --- a/js/net/src/lite/subscriber.ts +++ b/js/net/src/lite/subscriber.ts @@ -954,6 +954,7 @@ export class Subscriber { // matches what the upstream advertises (relays re-serve with the same bound). maxAge: info.maxAge === undefined ? undefined : Milli(info.maxAge), priority: info.priority, + refresh: info.refresh, }; } @@ -1294,11 +1295,23 @@ export class Subscriber { }, }; + let pendingWanted: number | undefined; + const demand = track.demand(); for (;;) { + const largest = hooks.cachedLargest(track)?.group; + const wanted = demand.wanted.peek(); + const refresh = + this.version === Version.DRAFT_07 && + largest !== undefined && + (pendingWanted === undefined || largest >= pendingWanted) && + wanted !== undefined && + wanted > largest + ? wanted + : undefined; const current = track.subscription.peek(); - if (current === undefined || this.#sameSubscription(current, lastSent)) { + if (current === undefined || (refresh === undefined && this.#sameSubscription(current, lastSent))) { // Nothing new to send; wait for a change or termination. - const next = await race([track.subscription.changed(), stopped]); + const next = await race([track.subscription.changed(), demand.wanted.changed(), stopped]); if (next === null) return; continue; } @@ -1317,6 +1330,7 @@ export class Subscriber { // Round-trip the other Subscribe parameters so the publisher doesn't // interpret SUBSCRIBE_UPDATE as a reset of ordered/maxDelay/etc. const update = new SubscribeUpdate({ + wantedGroup: refresh, priority: current.priority ?? 0, order: current.order, maxDelay: current.maxDelay, @@ -1334,6 +1348,7 @@ export class Subscriber { } catch { return; } + if (refresh !== undefined) pendingWanted = refresh; lastSent = { ...current }; console.debug(`subscribe update: id=${id} broadcast=${broadcast} track=${track.name}`); } diff --git a/js/net/src/lite/track.test.ts b/js/net/src/lite/track.test.ts index 096ad5dad9b..e33fab530c0 100644 --- a/js/net/src/lite/track.test.ts +++ b/js/net/src/lite/track.test.ts @@ -201,3 +201,12 @@ for (const version of [Version.DRAFT_05, Version.DRAFT_06]) { } }); } + +test("refresh ratio survives lite-07 and disappears on legacy wires", async () => { + for (const version of [Version.DRAFT_05, Version.DRAFT_06, Version.DRAFT_07]) { + const info = new TrackInfo({ priority: 7, refresh: 3 }); + const encoded = await bytes((w) => info.encode(w, version), version); + const decoded = await TrackInfo.decode(new Reader(undefined, encoded, version), version); + expect(decoded.refresh).toBe(version === Version.DRAFT_07 ? 3 : undefined); + } +}); diff --git a/js/net/src/lite/track.ts b/js/net/src/lite/track.ts index a787c203942..c787b580246 100644 --- a/js/net/src/lite/track.ts +++ b/js/net/src/lite/track.ts @@ -65,6 +65,8 @@ export class Track { * FETCH for the track. */ export class TrackInfo { + /** Refresh byte ratio on lite-07. */ + refresh?: number; /** The publisher's tie-break priority for this track. */ priority: number; /** @@ -83,10 +85,12 @@ export class TrackInfo { priority = 0, maxAge, timescale, + refresh, }: { priority?: number; maxAge?: number; timescale?: number; + refresh?: number; }) { if (!Number.isInteger(priority) || priority < 0 || priority > 255) { throw new RangeError(`priority must be an integer in 0..=255: ${priority}`); @@ -94,6 +98,9 @@ export class TrackInfo { if (maxAge !== undefined && (!Number.isSafeInteger(maxAge) || maxAge < 0)) { throw new RangeError(`maxAge must be a safe non-negative integer: ${maxAge}`); } + if (refresh !== undefined && (!Number.isInteger(refresh) || refresh < 0 || refresh > 0xffff_ffff)) + throw new RangeError("refresh exceeds u32"); + this.refresh = refresh; this.priority = priority; this.maxAge = maxAge; this.timescale = timescale === undefined ? undefined : Timescale(timescale); @@ -107,6 +114,7 @@ export class TrackInfo { const age = this.maxAge === undefined ? undefined : BigInt(this.maxAge); await w.u62(legacy ? (age ?? BigInt(Number.MAX_SAFE_INTEGER)) : age === undefined ? 0n : age + 1n); await w.u53(wireTimescale(version, this.timescale) ?? 0); + if (!legacy) await w.u53(this.refresh === undefined ? 0 : this.refresh + 1); } static async #decode(r: Reader, version: Version): Promise { @@ -127,7 +135,8 @@ export class TrackInfo { // Lite-05/06 have no untimed encoding, so zero is malformed there. const scale = await r.u53(); const timescale = scale === 0 && !legacy ? undefined : Timescale(scale); - return new TrackInfo({ priority, maxAge, timescale }); + const refresh = legacy ? undefined : (await r.u53()) - 1; + return new TrackInfo({ priority, maxAge, timescale, refresh: refresh === -1 ? undefined : refresh }); } async encode(w: Writer, version: Version): Promise { @@ -140,6 +149,11 @@ export class TrackInfo { if (this.maxAge !== undefined && (!Number.isSafeInteger(this.maxAge) || this.maxAge < 0)) { throw new RangeError(`maxAge must be a safe non-negative integer: ${this.maxAge}`); } + if ( + this.refresh !== undefined && + (!Number.isInteger(this.refresh) || this.refresh < 0 || this.refresh > 0xffff_ffff) + ) + throw new RangeError("refresh exceeds u32"); if (this.timescale !== undefined) Timescale(this.timescale); return Message.encode(w, (w) => this.#encode(w, version)); } diff --git a/js/net/src/resume.ts b/js/net/src/resume.ts index 2fc0b0fc443..cbfc1834735 100644 --- a/js/net/src/resume.ts +++ b/js/net/src/resume.ts @@ -672,6 +672,12 @@ class Reader implements ResumeSource { } } + join(): void { + this.sync(); + const serving = this.#serving(); + if (serving) hooks.joinSubscriber(serving.sub); + } + fork(options?: track.Subscription): track.Subscriber { this.sync(); const serving = this.#serving(); diff --git a/js/net/src/track.ts b/js/net/src/track.ts index 632df7bcfd4..a4c6e12c1db 100644 --- a/js/net/src/track.ts +++ b/js/net/src/track.ts @@ -721,6 +721,7 @@ export class Producer { } static { + hooks.joinProducer = (producer) => producer.#join(); hooks.endTrack = (producer, end) => producer.#endPending(end); hooks.startTrack = (producer, served) => { producer.#served = served; @@ -1784,6 +1785,10 @@ export class Subscriber { static { makeSubscriber = (name, state) => new Subscriber(name, state); + hooks.joinSubscriber = (subscriber) => { + if (subscriber.#resume) subscriber.#resume.join(); + else if (subscriber.#state.producer) hooks.joinProducer(subscriber.#state.producer); + }; hooks.tryRecvGroup = (subscriber, started) => subscriber.#tryRecvGroup(started); hooks.tryNextGroup = (subscriber) => subscriber.#tryNextGroup(); hooks.peekGroup = (subscriber, ordered) => subscriber.#peekGroup(ordered); diff --git a/rs/moq-net/src/fuzz.rs b/rs/moq-net/src/fuzz.rs index a2a48927a45..de4988abbff 100644 --- a/rs/moq-net/src/fuzz.rs +++ b/rs/moq-net/src/fuzz.rs @@ -611,6 +611,7 @@ impl Default for Messages { end_frame: None, }, lite_update: lite::SubscribeUpdate { + wanted_group: None, order: crate::track::Order::Descending, priority: 4, max_delay: Duration::from_millis(500), @@ -624,6 +625,7 @@ impl Default for Messages { largest: None, }), lite_info: lite::TrackInfo { + refresh: None, priority: 1, max_age: Some(Duration::from_secs(10)), timescale: Some(crate::Timescale::MICRO), diff --git a/rs/moq-net/src/lite/publisher.rs b/rs/moq-net/src/lite/publisher.rs index b97587899cb..778f4cd174f 100644 --- a/rs/moq-net/src/lite/publisher.rs +++ b/rs/moq-net/src/lite/publisher.rs @@ -1880,6 +1880,7 @@ impl Request for TrackInfoServe { // TRACK_INFO only flows on Lite05+ (the encode errors otherwise). writer.buffer(&lite::TrackInfo { + refresh: info.refresh, priority: info.priority, max_age: info.max_age, timescale: info.timescale, @@ -3386,6 +3387,12 @@ impl TrackRun { /// subscription. This is what lets relays pause an upstream subscription across /// consumer churn without tearing it down. fn update(&mut self, upd: lite::SubscribeUpdate) { + if upd + .wanted_group + .is_some_and(|wanted| self.track.peek_largest().is_none_or(|largest| wanted > largest.group)) + { + self.track.join(); + } if let Ok(mut value) = self.steer_tx.write() { *value = Steer { priority: upd.priority, @@ -4680,6 +4687,42 @@ mod serve_group_test { (TrackRun::new(ctx, track, bounds, steer), writer, log) } + #[test] + fn wanted_updates_ignore_stale_groups_and_recheck_the_ratio() { + let track = track::Producer::new( + Arc::new(broadcast::Info::default()), + "refresh", + track::Info::default().with_refresh(1), + ); + let subscriber = track.subscribe(None); + let (mut run, _, _) = lite_run(Version::Lite07, SinkSession::new(Log::default()), subscriber); + let mut group = track.append_group().unwrap(); + group.write_frame(None, &b"key"[..]).unwrap(); + group.write_frame(None, &b"more"[..]).unwrap(); + group.finish().unwrap(); + let update = |wanted_group| lite::SubscribeUpdate { + wanted_group, + priority: 0, + max_delay: Duration::ZERO, + start_group: None, + end_group: None, + start_frame: 0, + end_frame: None, + order: Order::Descending, + }; + run.update(update(Some(0))); + assert_eq!(track.demand().wanted(), Some(0), "stale request is not a join"); + run.update(update(Some(1))); + assert_eq!(track.demand().wanted(), Some(1)); + let mut group = track.append_group().unwrap(); + group.write_frame(None, &b"key"[..]).unwrap(); + group.finish().unwrap(); + run.update(update(Some(1))); + assert_eq!(track.demand().wanted(), Some(0), "answered request stays answered"); + run.update(update(Some(2))); + assert_eq!(track.demand().wanted(), Some(0), "new hop judges its own ratio"); + } + fn write_group(track: &mut track::Producer, sequence: u64, millis: u64) { let mut group = track.create_group(group::Info { sequence }).unwrap(); group @@ -4722,6 +4765,7 @@ mod serve_group_test { assert!(log.priorities().is_empty(), "the session queue ranks no stream"); run.update(lite::SubscribeUpdate { + wanted_group: None, order: Order::Ascending, priority: 7, max_delay: Duration::ZERO, @@ -4796,6 +4840,7 @@ mod serve_group_test { } run.update(lite::SubscribeUpdate { + wanted_group: None, order: Order::Ascending, priority: 3, max_delay: Duration::from_secs(3600), @@ -5085,6 +5130,7 @@ mod serve_group_test { assert_eq!(drops(&mut writer, &log, version).await, []); run.update(lite::SubscribeUpdate { + wanted_group: None, order: crate::track::Order::Descending, priority: 0, max_delay: Duration::from_secs(60), @@ -5239,6 +5285,7 @@ mod serve_group_test { assert_eq!(run.start, Some(5)); run.update(lite::SubscribeUpdate { + wanted_group: None, order: crate::track::Order::Descending, priority: 0, max_delay: Duration::from_secs(60), @@ -5281,6 +5328,7 @@ mod serve_group_test { moq_clock::sim::advance(Duration::from_secs(2)).await; run.update(lite::SubscribeUpdate { + wanted_group: None, order: crate::track::Order::Descending, priority: 0, max_delay: Duration::from_secs(1), @@ -5326,6 +5374,7 @@ mod serve_group_test { } let update = |start_group| lite::SubscribeUpdate { + wanted_group: None, order: crate::track::Order::Descending, priority: 0, max_delay: Duration::from_secs(1), @@ -5371,6 +5420,7 @@ mod serve_group_test { } let update = |start_group| lite::SubscribeUpdate { + wanted_group: None, order: crate::track::Order::Ascending, priority: 0, max_delay: Duration::from_secs(10), @@ -5418,6 +5468,7 @@ mod serve_group_test { assert_eq!(settle(&mut run), 1); run.update(lite::SubscribeUpdate { + wanted_group: None, order: crate::track::Order::Descending, priority: 0, max_delay: Duration::from_secs(60), @@ -5449,6 +5500,7 @@ mod serve_group_test { ); let (mut run, mut writer, _log) = lite_run(Version::Lite05, SinkSession::new(Log::default()), subscriber); run.update(lite::SubscribeUpdate { + wanted_group: None, order: crate::track::Order::Descending, priority: 0, max_delay: Duration::from_secs(60), @@ -5585,6 +5637,7 @@ mod serve_group_test { assert_eq!(relay.opened(), 0, "the resume is past the only group"); relay.run.update(lite::SubscribeUpdate { + wanted_group: None, order: crate::track::Order::Descending, priority: 0, max_delay: Duration::from_secs(30), @@ -5616,6 +5669,7 @@ mod serve_group_test { assert_eq!(relay.opened(), 2, "groups 1 and 2 are at or above the floor"); relay.run.update(lite::SubscribeUpdate { + wanted_group: None, order: crate::track::Order::Descending, priority: 0, max_delay: Duration::from_secs(30), @@ -5644,6 +5698,7 @@ mod serve_group_test { // The subscriber moves its start past the held group before the source resolves. let update = lite::SubscribeUpdate { + wanted_group: None, order: crate::track::Order::Descending, priority: 0, max_delay: Duration::ZERO, @@ -6545,6 +6600,7 @@ mod tests { assert!(!drive(&mut serve).await); let update = lite::SubscribeUpdate { + wanted_group: None, order: crate::track::Order::Descending, priority: 7, max_delay: Duration::ZERO, diff --git a/rs/moq-net/src/lite/subscribe.rs b/rs/moq-net/src/lite/subscribe.rs index f34b38d3d3a..7d3e257b89f 100644 --- a/rs/moq-net/src/lite/subscribe.rs +++ b/rs/moq-net/src/lite/subscribe.rs @@ -412,6 +412,8 @@ impl Message for SubscribeEnd { #[allow(dead_code)] #[derive(Clone, Debug)] pub struct SubscribeUpdate { + /// A join requesting this group or later, judged against the local refresh ratio. + pub wanted_group: Option, pub priority: u8, pub max_delay: std::time::Duration, pub start_group: Option, @@ -445,7 +447,17 @@ impl Message for SubscribeUpdate { let (start_frame, end_frame) = decode_frame_bounds(r, version, start_group, end_group)?; let start_group = canonical_start_group(version, start_group, start_frame); + let wanted_group = if matches!( + version, + Version::Lite03 | Version::Lite04 | Version::Lite05 | Version::Lite06 + ) { + None + } else { + r.varint()?.checked_sub(1) + }; + Ok(Self { + wanted_group, priority, max_delay, start_group, @@ -481,6 +493,12 @@ impl Message for SubscribeUpdate { self.end_frame, )?; + if !matches!( + version, + Version::Lite03 | Version::Lite04 | Version::Lite05 | Version::Lite06 + ) { + w.varint_opt(self.wanted_group)?; + } Ok(()) } } @@ -932,6 +950,34 @@ mod test { /// Lite-07 carries `Group Order` right after the priority, on SUBSCRIBE and /// SUBSCRIBE_UPDATE alike, and refuses a value it does not define. + #[test] + fn wanted_group_roundtrips_only_on_lite07() { + for version in [Version::Lite05, Version::Lite06, Version::Lite07] { + for wanted in [None, Some(0), Some(1), Some(u64::MAX - 1)] { + let update = SubscribeUpdate { + wanted_group: wanted, + priority: 0, + max_delay: std::time::Duration::ZERO, + start_group: None, + end_group: None, + start_frame: 0, + end_frame: None, + order: crate::track::Order::Descending, + }; + let buf = update.encode_bytes(version).unwrap(); + let got = crate::coding::decode_buf(&mut buf.as_ref(), version, SubscribeUpdate::decode).unwrap(); + assert_eq!( + got.wanted_group, + if matches!(version, Version::Lite07) { + wanted + } else { + None + } + ); + } + } + } + #[test] fn group_order_roundtrips_on_lite07() { use crate::track::Order; @@ -947,6 +993,7 @@ mod test { assert_eq!(got.order, order); let update = SubscribeUpdate { + wanted_group: None, priority: 3, max_delay: std::time::Duration::from_millis(250), start_group: None, diff --git a/rs/moq-net/src/lite/subscriber.rs b/rs/moq-net/src/lite/subscriber.rs index b7b55d2ed42..eb8e8af6e10 100644 --- a/rs/moq-net/src/lite/subscriber.rs +++ b/rs/moq-net/src/lite/subscriber.rs @@ -5138,7 +5138,7 @@ impl TrackServe { if start_moved { let _ = producer.start_at(active.start.map(|start| start.group)); } - buffer_update(active, subscription.end())?; + buffer_update(active, subscription.end(), None)?; } Ok(Begin::None) } @@ -5291,9 +5291,11 @@ enum Begin { fn buffer_update( active: &mut SubStream, end: Option, + wanted: Option, ) -> Result<(), Error> { let bounds = WireBounds::new(active.start, end); active.stream.writer.buffer(&lite::SubscribeUpdate { + wanted_group: wanted, priority: active.priority, max_delay: active.max_delay, start_group: bounds.start_group, @@ -5682,7 +5684,8 @@ impl TrackInfoFetch { let model = track::Info::default() .with_timescale(info.timescale) .with_max_age(info.max_age) - .with_priority(info.priority); + .with_priority(info.priority) + .with_refresh(info.refresh); return Poll::Ready(Ok((model, HeldTrack(stream)))); } } @@ -5712,6 +5715,8 @@ struct ServeLoop { /// through the producer's aggregate (including the resume floor after a source /// change). serving: track::Producer, + largest: Option, + wanted: Option, /// Watches `serving`'s subscribers, to release the copy once nobody reads it. demand: track::Demand, /// Serve on-demand fetches of uncached groups from this session. @@ -5922,6 +5927,8 @@ impl ServeLoop { let serving = request.accept(info); serving.received(); Self { + largest: None, + wanted: None, demand: serving.demand(), serving, dynamic, @@ -5956,7 +5963,10 @@ impl ServeLoop { let id = est.id; self.mode = ServeMode::Select; match res { - Ok(active) => self.sub = Sub::Active(active), + Ok(active) => { + self.wanted = None; + self.sub = Sub::Active(active); + } Err(err) => { // Opening the upstream failed (usually the session dying): hand // the track back for another route to resume. @@ -6048,6 +6058,30 @@ impl ServeLoop { Poll::Pending => {} } + // Each stream carries at most one outstanding refresh. Its new SUBSCRIBE + // already counted as a join at the upstream hop. + if matches!(serve.subscriber.version, Version::Lite07) { + if let Poll::Ready(Some(largest)) = self.serving.poll_largest(waiter) { + self.largest = Some(largest.group); + } + let _ = self.demand.poll_wanted_changed(waiter); + if let Sub::Active(active) = &mut self.sub + && let Some(largest) = self.largest + && self.wanted.is_none_or(|wanted| largest >= wanted) + && let Some(wanted) = self.demand.wanted().filter(|wanted| *wanted > largest) + { + self.wanted = Some(wanted); + if let Err(err) = buffer_update( + active, + self.serving.subscription().and_then(|sub| sub.end()), + Some(wanted), + ) { + return Poll::Ready(ServeEnd::GiveBack(err)); + } + continue; + } + } + // (2) In-flight fetches; completions just retire. The demand is settled, // so a held fetch with no feed open is a miss. let _ = self.fetches.poll(waiter); diff --git a/rs/moq-net/src/lite/track.rs b/rs/moq-net/src/lite/track.rs index bb8d5d4c706..adbaa6818b4 100644 --- a/rs/moq-net/src/lite/track.rs +++ b/rs/moq-net/src/lite/track.rs @@ -59,6 +59,8 @@ impl Message for Track<'_> { /// Lite05+ only. #[derive(Clone, Debug)] pub struct TrackInfo { + /// Refresh byte ratio, advertised on lite-07 only. + pub refresh: Option, /// The publisher's tie-break priority for this track. pub priority: u8, /// Publisher Max Age: an upper bound on how long the publisher caches a @@ -89,8 +91,19 @@ impl Message for TrackInfo { scale => Some(Timescale::new(scale).map_err(|_| DecodeError::InvalidValue)?), }; + let refresh = match version { + Version::Lite05 | Version::Lite06 => None, + _ => r + .varint()? + .checked_sub(1) + .map(u32::try_from) + .transpose() + .map_err(|_| DecodeError::InvalidValue)?, + }; + Ok(Self { priority, + refresh, max_age, timescale, }) @@ -111,6 +124,9 @@ impl Message for TrackInfo { }; w.varint(encoded)?; w.varint(version.wire_timescale(self.timescale).map_or(0, u64::from))?; + if !matches!(version, Version::Lite05 | Version::Lite06) { + w.varint(self.refresh.map_or(0, |ratio| u64::from(ratio) + 1))?; + } Ok(()) } } @@ -121,6 +137,7 @@ mod test { fn info_sample() -> TrackInfo { TrackInfo { + refresh: None, priority: 7, max_age: Some(Duration::from_millis(2000)), timescale: Some(Timescale::MICRO), @@ -135,6 +152,24 @@ mod test { crate::coding::decode_buf(&mut slice, version, TrackInfo::decode_msg).unwrap() } + #[test] + fn refresh_is_lite07_only() { + for version in [Version::Lite05, Version::Lite06, Version::Lite07] { + for ratio in [None, Some(0), Some(1), Some(u32::MAX)] { + let info = TrackInfo { + refresh: ratio, + ..info_sample() + }; + let expected = if matches!(version, Version::Lite07) { + ratio + } else { + None + }; + assert_eq!(info_roundtrip(version, &info).refresh, expected); + } + } + } + #[test] fn optional_max_age_roundtrips() { for version in [Version::Lite05, Version::Lite06, Version::Lite07] { @@ -208,6 +243,7 @@ mod test { fn track_info_defaults_match_cross_language_wire_bytes() { let info = crate::track::Info::default(); let info = TrackInfo { + refresh: None, priority: info.priority, max_age: info.max_age, // The default track is untimed, which lite-05 declares as milliseconds. @@ -276,6 +312,7 @@ mod test { #[test] fn track_info_roundtrips_varint_and_priority_bounds() { let info = TrackInfo { + refresh: None, priority: 255, max_age: None, timescale: Some(Timescale::new((1u64 << 62) - 1).unwrap()), @@ -289,6 +326,7 @@ mod test { #[test] fn track_info_encodes_sub_millisecond_max_age_as_zero() { let info = TrackInfo { + refresh: None, priority: 0, max_age: Some(Duration::from_nanos(999_999)), timescale: Some(Timescale::MILLI), @@ -301,6 +339,7 @@ mod test { fn track_info_encode_rejects_max_age_past_varint() { // Lite-07 varints carry the whole u64, and the age goes on the wire plus one. let info = TrackInfo { + refresh: None, priority: 7, max_age: Some(Duration::from_millis(u64::MAX)), timescale: Some(Timescale::MILLI), diff --git a/rs/moq-net/src/test_interop.rs b/rs/moq-net/src/test_interop.rs index 0911b3be94a..fdc8c2116f9 100644 --- a/rs/moq-net/src/test_interop.rs +++ b/rs/moq-net/src/test_interop.rs @@ -168,6 +168,7 @@ fn lite_varint_interop() { // An untimed track: zero on lite-07, milliseconds before it. let track_info = lite::TrackInfo { + refresh: None, priority: 1, max_age: None, timescale: None, diff --git a/rs/moq-net/tests/integration/main.rs b/rs/moq-net/tests/integration/main.rs index 7f2f87f934c..dfeacba826a 100644 --- a/rs/moq-net/tests/integration/main.rs +++ b/rs/moq-net/tests/integration/main.rs @@ -37,6 +37,7 @@ mod multi_cdn; mod partial_group; mod quiet_catalog; mod received_rewind; +mod refresh; mod rejoin; mod replacement; mod request_caps; diff --git a/rs/moq-net/tests/integration/refresh.rs b/rs/moq-net/tests/integration/refresh.rs new file mode 100644 index 00000000000..1886b874c0e --- /dev/null +++ b/rs/moq-net/tests/integration/refresh.rs @@ -0,0 +1,68 @@ +//! Refresh joins traverse two real protocol hops, judged independently from each cache. +use crate::support::harness::{MockConnectOptions, connect_mock, spawn}; +use moq_net::{Hop, Version, origin, track}; +use std::time::Duration; + +fn origin(hop: u64) -> origin::Producer { + let (origin, driver) = origin::Producer::new(origin::Config::new(Hop::new(hop).unwrap())); + spawn(driver); + origin +} + +#[moq_clock::test] +async fn ratio_joins_cross_two_relays() { + for name in ["moq-lite-06", "moq-lite-07-wip"] { + let version: Version = name.parse().unwrap(); + let source = origin(1); + let a = origin(2); + let b = origin(3); + let broadcast = source.create_broadcast("room").unwrap(); + let producer = broadcast + .create_track("data", track::Info::default().with_refresh(1)) + .unwrap(); + broadcast.announce(Default::default()).unwrap(); + let mut links = Vec::new(); + for (upstream, downstream) in [(&source, &a), (&a, &b)] { + let mut options = MockConnectOptions::new(version); + options.server_publish = Some(upstream.consume()); + options.client_subscribe = Some(downstream.clone()); + links.push(connect_mock(options).await); + } + b.consume().routed("room").await.unwrap(); + let remote = b.consume().request_broadcast("room", None).await.unwrap(); + let remote = remote.track("data").unwrap(); + let mut baseline = remote.subscribe(None).await.unwrap(); + assert_eq!(baseline.info().refresh, (name == "moq-lite-07-wip").then_some(1)); + crate::support::harness::subscribed(&producer).await; + let mut group = producer.append_group().unwrap(); + group.write_frame(None, &b"key"[..]).unwrap(); + group.write_frame(None, &b"abc"[..]).unwrap(); + let mut received = baseline.recv_group().await.unwrap().unwrap(); + assert_eq!(received.read_frame().await.unwrap().unwrap().payload.len(), 3); + assert_eq!(received.read_frame().await.unwrap().unwrap().payload.len(), 3); + let mut under = remote.subscribe(None).await.unwrap(); + let _under_group = under.recv_group().await.unwrap().unwrap(); + assert_eq!(producer.demand().wanted(), Some(0), "ratio equality does not refresh"); + group.write_frame(None, &b"d"[..]).unwrap(); + assert_eq!(received.read_frame().await.unwrap().unwrap().payload.len(), 1); + let mut joins = Vec::new(); + for _ in 0..8 { + let mut join = remote.subscribe(None).await.unwrap(); + let _group = join.recv_group().await.unwrap().unwrap(); + joins.push(join); + } + if name == "moq-lite-07-wip" { + let mut demand = producer.demand(); + moq_clock::timeout(Duration::from_secs(1), async { + while demand.wanted_changed().await.unwrap() != Some(1) {} + }) + .await + .unwrap(); + } else { + // Drain runnable protocol tasks on simulated time, without a wall-clock sleep. + moq_clock::sleep(Duration::from_millis(1)).await; + assert_eq!(producer.demand().wanted(), Some(0)); + } + drop((joins, under, received, baseline, group, links)); + } +} diff --git a/sh/gh/nightly.sh b/sh/gh/nightly.sh index 7ee65793ab0..4b7ace02b7f 100755 --- a/sh/gh/nightly.sh +++ b/sh/gh/nightly.sh @@ -102,7 +102,7 @@ case "$1" in done ;; js) - for benchmark in broadcasts request-ids requests forward reader frames varint lite-varint track resume interests priority; do + for benchmark in broadcasts request-ids requests forward reader frames varint lite-varint track resume interests priority refresh; do javascript "$benchmark" just js bench "$benchmark" done javascript catalog just js catalog-bench From acbe465a096e52f964b9fd3756b3d53a9d2bb215 Mon Sep 17 00:00:00 2001 From: Luke Curley <432854+kixelated@users.noreply.github.com> Date: Mon, 19 Oct 2026 18:49:39 -0700 Subject: [PATCH 03/14] test(lite): cover refresh codec bounds and stale requests Co-Authored-By: GPT-6.1-Sol --- js/net/src/lite/subscribe.test.ts | 19 +++++++++++++++---- js/net/src/lite/track.test.ts | 10 ++++++---- rs/moq-net/src/lite/publisher.rs | 4 ++-- 3 files changed, 23 insertions(+), 10 deletions(-) diff --git a/js/net/src/lite/subscribe.test.ts b/js/net/src/lite/subscribe.test.ts index 79496e96400..2fb8710658b 100644 --- a/js/net/src/lite/subscribe.test.ts +++ b/js/net/src/lite/subscribe.test.ts @@ -315,9 +315,20 @@ test.each([Version.DRAFT_03, Version.DRAFT_05, Version.DRAFT_06])( test("wanted group survives lite-07 and disappears on legacy wires", async () => { for (const version of [Version.DRAFT_05, Version.DRAFT_06, Version.DRAFT_07]) { - const update = new SubscribeUpdate({ priority: 7, wantedGroup: 3 }); - const encoded = await encodeMessage(version, update); - const decoded = await SubscribeUpdate.decode(new Reader(undefined, encoded, version), version); - expect(decoded.wantedGroup).toBe(version === Version.DRAFT_07 ? 3 : undefined); + for (const wantedGroup of [undefined, 0, 3, Number.MAX_SAFE_INTEGER]) { + const update = new SubscribeUpdate({ priority: 7, wantedGroup }); + const encoded = await encodeMessage(version, update); + const decoded = await SubscribeUpdate.decode(new Reader(undefined, encoded, version), version); + expect(decoded.wantedGroup).toBe(version === Version.DRAFT_07 ? wantedGroup : undefined); + } + } +}); + +test("wanted groups refuse malformed input before writing bytes", async () => { + for (const wantedGroup of [-1, 0.5, Number.MAX_SAFE_INTEGER + 1, Number.NaN]) { + expect(() => new SubscribeUpdate({ priority: 0, wantedGroup })).toThrow(RangeError); + const update = new SubscribeUpdate({ priority: 0 }); + update.wantedGroup = wantedGroup; + await expect(encodeMessage(Version.DRAFT_07, update)).rejects.toThrow(RangeError); } }); diff --git a/js/net/src/lite/track.test.ts b/js/net/src/lite/track.test.ts index e33fab530c0..e0c776bf829 100644 --- a/js/net/src/lite/track.test.ts +++ b/js/net/src/lite/track.test.ts @@ -204,9 +204,11 @@ for (const version of [Version.DRAFT_05, Version.DRAFT_06]) { test("refresh ratio survives lite-07 and disappears on legacy wires", async () => { for (const version of [Version.DRAFT_05, Version.DRAFT_06, Version.DRAFT_07]) { - const info = new TrackInfo({ priority: 7, refresh: 3 }); - const encoded = await bytes((w) => info.encode(w, version), version); - const decoded = await TrackInfo.decode(new Reader(undefined, encoded, version), version); - expect(decoded.refresh).toBe(version === Version.DRAFT_07 ? 3 : undefined); + for (const refresh of [undefined, 0, 3, 0xffff_ffff]) { + const info = new TrackInfo({ priority: 7, refresh }); + const encoded = await bytes((w) => info.encode(w, version), version); + const decoded = await TrackInfo.decode(new Reader(undefined, encoded, version), version); + expect(decoded.refresh).toBe(version === Version.DRAFT_07 ? refresh : undefined); + } } }); diff --git a/rs/moq-net/src/lite/publisher.rs b/rs/moq-net/src/lite/publisher.rs index 778f4cd174f..8e9a7cc2809 100644 --- a/rs/moq-net/src/lite/publisher.rs +++ b/rs/moq-net/src/lite/publisher.rs @@ -4718,9 +4718,9 @@ mod serve_group_test { group.write_frame(None, &b"key"[..]).unwrap(); group.finish().unwrap(); run.update(update(Some(1))); - assert_eq!(track.demand().wanted(), Some(0), "answered request stays answered"); + assert_eq!(track.demand().wanted(), Some(1), "answered request stays answered"); run.update(update(Some(2))); - assert_eq!(track.demand().wanted(), Some(0), "new hop judges its own ratio"); + assert_eq!(track.demand().wanted(), Some(1), "new hop judges its own ratio"); } fn write_group(track: &mut track::Producer, sequence: u64, millis: u64) { From f24b5e5a4dd4a96e075fed8b137967bf78407af5 Mon Sep 17 00:00:00 2001 From: Luke Curley <432854+kixelated@users.noreply.github.com> Date: Mon, 19 Oct 2026 18:50:27 -0700 Subject: [PATCH 04/14] docs(net): mark private refresh wire hooks Co-Authored-By: GPT-6.1-Sol --- js/net/src/internal.ts | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/js/net/src/internal.ts b/js/net/src/internal.ts index dc231a5c227..1d2a45c80ad 100644 --- a/js/net/src/internal.ts +++ b/js/net/src/internal.ts @@ -344,6 +344,12 @@ export const hooks: { * a higher one. Mirrors the Rust `finish_at_pending`; assigned by `track.ts`. */ endTrack: (producer: Producer, end: Location) => void; + // private: passthrough + /** Re-evaluate a live-edge join at this subscriber's copy. */ + joinSubscriber: (subscriber: Subscriber) => void; + /** Re-evaluate a live-edge join at a producer. */ + joinProducer: (producer: Producer) => void; + // pending: /quest/m1/public-model/deferred.md /** * Declare the first group a wire subscription's live feed serves (lite SUBSCRIBE_START, or @@ -351,10 +357,6 @@ export const hooks: { * that floor, a pending tail owes nothing below it. Mirrors the Rust `start_at`; assigned by * `track.ts`. */ - /** Re-evaluate a live-edge join at this subscriber's copy. */ - joinSubscriber: (subscriber: Subscriber) => void; - /** Re-evaluate a live-edge join at a producer. */ - joinProducer: (producer: Producer) => void; startTrack: (producer: Producer, served: { start: number; requested?: number }) => void; // pending: /quest/m1/public-model/ingest.md /** @@ -369,6 +371,7 @@ export const hooks: { pendingTrackProducer: (request: Request) => Producer; /** Have a producer write through a broadcast's sequence namespace for its name. */ bindSequence: (producer: Producer, sequence: TrackSequence) => void; + // private: capability gap /** The newest frame a producer's cache holds, read without subscribing; assigned by `track.ts`. */ cachedLargest: (producer: Producer) => Location | undefined; // private: capability gap From fa334fc2d302edf4eb3bae10f6249f8af63ba1c8 Mon Sep 17 00:00:00 2001 From: Luke Curley <432854+kixelated@users.noreply.github.com> Date: Mon, 19 Oct 2026 18:53:19 -0700 Subject: [PATCH 05/14] perf(lite): watch largest directly when forwarding refresh Co-Authored-By: GPT-6.1-Sol --- js/net/bench/refresh.ts | 135 +++++++++++++++++++--------------- js/net/src/internal.ts | 8 +- js/net/src/lite/subscriber.ts | 10 ++- js/net/src/track.ts | 1 + 4 files changed, 91 insertions(+), 63 deletions(-) diff --git a/js/net/bench/refresh.ts b/js/net/bench/refresh.ts index c26c3a3079c..1cfccd18b8c 100644 --- a/js/net/bench/refresh.ts +++ b/js/net/bench/refresh.ts @@ -1,4 +1,4 @@ -/** Sweep unrelated tracks and joined readers for a refresh crossing one lite hop. */ +/** Sweep retained groups, unrelated tracks, and joined readers for a refresh crossing one lite hop. */ import { Manual, Nano } from "@moq/clock"; import { accept } from "../src/connection/accept.ts"; import { connect } from "../src/connection/connect.ts"; @@ -8,64 +8,79 @@ import { Producer } from "../src/origin.ts"; import * as Path from "../src/path.ts"; console.debug = () => {}; -console.log("tracks,joined,refresh_us"); -for (const tracks of [1, 8, 32]) - for (const joined of [1, 8, 32]) { - const clock = new Manual(); - const restore = clock.install(); - const source = new Producer(); - const destination = new Producer(); - const broadcast = source.createBroadcast(Path.from("room")); - broadcast.announce(); - const producers = Array.from({ length: tracks }, (_, i) => broadcast.createTrack(`data${i}`, { refresh: 1 })); - const pair = createMockTransportPair(ALPN_07_WIP); - const url = new URL("https://localhost/refresh"); - const peers = await Promise.all([ - connect({ url, transport: pair.client, consume: destination }), - accept({ url, transport: pair.server, publish: source.consume() }), - ]); - try { - const announcements = destination.announced(); - while ((await announcements.next())?.kind !== "start") {} - const request = destination.request(Path.from("room")); - while (!request.active.peek()) await request.active.changed(); - const remote = request.active.peek()!; - const consumers = producers.map((_, i) => remote.track(`data${i}`)); - const baseline = consumers.map((track) => track.subscribe()); - for (let i = 0; i < tracks; i++) { - const group = producers[i].appendGroup(); - group.writeFrame({ payload: new Uint8Array(3) }); - group.close(); - const received = (await baseline[i].recvGroup())!; - await received.readFrame(); - received.close(); - } - const samples: number[] = []; - for (let round = 0; round < 9; round++) { - const group = producers[0].appendGroup(); - group.writeFrame({ payload: new Uint8Array(3) }); - group.writeFrame({ payload: new Uint8Array(4) }); - group.close(); - const received = (await baseline[0].recvGroup())!; - await received.readFrame(); - await received.readFrame(); - received.close(); - const start = performance.now(); - const joins = Array.from({ length: joined }, () => consumers[0].subscribe()); - const wanted = producers[0].demand().wanted; - while (wanted.peek() !== group.sequence + 1) await wanted.changed(); - if (round > 0) samples.push((performance.now() - start) * 1000); - for (const join of joins) join.close(); +console.log("retained,tracks,joined,refresh_us"); +for (const retained of [1, 64, 1024]) + for (const tracks of [1, 8, 32]) + for (const joined of [1, 8, 32]) { + const clock = new Manual(); + const restore = clock.install(); + const source = new Producer(); + const destination = new Producer(); + const broadcast = source.createBroadcast(Path.from("room")); + broadcast.announce(); + const producers = Array.from({ length: tracks }, (_, i) => + broadcast.createTrack(`data${i}`, { refresh: 1 }), + ); + const pair = createMockTransportPair(ALPN_07_WIP); + const url = new URL("https://localhost/refresh"); + const peers = await Promise.all([ + connect({ url, transport: pair.client, consume: destination }), + accept({ url, transport: pair.server, publish: source.consume() }), + ]); + try { + const announcements = destination.announced(); + while ((await announcements.next())?.kind !== "start") {} + const request = destination.request(Path.from("room")); + while (!request.active.peek()) await request.active.changed(); + const remote = request.active.peek()!; + const consumers = producers.map((_, i) => remote.track(`data${i}`)); + const baseline = consumers.map((track) => track.subscribe()); + for (let i = 0; i < tracks; i++) { + const group = producers[i].appendGroup(); + group.writeFrame({ payload: new Uint8Array(3) }); + group.close(); + const received = (await baseline[i].recvGroup())!; + await received.readFrame(); + received.close(); + } + // Keep this track's historical groups in its cache. Only the touched + // track grows, so scanning that cache appears independently of fanout. + for (let old = 1; old < retained; old++) { + const group = producers[0].appendGroup(); + group.writeFrame({ payload: new Uint8Array(3) }); + group.close(); + const received = await baseline[0].recvGroup(); + if (!received) throw new Error("historical group missing"); + await received.readFrame(); + received.close(); + } + + const samples: number[] = []; + for (let round = 0; round < 9; round++) { + const group = producers[0].appendGroup(); + group.writeFrame({ payload: new Uint8Array(3) }); + group.writeFrame({ payload: new Uint8Array(4) }); + group.close(); + const received = (await baseline[0].recvGroup())!; + await received.readFrame(); + await received.readFrame(); + received.close(); + const start = performance.now(); + const joins = Array.from({ length: joined }, () => consumers[0].subscribe()); + const wanted = producers[0].demand().wanted; + while (wanted.peek() !== group.sequence + 1) await wanted.changed(); + if (round > 0) samples.push((performance.now() - start) * 1000); + for (const join of joins) join.close(); + } + samples.sort((a, b) => a - b); + console.log(`${retained},${tracks},${joined},${samples[4].toFixed(2)}`); + for (const sub of baseline) sub.close(); + request.close(); + } finally { + destination.close(); + source.close(); + for (const peer of peers) peer.abort(); + await clock.advanceAsync(Nano(0)); + restore(); } - samples.sort((a, b) => a - b); - console.log(`${tracks},${joined},${samples[4].toFixed(2)}`); - for (const sub of baseline) sub.close(); - request.close(); - } finally { - destination.close(); - source.close(); - for (const peer of peers) peer.abort(); - await clock.advanceAsync(Nano(0)); - restore(); } - } diff --git a/js/net/src/internal.ts b/js/net/src/internal.ts index 1d2a45c80ad..b04d3ac489c 100644 --- a/js/net/src/internal.ts +++ b/js/net/src/internal.ts @@ -344,6 +344,10 @@ export const hooks: { * a higher one. Mirrors the Rust `finish_at_pending`; assigned by `track.ts`. */ endTrack: (producer: Producer, end: Location) => void; + // private: capability gap + /** The producer's largest reported location and its subsequent changes. */ + producerLargest: (producer: Producer) => Getter; + // private: passthrough /** Re-evaluate a live-edge join at this subscriber's copy. */ joinSubscriber: (subscriber: Subscriber) => void; @@ -371,7 +375,6 @@ export const hooks: { pendingTrackProducer: (request: Request) => Producer; /** Have a producer write through a broadcast's sequence namespace for its name. */ bindSequence: (producer: Producer, sequence: TrackSequence) => void; - // private: capability gap /** The newest frame a producer's cache holds, read without subscribing; assigned by `track.ts`. */ cachedLargest: (producer: Producer) => Location | undefined; // private: capability gap @@ -497,6 +500,9 @@ export const hooks: { endTrack: () => { throw new Error("track.ts not loaded"); }, + producerLargest: () => { + throw new Error("track.ts not loaded"); + }, joinProducer: () => { throw new Error("track.ts not loaded"); }, diff --git a/js/net/src/lite/subscriber.ts b/js/net/src/lite/subscriber.ts index 496e8cbb6a5..252a589cdba 100644 --- a/js/net/src/lite/subscriber.ts +++ b/js/net/src/lite/subscriber.ts @@ -1297,8 +1297,9 @@ export class Subscriber { let pendingWanted: number | undefined; const demand = track.demand(); + const edge = hooks.producerLargest(track); for (;;) { - const largest = hooks.cachedLargest(track)?.group; + const largest = edge.peek()?.group; const wanted = demand.wanted.peek(); const refresh = this.version === Version.DRAFT_07 && @@ -1311,7 +1312,12 @@ export class Subscriber { const current = track.subscription.peek(); if (current === undefined || (refresh === undefined && this.#sameSubscription(current, lastSent))) { // Nothing new to send; wait for a change or termination. - const next = await race([track.subscription.changed(), demand.wanted.changed(), stopped]); + const next = await race([ + track.subscription.changed(), + demand.wanted.changed(), + edge.changed(), + stopped, + ]); if (next === null) return; continue; } diff --git a/js/net/src/track.ts b/js/net/src/track.ts index a4c6e12c1db..89b797ea036 100644 --- a/js/net/src/track.ts +++ b/js/net/src/track.ts @@ -721,6 +721,7 @@ export class Producer { } static { + hooks.producerLargest = (producer) => producer.#state.largest; hooks.joinProducer = (producer) => producer.#join(); hooks.endTrack = (producer, end) => producer.#endPending(end); hooks.startTrack = (producer, served) => { From 22b3e9d41e52b112183fe6fe803d24dd30ee19c4 Mon Sep 17 00:00:00 2001 From: Luke Curley <432854+kixelated@users.noreply.github.com> Date: Mon, 19 Oct 2026 19:03:33 -0700 Subject: [PATCH 06/14] test(lite): run refresh request fixture on the simulated clock Co-Authored-By: GPT-6.1-Sol --- rs/moq-net/src/lite/publisher.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/rs/moq-net/src/lite/publisher.rs b/rs/moq-net/src/lite/publisher.rs index 8e9a7cc2809..8bb75e07570 100644 --- a/rs/moq-net/src/lite/publisher.rs +++ b/rs/moq-net/src/lite/publisher.rs @@ -4687,8 +4687,8 @@ mod serve_group_test { (TrackRun::new(ctx, track, bounds, steer), writer, log) } - #[test] - fn wanted_updates_ignore_stale_groups_and_recheck_the_ratio() { + #[moq_clock::test] + async fn wanted_updates_ignore_stale_groups_and_recheck_the_ratio() { let track = track::Producer::new( Arc::new(broadcast::Info::default()), "refresh", From 18a765ca00f8c63044e106d1b262cbdee5873ef8 Mon Sep 17 00:00:00 2001 From: Luke Curley <432854+kixelated@users.noreply.github.com> Date: Mon, 19 Oct 2026 19:23:16 -0700 Subject: [PATCH 07/14] test(lite): gate relay refresh integration on async support Co-Authored-By: GPT-6.1-Sol --- rs/moq-net/tests/integration/refresh.rs | 2 ++ 1 file changed, 2 insertions(+) diff --git a/rs/moq-net/tests/integration/refresh.rs b/rs/moq-net/tests/integration/refresh.rs index 1886b874c0e..2c11334e23f 100644 --- a/rs/moq-net/tests/integration/refresh.rs +++ b/rs/moq-net/tests/integration/refresh.rs @@ -1,3 +1,5 @@ +#![cfg(feature = "async")] + //! Refresh joins traverse two real protocol hops, judged independently from each cache. use crate::support::harness::{MockConnectOptions, connect_mock, spawn}; use moq_net::{Hop, Version, origin, track}; From 59618c8ecc9e13e5624c0461c61cbf6a97ec1dfd Mon Sep 17 00:00:00 2001 From: Luke Curley <432854+kixelated@users.noreply.github.com> Date: Mon, 19 Oct 2026 19:31:33 -0700 Subject: [PATCH 08/14] docs(lite): clarify refresh update helper Co-Authored-By: GPT-6.1-Sol --- rs/moq-net/src/lite/subscriber.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/rs/moq-net/src/lite/subscriber.rs b/rs/moq-net/src/lite/subscriber.rs index eb8e8af6e10..5e20cd0750f 100644 --- a/rs/moq-net/src/lite/subscriber.rs +++ b/rs/moq-net/src/lite/subscriber.rs @@ -5286,8 +5286,8 @@ enum Begin { Establish(Establish), } -/// Buffer a SUBSCRIBE_UPDATE echoing the current params, varying only the end -/// bound. The caller flushes. +/// Buffer the current SUBSCRIBE parameters with an updated end and optional refresh join. +/// The caller flushes. fn buffer_update( active: &mut SubStream, end: Option, From 220e48cebfa71e6cf29f0b9bfc67515a1b1d6022 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 19 Oct 2026 22:58:30 -0700 Subject: [PATCH 09/14] refactor(lite): gate refresh fields on a version helper Add has_refresh/hasRefresh in the existing default-forward form and use it for TRACK_INFO Refresh, SUBSCRIBE_UPDATE Wanted Group and the relay's upstream driver, which previously only matched lite-07 exactly. Add a unit test that concurrent joins send one SUBSCRIBE_UPDATE and the arrival of the requested group re-arms the next. Fix a doc comment the new codec test split from its test, simplify the JS refresh test setup, and retire the finished lite wire quest. Co-Authored-By: Claude Opus 5.5 --- drafts/draft-lcurley-moq-lite.md | 2 +- js/net/src/lite/refresh.test.ts | 21 ++++++-------- js/net/src/lite/subscribe.ts | 6 ++-- js/net/src/lite/subscriber.ts | 3 +- js/net/src/lite/track.ts | 6 ++-- js/net/src/lite/version.ts | 17 +++++++++++ quest/m1/ietf-extension/lite.md | 5 ++-- quest/m1/lite07-finalize.md | 1 - quest/m1/refresh/README.md | 1 - quest/m1/refresh/lite.md | 46 ----------------------------- rs/moq-net/src/lite/subscribe.rs | 29 ++++++------------- rs/moq-net/src/lite/subscriber.rs | 48 ++++++++++++++++++++++++++++++- rs/moq-net/src/lite/track.rs | 14 ++++----- rs/moq-net/src/lite/version.rs | 12 ++++++++ 14 files changed, 109 insertions(+), 102 deletions(-) delete mode 100644 quest/m1/refresh/lite.md diff --git a/drafts/draft-lcurley-moq-lite.md b/drafts/draft-lcurley-moq-lite.md index 3e031065f79..8bbf55dad61 100644 --- a/drafts/draft-lcurley-moq-lite.md +++ b/drafts/draft-lcurley-moq-lite.md @@ -1292,7 +1292,7 @@ An optional unsigned 32-bit byte ratio, encoded as the ratio plus one; `0` disab On a live-edge join, a publisher asks for a group beyond every sequence already produced when the newest group's bytes after its first frame exceed the ratio times that first frame's bytes. Joins coalesce until the requested group arrives. A relay preserves the ratio and evaluates joins against its own cache, forwarding demand in SUBSCRIBE_UPDATE. -Lite-05/06 omit Refresh and Wanted Group; a Track received on those versions never refreshes. +Versions before lite-07 omit Refresh and Wanted Group; a Track received on those versions never refreshes. ## SUBSCRIBE_OK {#subscribe-ok} A SUBSCRIBE_OK message confirms a subscription and resolves its absolute start position. diff --git a/js/net/src/lite/refresh.test.ts b/js/net/src/lite/refresh.test.ts index 2e76ec5fb26..c944d0cf6d8 100644 --- a/js/net/src/lite/refresh.test.ts +++ b/js/net/src/lite/refresh.test.ts @@ -16,8 +16,8 @@ test.each([ALPN_06, ALPN_07_WIP])("refresh joins reach a browser publisher on %s const broadcast = source.createBroadcast(Path.from("room")); broadcast.announce(); const producer = broadcast.createTrack("data", { refresh: 1 }); - const transports = [createMockTransportPair(alpn)]; - const peers = []; + const pair = createMockTransportPair(alpn); + const url = new URL("https://localhost/refresh"); const updates: number[] = []; const encode = SubscribeUpdate.prototype.encode; const spy = spyOn(SubscribeUpdate.prototype, "encode").mockImplementation(function ( @@ -28,17 +28,14 @@ test.each([ALPN_06, ALPN_07_WIP])("refresh joins reach a browser publisher on %s if (this.wantedGroup !== undefined) updates.push(this.wantedGroup); return encode.call(this, writer, version); }); + const peers: { abort(): void }[] = []; try { - for (const [index, [upstream, downstream]] of [[source, b]].entries()) { - const pair = transports[index]; - const url = new URL("https://localhost/refresh"); - peers.push( - ...(await Promise.all([ - connect({ url, transport: pair.client, consume: downstream }), - accept({ url, transport: pair.server, publish: upstream.consume() }), - ])), - ); - } + peers.push( + ...(await Promise.all([ + connect({ url, transport: pair.client, consume: b }), + accept({ url, transport: pair.server, publish: source.consume() }), + ])), + ); const announcements = b.announced(); while ((await announcements.next())?.kind !== "start") {} const request = b.request(Path.from("room")); diff --git a/js/net/src/lite/subscribe.ts b/js/net/src/lite/subscribe.ts index 82bc40f4bb1..b2a6903997d 100644 --- a/js/net/src/lite/subscribe.ts +++ b/js/net/src/lite/subscribe.ts @@ -5,7 +5,7 @@ import type { Reader, Writer } from "../stream.ts"; import type { Location, Order } from "../track.ts"; import { decodeEpoch, encodeEpoch } from "./epoch.ts"; import * as Message from "./message.ts"; -import { hasFrameBounds, hasGroupOrder, hasLargest, hasOrder, resolvesStart, Version } from "./version.ts"; +import { hasFrameBounds, hasGroupOrder, hasLargest, hasOrder, hasRefresh, resolvesStart, Version } from "./version.ts"; /** * Encode the `Group Start` field shared by SUBSCRIBE and SUBSCRIBE_UPDATE. @@ -230,7 +230,7 @@ export class SubscribeUpdate { await encodeStartGroup(w, version, this.startGroup); await w.u53(this.endGroup !== undefined ? this.endGroup + 1 : 0); await encodeFrameBounds(w, version, this); - if (version === Version.DRAFT_07) + if (hasRefresh(version)) await w.u62(this.wantedGroup === undefined ? 0n : BigInt(this.wantedGroup) + 1n); break; } @@ -249,7 +249,7 @@ export class SubscribeUpdate { const endGroup = (await r.u53()) || undefined; const end = endGroup !== undefined ? endGroup - 1 : undefined; const frames = await decodeFrameBounds(r, version, startGroup, end); - const wanted = version === Version.DRAFT_07 ? await r.u62() : 0n; + const wanted = hasRefresh(version) ? await r.u62() : 0n; if (wanted > BigInt(Number.MAX_SAFE_INTEGER) + 1n) throw new RangeError("wanted group exceeds safe integer"); return new SubscribeUpdate({ diff --git a/js/net/src/lite/subscriber.ts b/js/net/src/lite/subscriber.ts index 0e313232514..9ab999fd2c1 100644 --- a/js/net/src/lite/subscriber.ts +++ b/js/net/src/lite/subscriber.ts @@ -57,6 +57,7 @@ import { hasFetchMaxDelay, hasOrder, hasProbeRtt, + hasRefresh, resolvesStart, updateSupported, Version, @@ -1327,7 +1328,7 @@ export class Subscriber { const largest = edge.peek()?.group; const wanted = demand.wanted.peek(); const refresh = - this.version === Version.DRAFT_07 && + hasRefresh(this.version) && largest !== undefined && (pendingWanted === undefined || largest >= pendingWanted) && wanted !== undefined && diff --git a/js/net/src/lite/track.ts b/js/net/src/lite/track.ts index c787b580246..33b2e8b5141 100644 --- a/js/net/src/lite/track.ts +++ b/js/net/src/lite/track.ts @@ -4,7 +4,7 @@ import type { Reader, Writer } from "../stream.ts"; import { Timescale } from "../time.ts"; import { decodeEpoch, encodeEpoch } from "./epoch.ts"; import * as Message from "./message.ts"; -import { hasGroupOrder, Version, wireTimescale } from "./version.ts"; +import { hasGroupOrder, hasRefresh, Version, wireTimescale } from "./version.ts"; // The Track Stream (0x6) is draft-05+ only. function guardTrack(version: Version) { @@ -114,7 +114,7 @@ export class TrackInfo { const age = this.maxAge === undefined ? undefined : BigInt(this.maxAge); await w.u62(legacy ? (age ?? BigInt(Number.MAX_SAFE_INTEGER)) : age === undefined ? 0n : age + 1n); await w.u53(wireTimescale(version, this.timescale) ?? 0); - if (!legacy) await w.u53(this.refresh === undefined ? 0 : this.refresh + 1); + if (hasRefresh(version)) await w.u53(this.refresh === undefined ? 0 : this.refresh + 1); } static async #decode(r: Reader, version: Version): Promise { @@ -135,7 +135,7 @@ export class TrackInfo { // Lite-05/06 have no untimed encoding, so zero is malformed there. const scale = await r.u53(); const timescale = scale === 0 && !legacy ? undefined : Timescale(scale); - const refresh = legacy ? undefined : (await r.u53()) - 1; + const refresh = hasRefresh(version) ? (await r.u53()) - 1 : undefined; return new TrackInfo({ priority, maxAge, timescale, refresh: refresh === -1 ? undefined : refresh }); } diff --git a/js/net/src/lite/version.ts b/js/net/src/lite/version.ts index a101718c189..9bbb9f2530b 100644 --- a/js/net/src/lite/version.ts +++ b/js/net/src/lite/version.ts @@ -355,6 +355,23 @@ export function hasAnnounceCompression(version: Version): boolean { } } +/** Whether TRACK_INFO carries the refresh ratio and SUBSCRIBE_UPDATE a wanted group. Added in lite-07. + * Older peers see a track that never refreshes. */ +export function hasRefresh(version: Version): boolean { + // Explicitly list older versions so future versions keep the lite-07+ behavior. + switch (version) { + case Version.DRAFT_01: + case Version.DRAFT_02: + case Version.DRAFT_03: + case Version.DRAFT_04: + case Version.DRAFT_05: + case Version.DRAFT_06: + return false; + default: + return true; + } +} + /// The WebTransport subprotocol identifier for moq-lite. /// Version negotiation still happens via SETUP when this is used. export const ALPN = "moql"; diff --git a/quest/m1/ietf-extension/lite.md b/quest/m1/ietf-extension/lite.md index 7abbe62a543..fbfb48b122e 100644 --- a/quest/m1/ietf-extension/lite.md +++ b/quest/m1/ietf-extension/lite.md @@ -36,7 +36,8 @@ Decided 2026-10-13 (see the [epic](/quest/m1/ietf-extension/README.md)). unchanged inner bytes, so downstream IETF egress can refuse incompatible encodings. - Dynamic-group requests are not this extension's job. Native lite-07 - carries them as [refresh](/quest/m1/refresh/lite.md), decided 2026-10-16. + carries them as refresh (TRACK_INFO `Refresh` and SUBSCRIBE_UPDATE + `Wanted Group`), decided 2026-10-16. - Write `drafts/draft-lcurley-moq-ietf.md` for the extension and pass `just drafts check`. List it with the other project drafts in `doc/concept/standard.md`, and note in `doc/bin/relay/` that relays enable @@ -56,6 +57,4 @@ and the framing above, only when negotiated. ## Related -- [Refresh on the lite wire](/quest/m1/refresh/lite.md) - carries dynamic-group requests between relays instead of this extension - - [Finalize moq-lite-07](/quest/m1/lite07-finalize.md) - the extension targets the wip version and does not gate the cut diff --git a/quest/m1/lite07-finalize.md b/quest/m1/lite07-finalize.md index 9def8517eeb..7e5b829d113 100644 --- a/quest/m1/lite07-finalize.md +++ b/quest/m1/lite07-finalize.md @@ -87,7 +87,6 @@ is published; older versions are unchanged. - [Readers see SUBSCRIBE_DROP](/quest/m1/subscribe-drop-errors.md) - settles what lite-07's DROP Error Code means - [Subscribe ranges](/quest/m1/subscribe-ranges/README.md) - SUBSCRIBE carries ranges and an order and lite FETCH is gone, in Rust and JS - [Announcement takeover](/quest/m1/announce-takeover.md) - ANNOUNCE_TAKEOVER preserves a proven instance under a new independent route -- [Refresh on the lite wire](/quest/m1/refresh/lite.md) - TRACK_INFO carries the refresh ratio and SUBSCRIBE_UPDATE the wanted group - [Compressed tracks in Rust](/quest/m1/compress/core.md) - TRACK_INFO carries the compress flag and the frame header each compressed frame's inflated size - [Compressed tracks in js/net](/quest/m1/compress/js.md) - JS reads and writes compressed lite-07 tracks instead of refusing them - [TRACKS](/quest/m1/archive/tracks.md) - lite-07 carries the request listing a broadcast's tracks as they appear diff --git a/quest/m1/refresh/README.md b/quest/m1/refresh/README.md index 708e994f19d..af813a7d571 100644 --- a/quest/m1/refresh/README.md +++ b/quest/m1/refresh/README.md @@ -62,7 +62,6 @@ Work owned by this README, after the children land: ## Required -- [Lite wire](/quest/m1/refresh/lite.md) - lite-07 TRACK_INFO advertises the ratio and SUBSCRIBE_UPDATE carries the wanted group, so a join at any relay reaches the origin - [moq-json](/quest/m1/refresh/json.md) - snapshot and window groups roll on a qualifying join, reading the ratio from the track; `delta_ratio` and `op_ratio` become `deltas` and `ops` switches in every binding - [Video](/quest/m1/refresh/video.md) - video publishers advertise refresh and force a keyframe on demand, keeping the encoder's max GOP diff --git a/quest/m1/refresh/lite.md b/quest/m1/refresh/lite.md deleted file mode 100644 index 8ed29cc630e..00000000000 --- a/quest/m1/refresh/lite.md +++ /dev/null @@ -1,46 +0,0 @@ -# [M] Refresh on the moq-lite wire - -## Goal - -On lite-07, a track's refresh ratio reaches every subscriber in -TRACK_INFO. A join at any relay that crosses the ratio reaches the origin -publisher's `Demand::wanted`, through a relay cluster, in Rust and JS. A -peer on an older lite version sees a track that never refreshes. - -## Plan - -Decided 2026-10-16 (see the [epic](/quest/m1/refresh/README.md)). - -- **TRACK_INFO** gains a `Refresh` varint: 0 for none, otherwise ratio + 1, - matching how lite-07 encodes Publisher Max Age. lite-07 only, while it is - the wip version. This quest gates the - [lite-07 cut](/quest/m1/lite07-finalize.md), because missing it would push - core-message fields to lite-08. -- **SUBSCRIBE needs no field.** A new SUBSCRIBE is itself a join at the - upstream hop, which evaluates the ratio against its own cache. -- **SUBSCRIBE_UPDATE** gains a `Wanted Group` varint: 0 for none, otherwise - sequence + 1. A relay's upstream driver sends it when its track's - `Demand::wanted` passes the largest group. It sends nothing more until the - largest group reaches it, so redundant downstream joins coalesce at every - hop. Clear it with the subscription, so a reconnect inherits nothing. -- **Receiving it** counts as a join under the ratio at that hop, like a - downstream IETF NEW_GROUP_REQUEST. A stale value at or below the largest - group is ignored. -- **js/net** encodes and decodes both fields and feeds its `Demand::wanted`, - so a browser publisher refreshes. A browser subscriber's SUBSCRIBE is its - join. -- **Drafts.** Update `drafts/draft-lcurley-moq-lite.md` (TRACK_INFO, - SUBSCRIBE_UPDATE, the lite-07 changelog) and pass `just drafts check`. -- **The ietf extension.** Cluster hops no longer need it to carry - dynamic-group requests; native lite does. This quest removes that duty - from the [relay extension](/quest/m1/ietf-extension/lite.md) if that quest - has not landed yet, or deletes its request path if it has. - -Tests: codec round trips on lite-07 and an older version without the -fields. A two-relay cluster test checks that a join over the ratio at the far -relay reaches the origin's `wanted`, a join under it does not, and -concurrent joins send one SUBSCRIBE_UPDATE. Use simulated time. Run -`just test interop --all`. - -Public API: none beyond `Demand::wanted` and `track::Info::refresh`. Wire: two -new lite-07 fields. diff --git a/rs/moq-net/src/lite/subscribe.rs b/rs/moq-net/src/lite/subscribe.rs index fb898c51e42..570edad4f6f 100644 --- a/rs/moq-net/src/lite/subscribe.rs +++ b/rs/moq-net/src/lite/subscribe.rs @@ -436,13 +436,9 @@ impl Message for SubscribeUpdate { let (start_frame, end_frame) = decode_frame_bounds(r, version, start_group, end_group)?; let start_group = canonical_start_group(version, start_group, start_frame); - let wanted_group = if matches!( - version, - Version::Lite03 | Version::Lite04 | Version::Lite05 | Version::Lite06 - ) { - None - } else { - r.varint()?.checked_sub(1) + let wanted_group = match version.has_refresh() { + true => r.varint()?.checked_sub(1), + false => None, }; Ok(Self { @@ -482,10 +478,7 @@ impl Message for SubscribeUpdate { self.end_frame, )?; - if !matches!( - version, - Version::Lite03 | Version::Lite04 | Version::Lite05 | Version::Lite06 - ) { + if version.has_refresh() { w.varint_opt(self.wanted_group)?; } Ok(()) @@ -928,8 +921,7 @@ mod test { ); } - /// Lite-07 carries `Group Order` right after the priority, on SUBSCRIBE and - /// SUBSCRIBE_UPDATE alike, and refuses a value it does not define. + /// Lite-07 carries `Wanted Group` on SUBSCRIBE_UPDATE; older versions drop it. #[test] fn wanted_group_roundtrips_only_on_lite07() { for version in [Version::Lite05, Version::Lite06, Version::Lite07] { @@ -946,18 +938,13 @@ mod test { }; let buf = update.encode_bytes(version).unwrap(); let got = crate::coding::decode_buf(&mut buf.as_ref(), version, SubscribeUpdate::decode).unwrap(); - assert_eq!( - got.wanted_group, - if matches!(version, Version::Lite07) { - wanted - } else { - None - } - ); + assert_eq!(got.wanted_group, if version.has_refresh() { wanted } else { None }); } } } + /// Lite-07 carries `Group Order` right after the priority, on SUBSCRIBE and + /// SUBSCRIBE_UPDATE alike, and refuses a value it does not define. #[test] fn group_order_roundtrips_on_lite07() { use crate::track::Order; diff --git a/rs/moq-net/src/lite/subscriber.rs b/rs/moq-net/src/lite/subscriber.rs index 7debfdd810c..2e50fcd9cf9 100644 --- a/rs/moq-net/src/lite/subscriber.rs +++ b/rs/moq-net/src/lite/subscriber.rs @@ -3474,6 +3474,52 @@ mod tests { assert_eq!((msg.end_group, msg.end_frame), (Some(5), None)); } + /// Concurrent joins over the refresh ratio send one SUBSCRIBE_UPDATE upstream, and + /// the next request waits until the requested group arrives. + #[moq_clock::test] + async fn refresh_joins_coalesce_upstream() { + let h = Harness::new(Version::Lite07); + let request = h._broadcast.reserve_track("refresh").unwrap(); + let mut serving = ServeLoop::new(&h.serve, request, track::Info::default().with_refresh(1), None); + let track = h._broadcast.consume().track("refresh").unwrap(); + let _baseline = track.subscribe(None).await.unwrap(); + assert!(serving.poll(&h.serve, &kio::Waiter::noop()).is_pending()); + assert!(matches!(serving.sub, Sub::Active(_)), "the reader opens the upstream"); + let established = h.wire().len(); + + let arrive = |serving: &ServeLoop, sequence| { + let mut group = serving.serving.receive_group(group::Info { sequence }).unwrap(); + for frame in [&b"key"[..], b"abc", b"d"] { + group.write_frame(None, frame).unwrap(); + } + group.finish().unwrap(); + }; + let wanted = |h: &Harness| { + let wire = h.wire(); + let mut wire = &wire[established..]; + let mut wanted = Vec::new(); + while !wire.is_empty() { + let msg = crate::coding::decode_buf(&mut wire, Version::Lite07, lite::SubscribeUpdate::decode).unwrap(); + wanted.extend(msg.wanted_group); + } + wanted + }; + + // The deltas outweigh the first frame, so every join asks for group 1. + arrive(&serving, 0); + let mut joins = Vec::new(); + for _ in 0..8 { + joins.push(track.subscribe(None).await.unwrap()); + assert!(serving.poll(&h.serve, &kio::Waiter::noop()).is_pending()); + } + assert_eq!(wanted(&h), [1], "joins coalesce into one request"); + + arrive(&serving, 1); + joins.push(track.subscribe(None).await.unwrap()); + assert!(serving.poll(&h.serve, &kio::Waiter::noop()).is_pending()); + assert_eq!(wanted(&h), [1, 2], "the requested group re-arms the next request"); + } + /// A buffered SUBSCRIBE_START describes the demand its SUBSCRIBE carried, so /// it applies exactly while the current start matches that demand: an update /// that moves the start makes it stale (applying it could reopen a range the @@ -6120,7 +6166,7 @@ impl ServeLoop { // Each stream carries at most one outstanding refresh. Its new SUBSCRIBE // already counted as a join at the upstream hop. - if matches!(serve.subscriber.version, Version::Lite07) { + if serve.subscriber.version.has_refresh() { if let Poll::Ready(Some(largest)) = self.serving.poll_largest(waiter) { self.largest = Some(largest.group); } diff --git a/rs/moq-net/src/lite/track.rs b/rs/moq-net/src/lite/track.rs index adbaa6818b4..a2a5f5ca5f1 100644 --- a/rs/moq-net/src/lite/track.rs +++ b/rs/moq-net/src/lite/track.rs @@ -91,14 +91,14 @@ impl Message for TrackInfo { scale => Some(Timescale::new(scale).map_err(|_| DecodeError::InvalidValue)?), }; - let refresh = match version { - Version::Lite05 | Version::Lite06 => None, - _ => r + let refresh = match version.has_refresh() { + true => r .varint()? .checked_sub(1) .map(u32::try_from) .transpose() .map_err(|_| DecodeError::InvalidValue)?, + false => None, }; Ok(Self { @@ -124,7 +124,7 @@ impl Message for TrackInfo { }; w.varint(encoded)?; w.varint(version.wire_timescale(self.timescale).map_or(0, u64::from))?; - if !matches!(version, Version::Lite05 | Version::Lite06) { + if version.has_refresh() { w.varint(self.refresh.map_or(0, |ratio| u64::from(ratio) + 1))?; } Ok(()) @@ -160,11 +160,7 @@ mod test { refresh: ratio, ..info_sample() }; - let expected = if matches!(version, Version::Lite07) { - ratio - } else { - None - }; + let expected = if version.has_refresh() { ratio } else { None }; assert_eq!(info_roundtrip(version, &info).refresh, expected); } } diff --git a/rs/moq-net/src/lite/version.rs b/rs/moq-net/src/lite/version.rs index 1aab80781be..2f33d82b60d 100644 --- a/rs/moq-net/src/lite/version.rs +++ b/rs/moq-net/src/lite/version.rs @@ -285,6 +285,18 @@ impl Version { } } + /// Whether TRACK_INFO carries the refresh ratio and SUBSCRIBE_UPDATE a wanted group, + /// so a join at any hop reaches the publisher. Added in lite-07; older peers see a + /// track that never refreshes. + #[allow(clippy::match_like_matches_macro)] + pub(crate) fn has_refresh(self) -> bool { + // Match form so future versions default forward (AGENTS.md convention). + match self { + Self::Lite01 | Self::Lite02 | Self::Lite03 | Self::Lite04 | Self::Lite05 | Self::Lite06 => false, + _ => true, + } + } + /// Whether announcements carry the route cost: the marginal cost of pulling /// the broadcast via this route, accumulated per link. Added in lite-06. /// Older versions carry nothing, so a received route stays at zero and ranks From d5d0677d66f0523970484cca2b9a65c23450e45b Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 19 Oct 2026 23:47:46 -0700 Subject: [PATCH 10/14] fix(lite): keep a pending refresh request when coalescing updates A SUBSCRIBE_UPDATE arriving before the subscription starts replaced any earlier one, so a later parameter update dropped a Wanted Group that the relay sends only once. Fold pending updates through Request::coalesce, keeping the highest Wanted Group, and say so in the draft. The pre-start update test now subscribes from a cached group, as a relay does, so the SUBSCRIBE is not itself a live-edge join and the lost request shows. Co-Authored-By: Claude Opus 5.5 --- drafts/draft-lcurley-moq-lite.md | 1 + rs/moq-net/src/lite/publisher.rs | 48 ++++++++++++++++++++++++-------- 2 files changed, 37 insertions(+), 12 deletions(-) diff --git a/drafts/draft-lcurley-moq-lite.md b/drafts/draft-lcurley-moq-lite.md index 8bbf55dad61..96c56c067c2 100644 --- a/drafts/draft-lcurley-moq-lite.md +++ b/drafts/draft-lcurley-moq-lite.md @@ -1217,6 +1217,7 @@ Moving `Frame Start` forward within a group that is already being delivered does A live-edge join requesting this group or later, encoded as the sequence plus one; `0` means no request. A publisher MUST ignore a request at or below its largest group, and otherwise evaluate it as a new SUBSCRIBE under the Track's Refresh ratio. A relay sends a request when local demand wants a group beyond its largest, and MUST NOT send another until its largest reaches the requested group. +So a later SUBSCRIBE_UPDATE with `0` does not withdraw a request; a publisher that folds updates together before applying them MUST keep the highest Wanted Group. The pending request ends with the subscription. A new SUBSCRIBE itself counts as a join and needs no Wanted Group field. diff --git a/rs/moq-net/src/lite/publisher.rs b/rs/moq-net/src/lite/publisher.rs index cec094a9876..aba4d7ff2e5 100644 --- a/rs/moq-net/src/lite/publisher.rs +++ b/rs/moq-net/src/lite/publisher.rs @@ -1438,6 +1438,11 @@ trait Request: Sized { /// Apply an update from the requester. fn update(&mut self, update: Self::Update); + /// Fold an update into the one still waiting for the reply to start. The newest wins. + fn coalesce(pending: &mut Option, update: Self::Update) { + *pending = Some(update); + } + /// Write the reply: `Continue` after each unit of work, so the requester is checked /// between them even while work stays ready, and `Break` once all of it is buffered. fn poll( @@ -1475,7 +1480,7 @@ struct RequestServe> { // The request's place under the session's subscription cap. _charged: Option, _fetch: Option, - // The latest update to arrive before the reply started. Each one replaces the last. + // The updates to arrive before the reply started, folded by [`Request::coalesce`]. update: Option, /// Ends the request, even mid-reply, once the session stops allowing its broadcast. gate: Option, @@ -1732,7 +1737,7 @@ impl> RequestServe { }; match &mut self.state { RequestState::Serve(request) => request.update(update), - _ => self.update = Some(update), + _ => R::coalesce(&mut self.update, update), } } } @@ -1956,9 +1961,18 @@ impl Request for SubscribeServe { }) } + /// The newest parameters win, but a pending refresh request survives: the requester + /// sends each one once, until the group it asks for arrives. + fn coalesce(pending: &mut Option, mut update: lite::SubscribeUpdate) { + if let Some(older) = pending.take() { + update.wanted_group = update.wanted_group.max(older.wanted_group); + } + *pending = Some(update); + } + fn update(&mut self, update: lite::SubscribeUpdate) { match self { - Self::Confirm { update: pending, .. } => *pending = Some(update), + Self::Confirm { update: pending, .. } => Self::coalesce(pending, update), Self::Run(run) => run.update(update), // The track is over: nothing left to steer. Self::Drain { .. } => {} @@ -6545,7 +6559,8 @@ mod tests { } /// SUBSCRIBE_UPDATE is not a close: an update arriving while the subscription - /// resolves keeps it waiting, and still applies once it starts. + /// resolves keeps it waiting, and still applies once it starts. A later update keeps an + /// earlier refresh request, which the requester sends only once. #[moq_clock::test] async fn a_subscribe_update_is_not_a_close() { let origin = crate::origin::Config::new(crate::Hop::new(1).unwrap()).produce(); @@ -6582,7 +6597,8 @@ mod tests { track: "video".into(), priority: 1, max_delay: Duration::ZERO, - start_group: None, + // A relay asks from its cached group, so the SUBSCRIBE is not a live-edge join. + start_group: Some(1), end_group: None, start_frame: 0, end_frame: None, @@ -6602,31 +6618,39 @@ mod tests { let mut serve = RequestServe::<_, SubscribeServe>::new(publisher.shared.clone(), stream); assert!(!drive(&mut serve).await); - let update = lite::SubscribeUpdate { - wanted_group: None, + let update = |wanted_group, priority| lite::SubscribeUpdate { + wanted_group, order: crate::track::Order::Descending, - priority: 7, + priority, max_delay: Duration::ZERO, - start_group: None, + start_group: Some(1), end_group: None, start_frame: 0, end_frame: None, }; - session.push(&update.encode_bytes(version).unwrap()); + session.push(&update(Some(2), 3).encode_bytes(version).unwrap()); + session.push(&update(None, 7).encode_bytes(version).unwrap()); assert!(!drive(&mut serve).await, "an update ended the subscription"); - // Resolve the track: the run starts at the updated priority. + // Resolve the track with a group over the ratio: the run starts at the updated + // priority, and the held refresh request still joins. let request = dynamic .requested_track() .now_or_never() .expect("track requested") .unwrap(); - let _track = request.accept(crate::track::Info::timed()); + let track = request.accept(crate::track::Info::timed().with_refresh(1)); + let mut group = track.create_group(group::Info { sequence: 1 }).unwrap(); + for frame in [&b"key"[..], b"abc", b"d"] { + group.write_frame(crate::Timestamp::ZERO, frame).unwrap(); + } + group.finish().unwrap(); assert!(!drive(&mut serve).await, "the subscription ended"); let RequestState::Serve(SubscribeServe::Run(run)) = &serve.state else { panic!("the subscription is not running"); }; assert_eq!(run.steer_tx.read().priority, 7, "the update was lost"); + assert_eq!(track.demand().wanted(), Some(2), "the refresh request was lost"); } /// A subscription that always has another group ready yields within its budget, so a From 8d0e44cae0ef7b9c01354eea2e5c901c291f8d49 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 20 Oct 2026 00:42:58 -0700 Subject: [PATCH 11/14] docs(concept): say moq-lite-07 hops carry refresh demand The dynamic-groups note still said moq-lite hops carry no requests. lite-07 now carries the ratio in TRACK_INFO and the wanted group in SUBSCRIBE_UPDATE; earlier versions carry neither. Co-Authored-By: Claude Opus 5.5 --- doc/concept/standard.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/concept/standard.md b/doc/concept/standard.md index 46a1f5d1cec..bbfb3467f2d 100644 --- a/doc/concept/standard.md +++ b/doc/concept/standard.md @@ -32,7 +32,7 @@ subset drops. What a peer actually observes against this implementation: - **One `SETUP` credential**, forwarded to the [auth server](/bin/relay/auth#the-contract) unverified. A second `SETUP` token closes the session. We advertise no token cache, so an alias reference in `SETUP` closes it with `PROTOCOL_VIOLATION`, one on a request with `UNKNOWN_AUTH_TOKEN_ALIAS`, and a registration on a request with `AUTH_TOKEN_CACHE_OVERFLOW`. Where the Rust side authorizes the peer or verifies tokens, a token on a `SUBSCRIBE` or `PUBLISH_NAMESPACE` is verified like an in-band session token and authorizes that one request alone, even where that authorization already covers it; it never widens the session. It is refused with `NOT_SUPPORTED` when nothing verifies it, when it is empty, or when its Token Type is anything but 0 (out of band). A side that does neither, JavaScript included, ignores the token. Rust refuses a request carrying more than one distinct token with `NOT_SUPPORTED`, since it verifies one; JavaScript, which verifies none, ignores them all. A token-authorized `SUBSCRIBE` still stays within the grant the peer gave us. A token-authorized `PUBLISH_NAMESPACE` needs a grant covering everything beneath the namespace, and the tracks we subscribe under it rely on that announce instead of our limit, ending with it. An update renews the token, except on a drafts 14 and 15 `PUBLISH_NAMESPACE`, which has no update, and a refused renewal ends only that request. Rust and JavaScript send the token a route names (`Route::auth`) on its `PUBLISH_NAMESPACE`, including the one drafts 14 and 15 answer a solicited `SUBSCRIBE_NAMESPACE` with, and swapping it renews the request with `REQUEST_UPDATE` from draft 17, or ends and re-sends it before; the inline `NAMESPACE` that answers a solicited `SUBSCRIBE_NAMESPACE` from draft 16 carries no token. The token belongs to the session that added it, so a reconnect means adding it again and re-announcing. A token on any other request is decoded and grants nothing, and a request repeating one is refused with `MALFORMED_AUTH_TOKEN`. `SUBSCRIBE_TRACKS` reads its namespace before refusal; its token is not decoded. On draft 17 and later, the negotiated [MoQ Auth extension](/concept/moq-lite#authorization) accepts additional session tokens in band. - **Refused, not fatal.** A legal request this stack does not serve is rejected on its own and the session stays up: `FORWARD=0`, `SUBSCRIBE_TRACKS`, and the fetch forms above get `NOT_SUPPORTED`. Range Filters get `INVALID_FILTER` on draft 19 and later because the advertised filter limit is zero. On draft 21 and later, namespaces whose first tuple field is exactly `.` or `.session` get `DOES_NOT_EXIST` before application lookup; other dot prefixes still reach the application. Subscription updates accept priority, negotiated subscriber max age, and delivery timeouts; Rust also renews request tokens and judges `NEW_GROUP_REQUEST` as a join (see dynamic groups below). Other supported-but-unimplemented preferences end that subscription; a `TRACK_PROPERTY_FILTER` there closes the session with `PROTOCOL_VIOLATION`, since it belongs only to `SUBSCRIBE_TRACKS`. On draft 18 and later a namespace update may change its prefix; suffixes after the acknowledgement are relative to that new prefix. - **Objects and datagrams.** Only subgroup 0 is accepted: a stream for any other subgroup, whether its header gives the ID or takes it from the first Object ID, is stopped and the session stays up. Rust relays preserve Object IDs, gaps, object properties, FIRST\_OBJECT, and END\_OF\_GROUP status objects between moq-transport peers for subgroup 0. Datagrams retain their IDs, properties, priority, and status. Plain Rust readers and moq-lite peers see consecutive frames and normal datagram payloads; JavaScript supports only normal datagrams at Object ID 0. A malformed datagram closes the session; a relayed one the downstream draft cannot carry is dropped. A relayed Timestamp leaves in the units the downstream response declares, and is dropped where it declares none (drafts 14 through 16), as for a plain frame; an immutable one that would change or vanish is refused. Only property 0x10 is read as a Timestamp. Property 0x06 stays opaque and keeps its value regardless of timestamp units; it is dropped across the draft-19 boundary, or refused when immutable, because draft 19 assigns it to SUBGROUP\_DELIVERY\_TIMEOUT. From draft 15, a status object carrying properties is refused, and one relayed from draft 14 leaves without them. Draft 14 allows them, but an END\_OF\_TRACK carrying properties ends the subscription as unsupported, since a track end has nowhere to keep them. A `FETCH` carries the END\_OF\_GROUP object on drafts 14 and 15; later drafts have no FETCH status, so their response ends at the last frame. A group cannot resume across route changes by frame ordinal once Object IDs skip ahead of the ordinals on either route; recovery refuses it instead of splicing different objects. -- **Dynamic groups.** A track advertises `DYNAMIC_GROUPS` when its publisher sets a refresh ratio, and a track received with `DYNAMIC_GROUPS` gets a ratio of 0. A `NEW_GROUP_REQUEST` (draft 15 and later) counts as one more subscriber joining, which a `SUBSCRIBE` already is: it asks for a new group only when the newest group's bytes after its first frame exceed the ratio times the first frame. Joins coalesce until the asked-for group arrives. A Rust relay sends `NEW_GROUP_REQUEST` upstream, on the `SUBSCRIBE` or in a `REQUEST_UPDATE`, once a join wants a group past the newest it holds; a relay holding nothing yet asks for none. On a track without a ratio, an update carrying one ends the subscription with `UPDATE_FAILED`. On drafts 15 and 16, whose `TRACK_STATUS` answer has no room for it, a relay copy first learned from `TRACK_STATUS` (a fetch-only reader) does not advertise it to later subscribers. moq-lite hops do not carry requests yet. +- **Dynamic groups.** A track advertises `DYNAMIC_GROUPS` when its publisher sets a refresh ratio, and a track received with `DYNAMIC_GROUPS` gets a ratio of 0. A `NEW_GROUP_REQUEST` (draft 15 and later) counts as one more subscriber joining, which a `SUBSCRIBE` already is: it asks for a new group only when the newest group's bytes after its first frame exceed the ratio times the first frame. Joins coalesce until the asked-for group arrives. A Rust relay sends `NEW_GROUP_REQUEST` upstream, on the `SUBSCRIBE` or in a `REQUEST_UPDATE`, once a join wants a group past the newest it holds; a relay holding nothing yet asks for none. On a track without a ratio, an update carrying one ends the subscription with `UPDATE_FAILED`. On drafts 15 and 16, whose `TRACK_STATUS` answer has no room for it, a relay copy first learned from `TRACK_STATUS` (a fetch-only reader) does not advertise it to later subscribers. A moq-lite-07 hop (`moq-lite-07-wip`, opt-in) carries the same demand natively: the ratio in TRACK_INFO and the asked-for group in SUBSCRIBE_UPDATE. Earlier moq-lite versions carry neither, so a track received over one never refreshes. - **Priority.** Higher is served first. The IETF default of 128 is this stack's 127, and a track that never sets one is 127. A relay's upstream subscription carries the highest priority its subscribers ask for and updates it as they come and go; its group order stays as the `SUBSCRIBE` asked, since no draft lets an update change it. - **Size.** An object extension block larger than 64 KiB ends that subgroup stream. The session stays up. This cap is ours, not the draft's. From 1eeda9689e40fcd2950c37a830e0e1d811558d89 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 20 Oct 2026 00:49:25 -0700 Subject: [PATCH 12/14] docs(concept): code-format the lite message names Co-Authored-By: Claude Opus 5.5 --- doc/concept/standard.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/concept/standard.md b/doc/concept/standard.md index bbfb3467f2d..17306060d1a 100644 --- a/doc/concept/standard.md +++ b/doc/concept/standard.md @@ -32,7 +32,7 @@ subset drops. What a peer actually observes against this implementation: - **One `SETUP` credential**, forwarded to the [auth server](/bin/relay/auth#the-contract) unverified. A second `SETUP` token closes the session. We advertise no token cache, so an alias reference in `SETUP` closes it with `PROTOCOL_VIOLATION`, one on a request with `UNKNOWN_AUTH_TOKEN_ALIAS`, and a registration on a request with `AUTH_TOKEN_CACHE_OVERFLOW`. Where the Rust side authorizes the peer or verifies tokens, a token on a `SUBSCRIBE` or `PUBLISH_NAMESPACE` is verified like an in-band session token and authorizes that one request alone, even where that authorization already covers it; it never widens the session. It is refused with `NOT_SUPPORTED` when nothing verifies it, when it is empty, or when its Token Type is anything but 0 (out of band). A side that does neither, JavaScript included, ignores the token. Rust refuses a request carrying more than one distinct token with `NOT_SUPPORTED`, since it verifies one; JavaScript, which verifies none, ignores them all. A token-authorized `SUBSCRIBE` still stays within the grant the peer gave us. A token-authorized `PUBLISH_NAMESPACE` needs a grant covering everything beneath the namespace, and the tracks we subscribe under it rely on that announce instead of our limit, ending with it. An update renews the token, except on a drafts 14 and 15 `PUBLISH_NAMESPACE`, which has no update, and a refused renewal ends only that request. Rust and JavaScript send the token a route names (`Route::auth`) on its `PUBLISH_NAMESPACE`, including the one drafts 14 and 15 answer a solicited `SUBSCRIBE_NAMESPACE` with, and swapping it renews the request with `REQUEST_UPDATE` from draft 17, or ends and re-sends it before; the inline `NAMESPACE` that answers a solicited `SUBSCRIBE_NAMESPACE` from draft 16 carries no token. The token belongs to the session that added it, so a reconnect means adding it again and re-announcing. A token on any other request is decoded and grants nothing, and a request repeating one is refused with `MALFORMED_AUTH_TOKEN`. `SUBSCRIBE_TRACKS` reads its namespace before refusal; its token is not decoded. On draft 17 and later, the negotiated [MoQ Auth extension](/concept/moq-lite#authorization) accepts additional session tokens in band. - **Refused, not fatal.** A legal request this stack does not serve is rejected on its own and the session stays up: `FORWARD=0`, `SUBSCRIBE_TRACKS`, and the fetch forms above get `NOT_SUPPORTED`. Range Filters get `INVALID_FILTER` on draft 19 and later because the advertised filter limit is zero. On draft 21 and later, namespaces whose first tuple field is exactly `.` or `.session` get `DOES_NOT_EXIST` before application lookup; other dot prefixes still reach the application. Subscription updates accept priority, negotiated subscriber max age, and delivery timeouts; Rust also renews request tokens and judges `NEW_GROUP_REQUEST` as a join (see dynamic groups below). Other supported-but-unimplemented preferences end that subscription; a `TRACK_PROPERTY_FILTER` there closes the session with `PROTOCOL_VIOLATION`, since it belongs only to `SUBSCRIBE_TRACKS`. On draft 18 and later a namespace update may change its prefix; suffixes after the acknowledgement are relative to that new prefix. - **Objects and datagrams.** Only subgroup 0 is accepted: a stream for any other subgroup, whether its header gives the ID or takes it from the first Object ID, is stopped and the session stays up. Rust relays preserve Object IDs, gaps, object properties, FIRST\_OBJECT, and END\_OF\_GROUP status objects between moq-transport peers for subgroup 0. Datagrams retain their IDs, properties, priority, and status. Plain Rust readers and moq-lite peers see consecutive frames and normal datagram payloads; JavaScript supports only normal datagrams at Object ID 0. A malformed datagram closes the session; a relayed one the downstream draft cannot carry is dropped. A relayed Timestamp leaves in the units the downstream response declares, and is dropped where it declares none (drafts 14 through 16), as for a plain frame; an immutable one that would change or vanish is refused. Only property 0x10 is read as a Timestamp. Property 0x06 stays opaque and keeps its value regardless of timestamp units; it is dropped across the draft-19 boundary, or refused when immutable, because draft 19 assigns it to SUBGROUP\_DELIVERY\_TIMEOUT. From draft 15, a status object carrying properties is refused, and one relayed from draft 14 leaves without them. Draft 14 allows them, but an END\_OF\_TRACK carrying properties ends the subscription as unsupported, since a track end has nowhere to keep them. A `FETCH` carries the END\_OF\_GROUP object on drafts 14 and 15; later drafts have no FETCH status, so their response ends at the last frame. A group cannot resume across route changes by frame ordinal once Object IDs skip ahead of the ordinals on either route; recovery refuses it instead of splicing different objects. -- **Dynamic groups.** A track advertises `DYNAMIC_GROUPS` when its publisher sets a refresh ratio, and a track received with `DYNAMIC_GROUPS` gets a ratio of 0. A `NEW_GROUP_REQUEST` (draft 15 and later) counts as one more subscriber joining, which a `SUBSCRIBE` already is: it asks for a new group only when the newest group's bytes after its first frame exceed the ratio times the first frame. Joins coalesce until the asked-for group arrives. A Rust relay sends `NEW_GROUP_REQUEST` upstream, on the `SUBSCRIBE` or in a `REQUEST_UPDATE`, once a join wants a group past the newest it holds; a relay holding nothing yet asks for none. On a track without a ratio, an update carrying one ends the subscription with `UPDATE_FAILED`. On drafts 15 and 16, whose `TRACK_STATUS` answer has no room for it, a relay copy first learned from `TRACK_STATUS` (a fetch-only reader) does not advertise it to later subscribers. A moq-lite-07 hop (`moq-lite-07-wip`, opt-in) carries the same demand natively: the ratio in TRACK_INFO and the asked-for group in SUBSCRIBE_UPDATE. Earlier moq-lite versions carry neither, so a track received over one never refreshes. +- **Dynamic groups.** A track advertises `DYNAMIC_GROUPS` when its publisher sets a refresh ratio, and a track received with `DYNAMIC_GROUPS` gets a ratio of 0. A `NEW_GROUP_REQUEST` (draft 15 and later) counts as one more subscriber joining, which a `SUBSCRIBE` already is: it asks for a new group only when the newest group's bytes after its first frame exceed the ratio times the first frame. Joins coalesce until the asked-for group arrives. A Rust relay sends `NEW_GROUP_REQUEST` upstream, on the `SUBSCRIBE` or in a `REQUEST_UPDATE`, once a join wants a group past the newest it holds; a relay holding nothing yet asks for none. On a track without a ratio, an update carrying one ends the subscription with `UPDATE_FAILED`. On drafts 15 and 16, whose `TRACK_STATUS` answer has no room for it, a relay copy first learned from `TRACK_STATUS` (a fetch-only reader) does not advertise it to later subscribers. A moq-lite-07 hop (`moq-lite-07-wip`, opt-in) carries the same demand natively: the ratio in `TRACK_INFO` and the asked-for group in `SUBSCRIBE_UPDATE`. Earlier moq-lite versions carry neither, so a track received over one never refreshes. - **Priority.** Higher is served first. The IETF default of 128 is this stack's 127, and a track that never sets one is 127. A relay's upstream subscription carries the highest priority its subscribers ask for and updates it as they come and go; its group order stays as the `SUBSCRIBE` asked, since no draft lets an update change it. - **Size.** An object extension block larger than 64 KiB ends that subgroup stream. The session stays up. This cap is ours, not the draft's. From 5c428d34cf93b8f9bad3c8d97e54a4eaffd5ed2f Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 20 Oct 2026 09:12:09 -0700 Subject: [PATCH 13/14] feat(lite): make Wanted Group subscription state Per the maintainer: a relay restates its current wanted group in every SUBSCRIBE_UPDATE, indefinitely, and sends a new update only when a new group past its largest is wanted. Receivers keep the latest update and ignore a value at or below their largest, so restating it is harmless and no update needs folding. Drop Request::coalesce and the draft's keep-the-highest MUST, store the wanted group on the upstream SubStream in Rust, and mirror the send rule in js/net. Tests now prove a parameter update restates the wanted group, a restated value still joins before its group exists, and a stale one is ignored. Co-Authored-By: Claude Opus 5.5 --- drafts/draft-lcurley-moq-lite.md | 10 +++---- js/net/src/lite/publisher.ts | 2 ++ js/net/src/lite/refresh.test.ts | 6 +++- js/net/src/lite/subscriber.ts | 13 +++++---- rs/moq-net/src/lite/publisher.rs | 48 +++++++++++++++++-------------- rs/moq-net/src/lite/subscriber.rs | 46 +++++++++++++++-------------- 6 files changed, 70 insertions(+), 55 deletions(-) diff --git a/drafts/draft-lcurley-moq-lite.md b/drafts/draft-lcurley-moq-lite.md index 75a0aad3e01..583757c3888 100644 --- a/drafts/draft-lcurley-moq-lite.md +++ b/drafts/draft-lcurley-moq-lite.md @@ -1228,11 +1228,11 @@ Moving `Frame Start` forward within a group that is already being delivered does **Wanted Group**: -A live-edge join requesting this group or later, encoded as the sequence plus one; `0` means no request. -A publisher MUST ignore a request at or below its largest group, and otherwise evaluate it as a new SUBSCRIBE under the Track's Refresh ratio. -A relay sends a request when local demand wants a group beyond its largest, and MUST NOT send another until its largest reaches the requested group. -So a later SUBSCRIBE_UPDATE with `0` does not withdraw a request; a publisher that folds updates together before applying them MUST keep the highest Wanted Group. -The pending request ends with the subscription. +The newest group the subscriber's live-edge joins want, encoded as the sequence plus one; `0` means none. +Like the other fields, it is subscription state: every SUBSCRIBE_UPDATE restates it, and the latest one applies. +A relay sends a SUBSCRIBE_UPDATE when local demand wants a group beyond its largest that differs from the value it last sent, and keeps restating that value in later updates, including after the group arrives. +A publisher MUST ignore a value at or below its largest group, and otherwise evaluate it as a new SUBSCRIBE under the Track's Refresh ratio. +Restating a value is harmless: a join while a request is pending asks for the same group. A new SUBSCRIBE itself counts as a join and needs no Wanted Group field. ## TRACK diff --git a/js/net/src/lite/publisher.ts b/js/net/src/lite/publisher.ts index bda076947b0..c9e64cc4336 100644 --- a/js/net/src/lite/publisher.ts +++ b/js/net/src/lite/publisher.ts @@ -893,6 +893,8 @@ export class Publisher { writer: stream.writer, version: this.version, apply: (update) => { + // Every update restates the wanted group. Past our largest it is a join, which + // repeats the pending ask; at or below it the group already exists. const largest = hooks.peekLargest(track).largest?.group; if (update.wantedGroup !== undefined && (largest === undefined || update.wantedGroup > largest)) hooks.joinSubscriber(track); diff --git a/js/net/src/lite/refresh.test.ts b/js/net/src/lite/refresh.test.ts index c944d0cf6d8..45ac727154f 100644 --- a/js/net/src/lite/refresh.test.ts +++ b/js/net/src/lite/refresh.test.ts @@ -62,7 +62,11 @@ test.each([ALPN_06, ALPN_07_WIP])("refresh joins reach a browser publisher on %s } expect(producer.demand().wanted.peek()).toBe(alpn === ALPN_07_WIP ? 1 : 0); // Concurrent local joins coalesce into one upstream update. - expect(updates.length).toBe(alpn === ALPN_07_WIP ? 1 : 0); + expect(updates).toEqual(alpn === ALPN_07_WIP ? [1] : []); + // A parameter change restates the wanted group rather than clearing it. + joins.push(remote.subscribe({ priority: 9 })); + await clock.advanceAsync(Nano(0)); + expect(updates).toEqual(alpn === ALPN_07_WIP ? [1, 1] : []); for (const join of joins) join.close(); received!.close(); baseline.close(); diff --git a/js/net/src/lite/subscriber.ts b/js/net/src/lite/subscriber.ts index 917b5cb81b2..4a1cacc8009 100644 --- a/js/net/src/lite/subscriber.ts +++ b/js/net/src/lite/subscriber.ts @@ -1314,7 +1314,10 @@ export class Subscriber { }, }; - let pendingWanted: number | undefined; + // The wanted group is subscription state: an update announces each new one past our + // largest, and every later update restates it. Joins asking for the same group + // coalesce into that one update. + let sentWanted: number | undefined; const demand = track.demand(); const edge = hooks.producerLargest(track); for (;;) { @@ -1323,9 +1326,9 @@ export class Subscriber { const refresh = hasRefresh(this.version) && largest !== undefined && - (pendingWanted === undefined || largest >= pendingWanted) && wanted !== undefined && - wanted > largest + wanted > largest && + wanted !== sentWanted ? wanted : undefined; const current = track.subscription.peek(); @@ -1355,7 +1358,7 @@ export class Subscriber { // Round-trip the other Subscribe parameters so the publisher doesn't // interpret SUBSCRIBE_UPDATE as a reset of ordered/maxDelay/etc. const update = new SubscribeUpdate({ - wantedGroup: refresh, + wantedGroup: refresh ?? sentWanted, priority: current.priority ?? 0, order: current.order, maxDelay: current.maxDelay, @@ -1373,7 +1376,7 @@ export class Subscriber { } catch { return; } - if (refresh !== undefined) pendingWanted = refresh; + if (refresh !== undefined) sentWanted = refresh; lastSent = { ...current }; console.debug(`subscribe update: id=${id} broadcast=${broadcast} track=${track.name}`); } diff --git a/rs/moq-net/src/lite/publisher.rs b/rs/moq-net/src/lite/publisher.rs index 71d2f91a81a..133acc236b0 100644 --- a/rs/moq-net/src/lite/publisher.rs +++ b/rs/moq-net/src/lite/publisher.rs @@ -1496,11 +1496,6 @@ trait Request: Sized { /// Apply an update from the requester. fn update(&mut self, update: Self::Update); - /// Fold an update into the one still waiting for the reply to start. The newest wins. - fn coalesce(pending: &mut Option, update: Self::Update) { - *pending = Some(update); - } - /// Write the reply: `Continue` after each unit of work, so the requester is checked /// between them even while work stays ready, and `Break` once all of it is buffered. fn poll( @@ -1538,7 +1533,7 @@ struct RequestServe> { // The request's place under the session's subscription cap. _charged: Option, _fetch: Option, - // The updates to arrive before the reply started, folded by [`Request::coalesce`]. + // The latest update to arrive before the reply started. Each one replaces the last. update: Option, /// Ends the request, even mid-reply, once the session stops allowing its broadcast. gate: Option, @@ -1795,7 +1790,7 @@ impl> RequestServe { }; match &mut self.state { RequestState::Serve(request) => request.update(update), - _ => R::coalesce(&mut self.update, update), + _ => self.update = Some(update), } } } @@ -2019,18 +2014,9 @@ impl Request for SubscribeServe { }) } - /// The newest parameters win, but a pending refresh request survives: the requester - /// sends each one once, until the group it asks for arrives. - fn coalesce(pending: &mut Option, mut update: lite::SubscribeUpdate) { - if let Some(older) = pending.take() { - update.wanted_group = update.wanted_group.max(older.wanted_group); - } - *pending = Some(update); - } - fn update(&mut self, update: lite::SubscribeUpdate) { match self { - Self::Confirm { update: pending, .. } => Self::coalesce(pending, update), + Self::Confirm { update: pending, .. } => *pending = Some(update), Self::Run(run) => run.update(update), // The track is over: nothing left to steer. Self::Drain { .. } => {} @@ -3654,6 +3640,8 @@ impl TrackRun { /// subscription. This is what lets relays pause an upstream subscription across /// consumer churn without tearing it down. fn update(&mut self, upd: lite::SubscribeUpdate) { + // Every update restates the wanted group. Past our largest it is a join, which + // repeats the pending ask; at or below it the group already exists. if upd .wanted_group .is_some_and(|wanted| self.track.peek_largest().is_none_or(|largest| wanted > largest.group)) @@ -6820,8 +6808,9 @@ mod tests { } /// SUBSCRIBE_UPDATE is not a close: an update arriving while the subscription - /// resolves keeps it waiting, and still applies once it starts. A later update keeps an - /// earlier refresh request, which the requester sends only once. + /// resolves keeps it waiting, and the latest applies once it starts. Its wanted group + /// is state each update restates: past the largest it joins, and once that group + /// exists the same value asks for nothing more. #[moq_clock::test] async fn a_subscribe_update_is_not_a_close() { let origin = crate::origin::Config::new(crate::Hop::new(1).unwrap()).produce(); @@ -6890,11 +6879,11 @@ mod tests { end_frame: None, }; session.push(&update(Some(2), 3).encode_bytes(version).unwrap()); - session.push(&update(None, 7).encode_bytes(version).unwrap()); + session.push(&update(Some(2), 7).encode_bytes(version).unwrap()); assert!(!drive(&mut serve).await, "an update ended the subscription"); - // Resolve the track with a group over the ratio: the run starts at the updated - // priority, and the held refresh request still joins. + // Resolve the track with a group over the ratio: the run starts at the latest + // priority, and its restated wanted group joins. let request = dynamic .requested_track() .now_or_never() @@ -6912,6 +6901,21 @@ mod tests { }; assert_eq!(run.steer_tx.read().priority, 7, "the update was lost"); assert_eq!(track.demand().wanted(), Some(2), "the refresh request was lost"); + + // The asked-for group arrives, over the ratio too. A restated wanted group is now + // stale, so it is not another join. + let mut group = track.create_group(group::Info { sequence: 2 }).unwrap(); + for frame in [&b"key"[..], b"abc", b"d"] { + group.write_frame(crate::Timestamp::ZERO, frame).unwrap(); + } + group.finish().unwrap(); + session.push(&update(Some(2), 5).encode_bytes(version).unwrap()); + assert!(!drive(&mut serve).await, "the subscription ended"); + let RequestState::Serve(SubscribeServe::Run(run)) = &serve.state else { + panic!("the subscription is not running"); + }; + assert_eq!(run.steer_tx.read().priority, 5, "the update was lost"); + assert_eq!(track.demand().wanted(), Some(2), "a stale wanted group joined"); } /// A subscription that always has another group ready yields within its budget, so a diff --git a/rs/moq-net/src/lite/subscriber.rs b/rs/moq-net/src/lite/subscriber.rs index d9332b587a6..e664492f90d 100644 --- a/rs/moq-net/src/lite/subscriber.rs +++ b/rs/moq-net/src/lite/subscriber.rs @@ -1683,6 +1683,7 @@ mod tests { tail: tail.clone(), served: None, end: None, + wanted: None, }) } @@ -2095,6 +2096,7 @@ mod tests { tail: Default::default(), served: None, end: Some(lite::SubscribeEnd { group: 10 }), + wanted: None, }; assert_eq!( sub.owed(None), @@ -3480,8 +3482,8 @@ mod tests { assert_eq!((msg.end_group, msg.end_frame), (Some(5), None)); } - /// Concurrent joins over the refresh ratio send one SUBSCRIBE_UPDATE upstream, and - /// the next request waits until the requested group arrives. + /// Concurrent joins over the refresh ratio send one SUBSCRIBE_UPDATE upstream, a new + /// group past the largest sends the next, and every update restates the latest. #[moq_clock::test] async fn refresh_joins_coalesce_upstream() { let h = Harness::new(Version::Lite07); @@ -3524,6 +3526,11 @@ mod tests { joins.push(track.subscribe(None).await.unwrap()); assert!(serving.poll(&h.serve, &kio::Waiter::noop()).is_pending()); assert_eq!(wanted(&h), [1, 2], "the requested group re-arms the next request"); + + // A parameter change restates the pending wanted group rather than clearing it. + let _urgent = track.subscribe(Subscription::default().with_priority(9)).await.unwrap(); + assert!(serving.poll(&h.serve, &kio::Waiter::noop()).is_pending()); + assert_eq!(wanted(&h), [1, 2, 2], "every update restates the wanted group"); } /// A buffered SUBSCRIBE_START describes the demand its SUBSCRIBE carried, so @@ -4767,6 +4774,8 @@ struct SubStream { served: Option, /// The track's exclusive end (SUBSCRIBE_END), once declared. end: Option, + /// The refresh join's wanted group, restated in every SUBSCRIBE_UPDATE. + wanted: Option, } impl SubStream { @@ -5250,7 +5259,7 @@ impl TrackServe { if start_moved { let _ = producer.start_at(active.start.map(|start| start.group)); } - buffer_update(active, subscription.end(), None)?; + buffer_update(active, subscription.end())?; } Ok(Begin::None) } @@ -5398,16 +5407,14 @@ enum Begin { Establish(Establish), } -/// Buffer the current SUBSCRIBE parameters with an updated end and optional refresh join. -/// The caller flushes. +/// Buffer the current SUBSCRIBE parameters with an updated end. The caller flushes. fn buffer_update( active: &mut SubStream, end: Option, - wanted: Option, ) -> Result<(), Error> { let bounds = WireBounds::new(active.start, end); active.stream.writer.buffer(&lite::SubscribeUpdate { - wanted_group: wanted, + wanted_group: active.wanted, priority: active.priority, max_delay: active.max_delay, start_group: bounds.start_group, @@ -5527,6 +5534,7 @@ impl Establish { tail: self.tail.clone(), served: None, end: None, + wanted: None, } } } @@ -5842,7 +5850,6 @@ struct ServeLoop { /// change). serving: track::Producer, largest: Option, - wanted: Option, /// Watches `serving`'s subscribers, to release the copy once nobody reads it. demand: track::Demand, /// Serve on-demand fetches of uncached groups from this session. @@ -6052,7 +6059,6 @@ impl ServeLoop { serving.received(); Self { largest: None, - wanted: None, demand: serving.demand(), serving, dynamic, @@ -6087,10 +6093,7 @@ impl ServeLoop { let id = est.id; self.mode = ServeMode::Select; match res { - Ok(active) => { - self.wanted = None; - self.sub = Sub::Active(active); - } + Ok(active) => self.sub = Sub::Active(active), Err(err) => { // Opening the upstream failed (usually the session dying): hand // the track back for another route to resume. @@ -6181,8 +6184,9 @@ impl ServeLoop { Poll::Pending => {} } - // Each stream carries at most one outstanding refresh. Its new SUBSCRIBE - // already counted as a join at the upstream hop. + // The wanted group is subscription state: an update announces each new one + // past our largest, and every later update restates it. Joins asking for + // the same group coalesce into that one update. if serve.subscriber.version.has_refresh() { if let Poll::Ready(Some(largest)) = self.serving.poll_largest(waiter) { self.largest = Some(largest.group); @@ -6190,15 +6194,13 @@ impl ServeLoop { let _ = self.demand.poll_wanted_changed(waiter); if let Sub::Active(active) = &mut self.sub && let Some(largest) = self.largest - && self.wanted.is_none_or(|wanted| largest >= wanted) && let Some(wanted) = self.demand.wanted().filter(|wanted| *wanted > largest) + && active.wanted != Some(wanted) { - self.wanted = Some(wanted); - if let Err(err) = buffer_update( - active, - self.serving.subscription().and_then(|sub| sub.end()), - Some(wanted), - ) { + active.wanted = Some(wanted); + if let Err(err) = + buffer_update(active, self.serving.subscription().and_then(|sub| sub.end())) + { return Poll::Ready(ServeEnd::GiveBack(err)); } continue; From 3fd4249a86cde70b242f046a8d9067ba9482d586 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 20 Oct 2026 09:31:09 -0700 Subject: [PATCH 14/14] chore(lite): allow the live upstream stream's variant size Holding the wanted group on SubStream tipped Sub past clippy's variant-size threshold. There is one per track copy and it holds a live stream while anyone reads, so boxing would add an allocation per upstream subscription without saving memory; same reasoning as TrackRunState. Co-Authored-By: Claude Opus 5.5 --- rs/moq-net/src/lite/subscriber.rs | 3 +++ 1 file changed, 3 insertions(+) diff --git a/rs/moq-net/src/lite/subscriber.rs b/rs/moq-net/src/lite/subscriber.rs index e664492f90d..3f029582145 100644 --- a/rs/moq-net/src/lite/subscriber.rs +++ b/rs/moq-net/src/lite/subscriber.rs @@ -4797,6 +4797,9 @@ impl SubStream { } } +// One per track copy, which holds a live stream while anyone reads it, so boxing it +// would add an allocation per upstream subscription without saving memory. +#[allow(clippy::large_enum_variant)] enum Sub { None, Active(SubStream),