From a0fe6629d857621c0d03f1859de60f0f74f7f9d3 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sun, 18 Oct 2026 22:12:15 -0700 Subject: [PATCH 1/4] quest: claim m1/subscribe-ranges/ietf-update From 77b3fcb08f6971121e1c3f6a458173fb77f17d74 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sun, 18 Oct 2026 23:25:04 -0700 Subject: [PATCH 2/4] feat(net): follow the aggregate subscriber priority on moq-transport upstreams A relay's moq-transport subscription read the downstream aggregate once, at SUBSCRIBE. It now sends SUBSCRIBE_UPDATE (drafts 14 to 16) or REQUEST_UPDATE (draft 17 on) whenever the aggregate priority changes, one in flight at a time where the answer comes back on the request stream, as lite already does. Group order stays as SUBSCRIBE asked, since no draft lets an update change it. Draft-14's update has no optional fields, so it repeats the subscription's bounds: Rust's Largest Object subscription starts just past the answer's Largest, and JS's absolute one at {0, 0}. The JS adapter consumes the draft-15/16 answers to our own updates instead of warning about them. Co-Authored-By: Claude Opus 5.5 --- doc/concept/standard.md | 2 +- js/net/src/ietf/adapter.ts | 7 + js/net/src/ietf/subscribe.ts | 2 + js/net/src/ietf/subscriber.ts | 106 ++++++++++- js/net/src/subscribe_priority.test.ts | 71 ++++++++ quest/m1/subscribe-ranges/README.md | 1 - quest/m1/subscribe-ranges/ietf-update.md | 64 ------- quest/m1/subscribe-ranges/ietf.md | 11 ++ rs/moq-net/src/ietf/subscriber.rs | 167 +++++++++++++++--- rs/moq-net/tests/integration/main.rs | 1 + .../tests/integration/subscribe_priority.rs | 125 +++++++++++++ .../tests/integration/subscribe_ranges.rs | 4 +- 12 files changed, 461 insertions(+), 100 deletions(-) create mode 100644 js/net/src/subscribe_priority.test.ts delete mode 100644 quest/m1/subscribe-ranges/ietf-update.md create mode 100644 rs/moq-net/tests/integration/subscribe_priority.rs diff --git a/doc/concept/standard.md b/doc/concept/standard.md index 8e926905673..21a7868da3d 100644 --- a/doc/concept/standard.md +++ b/doc/concept/standard.md @@ -33,7 +33,7 @@ subset drops. What a peer actually observes against this implementation: - **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 and delivery timeouts; Rust also renews request tokens and relays `NEW_GROUP_REQUEST` (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 Rust relay advertises `DYNAMIC_GROUPS` only where the original publisher did, and carries `NEW_GROUP_REQUEST` (draft 15 and later) back to it: on the `SUBSCRIBE` that opens the upstream subscription, or in a `REQUEST_UPDATE` once it is established. Requests from every subscriber of a track coalesce, so one that names an existing group or that an outstanding request already covers goes no further. A request for 0 goes upstream as 0, unless another subscriber's request past the newest group held answers it too. The next group the relay receives answers every request it held, so new groups never send one again. 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. Local publishers never advertise `DYNAMIC_GROUPS`; on their tracks a `SUBSCRIBE`'s request is ignored and an update carrying one ends the subscription with `UPDATE_FAILED`. moq-lite hops do not carry requests yet. -- **Priority.** Higher is served first. The IETF default of 128 is this stack's 127, and a track that never sets one is 127. +- **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. Several project drafts extend the IETF wire without breaking it, since `SETUP` diff --git a/js/net/src/ietf/adapter.ts b/js/net/src/ietf/adapter.ts index 8e1a189a49d..1d4bb8b3af2 100644 --- a/js/net/src/ietf/adapter.ts +++ b/js/net/src/ietf/adapter.ts @@ -258,6 +258,10 @@ export class ControlStreamAdapter implements Session { // SubscribeNamespace requestIds — for routing 0x08/0x0E entries that lack requestId (v14/v15) #subscribeNamespaces = new Set(); + // Our updates' own request IDs on drafts 15 and 16, whose answer names that ID rather than + // the request it updated. Nothing waits on it, so it is consumed here. + #updates = new Set(); + // Incoming stream queue (for acceptBi) #incomingQueue: Stream[] = []; #incomingWaiters: ((stream: Stream | undefined) => void)[] = []; @@ -393,6 +397,7 @@ export class ControlStreamAdapter implements Session { } } else { spent = this.#updateId(toFlush); + if (spent !== undefined && this.version !== Version.DRAFT_14) this.#updates.add(spent); } await this.#send(toFlush, spent); @@ -499,6 +504,8 @@ export class ControlStreamAdapter implements Session { } const { route, requestId } = classified; + if ((route === Route.Response || route === Route.ErrorResponse) && this.#updates.delete(requestId)) + continue; switch (route) { case Route.NewRequest: diff --git a/js/net/src/ietf/subscribe.ts b/js/net/src/ietf/subscribe.ts index 52dbddb6dfc..1cc301f6ed2 100644 --- a/js/net/src/ietf/subscribe.ts +++ b/js/net/src/ietf/subscribe.ts @@ -430,6 +430,8 @@ export class SubscribeUpdate { await w.u62(this.ownRequestId); await w.u62(this.requestId); if (version === Version.DRAFT_14) { + // Every field is mandatory and the start must not move. Our subscriptions start at + // {0, 0} open ended (`joinFilter`), so zeroes repeat their bounds. await w.u62(0n); // start_group await w.u62(0n); // start_object await w.u62(0n); // end_group diff --git a/js/net/src/ietf/subscriber.ts b/js/net/src/ietf/subscriber.ts index 99dc5daa2a5..1f371ade089 100644 --- a/js/net/src/ietf/subscriber.ts +++ b/js/net/src/ietf/subscriber.ts @@ -42,6 +42,7 @@ import { hasFirstObjectBit, ObjectIdGap, } from "./object.ts"; +import { Parameters } from "./parameters.ts"; import { fromWire, toWire } from "./priority.ts"; import { type Publish, PublishDone, PublishDoneStatus, PublishError, publishDoneClean } from "./publish.ts"; import { @@ -735,6 +736,8 @@ export class Subscriber { let stream: Stream; let trackAlias: bigint; + // The SUBSCRIBER_PRIORITY the request went out with. + let priority: number; const abandoned = new Error("subscribe abandoned before it was accepted"); try { // Returning demand keeps the same setup and its original deadline. @@ -744,6 +747,7 @@ export class Subscriber { if (result !== null) { stream = result.stream; trackAlias = result.alias; + priority = result.priority; break; } if (demand.closed.peek() === undefined && demand.used.peek()) continue; @@ -822,11 +826,13 @@ export class Subscriber { // Terminal conditions settle at most once (PublishDone, track close = local // unsubscribe, a revoked grant); race them once so the demand loop doesn't // re-subscribe each pass. + const unanswered = new Signal(0); const done = race([ - this.#runPublishDone(stream, subscription, broadcast).then(() => publisherEnded), + this.#runPublishDone(stream, subscription, broadcast, unanswered).then(() => publisherEnded), producer.closed.then(() => localEnded), revoked, ]); + void this.#runUpdates(stream, requestId, producer, priority, unanswered, done); // Serve until a terminal condition fires or the last local subscriber leaves. The unused // wake is level-triggered: re-check demand so a subscriber that returns before we tear @@ -881,12 +887,30 @@ export class Subscriber { * is only a hint: a peer may send 0 regardless, so 0 waits out the grace. A request * stream that FINs without PUBLISH_DONE is a protocol violation. */ - async #runPublishDone(stream: Stream, subscription: Subscription, broadcast: Path.Valid): Promise { + async #runPublishDone( + stream: Stream, + subscription: Subscription, + broadcast: Path.Valid, + unanswered: Signal, + ): Promise { const version = this.#session.version; - if (await stream.reader.done()) throw new ProtocolViolation("subscribe stream ended without PUBLISH_DONE"); - const typeId = await stream.reader.u53(); - if (typeId !== PublishDone.id) { - throw new ProtocolViolation(`unexpected message on a subscription: 0x${typeId.toString(16)}`); + // A refused update is followed by PUBLISH_DONE, which ends the subscription, so no + // further answer is owed. + let refused = false; + for (;;) { + if (await stream.reader.done()) throw new ProtocolViolation("subscribe stream ended without PUBLISH_DONE"); + const typeId = await stream.reader.u53(); + if (typeId === PublishDone.id) break; + const answer = (typeId === RequestOk.id || typeId === RequestError.id) && !refused && unanswered.peek() > 0; + if (!answer) throw new ProtocolViolation(`unexpected message on a subscription: 0x${typeId.toString(16)}`); + if (typeId === RequestOk.id) { + await RequestOk.decode(stream.reader, version); + unanswered.update((count) => count - 1); + } else { + const err = await RequestError.decode(stream.reader, version); + console.debug(`subscription update refused: ${err.reasonPhrase}`); + refused = true; + } } const done = await PublishDone.decode(stream.reader, version); // A revocation reads the same as one from a moq-lite peer. @@ -901,6 +925,71 @@ export class Subscriber { await tail.settle(complete, track.closed); } + /** + * Follow the aggregate subscriber priority upstream until `done` settles: SUBSCRIBE_UPDATE + * through draft 16, REQUEST_UPDATE after, each under a Request ID of its own. From draft 17 + * the answer comes back on this stream, so one update is in flight at a time and changes + * meanwhile coalesce. No draft lets an update change the group order, so it stays as asked. + */ + async #runUpdates( + stream: Stream, + requestId: bigint, + producer: track.Producer, + sent: number, + unanswered: Signal, + done: Promise, + ): Promise { + const version = this.#session.version; + const legacy = version === Version.DRAFT_14 || version === Version.DRAFT_15 || version === Version.DRAFT_16; + const stopped = done.then( + () => null, + () => null, + ); + const stop = new AbortController(); + void stopped.then(() => stop.abort()); + + for (;;) { + const wanted = toWire(producer.subscription.peek()?.priority ?? 0); + if (wanted === sent || unanswered.peek() > 0) { + const disposes: Dispose[] = []; + const wake = new Promise((resolve) => { + disposes.push( + producer.subscription.changed(() => resolve()), + unanswered.changed(() => resolve()), + ); + }); + await race([wake, stopped]); + for (const dispose of disposes) dispose(); + if (stop.signal.aborted) return; + continue; + } + + let own: bigint | undefined; + try { + own = await this.#session.nextRequestId(stop.signal); + } catch { + return; + } + if (own === undefined) return; + + const parameters = new Parameters(); + parameters.subscriberPriority = wanted; + const update = legacy + ? new SubscribeUpdate({ requestId, ownRequestId: own, parameters }) + : new SubscribeUpdate({ requestId: own, parameters }); + try { + await stream.writer.u53(SubscribeUpdate.id); + await update.encode(stream.writer, version); + } catch { + // The publisher stopped reading; its responses decide how the track ends. + return; + } + sent = wanted; + if (!legacy) unanswered.update((count) => count + 1); + console.debug(`subscribe update: id=${requestId} priority=${wanted}`); + } + } + /** * Tell the publisher to stop serving a subscription we are walking away from. * @@ -933,7 +1022,7 @@ export class Subscriber { subscription: Subscription, requestId: bigint, deadline: Deadline, - ): Promise<{ stream: Stream; alias: bigint }> { + ): Promise<{ stream: Stream; alias: bigint; priority: number }> { const version = this.#session.version; const legacy = version === Version.DRAFT_14 || version === Version.DRAFT_15 || version === Version.DRAFT_16; @@ -956,6 +1045,7 @@ export class Subscriber { requestId, trackNamespace: broadcast, trackName: request.name, + // Read now, since a subscriber can join while the stream opened. Updates follow it. subscriberPriority: toWire(request.priority), // Fixed for the subscription's life: no REQUEST_UPDATE parameter carries it. groupOrder: request.subscription.order, @@ -1030,7 +1120,7 @@ export class Subscriber { throw err; } state.registeredAlias = ok.trackAlias; - return { stream: state.stream, alias: ok.trackAlias }; + return { stream: state.stream, alias: ok.trackAlias, priority: msg.subscriberPriority }; } /** diff --git a/js/net/src/subscribe_priority.test.ts b/js/net/src/subscribe_priority.test.ts new file mode 100644 index 00000000000..2c94a70adab --- /dev/null +++ b/js/net/src/subscribe_priority.test.ts @@ -0,0 +1,71 @@ +// One upstream subscription carries the aggregate priority of the subscribers it serves, and +// follows it as they come and go. The JS origin never serves a received route onward, so the +// relay case lives with the Rust relay (rs/moq-net/tests/integration/subscribe_priority.rs). + +import { expect, test } from "bun:test"; +import { accept, connect, type Established } from "./connection/index.ts"; +import * as Ietf from "./ietf/index.ts"; +import * as Lite from "./lite/index.ts"; +import { createMockTransportPair } from "./mock.ts"; +import { Producer as OriginProducer } from "./origin.ts"; +import * as Path from "./path.ts"; +import { Timescale } from "./time.ts"; +import type { Producer as TrackProducer } from "./track.ts"; +import { wireOf } from "./wire.ts"; + +const url = new URL("https://localhost:4443/test"); +const path = Path.from("test"); + +const LOW = 1; +const HIGH = 200; + +// Dial a session that consumes what `origin` serves. Draft-14's ALPN is the generic one, so +// the server is told the version instead. +async function session(protocol: string, origin: OriginProducer): Promise<[Established, Established]> { + const draft14 = protocol === Ietf.ALPN.DRAFT_14; + const pair = createMockTransportPair(draft14 ? "" : protocol); + return Promise.all([ + connect({ url, transport: pair.client }), + accept({ + transport: pair.server, + url, + publish: origin.consume(), + version: draft14 ? Ietf.Version.DRAFT_14 : undefined, + }), + ]); +} + +// Resolve once the subscription `track` serves asks for `want`. +async function priority(track: TrackProducer, want: number): Promise { + while (track.subscription.peek()?.priority !== want) await track.subscription.changed(); +} + +test.each([Lite.ALPN_07_WIP, ...Object.values(Ietf.ALPN)])( + "%s follows the aggregate priority upstream", + async (protocol) => { + const origin = new OriginProducer(); + const broadcast = origin.createBroadcast(path); + broadcast.announce(); + const video = broadcast.createTrack("video", { timescale: Timescale.MILLI }); + const [client, server] = await session(protocol, origin); + + const remote = wireOf(client).consume(path); + const low = remote.track("video").subscribe({ priority: LOW }); + await priority(video, LOW); + + // A second subscriber at a higher priority raises the one upstream request. + const high = remote.track("video").subscribe({ priority: HIGH }); + await priority(video, HIGH); + + // Leaving lowers it again. + high.close(); + await priority(video, LOW); + expect(video.subscription.peek()?.priority).toBe(LOW); + + low.close(); + remote.close(); + broadcast.close(); + client.abort(); + server.abort(); + }, +); diff --git a/quest/m1/subscribe-ranges/README.md b/quest/m1/subscribe-ranges/README.md index 20f0f240239..6897d975607 100644 --- a/quest/m1/subscribe-ranges/README.md +++ b/quest/m1/subscribe-ranges/README.md @@ -89,7 +89,6 @@ every sequence delivered or dropped. - [Dynamic range requests](/quest/m1/subscribe-ranges/dynamic.md) - `Dynamic` fills misses by range, a subscriber reads only its own ranges, and a range end may be a time - [SUBSCRIBE_DROP](/quest/m1/subscribe-drop.md) - publishers name every group they won't deliver - [Lite-07 ranges](/quest/m1/subscribe-ranges/lite.md) - the lite-07 wire, Rust publisher and subscriber, and the draft -- [moq-transport upstream updates](/quest/m1/subscribe-ranges/ietf-update.md) - the upstream request follows the aggregate priority; its order stays fixed, as every draft requires - [moq-transport ranges](/quest/m1/subscribe-ranges/ietf.md) - range FETCH upstream per missing run, and non-blocking FETCH served downstream - [JS ranges](/quest/m1/subscribe-ranges/js.md) - `@moq/net` model and lite-07 parity diff --git a/quest/m1/subscribe-ranges/ietf-update.md b/quest/m1/subscribe-ranges/ietf-update.md deleted file mode 100644 index 4f28237a813..00000000000 --- a/quest/m1/subscribe-ranges/ietf-update.md +++ /dev/null @@ -1,64 +0,0 @@ -# [S] moq-transport upstream updates - -## Goal - -A relay's moq-transport upstream subscription follows its downstream -subscribers: when their aggregate subscriber priority changes, the relay sends -SUBSCRIBE_UPDATE (drafts 14 and 15) or REQUEST_UPDATE (draft-16 on) with the -new priority, as lite-07 already does. Today the IETF subscriber reads the -aggregate once, at SUBSCRIBE (`rs/moq-net/src/ietf/subscriber.rs`, -`js/net/src/ietf/subscriber.ts`), and never updates the request. - -Group order is not part of this. The upstream order stays whatever SUBSCRIBE -asked for (decided 2026-10-13 in #5400: updates carry priority only, with no -re-subscribe and no forced Descending upstream). - -## Plan - -Researched 2026-10-13 against the published drafts 14 to 22: no moq-transport -draft lets a subscriber change a subscription's group order. - -- Every draft says the group order of an existing subscription cannot be - changed (§7.1 in 14 to 20, §5.1.1 in 21 and 22). -- Draft-14's SUBSCRIBE_UPDATE has no Group Order field. From draft-15 on, - GROUP_ORDER's list of allowed messages leaves out the update message, and - draft-22 spells out per request type what a REQUEST_UPDATE may carry. -- Sending it anyway is ignored on 14 and 15, ambiguous on 16, and a - PROTOCOL_VIOLATION from draft-17 on. Draft-20 to 22 allow GROUP_ORDER inside - FILL_PARAMETERS, but that orders a new fill, not the subscription. -- The only way to change the order is to UNSUBSCRIBE and SUBSCRIBE again with - a fill or FETCH for the gap. That is not planned: it costs a round trip and - a gap to change a transmission preference on one leg, and the relay already - serves each downstream subscriber in its own order. - -What an update can carry, and this quest sends: - -- Subscriber priority, on every draft: a fixed field on draft-14, the - SUBSCRIBER_PRIORITY parameter after. -- Draft-14's SUBSCRIBE_UPDATE also requires Start Location and End Group, so a - priority update repeats the subscription's current bounds rather than - zeroes, which a conforming peer would read as narrowing to group 0. -- From draft-15 on, a priority update omits the subscription filter. Today - `SubscribeUpdate::encode_msg` (`rs/moq-net/src/ietf/subscribe.rs`) always - writes `Filter::NextObject`, which would reset the filter. -- Forward stays 1. Pausing is not part of this. -- The subscription filter is updatable from draft-15 on. Narrowing upstream - ranges belongs to [moq-transport ranges](/quest/m1/subscribe-ranges/ietf.md), - which can reuse this update path. Widening is a bug today: on draft-20 and - later, a subscriber from a future group puts its absolute start in the - SUBSCRIBE filter, and a live subscriber merged in after it never gets the - current group. `rs/moq-net/tests/subscribe_ranges.rs` leaves draft-20+ out - for that reason; add it back once the update carries the widened filter. - -Implementation: the IETF subscriber watches the aggregate the way -`lite/subscriber.rs` does (`buffer_update`), sending one update per change -and coalescing changes while one is in flight. The publisher side already -applies a priority update to open group streams -(`subscription_update_reprioritizes_open_group_streams`), and so does the JS -publisher on every draft. Test on mock time, -in Rust and JS, directly and through a relay: a second downstream subscriber -at a higher priority raises the upstream priority, and leaving lowers it again. - -## Related - -- [Scope and sign track priority](/quest/m1/track-priority-scope.md) - may stop forwarding downstream priority upstream on relay-to-relay links, which changes what this sends diff --git a/quest/m1/subscribe-ranges/ietf.md b/quest/m1/subscribe-ranges/ietf.md index ef161efd4b1..2ad5580291d 100644 --- a/quest/m1/subscribe-ranges/ietf.md +++ b/quest/m1/subscribe-ranges/ietf.md @@ -33,6 +33,17 @@ bounded FETCH that ends exactly at the track's last object reports when the track has finished and the FETCH reaches its final object, never from a live track's Largest Object, and test both cases. +Upstream range changes ride the subscription update that already carries the +aggregate priority (`write_update` in `ietf/subscriber.rs`). Narrowing is +allowed from draft-15 on. Widening is a bug today: on draft-20 and later, a +subscriber from a future group puts its absolute start in the SUBSCRIBE filter, +and a live subscriber merged in after it never gets the current group. Draft-20 +lets an update lower the start with FILL_PARAMETERS for what it missed, which +opens a second fill stream on the subscription. Draft 14 forbids widening, and +15 to 19 have no fill. `rs/moq-net/tests/integration/subscribe_ranges.rs` +leaves draft-20+ out for that reason; add it back once the update carries the +widened filter. + moq-transport has no time filter, so a downstream `Time(pts)` end is resolved against the relay's cache before it goes upstream as a group range, or refused when the cache cannot resolve it. diff --git a/rs/moq-net/src/ietf/subscriber.rs b/rs/moq-net/src/ietf/subscriber.rs index 43ce2d39ce1..75876dbdbfc 100644 --- a/rs/moq-net/src/ietf/subscriber.rs +++ b/rs/moq-net/src/ietf/subscriber.rs @@ -2630,8 +2630,8 @@ where } // Write Subscribe message. The aggregate is read now: a subscriber can join while - // the request ID and stream were awaited, and nothing updates the priority or - // order after. + // the request ID and stream were awaited. Updates follow its priority from here, but + // no draft lets one change the order. let aggregate = target.subscription(); let priority = aggregate.as_ref().map(|s| s.priority).unwrap_or(0); let order = aggregate.map(|s| s.order).unwrap_or_default(); @@ -2922,7 +2922,7 @@ where Revoked, Done(Result), Fetch(group::Request), - NewGroup(u64), + Update(Update), } // The SUBSCRIBE's request is outstanding from the Largest Group its answer named. @@ -2933,6 +2933,15 @@ where let dynamic_groups = track.info().dynamic_groups && super::subscribe::has_new_group_request(self.version); // The aggregate request last read, so only a change is considered. let mut asked = None; + // The subscriber priority upstream holds, and the one the aggregate now asks for. + let mut sent_priority = priority; + let mut priority = priority; + // Draft-14's SUBSCRIBE_UPDATE repeats the bounds it leaves alone, and must not move the + // start. A Largest Object subscription starts just past the answer's Largest. + let start_location = largest.map_or(ietf::Location { group: 0, object: 0 }, |largest| ietf::Location { + group: largest.group, + object: largest.object.saturating_add(1), + }); // REQUEST_UPDATEs sent and not yet answered. Drafts 14-16 answer on the control // stream by the update's own Request ID, which reaches no subscription, so only // later drafts count them. @@ -2976,6 +2985,9 @@ where // lite, and the copy lingers for fetches and a returning subscriber. while let Poll::Ready(Ok(subscription)) = track.poll_subscription_changed(waiter) { subscribed = subscription.is_some(); + if let Some(subscription) = subscription { + priority = subscription.priority; + } } if !subscribed || demand.poll_unused(waiter).is_ready() { return Poll::Ready(End::Idle); @@ -2984,26 +2996,45 @@ where return Poll::Ready(End::Done(res)); } // One REQUEST_UPDATE in flight at a time, which any MAX_REQUEST_UPDATES - // allows. Requests arriving meanwhile coalesce into the aggregate, read + // allows. Changes arriving meanwhile coalesce into the aggregate, read // once its answer lands. Polled after the answers are read for that reason. - if dynamic_groups - && unanswered.load(Ordering::Relaxed) == 0 - && let Poll::Ready(Ok(Some(request))) = track.poll_new_group(&mut asked, waiter) - && new_groups.forward(request.value, largest_group(&track, largest)) - { - return Poll::Ready(End::NewGroup(request.value)); + if unanswered.load(Ordering::Relaxed) > 0 { + return Poll::Pending; + } + let new_group = match dynamic_groups { + true => match track.poll_new_group(&mut asked, waiter) { + Poll::Ready(Ok(Some(request))) + if new_groups.forward(request.value, largest_group(&track, largest)) => + { + Some(request.value) + } + _ => None, + }, + false => None, + }; + let update = Update { + start_location, + priority: (priority != sent_priority).then_some(priority), + new_group, + }; + match update.priority.is_some() || update.new_group.is_some() { + true => Poll::Ready(End::Update(update)), + false => Poll::Pending, } - Poll::Pending }) .await; match end { - End::NewGroup(value) => { - if let Err(err) = self.write_new_group(&mut stream.writer, request_id, value).await { - tracing::debug!(%err, "failed to request a new group"); + End::Update(update) => { + let wanted = update.priority; + if let Err(err) = self.write_update(&mut stream.writer, request_id, update).await { + tracing::debug!(%err, "failed to update the subscription"); let _ = track.clone().abort(err); break false; } + if let Some(wanted) = wanted { + sent_priority = wanted; + } if answered_here { unanswered.fetch_add(1, Ordering::Relaxed); } @@ -3242,40 +3273,41 @@ where match type_id { ietf::RequestOk::ID => { let msg = ietf::RequestOk::decode_msg(&mut data, version)?; - tracing::debug!(message = ?msg, "new group request ok"); + tracing::debug!(message = ?msg, "subscription update ok"); unanswered.fetch_sub(1, Ordering::Relaxed); } _ => { let msg = ietf::RequestError::decode_msg(&mut data, version)?; - tracing::debug!(message = ?msg, "new group request refused"); + tracing::debug!(message = ?msg, "subscription update refused"); refused = true; } } } } - /// Ask the publisher for a new group on an Established subscription: REQUEST_UPDATE - /// (SUBSCRIBE_UPDATE on draft-16) carrying NEW_GROUP_REQUEST and nothing else. - async fn write_new_group( + /// Update an Established subscription: REQUEST_UPDATE (SUBSCRIBE_UPDATE through draft-16) + /// carrying only what changed, under a Request ID of its own. + async fn write_update( &self, writer: &mut Writer, subscription: RequestId, - value: u64, + update: Update, ) -> Result<(), Error> { let request_id = self.control.next_request_id(&self.runtime).await?; writer.varint(ietf::SubscribeUpdate::ID).await?; writer .encode(&ietf::SubscribeUpdate { request_id, - subscription_request_id: matches!(self.version, Version::Draft15 | Version::Draft16) + subscription_request_id: matches!(self.version, Version::Draft14 | Version::Draft15 | Version::Draft16) .then_some(subscription), - start_location: ietf::Location { group: 0, object: 0 }, + start_location: update.start_location, + // Open ended, as every subscription we send. end_group: 0, - subscriber_priority: None, + subscriber_priority: update.priority.map(super::priority::to_wire), forward: None, filter: None, authorization_token: None, - new_group: Some(value), + new_group: update.new_group, }) .await } @@ -6783,6 +6815,83 @@ mod tests { ); } + /// Draft-14's SUBSCRIBE_UPDATE has no optional fields, so a priority update repeats the + /// subscription's bounds: a Largest Object subscription starts just past the answer's + /// Largest, open ended. Zeroes would move the start back, which the draft forbids. + #[moq_clock::test] + async fn a_draft14_priority_update_repeats_the_bounds() { + const VERSION: Version = Version::Draft14; + + let subscribe_ok = message( + ietf::SubscribeOk::ID, + &ietf::SubscribeOk { + request_id: Some(RequestId(0)), + track_alias: 7, + largest: Some(ietf::Location { group: 5, object: 2 }), + properties: Default::default(), + }, + VERSION, + ); + let session = crate::lite::test_transport::ScriptedSession::new(subscribe_ok); + let log = session.log.clone(); + + let (tasks, _task_set) = crate::util::TaskSet::new(); + let mut subscriber = Subscriber::new( + crate::time::sim(), + session, + crate::origin::Config::new(crate::Hop::new(1).unwrap()).produce(), + Control::new(None, false), + None, + peer::PeerSetup::default(), + crate::Hop::new(1).unwrap(), + None, + VERSION, + tasks, + Default::default(), + ); + + let producer = crate::broadcast::Info::default().produce(); + let mut dynamic = producer.dynamic(); + let consumer = producer.consume(); + let track = consumer.track("video").unwrap(); + let _low = track.subscribe(track::Subscription::default().with_priority(1)); + let request = dynamic.requested_track().await.expect("no track requested"); + let _serving = moq_clock::sim::spawn(async move { + subscriber + .run_subscribe(Path::new("broadcast"), dynamic, None, request) + .await; + }); + settle().await; + + let _high = track.subscribe(track::Subscription::default().with_priority(200)); + settle().await; + + let writes = log.writes.lock().unwrap().clone(); + let mut buf = Decoder::new(&writes, VERSION.into()); + let (mut subscribe, mut updates) = (None, Vec::new()); + while !buf.is_empty() { + let type_id = buf.varint().unwrap(); + let size = buf.u16().unwrap() as usize; + let mut body = Decoder::new(buf.slice(size).unwrap(), VERSION.into()); + match type_id { + ietf::Subscribe::ID => subscribe = Some(RequestId::decode(&mut body, VERSION).unwrap()), + ietf::SubscribeUpdate::ID => { + updates.push(ietf::SubscribeUpdate::decode_msg(&mut body, VERSION).unwrap()) + } + _ => {} + } + } + + let [update] = updates.as_slice() else { + panic!("one update, not {updates:?}"); + }; + assert_eq!(update.subscription_request_id, subscribe); + assert_eq!(update.start_location, ietf::Location { group: 5, object: 3 }); + assert_eq!(update.end_group, 0, "still open ended"); + assert_eq!(update.subscriber_priority, Some(super::super::priority::to_wire(200))); + assert_eq!(update.forward, Some(true)); + } + /// Establish a subscription on `version`, then drop its last consumer, and hand back /// what the session recorded on the way out. async fn cancel_a_subscription(version: Version) -> crate::lite::test_transport::Log { @@ -10697,6 +10806,16 @@ mod tests { /// What a SUBSCRIBE asks for: the range it delivers, and the backfill covering a head that /// range excludes. +/// What an update to an Established subscription changes. +struct Update { + /// Draft-14's mandatory Start Location, repeated as it stands; unused on later drafts. + start_location: ietf::Location, + /// The aggregate subscriber priority, in the model's higher-first terms. + priority: Option, + /// NEW_GROUP_REQUEST. + new_group: Option, +} + #[derive(Debug, Default, PartialEq, Eq)] struct Join { /// The Location Filter, bounding what the subscription itself delivers. diff --git a/rs/moq-net/tests/integration/main.rs b/rs/moq-net/tests/integration/main.rs index 458ccd8e1c9..cf32a42bef4 100644 --- a/rs/moq-net/tests/integration/main.rs +++ b/rs/moq-net/tests/integration/main.rs @@ -44,6 +44,7 @@ mod session_close; mod session_panic; mod settled_end_survives_abort; mod source_errors; +mod subscribe_priority; mod subscribe_ranges; mod subscribe_tracks; mod subscription_end_integrity; diff --git a/rs/moq-net/tests/integration/subscribe_priority.rs b/rs/moq-net/tests/integration/subscribe_priority.rs new file mode 100644 index 00000000000..2af297a313b --- /dev/null +++ b/rs/moq-net/tests/integration/subscribe_priority.rs @@ -0,0 +1,125 @@ +#![cfg(feature = "async")] + +//! One upstream subscription carries the aggregate priority of the subscribers it serves, +//! and follows it as they come and go, directly and through a relay. + +use crate::support; + +use std::time::Duration; + +use moq_net::track::{Info, Subscription}; +use moq_net::{Hop, Timescale, Version, origin}; +use support::harness::peer; + +const TIMEOUT: Duration = Duration::from_secs(10); + +const VERSIONS: &[&str] = &[ + "moq-lite-06", + "moq-lite-07-wip", + "moq-transport-14", + "moq-transport-15", + "moq-transport-16", + "moq-transport-17", + "moq-transport-18", + "moq-transport-19", + "moq-transport-20", + "moq-transport-21", + "moq-transport-22", +]; + +const LOW: u8 = 1; +const HIGH: u8 = 200; + +fn produce_origin(hop: u64) -> origin::Producer { + let (producer, driver) = origin::Producer::new(origin::Config::new(Hop::new(hop).unwrap())); + support::harness::spawn(driver); + producer +} + +/// Wait until the subscription `track` serves asks for `want`. +async fn priority(track: &moq_net::track::Producer, want: u8) -> Result<(), String> { + let mut track = track.clone(); + let reached = moq_clock::timeout(TIMEOUT, async { + while track + .subscription() + .is_none_or(|subscription| subscription.priority != want) + { + track.subscription_changed().await.expect("track open"); + } + }) + .await; + reached.map_err(|_| { + format!( + "priority stuck at {:?}, wanted {want}", + track.subscription().map(|s| s.priority) + ) + }) +} + +/// A low priority subscriber, joined by a high priority one that then leaves: the +/// publisher sees the priority rise and fall back. +async fn follows(version: Version, relay: bool) -> Result<(), String> { + let publisher = produce_origin(1); + let broadcast = publisher.create_broadcast("bcast").unwrap(); + let track = broadcast + .create_track("video", Info::default().with_timescale(Timescale::MILLI)) + .unwrap(); + broadcast.announce(Default::default()).unwrap(); + + let relay_origin = produce_origin(2); + let subscriber = produce_origin(3); + let mut pairs = Vec::new(); + if relay { + pairs.push(peer(version, &publisher, &relay_origin).await); + pairs.push(peer(version, &relay_origin, &subscriber).await); + } else { + pairs.push(peer(version, &publisher, &subscriber).await); + } + + let consumer = subscriber.consume(); + moq_clock::timeout(TIMEOUT, consumer.routed("bcast")) + .await + .expect("announce timeout") + .expect("routed"); + let remote = moq_clock::timeout(TIMEOUT, consumer.request_broadcast("bcast", None)) + .await + .expect("resolve timeout") + .expect("broadcast resolves"); + let subscribe = |priority: u8| { + let track = remote.track("video").unwrap(); + async move { + moq_clock::timeout( + TIMEOUT, + track.subscribe(Subscription::default().with_priority(priority)), + ) + .await + .expect("subscribe timeout") + .expect("subscribe") + } + }; + + let _low = subscribe(LOW).await; + priority(&track, LOW) + .await + .map_err(|err| format!("first subscriber: {err}"))?; + + let high = subscribe(HIGH).await; + priority(&track, HIGH).await.map_err(|err| format!("joined: {err}"))?; + + drop(high); + priority(&track, LOW).await.map_err(|err| format!("left: {err}"))?; + Ok(()) +} + +#[moq_clock::test] +async fn upstream_priority_follows_the_subscribers() { + let mut failures = Vec::new(); + for version in VERSIONS { + for relay in [false, true] { + if let Err(err) = follows(version.parse().unwrap(), relay).await { + failures.push(format!("{version} relay={relay}: {err}")); + } + } + } + assert!(failures.is_empty(), "{failures:#?}"); +} diff --git a/rs/moq-net/tests/integration/subscribe_ranges.rs b/rs/moq-net/tests/integration/subscribe_ranges.rs index e6016fecf19..8b7dddabb4b 100644 --- a/rs/moq-net/tests/integration/subscribe_ranges.rs +++ b/rs/moq-net/tests/integration/subscribe_ranges.rs @@ -16,8 +16,8 @@ const TIMEOUT: Duration = Duration::from_secs(10); const LITE: &[&str] = &["moq-lite-05", "moq-lite-06", "moq-lite-07-wip"]; /// Draft-20 and later are left out: the first subscriber's absolute start goes upstream -/// in the SUBSCRIBE filter, and the subscriber never updates it when a live one joins -/// (`quest/m1/subscribe-ranges/ietf-update.md`), so group 3 never arrives. +/// in the SUBSCRIBE filter, and the subscriber never widens it when a live one joins +/// (`quest/m1/subscribe-ranges/ietf.md`), so group 3 never arrives. const TRANSPORT: &[&str] = &["moq-transport-14", "moq-transport-17"]; fn produce_origin(hop: u64) -> moq_net::origin::Producer { From c3a5cc27f71bd2ab63f3bedc32e33280bc15f385 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sun, 18 Oct 2026 23:42:04 -0700 Subject: [PATCH 3/4] fix(net): finish a JS subscription update before cancelling Teardown awaited only the cancellation, so an update still being written could interleave with UNSUBSCRIBE, and on drafts 14 and 15 its spent request ID might never reach the wire, stalling later requests. Co-Authored-By: Claude Opus 5.5 --- js/net/src/ietf/subscriber.ts | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/js/net/src/ietf/subscriber.ts b/js/net/src/ietf/subscriber.ts index 1f371ade089..e3427771aa4 100644 --- a/js/net/src/ietf/subscriber.ts +++ b/js/net/src/ietf/subscriber.ts @@ -832,7 +832,7 @@ export class Subscriber { producer.closed.then(() => localEnded), revoked, ]); - void this.#runUpdates(stream, requestId, producer, priority, unanswered, done); + const updates = this.#runUpdates(stream, requestId, producer, priority, unanswered, done); // Serve until a terminal condition fires or the last local subscriber leaves. The unused // wake is level-triggered: re-check demand so a subscriber that returns before we tear @@ -857,6 +857,11 @@ export class Subscriber { producer.close(); } + // Closing settled `done`, so an update still being written finishes and nothing starts + // another. Its bytes must not interleave with the cancellation, and on drafts 14 and 15 + // its spent request ID must reach the wire before any later one can. + await updates; + // The publisher already ended the request, so there is nothing to cancel. Sending // UNSUBSCRIBE here would name a request it has already torn down. if (terminal !== publisherEnded) await this.#cancelSubscribe(stream, requestId); From 5c6fa053cea2049172a2abc57bcd821c8d3236f2 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 19 Oct 2026 09:37:42 -0700 Subject: [PATCH 4/4] fix(net): count an update as unanswered before writing it The publisher's answer could be read before the write's promise resolved, so the subscription saw REQUEST_OK with nothing outstanding and failed with an unexpected message. The test now acknowledges client writes a task late, which hits the race every run instead of about 1.7% under load. Co-Authored-By: Claude Opus 5.5 --- js/net/src/ietf/subscriber.ts | 3 ++- js/net/src/subscribe_priority.test.ts | 22 +++++++++++++++++++++- 2 files changed, 23 insertions(+), 2 deletions(-) diff --git a/js/net/src/ietf/subscriber.ts b/js/net/src/ietf/subscriber.ts index e3427771aa4..6fe030f0a5c 100644 --- a/js/net/src/ietf/subscriber.ts +++ b/js/net/src/ietf/subscriber.ts @@ -982,6 +982,8 @@ export class Subscriber { const update = legacy ? new SubscribeUpdate({ requestId, ownRequestId: own, parameters }) : new SubscribeUpdate({ requestId: own, parameters }); + // Counted before writing: the answer can be read before the write's promise resolves. + if (!legacy) unanswered.update((count) => count + 1); try { await stream.writer.u53(SubscribeUpdate.id); await update.encode(stream.writer, version); @@ -990,7 +992,6 @@ export class Subscriber { return; } sent = wanted; - if (!legacy) unanswered.update((count) => count + 1); console.debug(`subscribe update: id=${requestId} priority=${wanted}`); } } diff --git a/js/net/src/subscribe_priority.test.ts b/js/net/src/subscribe_priority.test.ts index 2c94a70adab..682259f1391 100644 --- a/js/net/src/subscribe_priority.test.ts +++ b/js/net/src/subscribe_priority.test.ts @@ -6,7 +6,7 @@ import { expect, test } from "bun:test"; import { accept, connect, type Established } from "./connection/index.ts"; import * as Ietf from "./ietf/index.ts"; import * as Lite from "./lite/index.ts"; -import { createMockTransportPair } from "./mock.ts"; +import { createMockTransportPair, type MockTransport } from "./mock.ts"; import { Producer as OriginProducer } from "./origin.ts"; import * as Path from "./path.ts"; import { Timescale } from "./time.ts"; @@ -24,6 +24,7 @@ const HIGH = 200; async function session(protocol: string, origin: OriginProducer): Promise<[Established, Established]> { const draft14 = protocol === Ietf.ALPN.DRAFT_14; const pair = createMockTransportPair(draft14 ? "" : protocol); + lateAcks(pair.client); return Promise.all([ connect({ url, transport: pair.client }), accept({ @@ -35,6 +36,25 @@ async function session(protocol: string, origin: OriginProducer): Promise<[Estab ]); } +// Acknowledge each write on the client's bidirectional streams a task late, after the peer +// can already have answered it, as a real send stream may. +function lateAcks(transport: MockTransport) { + const create = transport.createBidirectionalStream.bind(transport); + transport.createBidirectionalStream = async (options) => { + const stream = await create(options); + const inner = stream.writable.getWriter(); + const writable = new WritableStream({ + async write(chunk) { + await inner.write(chunk); + await new Promise((resolve) => setTimeout(resolve, 0)); + }, + close: () => inner.close(), + abort: (reason) => inner.abort(reason), + }); + return { readable: stream.readable, writable }; + }; +} + // Resolve once the subscription `track` serves asks for `want`. async function priority(track: TrackProducer, want: number): Promise { while (track.subscription.peek()?.priority !== want) await track.subscription.changed();