From 5779cde4c1e535f96dc600b28a53e9fa4a24612a Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Fri, 28 Aug 2026 14:42:34 -0700 Subject: [PATCH 1/4] feat(net): resolve an absent subscribe start from the subscriber's max age A SUBSCRIBE that names no Group Start meant the latest group, so a subscriber joining a track already in flight skipped everything the publisher was still holding for it. That is invisible on a continuous broadcast and obvious on a publisher that opens a track per utterance: the head of every track is discarded while it sits in the cache. Resolve the start from the budget the subscriber already sent instead. Max Age says how far behind the live edge a group may be before it is skipped, so the oldest group worth starting at is the oldest one that budget does not already convict. A zero budget (the default) still resolves to the latest group, since every older group is stale the moment a newer one exists, so an existing subscriber sees no change. The two bounds cannot disagree: the same predicate that expires a group on the way out picks where to begin, so a publisher never sends history the subscriber would discard on arrival, nor withholds a group it would have taken. A wire that cannot carry Max Age is served with an unbounded budget so backlog is never dropped under a legacy subscriber, and that must not read as a request to replay the cache, so those sessions keep resolving to the latest group. Groups go out newest-first, so the resolved head arrives after the live edge that was served alongside it. The container consumer dropped anything below its delivery cursor, which threw the head away again one layer down. Audio can take those: the ring is timestamp indexed, so a late group lands in its own slot however it arrives. Video cannot, so the strict cursor stays the default and audio opts in. Co-Authored-By: Claude Opus 5 --- doc/concept/layer/moq-lite.md | 7 +- drafts/draft-lcurley-moq-lite.md | 10 +- .../src/container/consumer.backfill.test.ts | 87 +++++++++++++ js/hang/src/container/consumer.ts | 27 +++- js/net/src/lite/publisher.ts | 26 +++- js/net/src/track.test.ts | 35 +++++ js/net/src/track.ts | 25 ++++ js/watch/src/audio/decoder.ts | 6 + rs/moq-net/src/lite/publisher.rs | 51 +++++++- rs/moq-net/src/model/track.rs | 121 ++++++++++++++++++ 10 files changed, 381 insertions(+), 14 deletions(-) create mode 100644 js/hang/src/container/consumer.backfill.test.ts diff --git a/doc/concept/layer/moq-lite.md b/doc/concept/layer/moq-lite.md index 0b43c17f849..928ea054c20 100644 --- a/doc/concept/layer/moq-lite.md +++ b/doc/concept/layer/moq-lite.md @@ -88,11 +88,13 @@ If the peer doesn't have the broadcast/track, they will get an error. Otherwise, the subscription is active and will stay open until closed by the publisher (possibly with an error). A track is broken into **groups**, each with an increasing ID. -Conceptually, these are join points, and new subscriptions will always start at the latest group. +Conceptually, these are join points, and new subscriptions start at the newest group they can still use. Groups are delivered independently and potentially out of order, so you should have some logic to reorder or skip during congestion. A group is closed when finished or aborted with an error (ex. during congestion). -A subscription starts at the latest group by default, but can name any (group, frame) position instead. +A subscription lets the publisher choose the start by default, but can name any (group, frame) position instead. +Left to the publisher, it resolves to the oldest group within **Subscriber Max Age**, which is the latest group at the default budget of zero. +A subscriber that buffers is then handed the head of what it can still play instead of only the live edge, and never history it would skip on arrival: one bound decides both. That is how a subscriber follows a track to a different publisher partway through a group, which matters when the current group may stay open indefinitely (a JSON append log, or a catalog that keeps appending deltas). A group can therefore be assembled from more than one publisher: each contributes a disjoint run of frames, and the subscriber concatenates them in index order. @@ -127,6 +129,7 @@ The media timeline keeps a backlog delivered as a burst old, while wall-clock ti Both ends apply it: the publisher skips a group rather than sending it, and the subscriber skips it again as it reads. The publisher only ever sees the most tolerant budget across its subscribers, which is why the subscriber applies it too. Asking for old groups with `Group Start` does not exempt them: a start bounds what you are sent, and a subscriber that wants history has to raise its budget to match. +That is also why the budget is what resolves an unset start: the groups worth sending are exactly the ones it would not immediately skip. The publisher also keeps old groups around for a best-effort **Publisher Max Age** cache window so relays and late subscribers can still fetch them. This defaults to 5 seconds. The subscriber's max age is bounded by this window: a group can't be waited for longer than it's actually kept around. diff --git a/drafts/draft-lcurley-moq-lite.md b/drafts/draft-lcurley-moq-lite.md index fb12d9836a5..adbdf2fa14b 100644 --- a/drafts/draft-lcurley-moq-lite.md +++ b/drafts/draft-lcurley-moq-lite.md @@ -185,7 +185,7 @@ Only the subscriber knows whether a partial Group is any use to it, so only the Frame indices are only meaningful relative to a Group the subscriber has already begun receiving, so: -- A `Frame Start` is meaningless without an absolute `Group Start`; a subscriber requesting the latest group (`Group Start` = 0) MUST send `Frame Start` = 0. +- A `Frame Start` is meaningless without an absolute `Group Start`; a subscriber letting the publisher choose the start (`Group Start` = 0) MUST send `Frame Start` = 0. - A `Frame End` is meaningless without a `Group End`; an unbounded subscription (`Group End` = 0) MUST send `Frame End` = 0. A publisher MUST treat a violation of either rule as a protocol violation and reset the stream. @@ -987,9 +987,14 @@ See the [Expiration](#expiration) section for more information. **Group Start**: The first group to deliver. -A value of 0 means the latest group (default). +A value of 0 means the publisher chooses (default). A non-zero value is the absolute group sequence + 1. +When it does, the publisher SHOULD start at the oldest cached group whose age is within `Subscriber Max Age`, and MUST NOT start at an older one. +A `Subscriber Max Age` of 0 therefore starts at the latest group, since every older group is already stale. +A subscriber that buffers has then been handed the head of what it can still play instead of only the live edge, and is never sent history it would discard on arrival: the same bound decides what to start at and what to expire, so the two cannot disagree. +This is a floor on delivery, not a guarantee that the groups exist; see `Publisher Max Age` in [TRACK_INFO](#track-info). + **Group End**: The last group to deliver (inclusive). A value of 0 means unbounded (default). @@ -1368,6 +1373,7 @@ The `Message Length` describes the payload size on the wire. - Exempted a ceiling-cost serving path from the actively-carrying cost discount: a relay whose serving path costs the saturation ceiling (primarily a session that received a GOAWAY) advertises the ceiling instead of 0, so the drain propagates downstream instead of being re-masked by each carrying hop. Keyed on the value, not the reason, which does not travel on the wire. - Added the Error Codes section, defining separate session and stream code spaces and listing the codes moq-lite uses, reused unchanged from moq-transport. Codes 64+ are the application's; 32-63 are reserved and MUST NOT be interpreted, pending a future revision. Previously the codes were unspecified, so an endpoint could neither send one a peer would understand nor safely interpret one it received. Note this renumbers every code an existing implementation sent, and that a stream reset of 0x0 is now INTERNAL_ERROR rather than a cancellation (CANCELLED is 0x1). - Renamed `Subscriber Max Latency` to `Subscriber Max Age` and `Publisher Max Latency` to `Publisher Max Age`. +- Resolve an absent `Group Start` from `Subscriber Max Age` rather than always taking the latest group, so a subscriber that buffers is handed the head of what it can still play. A zero budget still resolves to the latest group. ## moq-lite-05 - Renamed ANNOUNCE_INTEREST to ANNOUNCE_REQUEST and ANNOUNCE to ANNOUNCE_BROADCAST. diff --git a/js/hang/src/container/consumer.backfill.test.ts b/js/hang/src/container/consumer.backfill.test.ts new file mode 100644 index 00000000000..092668d9a51 --- /dev/null +++ b/js/hang/src/container/consumer.backfill.test.ts @@ -0,0 +1,87 @@ +import { expect, test } from "bun:test"; +import { Group, Time, Track, Varint } from "@moq/net"; +import { Consumer } from "./consumer.ts"; +import { Format as LegacyFormat } from "./legacy.ts"; + +// Standalone from consumer.test.ts so it only pulls the Legacy format, not the CMAF decoder. + +function encodeLegacyFrame(timestamp: Time.Micro, payload: Uint8Array): Uint8Array { + const tsBytes = Varint.encode(timestamp); + const data = new Uint8Array(tsBytes.byteLength + payload.byteLength); + data.set(tsBytes, 0); + data.set(payload, tsBytes.byteLength); + return data; +} + +/** Publish one closed group carrying a single frame at `millis`. */ +function publish(track: Track.Producer, sequence: number, millis: number) { + const group = new Group.Producer(sequence); + track.writeGroup(group); + group.writeFrame({ + payload: encodeLegacyFrame(Time.Micro.fromMilli(millis as Time.Milli), new Uint8Array([sequence])), + timestamp: Time.Timestamp.fromMillis(millis), + }); + group.close(); +} + +/** Every group and frame the consumer will hand over right now, as [group, payload] pairs. */ +async function drain(consumer: Consumer): Promise<[number, number | undefined][]> { + const seen: [number, number | undefined][] = []; + for (;;) { + const next = await Promise.race([consumer.next(), new Promise((resolve) => setTimeout(resolve, 50))]); + if (!next) break; + const { group, frame } = next as { group: number; frame?: { payload: Uint8Array } }; + seen.push([group, frame?.payload[0]]); + } + return seen; +} + +// A publisher resolving a start from the subscriber's max age serves the head of the window +// alongside the live edge, and groups go out newest-first, so the head arrives *after* the +// group that is already playing. A consumer placing frames by timestamp (the audio ring) can +// still use every one of them, so they must not be dropped for arriving in that order. +test("out-of-order groups reach a consumer that can place them", async () => { + const track = new Track.Producer("test").accept({ maxAge: 30_000 }); + const consumer = new Consumer(track.subscribe({ maxAge: 5000 }), { + format: new LegacyFormat(), + latency: 5000 as Time.Milli, + outOfOrder: true, + }); + + // The live edge lands first, and delivery starts there rather than waiting. + publish(track, 3, 30); + expect((await consumer.next())?.frame?.payload).toEqual(new Uint8Array([3])); + + // The window's head follows it. Every group is still within both budgets, so all three + // are handed over even though each sits below the group already delivered. + publish(track, 0, 0); + publish(track, 1, 10); + publish(track, 2, 20); + + const delivered = (await drain(consumer)).filter(([, payload]) => payload !== undefined); + expect(delivered).toEqual([ + [0, 0], + [1, 1], + [2, 2], + ]); +}); + +// The default stays strict: a decoder that consumes in order has nothing to do with a GoP +// that arrives after a newer one, so the cursor is a floor as before. +test("a late group is dropped unless the consumer opts in", async () => { + const track = new Track.Producer("test").accept({ maxAge: 30_000 }); + const consumer = new Consumer(track.subscribe({ maxAge: 5000 }), { + format: new LegacyFormat(), + latency: 5000 as Time.Milli, + }); + + publish(track, 3, 30); + expect((await consumer.next())?.frame?.payload).toEqual(new Uint8Array([3])); + + publish(track, 0, 0); + publish(track, 1, 10); + publish(track, 2, 20); + + const delivered = (await drain(consumer)).filter(([, payload]) => payload !== undefined); + expect(delivered).toEqual([]); +}); diff --git a/js/hang/src/container/consumer.ts b/js/hang/src/container/consumer.ts index f3bf50c65c2..8d84a18f014 100644 --- a/js/hang/src/container/consumer.ts +++ b/js/hang/src/container/consumer.ts @@ -12,6 +12,17 @@ export interface ConsumerProps { /** Target latency in milliseconds, controlling how aggressively slow groups are skipped (default: 0). */ // Read-only: a Getter (e.g. another component's output) is accepted directly. latency?: GetterInit; + /** + * Deliver a group that arrives below the delivery cursor instead of dropping it (default: + * false). + * + * Groups are sent newest-first, so the head a publisher serves ahead of the live edge + * arrives *after* it. Set this when the caller places frames by timestamp, as the audio + * ring does, and a late group lands in its own slot however it arrives. Leave it off for a + * decoder that consumes in order: a GoP that arrives after a newer one has nothing to + * contribute. The latency budget still bounds how far back one may be. + */ + outOfOrder?: boolean; } interface Group { @@ -113,6 +124,7 @@ export class Consumer { #track: Moq.Track.Subscriber; #format: Format; #latency: Getter; + #outOfOrder: boolean; #groups: Group[] = []; #active?: number; // the active group sequence number // Presentation end (max PTS + duration) of the group we most recently advanced past, so next()'s @@ -144,6 +156,7 @@ export class Consumer { this.#track = track; this.#format = props.format; this.#latency = getter(props.latency ?? Moq.Time.Milli.zero); + this.#outOfOrder = props.outOfOrder ?? false; this.#signals.spawn(this.#run.bind(this)); this.#signals.cleanup(() => { @@ -167,17 +180,21 @@ export class Consumer { this.#active = consumer.sequence; } - // Normally we drop anything behind the cursor. With an active reset the cursor isn't - // a valid floor (a late new-epoch group can sit below it); defer to the boundary and - // admit ambiguous groups so #runGroup can rule on them once their timestamps arrive. + // Normally we drop anything behind the cursor, unless the caller can place a late + // group anyway. With an active reset the cursor isn't a valid floor (a late + // new-epoch group can sit below it); defer to the boundary and admit ambiguous + // groups so #runGroup can rule on them once their timestamps arrive. A group the + // boundary proves reneged is dropped either way: it belongs to a timeline the + // publisher withdrew, which is not the same as arriving late. + const behind = !this.#outOfOrder && consumer.sequence < this.#active; let drop: boolean; if (this.#rewind.boundary) { const verdict = this.#rewind.boundary.bySequence(consumer.sequence); if (verdict === undefined) drop = false; else if (verdict) drop = true; - else drop = consumer.sequence < this.#active; + else drop = behind; } else { - drop = consumer.sequence < this.#active; + drop = behind; } if (drop) { diff --git a/js/net/src/lite/publisher.ts b/js/net/src/lite/publisher.ts index 7338202891b..d7bbf4d3012 100644 --- a/js/net/src/lite/publisher.ts +++ b/js/net/src/lite/publisher.ts @@ -270,8 +270,28 @@ function waitForSubscription(controls: SubscriptionControls, subscriber: track.S * and leave enforcement to the receiver, as the IETF path does for the same reason. */ function servingMaxAge(version: Version, requested: number | undefined): number { - const carriesMaxAge = version !== Version.DRAFT_01 && version !== Version.DRAFT_02; - return carriesMaxAge ? (requested ?? 0) : Number.MAX_SAFE_INTEGER; + return carriesMaxAge(version) ? (requested ?? 0) : Number.MAX_SAFE_INTEGER; +} + +/** Whether this version's SUBSCRIBE carries Subscriber Max Age at all. */ +function carriesMaxAge(version: Version): boolean { + return version !== Version.DRAFT_01 && version !== Version.DRAFT_02; +} + +/** + * Where a subscription that named no Group Start begins. + * + * The oldest group its own {@link servingMaxAge} budget still considers fresh, which is the + * live edge for the default zero budget. A subscriber that tolerates some age is then handed + * the head of what it can still use, rather than joining at the live edge and missing a + * track's opening groups that are sitting right here in the cache. + * + * A wire that cannot carry Max Age has no budget to resolve a start from: those sessions are + * served with an unbounded one so a legacy subscriber never has backlog dropped under it, and + * that must not read as a request to replay the whole cache on join. + */ +function resolvedStart(track: track.Subscriber, version: Version): number | undefined { + return carriesMaxAge(version) ? track.freshStart() : track.latest(); } /** @@ -471,7 +491,7 @@ export class Publisher { startGroup: msg.startGroup, endGroup: msg.endGroup, }); - const startGroup = msg.startGroup ?? track.latest(); + const startGroup = msg.startGroup ?? resolvedStart(track, this.version); if (startGroup !== undefined) track.startAt(startGroup); track.endAt(msg.endGroup); diff --git a/js/net/src/track.test.ts b/js/net/src/track.test.ts index c0c97c4a8a9..45f18d60ce9 100644 --- a/js/net/src/track.test.ts +++ b/js/net/src/track.test.ts @@ -270,6 +270,41 @@ test("latency budget admits groups within its presentation-time window", async ( expect((await track.recvGroup())?.sequence).toBe(2); }); +test("freshStart resolves a start from the subscriber's own budget", () => { + // A subscription that names no start resolves one from its budget, so a subscriber that + // tolerates some age is handed the head of what it can still use instead of only the live + // edge. It has to agree with what delivery keeps, or the publisher would either serve + // groups the subscriber discards on arrival or withhold ones it would have taken. + const producer = new TrackProducer("test").accept({ maxAge: 5000 }); + const live = producer.subscribe(); + const buffered = producer.subscribe({ maxAge: 1500 }); + + expect(live.freshStart()).toBeUndefined(); + + for (const timestamp of [0, 1000, 2000]) { + producer.writeFrame({ payload: enc.encode(`${timestamp}`), timestamp: Timestamp.fromMillis(timestamp) }); + } + + // The default zero budget calls every non-latest group stale, so the only start that + // delivers anything is the live edge. + expect(live.freshStart()).toBe(live.latest()); + expect(live.freshStart()).toBe(2); + expect(buffered.freshStart()).toBe(1); +}); + +test("freshStart is clamped to the publisher's window", () => { + const producer = new TrackProducer("test").accept({ maxAge: 1500 }); + const track = producer.subscribe({ maxAge: 60_000 }); + + for (const timestamp of [0, 1000, 2000]) { + producer.writeFrame({ payload: enc.encode(`${timestamp}`), timestamp: Timestamp.fromMillis(timestamp) }); + } + + // Asking to tolerate a minute cannot reach back further than the publisher keeps a group + // live, the same clamp delivery applies. + expect(track.freshStart()).toBe(1); +}); + test("wall-clock age expires a group stalled before its first frame", async () => { const clock = mockMonotonicTime(10_000); try { diff --git a/js/net/src/track.ts b/js/net/src/track.ts index 9d5f8a20130..b3c00412aba 100644 --- a/js/net/src/track.ts +++ b/js/net/src/track.ts @@ -812,6 +812,31 @@ export class Subscriber { return this.#state.latest; } + /** + * Where a subscription that named no {@link Subscription.startGroup} should begin: the + * oldest cached group this subscriber's {@link Subscription.maxAge} still considers fresh. + * + * A zero budget (the default) resolves to {@link latest}, since every non-latest group is + * stale the moment a newer one exists. A larger budget resolves further back, so a + * subscriber that tolerates some age is handed the head of what it can still use instead + * of only the live edge, without asking for history it would skip on arrival. Undefined + * when nothing is cached. + */ + freshStart(): number | undefined { + const drift = this.#drift(); + const { end } = this.#cursor.peek(); + + let oldest: number | undefined; + for (const { group } of this.#state.timeline.values()) { + if (end !== undefined && group.sequence > end) continue; + if (group.closed.peek() instanceof Error) continue; + if (oldest !== undefined && oldest <= group.sequence) continue; + if (this.#isStale(group, drift)) continue; + oldest = group.sequence; + } + return oldest; + } + /** * The track's exclusive final boundary, known once the producer closes cleanly: * one past the highest sequence produced, or 0 for a track that produced none. diff --git a/js/watch/src/audio/decoder.ts b/js/watch/src/audio/decoder.ts index 084f6d43ca0..33e8ace0827 100644 --- a/js/watch/src/audio/decoder.ts +++ b/js/watch/src/audio/decoder.ts @@ -310,6 +310,10 @@ export class Decoder { const consumer = new Container.Consumer(sub, { format, latency: this.#consumerLatency, + // The ring places samples by timestamp, so a group that arrives below the delivery + // cursor still lands in its own slot. That is how the head a publisher serves ahead + // of the live edge survives being sent after it (groups go newest-first). + outOfOrder: true, }); effect.cleanup(() => consumer.close()); @@ -415,6 +419,8 @@ export class Decoder { const consumer = new Container.Consumer(sub, { format: new Container.Cmaf.Format(init), latency: this.#consumerLatency, + // See #runLegacyDecoder: the ring is timestamp indexed, so a late group is usable. + outOfOrder: true, }); effect.cleanup(() => consumer.close()); diff --git a/rs/moq-net/src/lite/publisher.rs b/rs/moq-net/src/lite/publisher.rs index e41fe9bbe71..5f36cf1e6f6 100644 --- a/rs/moq-net/src/lite/publisher.rs +++ b/rs/moq-net/src/lite/publisher.rs @@ -108,6 +108,23 @@ fn serving_max_age(version: Version, requested: Duration) -> Duration { } } +/// Where a subscription that named no Group Start begins. +/// +/// The oldest group its own [`serving_max_age`] budget still considers fresh, which is the +/// live edge for the default zero budget. A subscriber that tolerates some age is then +/// handed the head of what it can still use, rather than joining at the live edge and +/// missing a track's opening groups that are sitting right here in the cache. +/// +/// A wire that cannot carry Max Age has no budget to resolve a start from: those sessions +/// are served with an unbounded one so a legacy subscriber never has backlog dropped under +/// it, and that must not read as a request to replay the whole cache on join. +fn resolved_start(track: &track::Subscriber, version: Version) -> Option { + match version.carries_max_age() { + true => track.fresh_start(), + false => track.latest(), + } +} + impl Shared { /// The origin to resolve a peer-requested broadcast from: excludes routes /// through the peer, so a subscription is never served data that flowed @@ -1759,6 +1776,31 @@ mod test { track::Producer::new(Arc::new(broadcast::Info::default()), name, None) } + /// A subscription that names no start resolves one from its own budget, so a subscriber + /// that tolerates some age is handed the head of what it can still use instead of only + /// the live edge. A wire that cannot declare a budget resolves to the live edge: those + /// sessions are served with an unbounded budget so nothing is dropped under them, and + /// reading that as a start would replay the entire cache to every legacy subscriber. + #[test] + fn an_absent_start_resolves_from_the_budget() { + let mut producer = track_producer("test"); + for second in 0..5 { + let mut group = producer.append_group().unwrap(); + group + .write_frame(Timestamp::from_millis(second * 1000).unwrap(), b"x".to_vec()) + .unwrap(); + group.finish().unwrap(); + } + + let live = producer.subscribe(None); + assert_eq!(resolved_start(&live, Version::Lite06Wip), Some(4)); + + let buffered = + producer.subscribe(track::Subscription::default().with_max_age(std::time::Duration::from_secs(2))); + assert_eq!(resolved_start(&buffered, Version::Lite06Wip), Some(2)); + assert_eq!(resolved_start(&buffered, Version::Lite01), Some(4)); + } + /// The run_track contract behind SUBSCRIBE_OK's implicit drop: once the first /// served group resolves the start, the cursor floor rises to it, so a lower /// group arriving late (unordered delivery) is never served after the range @@ -2863,8 +2905,13 @@ impl TrackRun { bounds: Bounds, track_priority_tx: kio::Producer, ) -> Self { - // Start the consumer at the specified sequence, otherwise start at the latest group. - if let Some(start_group) = bounds.start_group.or_else(|| track.latest()) { + // Start the consumer at the specified sequence. Otherwise start at the oldest group + // the subscriber's own max age still considers fresh, which is the latest group for + // the default zero budget: a subscriber that tolerates some age gets the head of what + // it can still use, rather than joining at the live edge and discarding a track's + // opening groups that are sitting right here in the cache. + let resolved = resolved_start(&track, ctx.version); + if let Some(start_group) = bounds.start_group.or(resolved) { track.start_at(start_group); } diff --git a/rs/moq-net/src/model/track.rs b/rs/moq-net/src/model/track.rs index 3f4886fc7ef..bb2afcc71a0 100644 --- a/rs/moq-net/src/model/track.rs +++ b/rs/moq-net/src/model/track.rs @@ -626,6 +626,34 @@ impl TrackState { wall_stale || presentation_stale } + /// The oldest cached group `budget` still considers fresh: the lowest sequence + /// [`Self::is_stale`] does not already convict, or `None` when nothing is cached. + /// + /// One [`Self::live_edge`] scan for the whole walk, like a poll's [`Drift`], so + /// resolving a start costs one pass over the cache rather than one per candidate. + fn fresh_start(&self, budget: Duration, cap: Option) -> Option { + let edge = self.live_edge(cap); + + let mut oldest: Option = None; + for slot in self.lookup.values() { + let sequence = slot.group.sequence; + if !slot.visible || slot.group.is_aborted() { + continue; + } + if cap.is_some_and(|cap| sequence > cap) { + continue; + } + if oldest.is_some_and(|oldest| oldest <= sequence) { + continue; + } + if self.is_stale(sequence, None, edge, budget) { + continue; + } + oldest = Some(sequence); + } + oldest + } + /// Resolve a one-shot fetch from the track side: the cached group, or an [`Error`] /// once it can never be served. A missing group is a failure ([`Error::NotFound`]), not an /// end-of-stream. The handler side (a rejection, or no [`Dynamic`] at all) lives @@ -2889,6 +2917,15 @@ impl PlainSubscriber { }) } + /// The oldest cached group this cursor's own budget still considers fresh, resolved + /// against the same clamped budget and live edge a poll would use. + fn fresh_start(&self) -> Option { + let max_age = self.subscription.read().max_age; + let cap = servable_cap(self.end_sequence, self.stale_cap); + let state = self.state.read(); + state.fresh_start(clamp_max_age(max_age, state.max_age_bound()), cap) + } + /// Whether the drift budget says to skip `group`, against a [`Drift`] already resolved /// for this poll. fn poll_stale(&self, group: &group::Consumer, drift: Drift, waiter: &kio::Waiter) -> Poll> { @@ -3373,6 +3410,25 @@ impl Subscriber { SubscriberKind::Spliced(spliced) => spliced.latest(), } } + + /// Where a subscription that named no [`Subscription::start`] should begin: the oldest + /// cached group this subscriber's [`Subscription::max_age`] still considers fresh. + /// + /// A zero budget (the default) resolves to [`Self::latest`], since every non-latest + /// group is stale the moment a newer one exists. A larger budget resolves further back, + /// so a subscriber that tolerates some age is handed the head of what it can still use + /// instead of only the live edge, without asking for history it would skip on arrival. + /// `None` when nothing is cached. + /// + /// A spliced (route-migrated) track resolves to [`Self::latest`]: its cache is a + /// composition of segments rather than one window, so there is no single oldest group to + /// measure against the live edge. + pub fn fresh_start(&self) -> Option { + match &self.inner { + SubscriberKind::Plain(plain) => plain.fresh_start(), + SubscriberKind::Spliced(spliced) => spliced.latest(), + } + } } /// A subscriber asked for a track this broadcast doesn't have yet. @@ -4335,6 +4391,71 @@ mod test { assert_eq!(drain(&mut subscriber), vec![2, 3, 4]); } + #[test] + fn fresh_start_without_a_budget_is_the_live_edge() { + let mut producer = track_producer("test", None); + for second in 0..5 { + append_at(&mut producer, second * 1000); + } + + // The default zero budget calls every non-latest group stale, so the only start + // that delivers anything is the live edge: what a publisher already picked before + // a start could be resolved from the budget at all. + let subscriber = producer.subscribe(None); + assert_eq!(subscriber.fresh_start(), subscriber.latest()); + assert_eq!(subscriber.fresh_start(), Some(4)); + } + + #[test] + fn fresh_start_reaches_back_over_the_budget() { + let mut producer = track_producer("test", None); + for second in 0..5 { + append_at(&mut producer, second * 1000); + } + + // Two seconds of tolerance covers the groups presenting within 2s of the live edge, + // so the start resolves to the oldest of those rather than the live edge. It has to + // agree with what delivery keeps, or the publisher would either serve groups the + // subscriber discards on arrival or withhold ones it would have taken. + let mut subscriber = producer.subscribe(Subscription::default().with_max_age(Duration::from_secs(2))); + assert_eq!(subscriber.fresh_start(), Some(2)); + assert_eq!(drain(&mut subscriber), vec![2, 3, 4]); + } + + #[test] + fn fresh_start_is_clamped_to_the_publisher_window() { + let mut producer = track_producer("test", Info::default().with_max_age(Duration::from_secs(2))); + for second in 0..5 { + append_at(&mut producer, second * 1000); + } + + // Asking to tolerate ten seconds cannot reach back further than the publisher keeps + // a group live, the same clamp delivery applies. + let subscriber = producer.subscribe(Subscription::default().with_max_age(Duration::from_secs(10))); + assert_eq!(subscriber.fresh_start(), Some(2)); + } + + #[test] + fn fresh_start_is_none_until_a_group_exists() { + let producer = track_producer("test", None); + let subscriber = producer.subscribe(replay()); + assert_eq!(subscriber.fresh_start(), None); + } + + #[test] + fn fresh_start_stays_under_the_end_cap() { + let mut producer = track_producer("test", None); + for second in 0..5 { + append_at(&mut producer, second * 1000); + } + + // The cap moves the live edge the budget measures against, so a subscription that + // stops at group 2 starts where 2 is the edge rather than 4. + let mut subscriber = producer.subscribe(Subscription::default().with_max_age(Duration::from_secs(1))); + subscriber.end_at(2); + assert_eq!(subscriber.fresh_start(), Some(1)); + } + #[test] fn drift_is_measured_in_presentation_time_not_arrival_time() { let mut producer = track_producer("test", None); From 2944f01de9c557d379a9f31fffaa250c04d9a07d Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Fri, 28 Aug 2026 15:03:19 -0700 Subject: [PATCH 2/4] refactor(net): resolve the start in subscribe() rather than a public helper The start a subscription resolves from its own max age was a method on track::Subscriber that every serving path had to remember to call, and a publisher that forgot got the old live-edge behaviour silently. It is also nothing a caller outside the model has any use for. Resolve it where a subscription becomes a cursor instead. A new subscriber starts at the group its subscription named, or the oldest cached one its max age still considers fresh, so the model answers the question once for every serving path (and honours an explicit start without the publisher translating it). The public surface goes back to what it was: no new API on either side. The lite publisher keeps one line of its own, for a wire that cannot carry Max Age: those sessions are served an unbounded budget so a legacy subscriber never has backlog dropped under it, and the cursor that budget would resolve to is the whole cache. A FETCH scan on the JS side walks a subscriber from the cache head, so it needs the exemption the Rust fetch path gets structurally: renamed the internal hook to say what it now covers, since a fetch names one old group explicitly and is neither late against the live edge nor bound by a live subscription's start. Co-Authored-By: Claude Opus 5 --- js/net/src/broadcast.ts | 2 +- js/net/src/internal.ts | 10 +- js/net/src/lite/publisher.ts | 26 +++-- js/net/src/track.test.ts | 47 ++++---- js/net/src/track.ts | 82 +++++++++----- rs/moq-net/src/lite/publisher.rs | 87 +++++++++------ rs/moq-net/src/model/track.rs | 182 ++++++++++++++++++++----------- 7 files changed, 274 insertions(+), 162 deletions(-) diff --git a/js/net/src/broadcast.ts b/js/net/src/broadcast.ts index 0712446eccb..eadd00ae802 100644 --- a/js/net/src/broadcast.ts +++ b/js/net/src/broadcast.ts @@ -114,7 +114,7 @@ async function fetchGroup( options: track.FetchGroupOptions = {}, ): Promise { const subscriber = subscribe(state, name, { priority: options.priority }); - hooks.ignoreLatency(subscriber); + hooks.exemptFetch(subscriber); try { for (;;) { const group = await subscriber.recvGroup(); diff --git a/js/net/src/internal.ts b/js/net/src/internal.ts index 2a98d17c30a..df25bad27de 100644 --- a/js/net/src/internal.ts +++ b/js/net/src/internal.ts @@ -77,8 +77,12 @@ export const hooks: { tryRecvGroup: (subscriber: Subscriber) => Recv; /** Wake once a subscriber's group cursor may read differently; assigned by `track.ts`. */ groupChanged: (subscriber: Subscriber, fn: () => void) => Dispose; - /** Disable subscription drift filtering for a one-shot FETCH scan. */ - ignoreLatency: (subscriber: Subscriber) => void; + /** + * Exempt a subscriber from live-delivery policy for a one-shot FETCH scan: it names one + * old group explicitly, so it is neither late against the live edge nor bound by the start + * a live subscription resolves to. + */ + exemptFetch: (subscriber: Subscriber) => void; /** Return a group's first timestamp, retained even after its first frame is read. */ groupTimestamp: (group: GroupConsumer) => Timestamp | undefined; /** Keep applying a subscription's drift policy after it hands a group out. */ @@ -102,7 +106,7 @@ export const hooks: { groupChanged: () => { throw new Error("track.ts not loaded"); }, - ignoreLatency: () => { + exemptFetch: () => { throw new Error("track.ts not loaded"); }, groupTimestamp: () => { diff --git a/js/net/src/lite/publisher.ts b/js/net/src/lite/publisher.ts index d7bbf4d3012..a32d4c8cbf1 100644 --- a/js/net/src/lite/publisher.ts +++ b/js/net/src/lite/publisher.ts @@ -279,19 +279,22 @@ function carriesMaxAge(version: Version): boolean { } /** - * Where a subscription that named no Group Start begins. + * Position a subscription's read cursor for the wire serving it. * - * The oldest group its own {@link servingMaxAge} budget still considers fresh, which is the - * live edge for the default zero budget. A subscriber that tolerates some age is then handed - * the head of what it can still use, rather than joining at the live edge and missing a - * track's opening groups that are sitting right here in the cache. + * Normally there is nothing to do: `Track.Producer.subscribe` resolves the cursor from the + * subscription itself, at the group it named or the oldest one its own Max Age still + * considers fresh. * - * A wire that cannot carry Max Age has no budget to resolve a start from: those sessions are - * served with an unbounded one so a legacy subscriber never has backlog dropped under it, and - * that must not read as a request to replay the whole cache on join. + * A wire that cannot carry Max Age is the exception. Those sessions are served with an + * unbounded budget so a legacy subscriber never has backlog dropped under it (see + * {@link servingMaxAge}), and read as a start that would replay the whole cache on join. + * Their drafts mean the latest group when no start is named, so say so explicitly. */ -function resolvedStart(track: track.Subscriber, version: Version): number | undefined { - return carriesMaxAge(version) ? track.freshStart() : track.latest(); +function positionCursor(track: track.Subscriber, version: Version, startGroup: number | undefined) { + if (carriesMaxAge(version) || startGroup !== undefined) return; + + const latest = track.latest(); + if (latest !== undefined) track.startAt(latest); } /** @@ -491,8 +494,7 @@ export class Publisher { startGroup: msg.startGroup, endGroup: msg.endGroup, }); - const startGroup = msg.startGroup ?? resolvedStart(track, this.version); - if (startGroup !== undefined) track.startAt(startGroup); + positionCursor(track, this.version, msg.startGroup); track.endAt(msg.endGroup); // The best-effort datagram loop, started once serving begins. It parks when the diff --git a/js/net/src/track.test.ts b/js/net/src/track.test.ts index 45f18d60ce9..a1bb7bc4dc6 100644 --- a/js/net/src/track.test.ts +++ b/js/net/src/track.test.ts @@ -270,29 +270,38 @@ test("latency budget admits groups within its presentation-time window", async ( expect((await track.recvGroup())?.sequence).toBe(2); }); -test("freshStart resolves a start from the subscriber's own budget", () => { - // A subscription that names no start resolves one from its budget, so a subscriber that - // tolerates some age is handed the head of what it can still use instead of only the live - // edge. It has to agree with what delivery keeps, or the publisher would either serve - // groups the subscriber discards on arrival or withhold ones it would have taken. - const producer = new TrackProducer("test").accept({ maxAge: 5000 }); - const live = producer.subscribe(); - const buffered = producer.subscribe({ maxAge: 1500 }); +test("a resolved start is a floor for later arrivals", async () => { + // A subscription that names no start resolves one from its budget when it opens: the + // oldest cached group that budget still admits. That start is a floor like any other, so a + // group arriving below it afterwards is behind the subscription, even carrying a timestamp + // the budget would otherwise admit. + const producer = new TrackProducer("test").accept({ maxAge: 30_000 }); + for (const [sequence, timestamp] of [ + [5, 0], + [6, 1000], + [7, 2000], + ]) { + const group = new GroupProducer(sequence); + producer.writeGroup(group); + group.writeFrame({ payload: enc.encode(`${timestamp}`), timestamp: Timestamp.fromMillis(timestamp) }); + group.close(); + } - expect(live.freshStart()).toBeUndefined(); + const track = producer.subscribe({ maxAge: 5000 }); - for (const timestamp of [0, 1000, 2000]) { - producer.writeFrame({ payload: enc.encode(`${timestamp}`), timestamp: Timestamp.fromMillis(timestamp) }); - } + const late = new GroupProducer(4); + producer.writeGroup(late); + late.writeFrame({ payload: enc.encode("late"), timestamp: Timestamp.fromMillis(500) }); + late.close(); - // The default zero budget calls every non-latest group stale, so the only start that - // delivers anything is the live edge. - expect(live.freshStart()).toBe(live.latest()); - expect(live.freshStart()).toBe(2); - expect(buffered.freshStart()).toBe(1); + expect((await track.recvGroup())?.sequence).toBe(5); + expect((await track.recvGroup())?.sequence).toBe(6); + expect((await track.recvGroup())?.sequence).toBe(7); + producer.close(); + expect(await track.recvGroup()).toBeUndefined(); }); -test("freshStart is clamped to the publisher's window", () => { +test("a start is clamped to the publisher's window", async () => { const producer = new TrackProducer("test").accept({ maxAge: 1500 }); const track = producer.subscribe({ maxAge: 60_000 }); @@ -302,7 +311,7 @@ test("freshStart is clamped to the publisher's window", () => { // Asking to tolerate a minute cannot reach back further than the publisher keeps a group // live, the same clamp delivery applies. - expect(track.freshStart()).toBe(1); + expect((await track.recvGroup())?.sequence).toBe(1); }); test("wall-clock age expires a group stalled before its first frame", async () => { diff --git a/js/net/src/track.ts b/js/net/src/track.ts index b3c00412aba..19bace05532 100644 --- a/js/net/src/track.ts +++ b/js/net/src/track.ts @@ -224,7 +224,13 @@ export class Consumer { this.#broadcast = broadcast; } - /** Open a live subscription to the track. */ + /** + * Open a live subscription to the track. + * + * The cursor starts where the subscription says: at the group it named, or at the oldest + * cached one its {@link Subscription.maxAge} still considers fresh, which is the latest + * group at the default budget of zero. + */ subscribe(options?: Subscription): Subscriber { return this.#broadcast.subscribe(this.name, options); } @@ -394,7 +400,13 @@ export class Producer { return this; } - /** An independent {@link Subscriber} receiving a full copy of this track's groups. */ + /** + * An independent {@link Subscriber} reading this track's groups. + * + * Its cursor starts where the subscription says: at the group it named, or at the oldest + * cached one its {@link Subscription.maxAge} still considers fresh, which is the latest + * group at the default budget of zero. + */ subscribe(options: Subscription = {}): Subscriber { const sink = new TrackState(options); this.#addSink(sink); @@ -692,12 +704,12 @@ export class Subscriber { #cursor = new Signal<{ start: number; end?: number }>({ start: 0 }); #enforceLatency = true; - #drift(): { + #drift(cap?: number): { budget: number; wall?: { sequence: number; time: number }; presentation?: { sequence: number; timestamp: Timestamp }; } { - const { end } = this.#cursor.peek(); + const end = cap ?? this.#cursor.peek().end; let wall: { sequence: number; time: number } | undefined; let presentation: { sequence: number; timestamp: Timestamp } | undefined; for (const { group, time } of this.#state.timeline.values()) { @@ -775,14 +787,49 @@ export class Subscriber { private constructor(name: string, state: TrackState) { this.name = name; this.#state = state; + this.#cursor.set({ start: this.#resolveStart() }); + } + + /** + * Where this subscription's read cursor starts. + * + * The group it named, or, failing that, the oldest cached group its own + * {@link Subscription.maxAge} still considers fresh. A zero budget (the default) resolves + * to the latest group, since every older group is stale the moment a newer one exists, so + * a subscription that says nothing still joins at the live edge. A larger budget starts + * further back, handing a subscriber that tolerates some age the head of what it can still + * use instead of only the live edge. + * + * Deriving the cursor from the same budget that expires a group is what keeps the two from + * disagreeing: a subscriber is never positioned over history it would discard on arrival, + * nor past a group it would have taken. An empty cache resolves to 0, where the first + * group produced lands. + */ + #resolveStart(): number { + const subscription = this.#state.update.peek(); + if (subscription?.startGroup !== undefined) return subscription.startGroup; + + const end = subscription?.endGroup; + const drift = this.#drift(end); + + let oldest: number | undefined; + for (const { group } of this.#state.timeline.values()) { + if (end !== undefined && group.sequence > end) continue; + if (group.closed.peek() instanceof Error) continue; + if (oldest !== undefined && oldest <= group.sequence) continue; + if (this.#isStale(group, drift)) continue; + oldest = group.sequence; + } + return oldest ?? 0; } static { makeSubscriber = (name, state) => new Subscriber(name, state); hooks.tryRecvGroup = (subscriber) => subscriber.#tryRecvGroup(); hooks.groupChanged = (subscriber, fn) => subscriber.#groupChanged(fn); - hooks.ignoreLatency = (subscriber) => { + hooks.exemptFetch = (subscriber) => { subscriber.#enforceLatency = false; + subscriber.#cursor.update((cursor) => ({ ...cursor, start: 0 })); }; } @@ -812,31 +859,6 @@ export class Subscriber { return this.#state.latest; } - /** - * Where a subscription that named no {@link Subscription.startGroup} should begin: the - * oldest cached group this subscriber's {@link Subscription.maxAge} still considers fresh. - * - * A zero budget (the default) resolves to {@link latest}, since every non-latest group is - * stale the moment a newer one exists. A larger budget resolves further back, so a - * subscriber that tolerates some age is handed the head of what it can still use instead - * of only the live edge, without asking for history it would skip on arrival. Undefined - * when nothing is cached. - */ - freshStart(): number | undefined { - const drift = this.#drift(); - const { end } = this.#cursor.peek(); - - let oldest: number | undefined; - for (const { group } of this.#state.timeline.values()) { - if (end !== undefined && group.sequence > end) continue; - if (group.closed.peek() instanceof Error) continue; - if (oldest !== undefined && oldest <= group.sequence) continue; - if (this.#isStale(group, drift)) continue; - oldest = group.sequence; - } - return oldest; - } - /** * The track's exclusive final boundary, known once the producer closes cleanly: * one past the highest sequence produced, or 0 for a track that produced none. diff --git a/rs/moq-net/src/lite/publisher.rs b/rs/moq-net/src/lite/publisher.rs index 5f36cf1e6f6..b7537a4581b 100644 --- a/rs/moq-net/src/lite/publisher.rs +++ b/rs/moq-net/src/lite/publisher.rs @@ -108,20 +108,23 @@ fn serving_max_age(version: Version, requested: Duration) -> Duration { } } -/// Where a subscription that named no Group Start begins. +/// Position a subscription's read cursor for the wire serving it. /// -/// The oldest group its own [`serving_max_age`] budget still considers fresh, which is the -/// live edge for the default zero budget. A subscriber that tolerates some age is then -/// handed the head of what it can still use, rather than joining at the live edge and -/// missing a track's opening groups that are sitting right here in the cache. +/// Normally there is nothing to do: `Consumer::subscribe` resolves the cursor from the +/// subscription itself, at the group it named or the oldest one its own Max Age still +/// considers fresh. /// -/// A wire that cannot carry Max Age has no budget to resolve a start from: those sessions -/// are served with an unbounded one so a legacy subscriber never has backlog dropped under -/// it, and that must not read as a request to replay the whole cache on join. -fn resolved_start(track: &track::Subscriber, version: Version) -> Option { - match version.carries_max_age() { - true => track.fresh_start(), - false => track.latest(), +/// A wire that cannot carry Max Age is the exception. Those sessions are served with an +/// unbounded budget so a legacy subscriber never has backlog dropped under it (see +/// [`serving_max_age`]), and read as a start that would replay the whole cache on join. +/// Their drafts mean the latest group when no start is named, so say so explicitly. +fn position_cursor(track: &mut track::Subscriber, version: Version, start_group: Option) { + if version.carries_max_age() || start_group.is_some() { + return; + } + + if let Some(latest) = track.latest() { + track.start_at(latest); } } @@ -1776,15 +1779,15 @@ mod test { track::Producer::new(Arc::new(broadcast::Info::default()), name, None) } - /// A subscription that names no start resolves one from its own budget, so a subscriber - /// that tolerates some age is handed the head of what it can still use instead of only - /// the live edge. A wire that cannot declare a budget resolves to the live edge: those - /// sessions are served with an unbounded budget so nothing is dropped under them, and - /// reading that as a start would replay the entire cache to every legacy subscriber. + /// A wire that cannot declare a budget is served from the live edge. Those sessions get an + /// unbounded budget so nothing is dropped under them, and the cursor that budget resolves + /// to would replay the entire cache to every legacy subscriber. #[test] - fn an_absent_start_resolves_from_the_budget() { + fn a_legacy_wire_is_pinned_to_the_live_edge() { + use futures::FutureExt; + let mut producer = track_producer("test"); - for second in 0..5 { + for second in 0..3 { let mut group = producer.append_group().unwrap(); group .write_frame(Timestamp::from_millis(second * 1000).unwrap(), b"x".to_vec()) @@ -1792,13 +1795,37 @@ mod test { group.finish().unwrap(); } - let live = producer.subscribe(None); - assert_eq!(resolved_start(&live, Version::Lite06Wip), Some(4)); + // What run_subscribe hands the model for a peer that sent no budget at all. + let served = |version| { + producer.subscribe( + track::Subscription::default().with_max_age(serving_max_age(version, std::time::Duration::ZERO)), + ) + }; + let drain = |subscriber: &mut track::Subscriber| { + let mut sequences = Vec::new(); + while let Some(Ok(Some(group))) = subscriber.recv_group().now_or_never() { + sequences.push(group.sequence); + } + sequences + }; + + let mut unpinned = served(Version::Lite01); + assert_eq!( + drain(&mut unpinned), + vec![0, 1, 2], + "the unbounded budget alone resolves to the whole cache" + ); + + let mut legacy = served(Version::Lite01); + position_cursor(&mut legacy, Version::Lite01, None); + assert_eq!(drain(&mut legacy), vec![2]); - let buffered = - producer.subscribe(track::Subscription::default().with_max_age(std::time::Duration::from_secs(2))); - assert_eq!(resolved_start(&buffered, Version::Lite06Wip), Some(2)); - assert_eq!(resolved_start(&buffered, Version::Lite01), Some(4)); + // A budget the peer actually declared is a real request, so the start it resolved to + // stands. + let mut declared = + producer.subscribe(track::Subscription::default().with_max_age(std::time::Duration::from_secs(5))); + position_cursor(&mut declared, Version::Lite06Wip, None); + assert_eq!(drain(&mut declared), vec![0, 1, 2]); } /// The run_track contract behind SUBSCRIBE_OK's implicit drop: once the first @@ -2905,15 +2932,7 @@ impl TrackRun { bounds: Bounds, track_priority_tx: kio::Producer, ) -> Self { - // Start the consumer at the specified sequence. Otherwise start at the oldest group - // the subscriber's own max age still considers fresh, which is the latest group for - // the default zero budget: a subscriber that tolerates some age gets the head of what - // it can still use, rather than joining at the live edge and discarding a track's - // opening groups that are sitting right here in the cache. - let resolved = resolved_start(&track, ctx.version); - if let Some(start_group) = bounds.start_group.or(resolved) { - track.start_at(start_group); - } + position_cursor(&mut track, ctx.version, bounds.start_group); // Apply the initial cap from the original Subscribe. Subsequent updates // flow through the SUBSCRIBE_UPDATE arm below. diff --git a/rs/moq-net/src/model/track.rs b/rs/moq-net/src/model/track.rs index bb2afcc71a0..1a959636eb7 100644 --- a/rs/moq-net/src/model/track.rs +++ b/rs/moq-net/src/model/track.rs @@ -1441,6 +1441,10 @@ impl Producer { /// /// The info is fixed at creation, so there's nothing to wait for (no /// SUBSCRIBE_OK round trip). Pass `None` for [`Subscription::default`]. + /// + /// The read cursor starts where the subscription says: at the group it named, or at the + /// oldest cached one its [`Subscription::max_age`] still considers fresh, which is the + /// latest group at the default budget of zero. pub fn subscribe(&self, subscription: impl Into>) -> Subscriber { let preferences = subscription.into().unwrap_or_default(); @@ -1449,23 +1453,27 @@ impl Producer { // subscriber surfaces the close/abort on its first read; the preferences are // simply never registered (nothing aggregates them anymore). let info = self.state.read().info.clone().expect("producer always has info"); + + // Hoisted, like `broadcast` below: a `read()` guard taken inside the struct literal + // would live to the end of it, deadlocking against the reads these make. + let state = self.state.consume(); + let min_sequence = resolve_start(&state, &preferences); + let subscription = kio::Producer::new(preferences); register_subscription(self.state.read(), &subscription); let drift_cap = kio::Producer::new(None); - // Hoisted: an inline `read()` guard would live to the end of the struct literal, - // deadlocking against the `consume()` below. let broadcast = self.state.read().broadcast.clone(); Subscriber { name: self.name.clone(), broadcast, info, inner: SubscriberKind::Plain(PlainSubscriber { - state: self.state.consume(), + state, subscription, + min_sequence, index: 0, datagram_index: 0, - min_sequence: 0, next_sequence: 0, end_sequence: None, parked: BTreeMap::new(), @@ -1830,6 +1838,32 @@ fn servable_cap(cursor: Option, outer: Option) -> Option { super::subscription::min_some(cursor, outer) } +/// Where a new subscription's read cursor starts. +/// +/// The group it named, or, failing that, the oldest cached group its own +/// [`Subscription::max_age`] still considers fresh. A zero budget (the default) resolves to +/// the latest group, since every older group is stale the moment a newer one exists, so a +/// subscription that says nothing still joins at the live edge. A larger budget starts +/// further back, handing a subscriber that tolerates some age the head of what it can still +/// use instead of only the live edge. +/// +/// Deriving the cursor from the same budget that expires a group is what keeps the two from +/// disagreeing: a subscriber is never positioned over history it would discard on arrival, +/// nor past a group it would have taken. It measures against the same capped live edge for +/// the same reason, since a route running on past the cap is data this subscription can never +/// be served and so cannot age it. An empty cache resolves to 0, where the first group +/// produced lands. +fn resolve_start(state: &kio::Consumer, subscription: &Subscription) -> u64 { + if let Some(start) = subscription.start { + return start.group; + } + + let cap = subscription.end.and_then(|end| end.before()).map(|end| end.group); + let state = state.read(); + let budget = clamp_max_age(subscription.max_age, state.max_age_bound()); + state.fresh_start(budget, cap).unwrap_or(0) +} + /// Clamp a drift budget to the publisher's retention window: nobody can wait for a late /// group longer than the publisher keeps it around. /// @@ -2087,6 +2121,10 @@ impl Consumer { /// Registers the subscription on the track and returns a [`kio::Pending`] that resolves to the /// [`Subscriber`] once the track info is available, or the track's abort error (or /// [`Error::Dropped`]) if it is already closed. + /// + /// The read cursor starts where the subscription says: at the group it named, or at the + /// oldest cached one its [`Subscription::max_age`] still considers fresh, which is the + /// latest group at the default budget of zero. pub fn subscribe(&self, subscription: impl Into>) -> kio::Pending { let subscription = kio::Producer::new(subscription.into().unwrap_or_default()); @@ -2390,6 +2428,7 @@ impl Subscribing { .map_err(|e| e.abort.clone().unwrap_or(Error::Dropped))??; let drift_cap = kio::Producer::new(None); + let min_sequence = resolve_start(state, &self.subscription.read()); Poll::Ready(Ok(Subscriber { name: self.name.clone(), broadcast: self.broadcast.clone(), @@ -2397,9 +2436,9 @@ impl Subscribing { inner: SubscriberKind::Plain(PlainSubscriber { state: state.clone(), subscription: self.subscription.clone(), + min_sequence, index: 0, datagram_index: 0, - min_sequence: 0, next_sequence: 0, end_sequence: None, parked: BTreeMap::new(), @@ -2686,6 +2725,11 @@ impl kio::Pollable for Fetching { /// cursor it's never told about. So setting only the cursor still transfers the skipped /// groups, and setting only the preference still returns groups another subscriber asked /// for. Set both to skip them *and* avoid the transfer. +/// +/// The one place they meet is where the cursor comes from. A new subscriber starts at the +/// group its own subscription named, or, failing that, at the oldest cached group its +/// [`Subscription::max_age`] still considers fresh, which is the latest group at the default +/// budget of zero. Every later move is the caller's. pub struct Subscriber { name: Arc, // The broadcast this track belongs to; see [`Self::broadcast`]. @@ -2917,15 +2961,6 @@ impl PlainSubscriber { }) } - /// The oldest cached group this cursor's own budget still considers fresh, resolved - /// against the same clamped budget and live edge a poll would use. - fn fresh_start(&self) -> Option { - let max_age = self.subscription.read().max_age; - let cap = servable_cap(self.end_sequence, self.stale_cap); - let state = self.state.read(); - state.fresh_start(clamp_max_age(max_age, state.max_age_bound()), cap) - } - /// Whether the drift budget says to skip `group`, against a [`Drift`] already resolved /// for this poll. fn poll_stale(&self, group: &group::Consumer, drift: Drift, waiter: &kio::Waiter) -> Poll> { @@ -3410,25 +3445,6 @@ impl Subscriber { SubscriberKind::Spliced(spliced) => spliced.latest(), } } - - /// Where a subscription that named no [`Subscription::start`] should begin: the oldest - /// cached group this subscriber's [`Subscription::max_age`] still considers fresh. - /// - /// A zero budget (the default) resolves to [`Self::latest`], since every non-latest - /// group is stale the moment a newer one exists. A larger budget resolves further back, - /// so a subscriber that tolerates some age is handed the head of what it can still use - /// instead of only the live edge, without asking for history it would skip on arrival. - /// `None` when nothing is cached. - /// - /// A spliced (route-migrated) track resolves to [`Self::latest`]: its cache is a - /// composition of segments rather than one window, so there is no single oldest group to - /// measure against the live edge. - pub fn fresh_start(&self) -> Option { - match &self.inner { - SubscriberKind::Plain(plain) => plain.fresh_start(), - SubscriberKind::Spliced(spliced) => spliced.latest(), - } - } } /// A subscriber asked for a track this broadcast doesn't have yet. @@ -4391,23 +4407,26 @@ mod test { assert_eq!(drain(&mut subscriber), vec![2, 3, 4]); } + /// The cursor a subscription starts at, without going through `subscribe`. + fn start_of(producer: &Producer, subscription: &Subscription) -> u64 { + resolve_start(&producer.state.consume(), subscription) + } + #[test] - fn fresh_start_without_a_budget_is_the_live_edge() { + fn a_start_resolves_to_the_live_edge_without_a_budget() { let mut producer = track_producer("test", None); for second in 0..5 { append_at(&mut producer, second * 1000); } - // The default zero budget calls every non-latest group stale, so the only start - // that delivers anything is the live edge: what a publisher already picked before - // a start could be resolved from the budget at all. - let subscriber = producer.subscribe(None); - assert_eq!(subscriber.fresh_start(), subscriber.latest()); - assert_eq!(subscriber.fresh_start(), Some(4)); + // The default zero budget calls every non-latest group stale, so the only start that + // delivers anything is the live edge. A subscription that says nothing therefore + // joins exactly where it always did. + assert_eq!(start_of(&producer, &Subscription::default()), 4); } #[test] - fn fresh_start_reaches_back_over_the_budget() { + fn a_start_reaches_back_over_the_budget() { let mut producer = track_producer("test", None); for second in 0..5 { append_at(&mut producer, second * 1000); @@ -4415,45 +4434,75 @@ mod test { // Two seconds of tolerance covers the groups presenting within 2s of the live edge, // so the start resolves to the oldest of those rather than the live edge. It has to - // agree with what delivery keeps, or the publisher would either serve groups the - // subscriber discards on arrival or withhold ones it would have taken. - let mut subscriber = producer.subscribe(Subscription::default().with_max_age(Duration::from_secs(2))); - assert_eq!(subscriber.fresh_start(), Some(2)); + // agree with what delivery keeps, or a subscriber would either be positioned over + // groups it discards on arrival or past ones it would have taken. + let budget = Subscription::default().with_max_age(Duration::from_secs(2)); + assert_eq!(start_of(&producer, &budget), 2); + + let mut subscriber = producer.subscribe(budget); assert_eq!(drain(&mut subscriber), vec![2, 3, 4]); } #[test] - fn fresh_start_is_clamped_to_the_publisher_window() { + fn a_named_start_wins_over_the_budget() { + let mut producer = track_producer("test", None); + for second in 0..5 { + append_at(&mut producer, second * 1000); + } + + // An explicit start is the request; the budget only fills in for its absence. It is + // still a start, not an exemption: delivery expires what the budget convicts, which + // is why asking for group 0 at real time yields the live edge anyway. + let named = Subscription::default().with_start(Position::group(1)); + assert_eq!(start_of(&producer, &named), 1); + + let mut subscriber = producer.subscribe(named); + assert_eq!(drain(&mut subscriber), vec![4]); + } + + #[test] + fn a_start_is_clamped_to_the_publisher_window() { let mut producer = track_producer("test", Info::default().with_max_age(Duration::from_secs(2))); for second in 0..5 { append_at(&mut producer, second * 1000); } - // Asking to tolerate ten seconds cannot reach back further than the publisher keeps - // a group live, the same clamp delivery applies. - let subscriber = producer.subscribe(Subscription::default().with_max_age(Duration::from_secs(10))); - assert_eq!(subscriber.fresh_start(), Some(2)); + // Asking to tolerate ten seconds cannot reach back further than the publisher keeps a + // group live, the same clamp delivery applies. + let over = Subscription::default().with_max_age(Duration::from_secs(10)); + assert_eq!(start_of(&producer, &over), 2); } #[test] - fn fresh_start_is_none_until_a_group_exists() { + fn a_start_on_an_empty_track_takes_the_first_group() { let producer = track_producer("test", None); - let subscriber = producer.subscribe(replay()); - assert_eq!(subscriber.fresh_start(), None); + + // Nothing cached to measure against, so the cursor sits where the first group lands + // rather than skipping it. + assert_eq!(start_of(&producer, &replay()), 0); } #[test] - fn fresh_start_stays_under_the_end_cap() { + fn a_resolved_start_is_a_floor_for_later_arrivals() { let mut producer = track_producer("test", None); - for second in 0..5 { - append_at(&mut producer, second * 1000); + for (sequence, millis) in [(5, 0), (6, 1000), (7, 2000)] { + let mut group = producer.create_group(group::Info { sequence }).unwrap(); + group + .write_frame(Timestamp::from_millis(millis).unwrap(), bytes::Bytes::from_static(b"x")) + .unwrap(); + group.finish().unwrap(); } - // The cap moves the live edge the budget measures against, so a subscription that - // stops at group 2 starts where 2 is the edge rather than 4. - let mut subscriber = producer.subscribe(Subscription::default().with_max_age(Duration::from_secs(1))); - subscriber.end_at(2); - assert_eq!(subscriber.fresh_start(), Some(1)); + // A budget covering everything cached resolves the start to the oldest of it, 5. + let mut subscriber = producer.subscribe(Subscription::default().with_max_age(Duration::from_secs(5))); + + // That start is a floor like any other, so a group arriving below it afterwards is + // behind the subscription, even carrying a timestamp the budget would admit. + let mut late = producer.create_group(group::Info { sequence: 4 }).unwrap(); + late.write_frame(Timestamp::from_millis(500).unwrap(), bytes::Bytes::from_static(b"late")) + .unwrap(); + late.finish().unwrap(); + assert_eq!(drain(&mut subscriber), vec![5, 6, 7]); } #[test] @@ -4936,13 +4985,17 @@ mod test { #[tokio::test] async fn read_frame_counts_what_it_skips() { let mut producer = track_producer("test", None); + + // Subscribed before any of it exists, so every group below the live edge is one this + // reader fell behind rather than backlog it joined past: a start resolves once, and + // what it resolved to is not a skip. + let mut subscriber = producer.subscribe(None); for second in 0..4 { append_at(&mut producer, second * 1000); } // A silent skip is indistinguishable from loss whichever read did it, so the // frame-level path reports its drops like the group-level ones. - let mut subscriber = producer.subscribe(None); subscriber.read_frame().await.unwrap().expect("a frame"); let stale = subscriber.take_stale(); assert_eq!(stale.groups, 3); @@ -4952,6 +5005,10 @@ mod test { #[tokio::test] async fn read_frame_counts_stale_groups_at_eof() { let mut producer = track_producer("test", None); + + // Subscribed first, so the two groups below the edge are ones this reader fell behind + // rather than backlog its start resolved past. See read_frame_counts_what_it_skips. + let mut subscriber = producer.subscribe(None); append_at(&mut producer, 0); append_at(&mut producer, 1000); @@ -4965,7 +5022,6 @@ mod test { edge.finish().unwrap(); producer.finish().unwrap(); - let mut subscriber = producer.subscribe(None); assert!(subscriber.read_frame().await.unwrap().is_none()); let stale = subscriber.take_stale(); assert_eq!(stale.groups, 2); From 49b5027dac074148f827a8f33c0120030b82ac0e Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Fri, 28 Aug 2026 15:14:10 -0700 Subject: [PATCH 3/4] fix(hang): stop dropping a group for arriving below the delivery cursor Groups are sent newest-first, so the head of a subscription arrives after the live edge it was served alongside. The container consumer dropped anything below its cursor, which threw that head away one layer below where the publisher had just served it. Both consumers can place a late group. Audio writes into a timestamp-indexed ring, which ignores anything behind the playhead and fills its own slot otherwise. Video drops a late frame at render, by timestamp, twice on the way. So there is no caller the strict cursor was protecting, and no reason for the opt-in this started as. How far back a group may be is the subscription's own max age, applied before it reaches here. A group the reset boundary proves reneged is still dropped, since that is a timeline the publisher withdrew rather than one that arrived late. Co-Authored-By: Claude Opus 5 --- ...ll.test.ts => consumer.outoforder.test.ts} | 28 +++--------- js/hang/src/container/consumer.test.ts | 12 ++--- js/hang/src/container/consumer.ts | 44 +++++-------------- js/watch/src/audio/decoder.ts | 6 --- 4 files changed, 23 insertions(+), 67 deletions(-) rename js/hang/src/container/{consumer.backfill.test.ts => consumer.outoforder.test.ts} (70%) diff --git a/js/hang/src/container/consumer.backfill.test.ts b/js/hang/src/container/consumer.outoforder.test.ts similarity index 70% rename from js/hang/src/container/consumer.backfill.test.ts rename to js/hang/src/container/consumer.outoforder.test.ts index 092668d9a51..7738bff039e 100644 --- a/js/hang/src/container/consumer.backfill.test.ts +++ b/js/hang/src/container/consumer.outoforder.test.ts @@ -38,14 +38,14 @@ async function drain(consumer: Consumer): Promise<[number, number | undefined][] // A publisher resolving a start from the subscriber's max age serves the head of the window // alongside the live edge, and groups go out newest-first, so the head arrives *after* the -// group that is already playing. A consumer placing frames by timestamp (the audio ring) can -// still use every one of them, so they must not be dropped for arriving in that order. -test("out-of-order groups reach a consumer that can place them", async () => { +// group that is already playing. Arriving in that order is not a reason to throw it away: +// audio writes into a timestamp-indexed ring and video drops a late frame at render, and the +// subscription's own max age already bounds how far back one can be. +test("out-of-order groups are delivered rather than dropped", async () => { const track = new Track.Producer("test").accept({ maxAge: 30_000 }); const consumer = new Consumer(track.subscribe({ maxAge: 5000 }), { format: new LegacyFormat(), latency: 5000 as Time.Milli, - outOfOrder: true, }); // The live edge lands first, and delivery starts there rather than waiting. @@ -64,24 +64,6 @@ test("out-of-order groups reach a consumer that can place them", async () => { [1, 1], [2, 2], ]); -}); - -// The default stays strict: a decoder that consumes in order has nothing to do with a GoP -// that arrives after a newer one, so the cursor is a floor as before. -test("a late group is dropped unless the consumer opts in", async () => { - const track = new Track.Producer("test").accept({ maxAge: 30_000 }); - const consumer = new Consumer(track.subscribe({ maxAge: 5000 }), { - format: new LegacyFormat(), - latency: 5000 as Time.Milli, - }); - publish(track, 3, 30); - expect((await consumer.next())?.frame?.payload).toEqual(new Uint8Array([3])); - - publish(track, 0, 0); - publish(track, 1, 10); - publish(track, 2, 20); - - const delivered = (await drain(consumer)).filter(([, payload]) => payload !== undefined); - expect(delivered).toEqual([]); + consumer.close(); }); diff --git a/js/hang/src/container/consumer.test.ts b/js/hang/src/container/consumer.test.ts index 06cfdda3699..64889cd51a7 100644 --- a/js/hang/src/container/consumer.test.ts +++ b/js/hang/src/container/consumer.test.ts @@ -344,7 +344,7 @@ test("Consumer delivers groups in sequence order regardless of arrival order", a consumer.close(); }); -test("Consumer rejects stale groups", async () => { +test("Consumer delivers a group that arrives below the cursor", async () => { const track = new Track.Producer("test"); const consumer = new Consumer(replay(track), { format: new LegacyFormat(), latency: 500 as Time.Milli }); @@ -352,18 +352,18 @@ test("Consumer rejects stale groups", async () => { writeGroupWithLegacyFrames(track, 5, [0 as Time.Micro]); await new Promise((resolve) => setTimeout(resolve, 50)); - // Group.Producer 3 is stale + // Group.Producer 3 lands behind it, and Group.Producer 6 ahead of it. Arriving below the + // cursor is not what makes content stale: how far behind the live edge a group may be is + // the subscription's own max age, which `replay` deliberately opens wide here. So all + // three are handed over, in sequence order, since delivery has not passed any of them yet. writeGroupWithLegacyFrames(track, 3, [100_000 as Time.Micro]); - // Group.Producer 6 is valid writeGroupWithLegacyFrames(track, 6, [30_000 as Time.Micro]); track.close(); await new Promise((resolve) => setTimeout(resolve, 100)); const frames = await drainFrames(consumer, 500); - expect(frames).toHaveLength(2); - expect(frames[0].group).toBe(5); - expect(frames[1].group).toBe(6); + expect(frames.map((frame) => frame.group)).toEqual([3, 5, 6]); consumer.close(); }); diff --git a/js/hang/src/container/consumer.ts b/js/hang/src/container/consumer.ts index 8d84a18f014..42b6cd9a6da 100644 --- a/js/hang/src/container/consumer.ts +++ b/js/hang/src/container/consumer.ts @@ -12,17 +12,6 @@ export interface ConsumerProps { /** Target latency in milliseconds, controlling how aggressively slow groups are skipped (default: 0). */ // Read-only: a Getter (e.g. another component's output) is accepted directly. latency?: GetterInit; - /** - * Deliver a group that arrives below the delivery cursor instead of dropping it (default: - * false). - * - * Groups are sent newest-first, so the head a publisher serves ahead of the live edge - * arrives *after* it. Set this when the caller places frames by timestamp, as the audio - * ring does, and a late group lands in its own slot however it arrives. Leave it off for a - * decoder that consumes in order: a GoP that arrives after a newer one has nothing to - * contribute. The latency budget still bounds how far back one may be. - */ - outOfOrder?: boolean; } interface Group { @@ -124,7 +113,6 @@ export class Consumer { #track: Moq.Track.Subscriber; #format: Format; #latency: Getter; - #outOfOrder: boolean; #groups: Group[] = []; #active?: number; // the active group sequence number // Presentation end (max PTS + duration) of the group we most recently advanced past, so next()'s @@ -156,7 +144,6 @@ export class Consumer { this.#track = track; this.#format = props.format; this.#latency = getter(props.latency ?? Moq.Time.Milli.zero); - this.#outOfOrder = props.outOfOrder ?? false; this.#signals.spawn(this.#run.bind(this)); this.#signals.cleanup(() => { @@ -180,25 +167,18 @@ export class Consumer { this.#active = consumer.sequence; } - // Normally we drop anything behind the cursor, unless the caller can place a late - // group anyway. With an active reset the cursor isn't a valid floor (a late - // new-epoch group can sit below it); defer to the boundary and admit ambiguous - // groups so #runGroup can rule on them once their timestamps arrive. A group the - // boundary proves reneged is dropped either way: it belongs to a timeline the - // publisher withdrew, which is not the same as arriving late. - const behind = !this.#outOfOrder && consumer.sequence < this.#active; - let drop: boolean; - if (this.#rewind.boundary) { - const verdict = this.#rewind.boundary.bySequence(consumer.sequence); - if (verdict === undefined) drop = false; - else if (verdict) drop = true; - else drop = behind; - } else { - drop = behind; - } - - if (drop) { - console.warn(`skipping old group: track=${this.#track.name} ${consumer.sequence}`); + // Arriving below the delivery cursor is not a reason to drop a group. Groups are + // sent newest-first, so the head of a subscription arrives after the live edge it + // was served alongside, and both consumers can still place one: audio writes into + // a timestamp-indexed ring, video drops a late frame at render. How far back one + // may be is the subscription's own max age, applied before it ever reaches here. + // + // A group the reset boundary proves reneged is different, and still dropped: it + // belongs to a timeline the publisher withdrew rather than one that arrived late. + // An ambiguous one is admitted so #runGroup can rule on it once its timestamps + // arrive. + if (this.#rewind.boundary?.bySequence(consumer.sequence) === true) { + console.warn(`skipping reneged group: track=${this.#track.name} ${consumer.sequence}`); consumer.close(); continue; } diff --git a/js/watch/src/audio/decoder.ts b/js/watch/src/audio/decoder.ts index 33e8ace0827..084f6d43ca0 100644 --- a/js/watch/src/audio/decoder.ts +++ b/js/watch/src/audio/decoder.ts @@ -310,10 +310,6 @@ export class Decoder { const consumer = new Container.Consumer(sub, { format, latency: this.#consumerLatency, - // The ring places samples by timestamp, so a group that arrives below the delivery - // cursor still lands in its own slot. That is how the head a publisher serves ahead - // of the live edge survives being sent after it (groups go newest-first). - outOfOrder: true, }); effect.cleanup(() => consumer.close()); @@ -419,8 +415,6 @@ export class Decoder { const consumer = new Container.Consumer(sub, { format: new Container.Cmaf.Format(init), latency: this.#consumerLatency, - // See #runLegacyDecoder: the ring is timestamp indexed, so a late group is usable. - outOfOrder: true, }); effect.cleanup(() => consumer.close()); From 42f98a79c4b0780ae649f43ddcc26be5d798f497 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Fri, 28 Aug 2026 17:14:11 -0700 Subject: [PATCH 4/4] feat(net)!: make Group Start an absolute floor, gated by max age alone Reworks the resolution design per review: the model no longer scans the cache to resolve a start. A subscription's named start is a floor (min group), the budget is the only thing that asks for data, and delivery's existing staleness gate decides what above the floor is worth sending. A zero budget still delivers only the latest group; a larger one reaches back over the head of what the subscriber can still use. A late lower group within the budget is now delivered rather than suppressed, which is what the resume layer's pruned-cursor semantics always required. On the lite-06 wire, Group Start becomes the raw absolute floor (default 0) instead of sequence + 1 with 0 meaning the latest group. A vacuous floor (0 with no frame offset) canonicalizes to absent on decode, and folds back to absent when re-encoded toward a pre-06 wire, whose explicit group 0 means "replay from the beginning". Group 0 stays nameable when a Frame Start qualifies it, so a mid-group-0 resume (a catalog never leaves group 0) survives. Pre-06 wires are pinned to the latest group when they name no start, matching their published drafts; only lite-06 resolves from the budget. The spliced (origin-backed) serving path now honors floors at all: poll_activate assigned the inner cursor's start, discarding the floor the inner subscription carried, so an explicit start never survived an origin. It raises the floor instead (track::Subscriber::raise_start_to). The broadcast_route_migration test names its floor explicitly, which is the migration semantics the old default start was standing in for. The hang container consumer no longer truncates a below-cursor group whose buffer momentarily drains mid-download: removal now waits for the group to finish, with the latency skip still bounding a stalled head. Co-Authored-By: Claude Fable 5 --- doc/concept/layer/moq-lite.md | 8 +- drafts/draft-lcurley-moq-lite.md | 26 +-- .../src/container/consumer.outoforder.test.ts | 58 ++++- js/hang/src/container/consumer.ts | 14 +- js/net/src/integration.test.ts | 8 +- js/net/src/lite/publisher.ts | 18 +- js/net/src/lite/subscribe.test.ts | 42 +++- js/net/src/lite/subscribe.ts | 69 ++++-- js/net/src/lite/version.ts | 23 ++ js/net/src/track.test.ts | 36 ++- js/net/src/track.ts | 77 +++---- rs/libmoq/src/api.rs | 6 +- rs/moq-ffi/src/consumer.rs | 5 +- rs/moq-net/src/lite/publisher.rs | 36 +-- rs/moq-net/src/lite/subscribe.rs | 125 ++++++++-- rs/moq-net/src/lite/version.rs | 16 ++ rs/moq-net/src/model/resume.rs | 18 +- rs/moq-net/src/model/subscription.rs | 49 ++-- rs/moq-net/src/model/track.rs | 217 +++++++----------- rs/moq-tokio/tests/broadcast.rs | 12 +- 20 files changed, 559 insertions(+), 304 deletions(-) diff --git a/doc/concept/layer/moq-lite.md b/doc/concept/layer/moq-lite.md index 928ea054c20..9812000b92c 100644 --- a/doc/concept/layer/moq-lite.md +++ b/doc/concept/layer/moq-lite.md @@ -92,8 +92,8 @@ Conceptually, these are join points, and new subscriptions start at the newest g Groups are delivered independently and potentially out of order, so you should have some logic to reorder or skip during congestion. A group is closed when finished or aborted with an error (ex. during congestion). -A subscription lets the publisher choose the start by default, but can name any (group, frame) position instead. -Left to the publisher, it resolves to the oldest group within **Subscriber Max Age**, which is the latest group at the default budget of zero. +A subscription can name a (group, frame) floor, but the floor is not a request: **Subscriber Max Age** is the only thing that asks for data. +Delivery starts at the oldest group at or above the floor within that budget, which is the latest group at the default budget of zero. A subscriber that buffers is then handed the head of what it can still play instead of only the live edge, and never history it would skip on arrival: one bound decides both. That is how a subscriber follows a track to a different publisher partway through a group, which matters when the current group may stay open indefinitely (a JSON append log, or a catalog that keeps appending deltas). A group can therefore be assembled from more than one publisher: each contributes a disjoint run of frames, and the subscriber concatenates them in index order. @@ -128,8 +128,8 @@ That age is measured both on the media timeline (a group's first timestamp again The media timeline keeps a backlog delivered as a burst old, while wall-clock time backstops stalled or empty groups that have no timestamp. Both ends apply it: the publisher skips a group rather than sending it, and the subscriber skips it again as it reads. The publisher only ever sees the most tolerant budget across its subscribers, which is why the subscriber applies it too. -Asking for old groups with `Group Start` does not exempt them: a start bounds what you are sent, and a subscriber that wants history has to raise its budget to match. -That is also why the budget is what resolves an unset start: the groups worth sending are exactly the ones it would not immediately skip. +Asking for old groups with `Group Start` does not exempt them: a floor only bounds what you are sent, and a subscriber that wants history has to raise its budget to match. +That is also why the budget is what decides where delivery starts: the groups worth sending are exactly the ones it would not immediately skip. The publisher also keeps old groups around for a best-effort **Publisher Max Age** cache window so relays and late subscribers can still fetch them. This defaults to 5 seconds. The subscriber's max age is bounded by this window: a group can't be waited for longer than it's actually kept around. diff --git a/drafts/draft-lcurley-moq-lite.md b/drafts/draft-lcurley-moq-lite.md index adbdf2fa14b..974e9998b0a 100644 --- a/drafts/draft-lcurley-moq-lite.md +++ b/drafts/draft-lcurley-moq-lite.md @@ -185,7 +185,8 @@ Only the subscriber knows whether a partial Group is any use to it, so only the Frame indices are only meaningful relative to a Group the subscriber has already begun receiving, so: -- A `Frame Start` is meaningless without an absolute `Group Start`; a subscriber letting the publisher choose the start (`Group Start` = 0) MUST send `Frame Start` = 0. +- A `Frame Start` qualifies the group `Group Start` names, group 0 included. + A subscriber that has seen no such group MUST send `Frame Start` = 0, since it cannot number the frames of a group it has not received. - A `Frame End` is meaningless without a `Group End`; an unbounded subscription (`Group End` = 0) MUST send `Frame End` = 0. A publisher MUST treat a violation of either rule as a protocol violation and reset the stream. @@ -986,14 +987,14 @@ This is a delivery-time preference, not a retention rule: the publisher MAY stil See the [Expiration](#expiration) section for more information. **Group Start**: -The first group to deliver. -A value of 0 means the publisher chooses (default). -A non-zero value is the absolute group sequence + 1. +The minimum group sequence to deliver: an absolute floor, defaulting to 0 (no floor). -When it does, the publisher SHOULD start at the oldest cached group whose age is within `Subscriber Max Age`, and MUST NOT start at an older one. +A floor is not a request; `Subscriber Max Age` is the only thing that asks for data. +The publisher SHOULD start at the oldest group at or above the floor whose age (relative to the latest group, measured from its first frame) is within `Subscriber Max Age`, and MUST NOT deliver an older one. A `Subscriber Max Age` of 0 therefore starts at the latest group, since every older group is already stale. -A subscriber that buffers has then been handed the head of what it can still play instead of only the live edge, and is never sent history it would discard on arrival: the same bound decides what to start at and what to expire, so the two cannot disagree. -This is a floor on delivery, not a guarantee that the groups exist; see `Publisher Max Age` in [TRACK_INFO](#track-info). +A subscriber that buffers is then handed the head of what it can still play instead of only the live edge, and is never sent history it would discard on arrival: the same bound decides what to start at and what to expire, so the two cannot disagree. +A floor above the latest group simply waits there: that is a resumed subscription naming where it left off. +Reaching back is best-effort, not a guarantee that the groups still exist; see `Publisher Max Age` in [TRACK_INFO](#track-info). **Group End**: The last group to deliver (inclusive). @@ -1001,11 +1002,10 @@ A value of 0 means unbounded (default). A non-zero value is the absolute group sequence + 1. **Frame Start**: -The index of the first frame to deliver within the start group (see [Positions](#positions)). +The index of the first frame to deliver within the `Group Start` group (see [Positions](#positions)). A value of 0 means from the start of that group (default), so the group is delivered whole. -Unlike `Group Start` this is a plain absolute index, not the `absolute + 1` form: 0 is both a valid index and the default, so there is no absent case to encode around. -Frames before this index are not delivered, even though the start group itself is. -MUST be 0 when `Group Start` is 0, since the subscriber cannot number the frames of a group it has not seen. +Frames before this index are not delivered, even when delivery begins at that exact group; a start resolved at a later group is always delivered from frame 0. +A subscriber that has received no group MUST send 0, since it cannot number the frames of a group it has not seen. **Frame End**: The last frame to deliver (inclusive) within the end group (see [Positions](#positions)). @@ -1364,7 +1364,7 @@ The `Message Length` describes the payload size on the wire. - Added a SETUP `Origin` parameter (0x5): each endpoint declares its Hop ID at session setup, carrying session-wide the identity `Exclude Hop` carried per announce stream, and filtering subscriptions as well as announcements (including sessions that never open an Announce Stream). - Made advertisement selection per subscriber: a publisher MUST NOT advertise a path containing the subscriber's declared origin and otherwise advertises the best remaining one (a subscriber the serving path flows through receives the best standby instead of nothing), MUST serve subscriptions by the same exclusion, and the actively-carrying cost discount applies only to the serving path. This is how redundant publishers fail over across a mesh. - Defined same-path advertisements with the same non-zero Epoch as interchangeable content a relay may splice across at a Position. When both Epochs are 0, identity falls back to a shared non-zero first Hop ID; differing or unknown identities never splice. -- Added `Frame Start` and `Frame End` to SUBSCRIBE and SUBSCRIBE_UPDATE, qualifying the start and end group with a frame index so a subscription can begin or end partway through a group. `Frame Start` is a plain index; `Frame End` is the index + 1, matching `Group End`. Both MUST be 0 when the group bound they qualify is absent. +- Added `Frame Start` and `Frame End` to SUBSCRIBE and SUBSCRIBE_UPDATE, qualifying the start and end group with a frame index so a subscription can begin or end partway through a group. `Frame Start` is a plain index qualifying the `Group Start` group; `Frame End` is the index + 1, matching `Group End`, and MUST be 0 when `Group End` is absent. - Added `Frame Start` and `Frame End` to FETCH, bounding the returned frames within the group. A publisher that cannot serve the full range resets the stream. - Added `Frame Start` to GROUP, giving the index of the first FRAME on the stream so a partial group is self-describing. - Added the Positions section defining a (group, frame) position, its lexicographic ordering, and the rule that a partial group is only ever delivered to a subscriber that asked for one. A publisher that cannot serve a group from the requested frame skips it and resolves to a later group, so SUBSCRIBE_OK needs no frame field: the start frame follows from `Group` and the subscriber's own request. @@ -1373,7 +1373,7 @@ The `Message Length` describes the payload size on the wire. - Exempted a ceiling-cost serving path from the actively-carrying cost discount: a relay whose serving path costs the saturation ceiling (primarily a session that received a GOAWAY) advertises the ceiling instead of 0, so the drain propagates downstream instead of being re-masked by each carrying hop. Keyed on the value, not the reason, which does not travel on the wire. - Added the Error Codes section, defining separate session and stream code spaces and listing the codes moq-lite uses, reused unchanged from moq-transport. Codes 64+ are the application's; 32-63 are reserved and MUST NOT be interpreted, pending a future revision. Previously the codes were unspecified, so an endpoint could neither send one a peer would understand nor safely interpret one it received. Note this renumbers every code an existing implementation sent, and that a stream reset of 0x0 is now INTERNAL_ERROR rather than a cancellation (CANCELLED is 0x1). - Renamed `Subscriber Max Latency` to `Subscriber Max Age` and `Publisher Max Latency` to `Publisher Max Age`. -- Resolve an absent `Group Start` from `Subscriber Max Age` rather than always taking the latest group, so a subscriber that buffers is handed the head of what it can still play. A zero budget still resolves to the latest group. +- Made `Group Start` an absolute floor (the raw minimum group sequence, default 0) rather than the sequence + 1 with 0 meaning the latest group. The start resolves from `Subscriber Max Age` instead: the oldest group at or above the floor within the budget, so a subscriber that buffers is handed the head of what it can still play. A zero budget still resolves to the latest group, which was the only start the old encoding could ask for by default. ## moq-lite-05 - Renamed ANNOUNCE_INTEREST to ANNOUNCE_REQUEST and ANNOUNCE to ANNOUNCE_BROADCAST. diff --git a/js/hang/src/container/consumer.outoforder.test.ts b/js/hang/src/container/consumer.outoforder.test.ts index 7738bff039e..03b5b869270 100644 --- a/js/hang/src/container/consumer.outoforder.test.ts +++ b/js/hang/src/container/consumer.outoforder.test.ts @@ -13,14 +13,19 @@ function encodeLegacyFrame(timestamp: Time.Micro, payload: Uint8Array): Uint8Arr return data; } +/** Write one frame into an open group: `millis` on the timeline, tagged `tag`. */ +function publishFrame(group: Group.Producer, millis: number, tag: number) { + group.writeFrame({ + payload: encodeLegacyFrame(Time.Micro.fromMilli(millis as Time.Milli), new Uint8Array([tag])), + timestamp: Time.Timestamp.fromMillis(millis), + }); +} + /** Publish one closed group carrying a single frame at `millis`. */ function publish(track: Track.Producer, sequence: number, millis: number) { const group = new Group.Producer(sequence); track.writeGroup(group); - group.writeFrame({ - payload: encodeLegacyFrame(Time.Micro.fromMilli(millis as Time.Milli), new Uint8Array([sequence])), - timestamp: Time.Timestamp.fromMillis(millis), - }); + publishFrame(group, millis, sequence); group.close(); } @@ -36,9 +41,9 @@ async function drain(consumer: Consumer): Promise<[number, number | undefined][] return seen; } -// A publisher resolving a start from the subscriber's max age serves the head of the window -// alongside the live edge, and groups go out newest-first, so the head arrives *after* the -// group that is already playing. Arriving in that order is not a reason to throw it away: +// A publisher serving a subscriber's max age hands over the head of the window alongside +// the live edge, and groups go out newest-first, so the head arrives *after* the group +// that is already playing. Arriving in that order is not a reason to throw it away: // audio writes into a timestamp-indexed ring and video drops a late frame at render, and the // subscription's own max age already bounds how far back one can be. test("out-of-order groups are delivered rather than dropped", async () => { @@ -67,3 +72,42 @@ test("out-of-order groups are delivered rather than dropped", async () => { consumer.close(); }); + +// A below-cursor group may still be downloading when its buffered frames are momentarily +// drained (the decode loop consumes faster than the network delivers). Removing it at that +// instant silently truncates its tail, so removal must wait for the group to finish. +test("a below-cursor group still downloading is not truncated", async () => { + const track = new Track.Producer("test").accept({ maxAge: 30_000 }); + const consumer = new Consumer(track.subscribe({ maxAge: 5000 }), { + format: new LegacyFormat(), + latency: 5000 as Time.Milli, + }); + + // The live edge group arrives first and starts delivery (still open). + const live = new Group.Producer(3); + track.writeGroup(live); + publishFrame(live, 3000, 30); + expect((await consumer.next())?.frame?.payload[0]).toBe(30); + + // A backlog group lands below the cursor, one frame at a time (mid-download). + const backlog = new Group.Producer(1); + track.writeGroup(backlog); + publishFrame(backlog, 1000, 10); + const first = await consumer.next(); + expect(first?.group).toBe(1); + expect(first?.frame?.payload[0]).toBe(10); + + // The consumer finds the group's buffer empty while it is still open. It must wait + // rather than shift the group out, so the second frame still arrives. + const pending = consumer.next(); + publishFrame(backlog, 1500, 11); + backlog.close(); + + const second = (await pending) as { group: number; frame?: { payload: Uint8Array } }; + expect(second.group).toBe(1); + expect(second.frame?.payload[0]).toBe(11); + + live.close(); + track.close(); + consumer.close(); +}); diff --git a/js/hang/src/container/consumer.ts b/js/hang/src/container/consumer.ts index 42b6cd9a6da..d60d6a98929 100644 --- a/js/hang/src/container/consumer.ts +++ b/js/hang/src/container/consumer.ts @@ -586,12 +586,14 @@ export class Consumer { return { frame, group: seq, discontinuity: this.#rewind.discontinuity, continuous }; } - // Check if the group is done and then remove it. - // A group is removable when #active has advanced past it, OR when - // its #runGroup task has finished (done) and all frames are consumed. - // The latter handles the case where #runGroup finished before - // #active reached this group (e.g. after a latency skip). - if (this.#active > this.#groups[0].consumer.sequence || this.#groups[0].done) { + // Check if the group is done and then remove it. A group is removable only + // once its #runGroup task has finished (done) and all frames are consumed: + // a below-#active group (a backlog group admitted behind the live edge) may + // still be downloading when its buffer momentarily drains, and removing it + // then silently truncates its tail. #runGroup notifies whenever the head + // group gains a frame, so waiting here is woken, and #checkLatency bounds + // how long a stalled head can hold delivery up. + if (this.#groups[0].done) { if (this.#groups[0].consumer.sequence === this.#active) { // The cursor moves past this group here rather than in #runGroup's finally // block whenever the group finished before it became active, so this is the diff --git a/js/net/src/integration.test.ts b/js/net/src/integration.test.ts index 4cb36f2b012..fa0d703d00f 100644 --- a/js/net/src/integration.test.ts +++ b/js/net/src/integration.test.ts @@ -132,16 +132,18 @@ test("integration: lite subscription options and updates reach the publisher", a const request = await broadcast.requested(); if (!request) return; const producer = request.accept(); - if (request.subscription.startGroup === 0) resolveProducer?.(producer); + if (request.subscription.startGroup === 1) resolveProducer?.(producer); } })(); const remote = client.consume(Path.from("test")); + // A floor of 1, not 0: a pre-06 wire folds a vacuous floor of 0 back to absent, since + // its encoding of group 0 means "replay from the beginning" instead. const subscriber = remote.track("video").subscribe({ priority: 3, ordered: true, maxAge: 250, - startGroup: 0, + startGroup: 1, endGroup: 9, }); const producer = await accepted; @@ -149,7 +151,7 @@ test("integration: lite subscription options and updates reach the publisher", a priority: 3, ordered: true, maxAge: 250, - startGroup: 0, + startGroup: 1, endGroup: 9, }); diff --git a/js/net/src/lite/publisher.ts b/js/net/src/lite/publisher.ts index a32d4c8cbf1..bda78ad0b68 100644 --- a/js/net/src/lite/publisher.ts +++ b/js/net/src/lite/publisher.ts @@ -25,7 +25,7 @@ import { SubscribeUpdate, } from "./subscribe.ts"; import { TrackInfo as TrackInfoMessage, type Track as TrackMessage } from "./track.ts"; -import { hasAnnounceId, hasAnnounceOk, hasDatagrams, hasProbeRtt, Version } from "./version.ts"; +import { hasAnnounceId, hasAnnounceOk, hasDatagrams, hasProbeRtt, resolvesStart, Version } from "./version.ts"; const PROBE_INTERVAL = 100; // ms const PROBE_MAX_AGE = 10_000; // ms @@ -281,17 +281,17 @@ function carriesMaxAge(version: Version): boolean { /** * Position a subscription's read cursor for the wire serving it. * - * Normally there is nothing to do: `Track.Producer.subscribe` resolves the cursor from the - * subscription itself, at the group it named or the oldest one its own Max Age still - * considers fresh. + * On lite-06 there is nothing to do: the cursor is floored at the group the subscription + * named (or 0), and its Max Age decides what above the floor is worth delivering. * - * A wire that cannot carry Max Age is the exception. Those sessions are served with an - * unbounded budget so a legacy subscriber never has backlog dropped under it (see - * {@link servingMaxAge}), and read as a start that would replay the whole cache on join. - * Their drafts mean the latest group when no start is named, so say so explicitly. + * Pre-06 wires are the exception: their drafts define an absent `Group Start` as the + * latest group, so say so explicitly rather than letting the budget reach back. Lite-03/04/05 + * carry a Max Age, but there it is a staleness tolerance only; lite-01/02 additionally get + * an unbounded budget so nothing is dropped under them (see {@link servingMaxAge}), which + * must not read as a request to replay the whole cache on join. */ function positionCursor(track: track.Subscriber, version: Version, startGroup: number | undefined) { - if (carriesMaxAge(version) || startGroup !== undefined) return; + if (resolvesStart(version) || startGroup !== undefined) return; const latest = track.latest(); if (latest !== undefined) track.startAt(latest); diff --git a/js/net/src/lite/subscribe.test.ts b/js/net/src/lite/subscribe.test.ts index 6aa2ebf165a..f6b3ef407d3 100644 --- a/js/net/src/lite/subscribe.test.ts +++ b/js/net/src/lite/subscribe.test.ts @@ -86,15 +86,37 @@ test("Subscribe round-trips every option including startGroup 0", async () => { startGroup: 0, endGroup: 9, }); + // Lite-06 carries the raw floor, and a floor of 0 with no frame offset is the same + // absence of a constraint as no floor at all, so it canonicalizes to undefined. const got = await Subscribe.decode( - new Reader(undefined, await encodeMessage(Version.DRAFT_05, message)), - Version.DRAFT_05, + new Reader(undefined, await encodeMessage(Version.DRAFT_06, message)), + Version.DRAFT_06, ); expect(got.priority).toBe(7); expect(got.ordered).toBe(true); expect(got.maxAge).toBe(250); - expect(got.startGroup).toBe(0); + expect(got.startGroup).toBeUndefined(); expect(got.endGroup).toBe(9); + + // Group 0 stays named when a Frame Start qualifies it: a subscription can resume + // partway through group 0 (a catalog never leaves it). + message.startFrame = 4; + const resumed = await Subscribe.decode( + new Reader(undefined, await encodeMessage(Version.DRAFT_06, message)), + Version.DRAFT_06, + ); + expect(resumed.startGroup).toBe(0); + expect(resumed.startFrame).toBe(4); + message.startFrame = 0; + + // A pre-06 wire folds the vacuous floor back to absent: an explicit group 0 there + // would mean "replay from the beginning", which is not what a floor of 0 asks for. + const folded = await Subscribe.decode( + new Reader(undefined, await encodeMessage(Version.DRAFT_05, message)), + Version.DRAFT_05, + ); + expect(folded.startGroup).toBeUndefined(); + expect(folded.endGroup).toBe(9); }); test("SubscribeUpdate round-trips every option including startGroup 0", async () => { @@ -106,14 +128,22 @@ test("SubscribeUpdate round-trips every option including startGroup 0", async () endGroup: 12, }); const got = await SubscribeUpdate.decode( - new Reader(undefined, await encodeMessage(Version.DRAFT_05, message)), - Version.DRAFT_05, + new Reader(undefined, await encodeMessage(Version.DRAFT_06, message)), + Version.DRAFT_06, ); expect(got.priority).toBe(8); expect(got.ordered).toBe(true); expect(got.maxAge).toBe(500); - expect(got.startGroup).toBe(0); + expect(got.startGroup).toBeUndefined(); expect(got.endGroup).toBe(12); + + // The same fold as SUBSCRIBE on a pre-06 wire. + const folded = await SubscribeUpdate.decode( + new Reader(undefined, await encodeMessage(Version.DRAFT_05, message)), + Version.DRAFT_05, + ); + expect(folded.startGroup).toBeUndefined(); + expect(folded.endGroup).toBe(12); }); test("SubscribeStart round-trips on draft-05", async () => { diff --git a/js/net/src/lite/subscribe.ts b/js/net/src/lite/subscribe.ts index 4a2be25a3fe..494b19bf8a8 100644 --- a/js/net/src/lite/subscribe.ts +++ b/js/net/src/lite/subscribe.ts @@ -1,7 +1,46 @@ import * as Path from "../path.ts"; import type { Reader, Writer } from "../stream.ts"; import * as Message from "./message.ts"; -import { hasFrameBounds, Version } from "./version.ts"; +import { hasFrameBounds, resolvesStart, Version } from "./version.ts"; + +/** + * Encode the `Group Start` field shared by SUBSCRIBE and SUBSCRIBE_UPDATE. + * + * Lite-06 writes the raw floor (`undefined` and 0 are the same absence of a constraint), + * while a pre-06 wire encodes the sequence + 1 and gets a vacuous floor folded back to + * absent: an explicit group 0 there means "replay from the beginning", which is not what + * a floor of 0 asks for. + */ +async function encodeStartGroup(w: Writer, version: Version, startGroup?: number) { + if (resolvesStart(version)) { + await w.u53(startGroup ?? 0); + return; + } + await w.u53(startGroup !== undefined && startGroup > 0 ? startGroup + 1 : 0); +} + +/** + * Decode the `Group Start` field shared by SUBSCRIBE and SUBSCRIBE_UPDATE. + * + * The inverse of {@link encodeStartGroup}. Callers canonicalize with + * {@link canonicalStartGroup} once the frame bounds are known. + */ +async function decodeStartGroup(r: Reader, version: Version): Promise { + const value = await r.u53(); + if (resolvesStart(version)) return value; + return value > 0 ? value - 1 : undefined; +} + +/** + * Canonicalize a decoded floor: a lite-06 `Group Start` of 0 with no frame offset is the + * same absence of a constraint as no floor at all, so it decodes as undefined. Group 0 + * stays named only when a `Frame Start` actually qualifies it (a subscription can resume + * partway through group 0: a catalog never leaves it). + */ +function canonicalStartGroup(version: Version, startGroup: number | undefined, startFrame: number): number | undefined { + if (resolvesStart(version) && startGroup === 0 && startFrame === 0) return undefined; + return startGroup; +} /** * Encode the trailing `Frame Start` / `Frame End` pair shared by SUBSCRIBE and @@ -99,7 +138,7 @@ export class SubscribeUpdate { await w.u8(this.priority); await w.bool(this.ordered); await w.u53(this.maxAge); - await w.u53(this.startGroup !== undefined ? this.startGroup + 1 : 0); + await encodeStartGroup(w, version, this.startGroup); await w.u53(this.endGroup !== undefined ? this.endGroup + 1 : 0); await encodeFrameBounds(w, version, this); break; @@ -115,20 +154,16 @@ export class SubscribeUpdate { const priority = await r.u8(); const ordered = await r.bool(); const maxAge = await r.u53(); - const startGroup = (await r.u53()) || undefined; + const startGroup = await decodeStartGroup(r, version); const endGroup = (await r.u53()) || undefined; - const frames = await decodeFrameBounds( - r, - version, - startGroup !== undefined ? startGroup - 1 : undefined, - endGroup !== undefined ? endGroup - 1 : undefined, - ); + const end = endGroup !== undefined ? endGroup - 1 : undefined; + const frames = await decodeFrameBounds(r, version, startGroup, end); return new SubscribeUpdate({ priority, ordered, maxAge, - startGroup: startGroup !== undefined ? startGroup - 1 : undefined, - endGroup: endGroup !== undefined ? endGroup - 1 : undefined, + startGroup: canonicalStartGroup(version, startGroup, frames.startFrame), + endGroup: end, ...frames, }); } @@ -162,7 +197,8 @@ export class Subscribe { /** * First frame to deliver within `startGroup`'s group; 0 is the whole group. - * Lite-06+, and meaningless without an explicit `startGroup`. + * Lite-06+. It qualifies the named group, so it needs `startGroup` to name one + * (defined, including 0: group 0 can host a mid-group resume). */ startFrame: number; @@ -209,7 +245,7 @@ export class Subscribe { default: await w.bool(this.ordered); await w.u53(this.maxAge); - await w.u53(this.startGroup !== undefined ? this.startGroup + 1 : 0); + await encodeStartGroup(w, version, this.startGroup); await w.u53(this.endGroup !== undefined ? this.endGroup + 1 : 0); await encodeFrameBounds(w, version, this); break; @@ -229,11 +265,10 @@ export class Subscribe { default: { const ordered = await r.bool(); const maxAge = await r.u53(); - const startGroup = (await r.u53()) || undefined; + const startGroup = await decodeStartGroup(r, version); const endGroup = (await r.u53()) || undefined; - const start = startGroup !== undefined ? startGroup - 1 : undefined; const end = endGroup !== undefined ? endGroup - 1 : undefined; - const frames = await decodeFrameBounds(r, version, start, end); + const frames = await decodeFrameBounds(r, version, startGroup, end); return new Subscribe({ id, broadcast, @@ -241,7 +276,7 @@ export class Subscribe { priority, ordered, maxAge, - startGroup: start, + startGroup: canonicalStartGroup(version, startGroup, frames.startFrame), endGroup: end, ...frames, }); diff --git a/js/net/src/lite/version.ts b/js/net/src/lite/version.ts index 037fac7dc41..e800666cbbe 100644 --- a/js/net/src/lite/version.ts +++ b/js/net/src/lite/version.ts @@ -168,6 +168,29 @@ export function hasFrameBounds(version: Version): boolean { } } +/** + * Whether SUBSCRIBE's `Group Start` is an absolute floor the publisher resolves a start + * from: the raw minimum group sequence (default 0), with `Subscriber Max Age` as the only + * gate on how far back delivery begins. Changed in lite-06. + * + * Older versions encode `Group Start` as the sequence + 1, with 0 meaning the latest + * group, so an absent start there pins the cursor to the live edge instead of letting the + * budget reach back. + */ +export function resolvesStart(version: Version): boolean { + // Explicitly list older versions so future versions keep the lite-06+ behavior. + switch (version) { + case Version.DRAFT_01: + case Version.DRAFT_02: + case Version.DRAFT_03: + case Version.DRAFT_04: + case Version.DRAFT_05: + 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/js/net/src/track.test.ts b/js/net/src/track.test.ts index a1bb7bc4dc6..c212b5704d3 100644 --- a/js/net/src/track.test.ts +++ b/js/net/src/track.test.ts @@ -270,11 +270,7 @@ test("latency budget admits groups within its presentation-time window", async ( expect((await track.recvGroup())?.sequence).toBe(2); }); -test("a resolved start is a floor for later arrivals", async () => { - // A subscription that names no start resolves one from its budget when it opens: the - // oldest cached group that budget still admits. That start is a floor like any other, so a - // group arriving below it afterwards is behind the subscription, even carrying a timestamp - // the budget would otherwise admit. +test("a late lower group within the budget is delivered", async () => { const producer = new TrackProducer("test").accept({ maxAge: 30_000 }); for (const [sequence, timestamp] of [ [5, 0], @@ -288,20 +284,42 @@ test("a resolved start is a floor for later arrivals", async () => { } const track = producer.subscribe({ maxAge: 5000 }); + expect((await track.recvGroup())?.sequence).toBe(5); + expect((await track.recvGroup())?.sequence).toBe(6); + expect((await track.recvGroup())?.sequence).toBe(7); + // Arriving below everything already delivered is not what makes content stale: the + // budget is the only gate, and this straggler's timestamp is within it. A consumer + // that needs sequence order reorders (or drops) it itself. const late = new GroupProducer(4); producer.writeGroup(late); late.writeFrame({ payload: enc.encode("late"), timestamp: Timestamp.fromMillis(500) }); late.close(); - expect((await track.recvGroup())?.sequence).toBe(5); - expect((await track.recvGroup())?.sequence).toBe(6); - expect((await track.recvGroup())?.sequence).toBe(7); + expect((await track.recvGroup())?.sequence).toBe(4); producer.close(); expect(await track.recvGroup()).toBeUndefined(); }); -test("a start is clamped to the publisher's window", async () => { +test("a named start is a floor, not a request", async () => { + const producer = new TrackProducer("test").accept({ maxAge: 30_000 }); + for (const timestamp of [0, 1000, 2000, 3000, 4000]) { + producer.writeFrame({ payload: enc.encode(`${timestamp}`), timestamp: Timestamp.fromMillis(timestamp) }); + } + + // The budget is the only thing that asks for data; a named start only bounds how far + // back it may reach. + const floored = producer.subscribe({ startGroup: 3, maxAge: 60_000 }); + expect((await floored.recvGroup())?.sequence).toBe(3); + expect((await floored.recvGroup())?.sequence).toBe(4); + + // Naming group 1 at real time still delivers the live edge alone: the zero budget + // calls everything older stale. + const named = producer.subscribe({ startGroup: 1 }); + expect((await named.recvGroup())?.sequence).toBe(4); +}); + +test("the budget is clamped to the publisher's window", async () => { const producer = new TrackProducer("test").accept({ maxAge: 1500 }); const track = producer.subscribe({ maxAge: 60_000 }); diff --git a/js/net/src/track.ts b/js/net/src/track.ts index 19bace05532..4e88c2245a1 100644 --- a/js/net/src/track.ts +++ b/js/net/src/track.ts @@ -90,7 +90,14 @@ export interface Subscription { ordered?: boolean; /** Maximum age (milliseconds) of a non-latest group before it is skipped. Defaults to `0`. */ maxAge?: number; - /** First group the publisher should deliver, or omit to start at the latest group. */ + /** + * The lowest group the publisher may deliver (a floor), or omit for none. + * + * A floor, not a request: only {@link maxAge} asks for data, and the floor bounds how + * far back it may reach. Omitting it and a floor of 0 mean the same thing, and a floor + * above the live edge simply waits there (a resumed subscription naming where it left + * off). + */ startGroup?: number; /** Last group the publisher should deliver (inclusive), or omit for no end. */ endGroup?: number; @@ -123,11 +130,12 @@ function combineSubscriptions(states: Iterable): Subscription | unde combined.ordered = (combined.ordered ?? false) && (subscription.ordered ?? false); combined.maxAge = Math.max(combined.maxAge ?? 0, subscription.maxAge ?? 0); - if (subscription.startGroup !== undefined) { - combined.startGroup = - combined.startGroup === undefined - ? subscription.startGroup - : Math.min(combined.startGroup, subscription.startGroup); + // A floor only restricts, so a subscriber without one clears the aggregate: + // its budget may reach below any floor the others set. + if (combined.startGroup === undefined || subscription.startGroup === undefined) { + combined.startGroup = undefined; + } else { + combined.startGroup = Math.min(combined.startGroup, subscription.startGroup); } if (combined.endGroup === undefined || subscription.endGroup === undefined) { @@ -227,9 +235,10 @@ export class Consumer { /** * Open a live subscription to the track. * - * The cursor starts where the subscription says: at the group it named, or at the oldest - * cached one its {@link Subscription.maxAge} still considers fresh, which is the latest - * group at the default budget of zero. + * The cursor starts at the group the subscription named (its floor), or 0. + * {@link Subscription.maxAge} is what asks for data: delivery skips everything above + * the floor that the budget convicts, so the default budget of zero delivers only the + * latest group and a larger one reaches back over what it can still use. */ subscribe(options?: Subscription): Subscriber { return this.#broadcast.subscribe(this.name, options); @@ -403,9 +412,10 @@ export class Producer { /** * An independent {@link Subscriber} reading this track's groups. * - * Its cursor starts where the subscription says: at the group it named, or at the oldest - * cached one its {@link Subscription.maxAge} still considers fresh, which is the latest - * group at the default budget of zero. + * Its cursor starts at the group the subscription named (its floor), or 0. + * {@link Subscription.maxAge} is what asks for data: delivery skips everything above + * the floor that the budget convicts, so the default budget of zero delivers only the + * latest group and a larger one reaches back over what it can still use. */ subscribe(options: Subscription = {}): Subscriber { const sink = new TrackState(options); @@ -704,12 +714,12 @@ export class Subscriber { #cursor = new Signal<{ start: number; end?: number }>({ start: 0 }); #enforceLatency = true; - #drift(cap?: number): { + #drift(): { budget: number; wall?: { sequence: number; time: number }; presentation?: { sequence: number; timestamp: Timestamp }; } { - const end = cap ?? this.#cursor.peek().end; + const { end } = this.#cursor.peek(); let wall: { sequence: number; time: number } | undefined; let presentation: { sequence: number; timestamp: Timestamp } | undefined; for (const { group, time } of this.#state.timeline.values()) { @@ -787,40 +797,10 @@ export class Subscriber { private constructor(name: string, state: TrackState) { this.name = name; this.#state = state; - this.#cursor.set({ start: this.#resolveStart() }); - } - - /** - * Where this subscription's read cursor starts. - * - * The group it named, or, failing that, the oldest cached group its own - * {@link Subscription.maxAge} still considers fresh. A zero budget (the default) resolves - * to the latest group, since every older group is stale the moment a newer one exists, so - * a subscription that says nothing still joins at the live edge. A larger budget starts - * further back, handing a subscriber that tolerates some age the head of what it can still - * use instead of only the live edge. - * - * Deriving the cursor from the same budget that expires a group is what keeps the two from - * disagreeing: a subscriber is never positioned over history it would discard on arrival, - * nor past a group it would have taken. An empty cache resolves to 0, where the first - * group produced lands. - */ - #resolveStart(): number { - const subscription = this.#state.update.peek(); - if (subscription?.startGroup !== undefined) return subscription.startGroup; - - const end = subscription?.endGroup; - const drift = this.#drift(end); - - let oldest: number | undefined; - for (const { group } of this.#state.timeline.values()) { - if (end !== undefined && group.sequence > end) continue; - if (group.closed.peek() instanceof Error) continue; - if (oldest !== undefined && oldest <= group.sequence) continue; - if (this.#isStale(group, drift)) continue; - oldest = group.sequence; - } - return oldest ?? 0; + // The cursor's floor is the group the subscription named, or 0. A floor is the + // only thing a start contributes; {@link Subscription.maxAge} is what asks for + // data, and delivery skips everything above the floor that the budget convicts. + this.#cursor.set({ start: state.update.peek()?.startGroup ?? 0 }); } static { @@ -829,7 +809,6 @@ export class Subscriber { hooks.groupChanged = (subscriber, fn) => subscriber.#groupChanged(fn); hooks.exemptFetch = (subscriber) => { subscriber.#enforceLatency = false; - subscriber.#cursor.update((cursor) => ({ ...cursor, start: 0 })); }; } diff --git a/rs/libmoq/src/api.rs b/rs/libmoq/src/api.rs index 129962b81a7..681d9738c45 100644 --- a/rs/libmoq/src/api.rs +++ b/rs/libmoq/src/api.rs @@ -481,9 +481,11 @@ pub struct moq_subscription { /// Zero skips immediately. Enforced by the publisher's cache and by any local buffering. pub max_age_ms: u64, - /// First group to deliver. + /// The lowest group to deliver (a floor). A floor is not a request: `max_age_ms` is + /// what asks for data, and delivery starts at the oldest group at or above the floor + /// within that budget (the latest group at the default budget of 0). pub group_start: u64, - /// Whether `group_start` is present. When false, delivery starts at the latest group. + /// Whether `group_start` is present. When false, there is no floor. pub group_start_present: bool, /// Last group to deliver, inclusive. diff --git a/rs/moq-ffi/src/consumer.rs b/rs/moq-ffi/src/consumer.rs index 280a8baf8f4..6620e6b884c 100644 --- a/rs/moq-ffi/src/consumer.rs +++ b/rs/moq-ffi/src/consumer.rs @@ -62,7 +62,10 @@ pub struct MoqSubscription { /// buffering, such as `subscribe_media`'s jitter buffer. #[uniffi(default = 0)] pub max_age_ms: u64, - /// First group to deliver, or null to start at the latest group. + /// The lowest group to deliver (a floor), or null for none. A floor is not a + /// request: `max_age_ms` is what asks for data, and delivery starts at the oldest + /// group at or above the floor within that budget (the latest group at the default + /// budget of 0). #[uniffi(default = None)] pub group_start: Option, /// Last group to deliver (inclusive), or null for no end. diff --git a/rs/moq-net/src/lite/publisher.rs b/rs/moq-net/src/lite/publisher.rs index b7537a4581b..2b670ffe22c 100644 --- a/rs/moq-net/src/lite/publisher.rs +++ b/rs/moq-net/src/lite/publisher.rs @@ -110,16 +110,17 @@ fn serving_max_age(version: Version, requested: Duration) -> Duration { /// Position a subscription's read cursor for the wire serving it. /// -/// Normally there is nothing to do: `Consumer::subscribe` resolves the cursor from the -/// subscription itself, at the group it named or the oldest one its own Max Age still -/// considers fresh. +/// On lite-06 there is nothing to do: `Consumer::subscribe` resolves the cursor from the +/// subscription itself, at the oldest group its own Max Age still considers fresh, floored +/// at the group it named. /// -/// A wire that cannot carry Max Age is the exception. Those sessions are served with an -/// unbounded budget so a legacy subscriber never has backlog dropped under it (see -/// [`serving_max_age`]), and read as a start that would replay the whole cache on join. -/// Their drafts mean the latest group when no start is named, so say so explicitly. +/// Pre-06 wires are the exception: their drafts define an absent `Group Start` as the +/// latest group, so say so explicitly rather than letting the budget reach back. Lite03-05 +/// carry a Max Age, but there it is a staleness tolerance only; Lite01/02 additionally get +/// an unbounded budget so nothing is dropped under them (see [`serving_max_age`]), which +/// must not read as a request to replay the whole cache on join. fn position_cursor(track: &mut track::Subscriber, version: Version, start_group: Option) { - if version.carries_max_age() || start_group.is_some() { + if version.resolves_start() || start_group.is_some() { return; } @@ -1779,11 +1780,12 @@ mod test { track::Producer::new(Arc::new(broadcast::Info::default()), name, None) } - /// A wire that cannot declare a budget is served from the live edge. Those sessions get an - /// unbounded budget so nothing is dropped under them, and the cursor that budget resolves - /// to would replay the entire cache to every legacy subscriber. + /// A pre-06 wire is served from the live edge when it names no start: those drafts + /// define an absent `Group Start` as the latest group, and Lite01/02 additionally get + /// an unbounded budget (so nothing is dropped under them) that must not read as a + /// request to replay the whole cache. #[test] - fn a_legacy_wire_is_pinned_to_the_live_edge() { + fn a_pre06_wire_is_pinned_to_the_live_edge() { use futures::FutureExt; let mut producer = track_producer("test"); @@ -1820,8 +1822,14 @@ mod test { position_cursor(&mut legacy, Version::Lite01, None); assert_eq!(drain(&mut legacy), vec![2]); - // A budget the peer actually declared is a real request, so the start it resolved to - // stands. + // Lite03-05 declare a budget, but their drafts define it as a staleness tolerance + // and an absent start as the latest group, so they are pinned all the same. + let mut tolerant = + producer.subscribe(track::Subscription::default().with_max_age(std::time::Duration::from_secs(5))); + position_cursor(&mut tolerant, Version::Lite05, None); + assert_eq!(drain(&mut tolerant), vec![2]); + + // On lite-06 the declared budget is what resolves the start, so it stands. let mut declared = producer.subscribe(track::Subscription::default().with_max_age(std::time::Duration::from_secs(5))); position_cursor(&mut declared, Version::Lite06Wip, None); diff --git a/rs/moq-net/src/lite/subscribe.rs b/rs/moq-net/src/lite/subscribe.rs index c012ed14809..4834efef18f 100644 --- a/rs/moq-net/src/lite/subscribe.rs +++ b/rs/moq-net/src/lite/subscribe.rs @@ -18,10 +18,15 @@ pub struct Subscribe<'a> { pub priority: u8, pub ordered: bool, pub max_age: std::time::Duration, + /// The minimum group to deliver (a floor). On lite-06 the wire carries the raw + /// sequence and `None` is interchangeable with `Some(0)`: a floor of 0 constrains + /// nothing, and the start resolves from `max_age`. Pre-06 wires encode the + /// sequence + 1 and an absent start means the latest group. pub start_group: Option, pub end_group: Option, /// First frame to deliver within `start_group`'s group; 0 is the whole group. - /// Lite06+ only, and meaningless without an explicit `start_group`. + /// Lite06+ only. It qualifies the named group, so it needs `start_group` to name one + /// (`Some`, including `Some(0)`: group 0 can host a mid-group resume). pub start_frame: u64, /// Last frame to deliver (inclusive) within `end_group`'s group, or `None` for the /// whole group. Lite06+ only, and meaningless without an explicit `end_group`. @@ -51,13 +56,14 @@ impl Message for Subscribe<'_> { _ => { let ordered = u8::decode(r, version)? != 0; let max_age = std::time::Duration::decode(r, version)?; - let start_group = Option::::decode(r, version)?; + let start_group = decode_start_group(r, version)?; let end_group = Option::::decode(r, version)?; (ordered, max_age, start_group, end_group) } }; 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); Ok(Self { id, @@ -84,7 +90,7 @@ impl Message for Subscribe<'_> { _ => { (self.ordered as u8).encode(w, version)?; self.max_age.encode(w, version)?; - self.start_group.encode(w, version)?; + encode_start_group(w, version, self.start_group)?; self.end_group.encode(w, version)?; } } @@ -102,6 +108,47 @@ impl Message for Subscribe<'_> { } } +/// Decode the `Group Start` field shared by SUBSCRIBE and SUBSCRIBE_UPDATE. +/// +/// Lite-06 carries the raw floor, so every value names a concrete group and 0 decodes as +/// `Some(0)`. Pre-06 wires encode the sequence + 1, with 0 meaning the latest group +/// (`None`). Callers canonicalize with [`canonical_start_group`] once the frame bounds +/// are known. +fn decode_start_group(r: &mut R, version: Version) -> Result, DecodeError> { + if version.resolves_start() { + return Ok(Some(u64::decode(r, version)?)); + } + Option::::decode(r, version) +} + +/// Canonicalize a decoded floor: a lite-06 `Group Start` of 0 with no frame offset is the +/// same absence of a constraint as no floor at all, so it decodes as `None`. Group 0 stays +/// named only when a `Frame Start` actually qualifies it (a subscription can resume +/// partway through group 0, e.g. a catalog that never leaves it). +fn canonical_start_group(version: Version, start_group: Option, start_frame: u64) -> Option { + match (start_group, start_frame) { + (Some(0), 0) if version.resolves_start() => None, + (start_group, _) => start_group, + } +} + +/// Encode the `Group Start` field shared by SUBSCRIBE and SUBSCRIBE_UPDATE. +/// +/// The inverse of [`decode_start_group`]: lite-06 writes the raw floor (`None` and +/// `Some(0)` are the same absence of a constraint), while a pre-06 wire gets `Some(0)` +/// folded back to absent. On those wires an explicit group 0 means "replay from the +/// beginning", which is not what a vacuous floor asks for. +fn encode_start_group( + w: &mut W, + version: Version, + start_group: Option, +) -> Result<(), EncodeError> { + if version.resolves_start() { + return start_group.unwrap_or(0).encode(w, version); + } + start_group.filter(|&group| group > 0).encode(w, version) +} + /// Decode the trailing `Frame Start` / `Frame End` pair shared by SUBSCRIBE, /// SUBSCRIBE_UPDATE, and FETCH. /// @@ -311,16 +358,14 @@ impl Message for SubscribeUpdate { let priority = u8::decode(r, version)?; let ordered = u8::decode(r, version)? != 0; let max_age = std::time::Duration::decode(r, version)?; - let start_group = match u64::decode(r, version)? { - 0 => None, - group => Some(group - 1), - }; + let start_group = decode_start_group(r, version)?; let end_group = match u64::decode(r, version)? { 0 => None, group => Some(group - 1), }; 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); Ok(Self { priority, @@ -345,13 +390,7 @@ impl Message for SubscribeUpdate { (self.ordered as u8).encode(w, version)?; self.max_age.encode(w, version)?; - match self.start_group { - Some(start_group) => start_group - .checked_add(1) - .ok_or(EncodeError::TooLarge)? - .encode(w, version)?, - None => 0u64.encode(w, version)?, - } + encode_start_group(w, version, self.start_group)?; match self.end_group { Some(end_group) => end_group @@ -594,10 +633,12 @@ mod test { } /// The whole-group defaults are what a version without the fields decodes to, so - /// lite-05 stays byte-identical. + /// lite-05 stays byte-identical. Compared without a floor, since `Group Start` itself + /// encodes differently across the two (see `group_start_is_absolute_on_lite06`). #[test] fn subscribe_without_frame_bounds_is_unchanged_on_lite05() { let mut msg = subscribe_sample(); + msg.start_group = None; msg.start_frame = 0; msg.end_frame = None; @@ -614,6 +655,60 @@ mod test { assert_eq!((got.start_frame, got.end_frame), (0, None)); } + /// Lite06 carries the raw floor; pre-06 wires encode the sequence + 1 with 0 meaning + /// the latest group. A vacuous floor folds to absent on the old wire, where an + /// explicit group 0 would mean "replay from the beginning" instead. + #[test] + fn group_start_is_absolute_on_lite06() { + let mut msg = subscribe_sample(); + msg.start_frame = 0; + msg.end_frame = None; + + let mut lite05 = Vec::new(); + msg.encode_msg(&mut lite05, Version::Lite05).unwrap(); + let mut lite06 = Vec::new(); + msg.encode_msg(&mut lite06, Version::Lite06Wip).unwrap(); + + let on05 = Subscribe::decode_msg(&mut lite05.as_slice(), Version::Lite05).unwrap(); + let on06 = Subscribe::decode_msg(&mut lite06.as_slice(), Version::Lite06Wip).unwrap(); + assert_eq!(on05.start_group, Some(7)); + assert_eq!(on06.start_group, Some(7)); + // The raw byte differs: 7 on the wire, not 7 + 1. + assert_ne!(lite05, lite06); + + // No floor and a floor of 0 are the same absence of a constraint on lite-06: + // byte-identical on the wire, and canonicalized to absent on decode. + msg.start_group = None; + let mut absent = Vec::new(); + msg.encode_msg(&mut absent, Version::Lite06Wip).unwrap(); + msg.start_group = Some(0); + let mut zero = Vec::new(); + msg.encode_msg(&mut zero, Version::Lite06Wip).unwrap(); + assert_eq!(absent, zero); + let got = Subscribe::decode_msg(&mut zero.as_slice(), Version::Lite06Wip).unwrap(); + assert_eq!(got.start_group, None); + + // On the pre-06 wire the vacuous floor folds to absent (the latest group). + let mut folded = Vec::new(); + msg.encode_msg(&mut folded, Version::Lite05).unwrap(); + let got = Subscribe::decode_msg(&mut folded.as_slice(), Version::Lite05).unwrap(); + assert_eq!(got.start_group, None); + } + + /// A subscription can resume partway through group 0 (a catalog never leaves it), so + /// a `Frame Start` qualifying the zero floor must survive the round trip. + #[test] + fn frame_start_may_qualify_group_zero_on_lite06() { + let mut msg = subscribe_sample(); + msg.start_group = Some(0); + msg.start_frame = 4; + + let mut buf = Vec::new(); + msg.encode_msg(&mut buf, Version::Lite06Wip).unwrap(); + let got = Subscribe::decode_msg(&mut buf.as_slice(), Version::Lite06Wip).unwrap(); + assert_eq!((got.start_group, got.start_frame), (Some(0), 4)); + } + /// Silently widening to the whole group would deliver frames the caller excluded. #[test] fn subscribe_frame_bounds_rejected_before_lite06() { diff --git a/rs/moq-net/src/lite/version.rs b/rs/moq-net/src/lite/version.rs index 7882ceffc95..f0520ea659f 100644 --- a/rs/moq-net/src/lite/version.rs +++ b/rs/moq-net/src/lite/version.rs @@ -138,6 +138,22 @@ impl Version { } } + /// Whether SUBSCRIBE's `Group Start` is an absolute floor the publisher resolves a + /// start from: the raw minimum group sequence (default 0), with `Subscriber Max Age` + /// as the only gate on how far back delivery begins. Changed in lite-06. + /// + /// Older versions encode `Group Start` as the sequence + 1, with 0 meaning the + /// latest group, so an absent start there pins the cursor to the live edge instead + /// of resolving it from the budget. + #[allow(clippy::match_like_matches_macro)] + pub(crate) fn resolves_start(self) -> bool { + // Match form so future versions default forward (CLAUDE.md convention). + match self { + Self::Lite01 | Self::Lite02 | Self::Lite03 | Self::Lite04 | Self::Lite05 => 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 diff --git a/rs/moq-net/src/model/resume.rs b/rs/moq-net/src/model/resume.rs index 43d2ad98d7b..6cb4d9ee485 100644 --- a/rs/moq-net/src/model/resume.rs +++ b/rs/moq-net/src/model/resume.rs @@ -1470,8 +1470,10 @@ impl Subscriber { // case a boundary moved while the subscription was pending. The // upper bounds (segment boundary and `end_at` cap) are enforced by // this subscriber, never on the inner cursor: an inner cap would - // park groups there and hide the segment's completion. - sub.start_at(seg.first_group().max(min_sequence)); + // park groups there and hide the segment's completion. Raised, not + // assigned: the inner subscription resolved its own start from its + // budget and floor, and this must not rewind past it. + sub.raise_start_to(seg.first_group().max(min_sequence)); sub.set_stale_cap(Self::stale_cap(seg, end_sequence)); let _ = sub.update(slice(prefs, seg.start, seg.end)); seg.sub = SubState::Active(sub); @@ -1833,6 +1835,18 @@ impl Subscriber { } } + /// Raise the floor to `sequence`, keeping any higher floor already set. See + /// [`track::Subscriber::raise_start_to`]. + pub(crate) fn raise_start_to(&mut self, sequence: u64) { + self.min_sequence = self.min_sequence.max(sequence); + for seg in &mut self.segments { + let floor = seg.first_group().max(sequence); + if let SubState::Active(sub) = &mut seg.sub { + sub.raise_start_to(floor); + } + } + } + /// Cap the subscriber at the specified sequence (inclusive), or remove the cap. /// /// Enforced on this subscriber's reads (see [`Self::poll_recv_group`]), never diff --git a/rs/moq-net/src/model/subscription.rs b/rs/moq-net/src/model/subscription.rs index 4670f089812..1fb4ed988d2 100644 --- a/rs/moq-net/src/model/subscription.rs +++ b/rs/moq-net/src/model/subscription.rs @@ -53,13 +53,18 @@ pub struct Subscription { /// in three reads as three. The publisher's copy is stamped as it produces, so the /// gate there still holds; it is just the coarser of the two. pub max_age: Duration, - /// First [`Position`] the publisher should deliver, or `None` to start at the latest - /// group. + /// The lowest [`Position`] the publisher may deliver, or `None` for no floor. /// - /// A request, aggregated across every live subscriber (the earliest explicit start - /// wins), so it says what the publisher sends, not what any one subscriber sees. - /// [`crate::track::Subscriber::start_at`] is the local read cursor; setting one does - /// not imply the other. See [Local cursor vs wire + /// A floor, not a request: only [`Self::max_age`] asks for data, and the floor bounds + /// how far back it may reach. `None` and a floor of group 0 mean the same thing, since + /// nothing sits below group 0. Delivery starts at the oldest group at or above the + /// floor that the budget still considers fresh, so a floor above the live edge simply + /// waits there (a resumed subscription naming where it left off). + /// + /// Aggregated across every live subscriber (the loosest floor wins, and any subscriber + /// without one clears it), so it says what the publisher sends, not what any one + /// subscriber sees. [`crate::track::Subscriber::start_at`] is the local read cursor; + /// setting one does not imply the other. See [Local cursor vs wire /// preference](crate::track::Subscriber#local-cursor-vs-wire-preference). pub start: Option, /// First [`Position`] the publisher should *not* deliver, or `None` for no end. @@ -111,10 +116,11 @@ impl Subscription { self } - /// Start delivery at `start`, or at the latest group when `None`. Returns `self` for + /// Floor delivery at `start`, or leave it unfloored when `None`. Returns `self` for /// chaining. /// - /// [`Position::group`] is the whole-group form. + /// A floor bounds how far back [`Self::max_age`] may reach; it does not request data + /// on its own. [`Position::group`] is the whole-group form. pub fn with_start(mut self, start: impl Into>) -> Self { self.start = start.into(); self @@ -147,7 +153,7 @@ impl Subscription { // Bounds fold as whole positions. Two subscribers starting in the same group // are separated only by their frame, so folding group and frame independently // would invent a bound neither asked for. - start: min_some(self.start, combined.start), + start: min_floored(self.start, combined.start), end: max_unbounded(self.end, combined.end), }; @@ -237,6 +243,16 @@ pub(super) fn min_some(a: Option, b: Option) -> Option { } } +/// The lower of two optional floors, treating `None` as no floor (and therefore +/// absorbing). The mirror of [`max_unbounded`]: both bounds only ever *restrict*, so a +/// subscriber without one keeps the aggregate unrestricted. +pub(super) fn min_floored(a: Option, b: Option) -> Option { + match (a, b) { + (Some(a), Some(b)) => Some(a.min(b)), + (None, _) | (_, None) => None, + } +} + /// The higher of two optional bounds, treating `None` as unbounded (and therefore /// absorbing). pub(super) fn max_unbounded(a: Option, b: Option) -> Option { @@ -313,15 +329,18 @@ mod tests { } #[test] - fn combined_group_start_uses_earliest_explicit_start() { - // No start at all is the live edge, which loses to any explicit one. - let live = Subscription::default(); + fn combined_group_start_keeps_the_loosest_floor() { + // A floor only restricts, so the lowest one wins across floored subscribers. let catchup = Subscription::default().with_start(Position::group(10)); let older_catchup = Subscription::default().with_start(Position::group(5)); - - let combined = combine(&[live, catchup, older_catchup]).unwrap(); - + let combined = combine(&[catchup.clone(), older_catchup]).unwrap(); assert_eq!(combined.start, Some(Position::group(5))); + + // A subscriber with no floor at all clears the aggregate: its budget may reach + // below any floor the others set. + let unfloored = Subscription::default(); + let combined = combine(&[catchup, unfloored]).unwrap(); + assert_eq!(combined.start, None); } #[test] diff --git a/rs/moq-net/src/model/track.rs b/rs/moq-net/src/model/track.rs index 1a959636eb7..f8813707f42 100644 --- a/rs/moq-net/src/model/track.rs +++ b/rs/moq-net/src/model/track.rs @@ -626,34 +626,6 @@ impl TrackState { wall_stale || presentation_stale } - /// The oldest cached group `budget` still considers fresh: the lowest sequence - /// [`Self::is_stale`] does not already convict, or `None` when nothing is cached. - /// - /// One [`Self::live_edge`] scan for the whole walk, like a poll's [`Drift`], so - /// resolving a start costs one pass over the cache rather than one per candidate. - fn fresh_start(&self, budget: Duration, cap: Option) -> Option { - let edge = self.live_edge(cap); - - let mut oldest: Option = None; - for slot in self.lookup.values() { - let sequence = slot.group.sequence; - if !slot.visible || slot.group.is_aborted() { - continue; - } - if cap.is_some_and(|cap| sequence > cap) { - continue; - } - if oldest.is_some_and(|oldest| oldest <= sequence) { - continue; - } - if self.is_stale(sequence, None, edge, budget) { - continue; - } - oldest = Some(sequence); - } - oldest - } - /// Resolve a one-shot fetch from the track side: the cached group, or an [`Error`] /// once it can never be served. A missing group is a failure ([`Error::NotFound`]), not an /// end-of-stream. The handler side (a rejection, or no [`Dynamic`] at all) lives @@ -1442,9 +1414,10 @@ impl Producer { /// The info is fixed at creation, so there's nothing to wait for (no /// SUBSCRIBE_OK round trip). Pass `None` for [`Subscription::default`]. /// - /// The read cursor starts where the subscription says: at the group it named, or at the - /// oldest cached one its [`Subscription::max_age`] still considers fresh, which is the - /// latest group at the default budget of zero. + /// The read cursor starts at the group the subscription named (its floor), or 0. + /// [`Subscription::max_age`] is what asks for data: delivery skips everything above + /// the floor that the budget convicts, so the default budget of zero delivers only + /// the latest group and a larger one reaches back over what it can still use. pub fn subscribe(&self, subscription: impl Into>) -> Subscriber { let preferences = subscription.into().unwrap_or_default(); @@ -1454,22 +1427,20 @@ impl Producer { // simply never registered (nothing aggregates them anymore). let info = self.state.read().info.clone().expect("producer always has info"); - // Hoisted, like `broadcast` below: a `read()` guard taken inside the struct literal - // would live to the end of it, deadlocking against the reads these make. - let state = self.state.consume(); - let min_sequence = resolve_start(&state, &preferences); - + let min_sequence = floor_of(&preferences); let subscription = kio::Producer::new(preferences); register_subscription(self.state.read(), &subscription); let drift_cap = kio::Producer::new(None); + // Hoisted: an inline `read()` guard would live to the end of the struct literal, + // deadlocking against the `consume()` below. let broadcast = self.state.read().broadcast.clone(); Subscriber { name: self.name.clone(), broadcast, info, inner: SubscriberKind::Plain(PlainSubscriber { - state, + state: self.state.consume(), subscription, min_sequence, index: 0, @@ -1838,30 +1809,16 @@ fn servable_cap(cursor: Option, outer: Option) -> Option { super::subscription::min_some(cursor, outer) } -/// Where a new subscription's read cursor starts. +/// The read cursor's floor: the group the subscription named, or 0 (no floor). /// -/// The group it named, or, failing that, the oldest cached group its own -/// [`Subscription::max_age`] still considers fresh. A zero budget (the default) resolves to -/// the latest group, since every older group is stale the moment a newer one exists, so a -/// subscription that says nothing still joins at the live edge. A larger budget starts -/// further back, handing a subscriber that tolerates some age the head of what it can still -/// use instead of only the live edge. -/// -/// Deriving the cursor from the same budget that expires a group is what keeps the two from -/// disagreeing: a subscriber is never positioned over history it would discard on arrival, -/// nor past a group it would have taken. It measures against the same capped live edge for -/// the same reason, since a route running on past the cap is data this subscription can never -/// be served and so cannot age it. An empty cache resolves to 0, where the first group -/// produced lands. -fn resolve_start(state: &kio::Consumer, subscription: &Subscription) -> u64 { - if let Some(start) = subscription.start { - return start.group; - } - - let cap = subscription.end.and_then(|end| end.before()).map(|end| end.group); - let state = state.read(); - let budget = clamp_max_age(subscription.max_age, state.max_age_bound()); - state.fresh_start(budget, cap).unwrap_or(0) +/// A floor is the only thing a start contributes; [`Subscription::max_age`] is what asks +/// for data. Delivery walks everything at or above the floor and skips what the budget +/// convicts, so a zero budget (the default) delivers only the live edge, a larger one +/// reaches back over what it can still use, and a floor above the live edge simply waits +/// there (a resumed subscription naming where it left off). One bound decides both what +/// is sent and what is expired, so the two cannot disagree. +fn floor_of(subscription: &Subscription) -> u64 { + subscription.start.map(|start| start.group).unwrap_or(0) } /// Clamp a drift budget to the publisher's retention window: nobody can wait for a late @@ -2122,9 +2079,10 @@ impl Consumer { /// [`Subscriber`] once the track info is available, or the track's abort error (or /// [`Error::Dropped`]) if it is already closed. /// - /// The read cursor starts where the subscription says: at the group it named, or at the - /// oldest cached one its [`Subscription::max_age`] still considers fresh, which is the - /// latest group at the default budget of zero. + /// The read cursor starts at the group the subscription named (its floor), or 0. + /// [`Subscription::max_age`] is what asks for data: delivery skips everything above + /// the floor that the budget convicts, so the default budget of zero delivers only + /// the latest group and a larger one reaches back over what it can still use. pub fn subscribe(&self, subscription: impl Into>) -> kio::Pending { let subscription = kio::Producer::new(subscription.into().unwrap_or_default()); @@ -2428,7 +2386,7 @@ impl Subscribing { .map_err(|e| e.abort.clone().unwrap_or(Error::Dropped))??; let drift_cap = kio::Producer::new(None); - let min_sequence = resolve_start(state, &self.subscription.read()); + let min_sequence = floor_of(&self.subscription.read()); Poll::Ready(Ok(Subscriber { name: self.name.clone(), broadcast: self.broadcast.clone(), @@ -2726,10 +2684,10 @@ impl kio::Pollable for Fetching { /// groups, and setting only the preference still returns groups another subscriber asked /// for. Set both to skip them *and* avoid the transfer. /// -/// The one place they meet is where the cursor comes from. A new subscriber starts at the -/// group its own subscription named, or, failing that, at the oldest cached group its -/// [`Subscription::max_age`] still considers fresh, which is the latest group at the default -/// budget of zero. Every later move is the caller's. +/// The one place they meet is where the cursor comes from. A new subscriber's cursor is +/// floored at the group its own subscription named (or 0), and its +/// [`Subscription::max_age`] decides what above the floor is worth delivering. Every later +/// move is the caller's. pub struct Subscriber { name: Arc, // The broadcast this track belongs to; see [`Self::broadcast`]. @@ -3395,6 +3353,18 @@ impl Subscriber { } } + /// Raise the read cursor's floor to `sequence`, keeping any higher floor already set. + /// + /// The spliced layer positions a segment's inner cursor with this instead of + /// [`Self::start_at`]: the inner subscription already resolved a start from its own + /// budget and floor, and an assignment would discard it. + pub(crate) fn raise_start_to(&mut self, sequence: u64) { + match &mut self.inner { + SubscriberKind::Plain(plain) => plain.min_sequence = plain.min_sequence.max(sequence), + SubscriberKind::Spliced(spliced) => spliced.raise_start_to(sequence), + } + } + /// Cap this subscriber's read cursor at the given sequence (inclusive), or remove the /// cap entirely. /// @@ -4407,83 +4377,80 @@ mod test { assert_eq!(drain(&mut subscriber), vec![2, 3, 4]); } - /// The cursor a subscription starts at, without going through `subscribe`. - fn start_of(producer: &Producer, subscription: &Subscription) -> u64 { - resolve_start(&producer.state.consume(), subscription) - } - #[test] - fn a_start_resolves_to_the_live_edge_without_a_budget() { + fn a_budget_reaches_back_over_the_cache() { let mut producer = track_producer("test", None); for second in 0..5 { append_at(&mut producer, second * 1000); } - // The default zero budget calls every non-latest group stale, so the only start that - // delivers anything is the live edge. A subscription that says nothing therefore - // joins exactly where it always did. - assert_eq!(start_of(&producer, &Subscription::default()), 4); - } - - #[test] - fn a_start_reaches_back_over_the_budget() { - let mut producer = track_producer("test", None); - for second in 0..5 { - append_at(&mut producer, second * 1000); - } + // The default zero budget calls every non-latest group stale, so a subscription + // that says nothing joins at the live edge. + let mut live = producer.subscribe(None); + assert_eq!(drain(&mut live), vec![4]); - // Two seconds of tolerance covers the groups presenting within 2s of the live edge, - // so the start resolves to the oldest of those rather than the live edge. It has to - // agree with what delivery keeps, or a subscriber would either be positioned over - // groups it discards on arrival or past ones it would have taken. + // Two seconds of tolerance covers the groups presenting within 2s of the live + // edge, so the same join is handed the head of what it can still use. One bound + // decides both what is sent and what is expired, so a subscriber is never sent + // history it would discard on arrival. let budget = Subscription::default().with_max_age(Duration::from_secs(2)); - assert_eq!(start_of(&producer, &budget), 2); - let mut subscriber = producer.subscribe(budget); assert_eq!(drain(&mut subscriber), vec![2, 3, 4]); } #[test] - fn a_named_start_wins_over_the_budget() { + fn a_named_start_is_a_floor_not_a_request() { let mut producer = track_producer("test", None); for second in 0..5 { append_at(&mut producer, second * 1000); } - // An explicit start is the request; the budget only fills in for its absence. It is - // still a start, not an exemption: delivery expires what the budget convicts, which - // is why asking for group 0 at real time yields the live edge anyway. + // The budget is the only thing that asks for data; a named start only bounds how + // far back it may reach. Naming group 1 at real time still delivers the live edge + // alone, since the zero budget calls everything older stale. let named = Subscription::default().with_start(Position::group(1)); - assert_eq!(start_of(&producer, &named), 1); - let mut subscriber = producer.subscribe(named); assert_eq!(drain(&mut subscriber), vec![4]); + + // A budget reaching further back than the floor is cut off at it. + let floored = Subscription::default() + .with_start(Position::group(3)) + .with_max_age(Duration::from_secs(10)); + let mut subscriber = producer.subscribe(floored); + assert_eq!(drain(&mut subscriber), vec![3, 4]); + + // A floor below what the budget admits changes nothing. + let slack = Subscription::default() + .with_start(Position::group(1)) + .with_max_age(Duration::from_secs(2)); + let mut subscriber = producer.subscribe(slack); + assert_eq!(drain(&mut subscriber), vec![2, 3, 4]); } #[test] - fn a_start_is_clamped_to_the_publisher_window() { - let mut producer = track_producer("test", Info::default().with_max_age(Duration::from_secs(2))); - for second in 0..5 { + fn a_floor_above_the_live_edge_waits_there() { + let mut producer = track_producer("test", None); + for second in 0..3 { append_at(&mut producer, second * 1000); } - // Asking to tolerate ten seconds cannot reach back further than the publisher keeps a - // group live, the same clamp delivery applies. - let over = Subscription::default().with_max_age(Duration::from_secs(10)); - assert_eq!(start_of(&producer, &over), 2); - } - - #[test] - fn a_start_on_an_empty_track_takes_the_first_group() { - let producer = track_producer("test", None); - - // Nothing cached to measure against, so the cursor sits where the first group lands - // rather than skipping it. - assert_eq!(start_of(&producer, &replay()), 0); + // A resumed subscription names where it left off, which may not exist yet. The + // cursor sits at the floor rather than sliding back to what is cached. + let resumed = Subscription::default() + .with_start(Position::group(7)) + .with_max_age(Duration::from_secs(10)); + let mut subscriber = producer.subscribe(resumed); + assert_eq!(drain(&mut subscriber), Vec::::new()); + append_at(&mut producer, 3000); // sequence 3: still below the floor + assert_eq!(drain(&mut subscriber), Vec::::new()); + for second in 4..8 { + append_at(&mut producer, second * 1000); + } + assert_eq!(drain(&mut subscriber), vec![7]); } #[test] - fn a_resolved_start_is_a_floor_for_later_arrivals() { + fn a_late_lower_group_within_the_budget_is_delivered() { let mut producer = track_producer("test", None); for (sequence, millis) in [(5, 0), (6, 1000), (7, 2000)] { let mut group = producer.create_group(group::Info { sequence }).unwrap(); @@ -4493,16 +4460,17 @@ mod test { group.finish().unwrap(); } - // A budget covering everything cached resolves the start to the oldest of it, 5. let mut subscriber = producer.subscribe(Subscription::default().with_max_age(Duration::from_secs(5))); + assert_eq!(drain(&mut subscriber), vec![5, 6, 7]); - // That start is a floor like any other, so a group arriving below it afterwards is - // behind the subscription, even carrying a timestamp the budget would admit. + // Arriving below everything already delivered is not what makes content stale: + // the budget is the only gate, and this straggler's timestamp is within it. A + // consumer that needs sequence order reorders (or drops) it itself. let mut late = producer.create_group(group::Info { sequence: 4 }).unwrap(); late.write_frame(Timestamp::from_millis(500).unwrap(), bytes::Bytes::from_static(b"late")) .unwrap(); late.finish().unwrap(); - assert_eq!(drain(&mut subscriber), vec![5, 6, 7]); + assert_eq!(drain(&mut subscriber), vec![4]); } #[test] @@ -4985,17 +4953,13 @@ mod test { #[tokio::test] async fn read_frame_counts_what_it_skips() { let mut producer = track_producer("test", None); - - // Subscribed before any of it exists, so every group below the live edge is one this - // reader fell behind rather than backlog it joined past: a start resolves once, and - // what it resolved to is not a skip. - let mut subscriber = producer.subscribe(None); for second in 0..4 { append_at(&mut producer, second * 1000); } // A silent skip is indistinguishable from loss whichever read did it, so the // frame-level path reports its drops like the group-level ones. + let mut subscriber = producer.subscribe(None); subscriber.read_frame().await.unwrap().expect("a frame"); let stale = subscriber.take_stale(); assert_eq!(stale.groups, 3); @@ -5005,10 +4969,6 @@ mod test { #[tokio::test] async fn read_frame_counts_stale_groups_at_eof() { let mut producer = track_producer("test", None); - - // Subscribed first, so the two groups below the edge are ones this reader fell behind - // rather than backlog its start resolved past. See read_frame_counts_what_it_skips. - let mut subscriber = producer.subscribe(None); append_at(&mut producer, 0); append_at(&mut producer, 1000); @@ -5022,6 +4982,7 @@ mod test { edge.finish().unwrap(); producer.finish().unwrap(); + let mut subscriber = producer.subscribe(None); assert!(subscriber.read_frame().await.unwrap().is_none()); let stale = subscriber.take_stale(); assert_eq!(stale.groups, 2); diff --git a/rs/moq-tokio/tests/broadcast.rs b/rs/moq-tokio/tests/broadcast.rs index 170bd3d0442..85893efd971 100644 --- a/rs/moq-tokio/tests/broadcast.rs +++ b/rs/moq-tokio/tests/broadcast.rs @@ -833,8 +833,12 @@ async fn broadcast_route_migration() { let broadcast = broadcast.expect("expected announce"); // Subscribe once, with a generous stale window so the continuation B already holds - // is served rather than aged out. - let subscription = moq_net::track::Subscription::default().with_max_age(Duration::from_secs(10)); + // is served rather than aged out, and a floor at the live edge so that window is a + // tolerance rather than a request for A's backlog: the budget alone would resolve + // the start at a0. + let subscription = moq_net::track::Subscription::default() + .with_start(moq_net::track::Position::group(1)) + .with_max_age(Duration::from_secs(10)); let mut sub = broadcast .track("video") .unwrap() @@ -842,8 +846,8 @@ async fn broadcast_route_migration() { .await .expect("subscribe failed"); - // The preferred route (A) serves the track. A live-edge subscription tunes in - // at the latest group, so only A's newest group arrives. + // The preferred route (A) serves the track from the floor, so only A's newest + // group arrives. assert_eq!(read_payloads(&mut sub, 1).await, ["a1"]); // Kill the serving session. The track migrates to B and the same subscriber keeps