diff --git a/doc/concept/layer/moq-lite.md b/doc/concept/layer/moq-lite.md index 0b43c17f849..9812000b92c 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 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. @@ -126,7 +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. +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 fb12d9836a5..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 requesting the latest group (`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,9 +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 latest group (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). + +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 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). @@ -996,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)). @@ -1359,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. @@ -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`. +- 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 new file mode 100644 index 00000000000..03b5b869270 --- /dev/null +++ b/js/hang/src/container/consumer.outoforder.test.ts @@ -0,0 +1,113 @@ +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; +} + +/** 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); + publishFrame(group, millis, sequence); + 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 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 () => { + 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 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], + ]); + + 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.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 f3bf50c65c2..d60d6a98929 100644 --- a/js/hang/src/container/consumer.ts +++ b/js/hang/src/container/consumer.ts @@ -167,21 +167,18 @@ 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. - 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 = consumer.sequence < this.#active; - } - - 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; } @@ -589,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/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/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/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 7338202891b..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 @@ -270,8 +270,31 @@ 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; +} + +/** + * Position a subscription's read cursor for the wire serving it. + * + * 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. + * + * 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 (resolvesStart(version) || startGroup !== undefined) return; + + const latest = track.latest(); + if (latest !== undefined) track.startAt(latest); } /** @@ -471,8 +494,7 @@ export class Publisher { startGroup: msg.startGroup, endGroup: msg.endGroup, }); - const startGroup = msg.startGroup ?? track.latest(); - 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/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 c0c97c4a8a9..c212b5704d3 100644 --- a/js/net/src/track.test.ts +++ b/js/net/src/track.test.ts @@ -270,6 +270,68 @@ test("latency budget admits groups within its presentation-time window", async ( expect((await track.recvGroup())?.sequence).toBe(2); }); +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], + [6, 1000], + [7, 2000], + ]) { + const group = new GroupProducer(sequence); + producer.writeGroup(group); + group.writeFrame({ payload: enc.encode(`${timestamp}`), timestamp: Timestamp.fromMillis(timestamp) }); + group.close(); + } + + 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(4); + producer.close(); + expect(await track.recvGroup()).toBeUndefined(); +}); + +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 }); + + 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((await track.recvGroup())?.sequence).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..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) { @@ -224,7 +232,14 @@ export class Consumer { this.#broadcast = broadcast; } - /** Open a live subscription to the track. */ + /** + * Open a live subscription to the track. + * + * 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); } @@ -394,7 +409,14 @@ 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 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); this.#addSink(sink); @@ -775,13 +797,17 @@ export class Subscriber { private constructor(name: string, state: TrackState) { this.name = name; this.#state = state; + // 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 { 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; }; } 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 e41fe9bbe71..2b670ffe22c 100644 --- a/rs/moq-net/src/lite/publisher.rs +++ b/rs/moq-net/src/lite/publisher.rs @@ -108,6 +108,27 @@ fn serving_max_age(version: Version, requested: Duration) -> Duration { } } +/// Position a subscription's read cursor for the wire serving it. +/// +/// 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. +/// +/// 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.resolves_start() || start_group.is_some() { + return; + } + + if let Some(latest) = track.latest() { + track.start_at(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 +1780,62 @@ mod test { track::Producer::new(Arc::new(broadcast::Info::default()), name, None) } + /// 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_pre06_wire_is_pinned_to_the_live_edge() { + use futures::FutureExt; + + let mut producer = track_producer("test"); + 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()) + .unwrap(); + group.finish().unwrap(); + } + + // 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]); + + // 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); + assert_eq!(drain(&mut declared), vec![0, 1, 2]); + } + /// 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,10 +2940,7 @@ 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()) { - 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/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 3f4886fc7ef..f8813707f42 100644 --- a/rs/moq-net/src/model/track.rs +++ b/rs/moq-net/src/model/track.rs @@ -1413,6 +1413,11 @@ 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 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(); @@ -1421,6 +1426,8 @@ 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"); + + 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); @@ -1435,9 +1442,9 @@ impl Producer { inner: SubscriberKind::Plain(PlainSubscriber { state: self.state.consume(), subscription, + min_sequence, index: 0, datagram_index: 0, - min_sequence: 0, next_sequence: 0, end_sequence: None, parked: BTreeMap::new(), @@ -1802,6 +1809,18 @@ fn servable_cap(cursor: Option, outer: Option) -> Option { super::subscription::min_some(cursor, outer) } +/// The read cursor's floor: the group the subscription named, or 0 (no floor). +/// +/// 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 /// group longer than the publisher keeps it around. /// @@ -2059,6 +2078,11 @@ 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 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()); @@ -2362,6 +2386,7 @@ impl Subscribing { .map_err(|e| e.abort.clone().unwrap_or(Error::Dropped))??; let drift_cap = kio::Producer::new(None); + let min_sequence = floor_of(&self.subscription.read()); Poll::Ready(Ok(Subscriber { name: self.name.clone(), broadcast: self.broadcast.clone(), @@ -2369,9 +2394,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(), @@ -2658,6 +2683,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'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`]. @@ -3323,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. /// @@ -4335,6 +4377,102 @@ mod test { assert_eq!(drain(&mut subscriber), vec![2, 3, 4]); } + #[test] + 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 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 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)); + let mut subscriber = producer.subscribe(budget); + assert_eq!(drain(&mut subscriber), vec![2, 3, 4]); + } + + #[test] + 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); + } + + // 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)); + 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_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); + } + + // 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_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(); + group + .write_frame(Timestamp::from_millis(millis).unwrap(), bytes::Bytes::from_static(b"x")) + .unwrap(); + group.finish().unwrap(); + } + + let mut subscriber = producer.subscribe(Subscription::default().with_max_age(Duration::from_secs(5))); + assert_eq!(drain(&mut subscriber), vec![5, 6, 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. + 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![4]); + } + #[test] fn drift_is_measured_in_presentation_time_not_arrival_time() { let mut producer = track_producer("test", None); 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