diff --git a/doc/concept/layer/moq-lite.md b/doc/concept/layer/moq-lite.md index 1327edc9fc4..be7c57e570a 100644 --- a/doc/concept/layer/moq-lite.md +++ b/doc/concept/layer/moq-lite.md @@ -82,7 +82,8 @@ 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. A new subscription starts at the oldest cached group +within its Subscriber Max Latency budget; the default zero budget starts at the latest group. 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). @@ -111,6 +112,7 @@ Each Subscription consists of a few properties: - **Track Priority**: A value between 0 and 255. Tracks with higher priority will be delivered first. - **Group Order**: The order in which groups are delivered. Defaults to descending; higher IDs are delivered first. - **Subscriber Max Latency**: The maximum age of a non-latest group before it is skipped. Defaults to zero, so stale groups are skipped immediately. +- **Group Start**: An optional absolute floor on the publisher's choice. When omitted, the publisher chooses the starting group using Subscriber Max Latency with an implicit floor of group 0. A supplied floor restricts that choice but does not request history by itself. The publisher also keeps old groups around for a best-effort **Publisher Max Latency** cache window so relays and late subscribers can still fetch them. This defaults to 5 seconds. The subscriber's maximum latency is bounded by this window: a group can't be waited for longer than it's actually kept around. @@ -168,7 +170,7 @@ But if a publisher needs a feature, then the subscriber needs it too, so you can - **No Request IDs**: A bidirectional stream for each request to avoid HoLB. (NOTE: likely to be upstreamed into moq-transport) - **No Push**: A subscriber must explicitly subscribe to each track. - **Single-group FETCH only (lite-05+)**: Fetch one complete group by sequence. Ranges and joining fetches are not supported. -- **No Joining Fetch**: Subscriptions start at the latest group, not the latest frame. +- **No Joining Fetch**: Subscriptions start at a group boundary selected by Subscriber Max Latency, never in the middle of a group. - **No sub-groups**: SVC layers should be separate tracks. - **No gaps**: Makes life much easier for the relay and every application. - **No object properties**: Encode your metadata into the frame payload. diff --git a/drafts/draft-lcurley-moq-lite.md b/drafts/draft-lcurley-moq-lite.md index 3054ecc8329..cb3a46d57fc 100644 --- a/drafts/draft-lcurley-moq-lite.md +++ b/drafts/draft-lcurley-moq-lite.md @@ -844,8 +844,8 @@ 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). +An optional lower bound on the publisher-selected starting group. +A value of 0 means absent (default): the publisher chooses using `Subscriber Max Latency` with an implicit floor of absolute group 0. A non-zero value is the absolute group sequence + 1. **Group End**: @@ -853,7 +853,7 @@ The last group to deliver (inclusive). A value of 0 means unbounded (default). A non-zero value is the absolute group sequence + 1. -`Group Start` and `Group End` are offset by 1 only so 0 can mean "absent"; every other group field in this document is a plain absolute sequence. +`Group Start` and `Group End` are offset by 1 only so 0 can mean "absent"; every other group field in this document is a plain absolute sequence. An absent `Group Start` leaves the starting position to the publisher, bounded below by absolute group 0. With the default `Subscriber Max Latency` of 0 the publisher chooses the latest group, because every older group is immediately stale. ## SUBSCRIBE_UPDATE @@ -965,7 +965,7 @@ Set to 0x0 to indicate a SUBSCRIBE_OK message. **Group**: The absolute sequence number of the first group that will be delivered. It MUST be greater than or equal to the requested start group; any groups in between are unavailable and implicitly dropped, with no separate SUBSCRIBE_DROP required. -A subscriber that requested the latest group learns the resolved sequence here. +A subscriber with no explicit floor learns the age-resolved sequence here. ## SUBSCRIBE_END {#subscribe-end} A SUBSCRIBE_END message is sent by the publisher to signal that no group at or after a given sequence will be produced. @@ -1138,6 +1138,7 @@ The `Message Length` describes the payload size on the wire. # Appendix A: Changelog ## moq-lite-06 +- Made an absent `Group Start` publisher-selected with an implicit floor of group 0; `Subscriber Max Latency` determines the starting group. - Moved the Qmux-over-WebSocket binding details to draft-lcurley-qmux-websocket; the binding itself is unchanged. - Extended the SETUP `Path` parameter to carry the URI query: a client appends `?` and the query component after the path, matching moq-transport's PATH option. The credential a deployment puts in the query was previously unrepresentable on a binding with no request URI. - Allowed an empty SETUP `Path` parameter, equivalent to omitting it; both request the server's default path. Previously an empty value was a protocol violation, which made the two ways of asking for the default disagree. diff --git a/js/json/src/snapshot/compression.test.ts b/js/json/src/snapshot/compression.test.ts index 235d42dd2bb..5a4ee012e5d 100644 --- a/js/json/src/snapshot/compression.test.ts +++ b/js/json/src/snapshot/compression.test.ts @@ -39,12 +39,13 @@ async function groupCount(track: Track.Subscriber): Promise { test("compressed snapshot per group round-trips", async () => { const track = new Track.Producer("test"); const producer = new Producer({ track, deltaRatio: 0, compression: true }); + const subscriber = track.subscribe(); producer.update({ a: 1 }); producer.update({ a: 2 }); producer.finish(); // Deltas off: one compressed snapshot per group, reconstructed in order. - expect(await drainCompressed(track.subscribe())).toEqual([{ a: 1 }, { a: 2 }]); + expect(await drainCompressed(subscriber)).toEqual([{ a: 1 }, { a: 2 }]); }); test("compressed live consumer sees each update in order", async () => { diff --git a/js/json/src/snapshot/snapshot.test.ts b/js/json/src/snapshot/snapshot.test.ts index f1b3e1d0e81..4a176973c48 100644 --- a/js/json/src/snapshot/snapshot.test.ts +++ b/js/json/src/snapshot/snapshot.test.ts @@ -13,7 +13,8 @@ async function drain(track: Track.Subscriber): Promise { } // Inspect the published layout via the public API: the frame count of each group, in order. -// The track must be finished first so group/frame reads terminate. +// The track must be finished first so group/frame reads terminate, and the subscriber has to +// exist before the first update: a fresh one starts at the live edge, not at group 0. async function structure(track: Track.Subscriber): Promise { const counts: number[] = []; for (;;) { @@ -30,24 +31,26 @@ async function structure(track: Track.Subscriber): Promise { test("deltas off: a snapshot group per change", async () => { const track = new Track.Producer("test"); const producer = new Producer({ track, deltaRatio: 0 }); + const subscriber = track.subscribe(); producer.update({ a: 1 }); producer.update({ a: 2 }); producer.finish(); // Two changes => two single-frame snapshot groups, reconstructed in order. - expect(await drain(track.subscribe())).toEqual([{ a: 1 }, { a: 2 }]); + expect(await drain(subscriber)).toEqual([{ a: 1 }, { a: 2 }]); }); test("deltaRatio 0 disables deltas, like off", async () => { const track = new Track.Producer("test"); const producer = new Producer({ track, deltaRatio: 0 }); + const subscriber = track.subscribe(); producer.update({ a: 1 }); producer.update({ a: 2 }); producer.finish(); // `0` is treated as off, not a degenerate "enabled" value that keeps the group open: each change // is its own single-frame snapshot group. - expect(await structure(track.subscribe())).toEqual([1, 1]); + expect(await structure(subscriber)).toEqual([1, 1]); }); test("live consumer sees each update", async () => { @@ -155,13 +158,14 @@ test("tight ratio rolls snapshots", async () => { // the deltas already written, so the delta that tips the group over budget still lands (a one-frame // overshoot): group 0 takes two deltas (14 bytes) before the fourth update rolls group 1. const producer = new Producer({ track, deltaRatio: 1 }); + const subscriber = track.subscribe(); producer.update({ a: 1 }); // snapshot, group 0 producer.update({ a: 2 }); // delta, group 0 (deltas = 7) producer.update({ a: 3 }); // delta, group 0 (deltas = 14, now over budget) producer.update({ a: 4 }); // budget already exceeded, rolls group 1 producer.finish(); - expect(await structure(track.subscribe())).toEqual([3, 1]); + expect(await structure(subscriber)).toEqual([3, 1]); }); test("deltas stay within ratio times snapshot", async () => { @@ -172,10 +176,11 @@ test("deltas stay within ratio times snapshot", async () => { // until they first exceed 56 (nine deltas = 63 bytes) and the next update rolls (a one-frame // overshoot past the 56-byte budget). const producer = new Producer({ track, deltaRatio: 8 }); + const subscriber = track.subscribe(); for (let n = 0; n <= 10; n++) producer.update({ n }); producer.finish(); - expect(await structure(track.subscribe())).toEqual([10, 1]); + expect(await structure(subscriber)).toEqual([10, 1]); }); test("array change is a wholesale delta", async () => { @@ -206,11 +211,12 @@ test("late joiner collapses a buffered backlog to the latest value", async () => test("frame cap rolls snapshot", async () => { const track = new Track.Producer("test"); const producer = new Producer({ track, deltaRatio: 1_000_000 }); + const subscriber = track.subscribe(); // First update is the snapshot; deltas fill the group until the frame cap forces a roll. for (let i = 0; i <= 256; i++) { producer.update({ n: i }); } producer.finish(); - expect(await structure(track.subscribe())).toEqual([256, 1]); + expect(await structure(subscriber)).toEqual([256, 1]); }); diff --git a/js/net/src/broadcast.ts b/js/net/src/broadcast.ts index 01b22f7b434..49e79bd8592 100644 --- a/js/net/src/broadcast.ts +++ b/js/net/src/broadcast.ts @@ -114,6 +114,10 @@ async function fetchGroup( options: track.FetchGroupOptions = {}, ): Promise { const subscriber = subscribe(state, name, { priority: options.priority }); + // FETCH names an exact cached group, so it must not inherit the live + // subscription cursor selected from max latency (zero selects the latest). + subscriber.startAt(sequence); + subscriber.endAt(sequence); try { for (;;) { const group = await subscriber.recvGroup(); diff --git a/js/net/src/integration.test.ts b/js/net/src/integration.test.ts index 6ffd726d5d3..0b79b7f414d 100644 --- a/js/net/src/integration.test.ts +++ b/js/net/src/integration.test.ts @@ -172,7 +172,7 @@ test("integration: lite applies initial and updated group bounds", async () => { const remote = client.consume(Path.from("test")); const subscriber = remote .track("video") - .subscribe({ startGroup: INITIAL_START_GROUP, endGroup: INITIAL_END_GROUP }); + .subscribe({ latencyMax: 1000, startGroup: INITIAL_START_GROUP, endGroup: INITIAL_END_GROUP }); try { expect((await subscriber.nextGroup())?.sequence).toBe(INITIAL_START_GROUP); expect((await subscriber.nextGroup())?.sequence).toBe(INITIAL_END_GROUP); diff --git a/js/net/src/internal.ts b/js/net/src/internal.ts index b83d936260f..6ff621f3733 100644 --- a/js/net/src/internal.ts +++ b/js/net/src/internal.ts @@ -5,7 +5,7 @@ * * @module */ -import type { Producer, Request } from "./track.ts"; +import type { Producer, Request, Subscriber } from "./track.ts"; /** The next group or datagram sequence shared by dynamic producers of one broadcast track. */ export interface TrackSequence { @@ -29,8 +29,13 @@ export interface TrackRequestOptions { export const hooks: { /** Mint a track {@link Request}; assigned by `track.ts`. */ makeRequest: (options: TrackRequestOptions) => Request; + /** Re-resolve a subscriber's publisher-selected start, preserving an announced floor. */ + positionSubscriber: (subscriber: Subscriber, announcedStart?: number) => void; } = { makeRequest: () => { throw new Error("track.ts not loaded"); }, + positionSubscriber: () => { + throw new Error("track.ts not loaded"); + }, }; diff --git a/js/net/src/lite/publisher.test.ts b/js/net/src/lite/publisher.test.ts index 9f62d8ecdd5..c06b87422a4 100644 --- a/js/net/src/lite/publisher.test.ts +++ b/js/net/src/lite/publisher.test.ts @@ -358,13 +358,22 @@ test("lite draft-05: the fetch response ranks the publisher's own writes", async // Opens a served subscription and returns the machinery to write groups and observe // which of them the publisher put on the wire (each group gets its own uni stream). -async function servedSubscription(options: { startGroup?: number } = {}) { +async function servedSubscription( + options: { startGroup?: number; maxLatency?: number; version?: Version; initialGroups?: number[] } = {}, +) { + const version = options.version ?? Version.DRAFT_05; const pair = createMockTransportPair(ALPN_05); - const publisher = new Publisher(pair.server, Version.DRAFT_05, randomOrigin()); + const publisher = new Publisher(pair.server, version, randomOrigin()); const broadcast = new BroadcastProducer(); const track = broadcast.createTrack("video"); publisher.publish(Path.from("test"), broadcast); + for (const sequence of options.initialGroups ?? []) { + const group = new GroupProducer(sequence); + group.writeString("cached"); + group.close(); + track.writeGroup(group); + } const client = await Stream.open(pair.client); const server = await Stream.accept(pair.server); @@ -375,6 +384,7 @@ async function servedSubscription(options: { startGroup?: number } = {}) { broadcast: Path.from("test"), track: "video", priority: 0, + maxLatency: options.maxLatency, startGroup: options.startGroup, }); void publisher.runSubscribe(msg, server); @@ -383,6 +393,19 @@ async function servedSubscription(options: { startGroup?: number } = {}) { return { client, + async update(options: { maxLatency?: number; startGroup?: number; endGroup?: number }) { + await new SubscribeUpdate({ priority: 0, ...options }).encode(client.writer, version); + for (;;) { + const current = track.subscription.peek(); + if ( + current?.latencyMax === (options.maxLatency ?? 0) && + current.startGroup === options.startGroup && + current.endGroup === options.endGroup + ) + return; + await track.subscription.changed(); + } + }, serve(sequence: number) { const group = new GroupProducer(sequence); group.writeString("hello"); @@ -405,11 +428,32 @@ async function servedSubscription(options: { startGroup?: number } = {}) { }; } +test("every lite version resolves an omitted start from the zero max-latency budget", async () => { + for (const version of Object.values(Version)) { + const sub = await servedSubscription({ version, initialGroups: [0, 1] }); + try { + expect(await sub.servedSequence()).toBe(1); + } finally { + sub.close(); + } + } +}); + +test("lite draft-05: an update re-resolves an absent start from max latency", async () => { + const sub = await servedSubscription({ startGroup: 10, initialGroups: [0, 1] }); + try { + await sub.update({ maxLatency: 0 }); + expect(await sub.servedSequence()).toBe(1); + } finally { + sub.close(); + } +}); + // A relay can ingest back-to-back groups micro-reordered (the upstream leg sends // newest-first). The older group is cached and in demand, so serving must still // deliver it; a sequence cursor would skip it permanently. test("lite draft-05: a late-arriving older group is still served", async () => { - const sub = await servedSubscription({ startGroup: 1 }); + const sub = await servedSubscription({ startGroup: 1, maxLatency: 1 }); try { // Serve one at a time so arrival order at the publisher is the order given. sub.serve(1); @@ -439,9 +483,11 @@ test("lite draft-05: a straggler below the announced start group is not served", if (!("start" in resp)) throw new Error("expected SUBSCRIBE_START"); expect(resp.start.group).toBe(2); - // A straggler below the announced start never reaches the wire: the next - // stream the publisher opens is group 3's. + // Re-resolving an update with a cap below the announced start must not + // lower the promise already sent to the peer. + await sub.update({ maxLatency: 60_000, endGroup: 1 }); sub.serve(1); + await sub.update({ maxLatency: 0 }); sub.serve(3); expect(await sub.servedSequence()).toBe(3); } finally { diff --git a/js/net/src/lite/publisher.ts b/js/net/src/lite/publisher.ts index ae24272cdb0..8adbb0a6fd7 100644 --- a/js/net/src/lite/publisher.ts +++ b/js/net/src/lite/publisher.ts @@ -2,6 +2,7 @@ import { type Dispose, Signal } from "@moq/signals"; import type * as broadcast from "../broadcast.ts"; import { error, reason } from "../error.ts"; import type * as group from "../group.ts"; +import { hooks } from "../internal.ts"; import type { Origin } from "../origin.ts"; import * as Path from "../path.ts"; import { type Stream, Writer } from "../stream.ts"; @@ -278,8 +279,6 @@ export class Publisher { startGroup: msg.startGroup, endGroup: msg.endGroup, }); - const startGroup = msg.startGroup ?? track.latest(); - if (startGroup !== undefined) track.startAt(startGroup); track.endAt(msg.endGroup); // The best-effort datagram loop, started once serving begins. It parks when the @@ -316,7 +315,8 @@ export class Publisher { console.debug(`publish ok: broadcast=${msg.broadcast} track=${track.name}`); - const serving = this.#runTrack(msg.id, msg.broadcast, track, stream.writer, timescale); + const range: { start?: number } = {}; + const serving = this.#runTrack(msg.id, msg.broadcast, track, stream.writer, timescale, range); // Serve datagrams concurrently with groups whenever the transport carries them // (the writer exists iff so). No group fallback: otherwise they simply aren't sent. @@ -332,6 +332,7 @@ export class Publisher { if (result instanceof SubscribeUpdate) { console.debug(`subscribe update: broadcast=${msg.broadcast} track=${track.name}`); + const previous = track.subscription.peek(); track.update({ priority: result.priority, ordered: result.ordered, @@ -339,7 +340,13 @@ export class Publisher { startGroup: result.startGroup, endGroup: result.endGroup, }); - if (result.startGroup !== undefined) track.startAt(result.startGroup); + if ( + previous?.latencyMax !== result.maxLatency || + previous.startGroup !== result.startGroup || + previous.endGroup !== result.endGroup + ) { + hooks.positionSubscriber(track, range.start); + } track.endAt(result.endGroup); } } @@ -408,7 +415,14 @@ export class Publisher { * * @internal */ - async #runTrack(sub: bigint, broadcast: Path.Valid, track: track.Subscriber, stream: Writer, timescale: Timescale) { + async #runTrack( + sub: bigint, + broadcast: Path.Valid, + track: track.Subscriber, + stream: Writer, + timescale: Timescale, + range: { start?: number }, + ) { // Lite-05+ resolves the range on the subscribe stream: SUBSCRIBE_START once the // first group is known, SUBSCRIBE_END when the track finishes. const emitRange = supportsTrackStream(this.version); @@ -453,6 +467,7 @@ export class Publisher { if (emitRange && !startSent) { startSent = true; + range.start = group.sequence; // SUBSCRIBE_START promises nothing below this sequence will be delivered. // Arrival-order serving could later surface a straggler below the first // group, so pin the floor to what was announced. diff --git a/js/net/src/track.test.ts b/js/net/src/track.test.ts index 2e73a62d050..071fa6429d0 100644 --- a/js/net/src/track.test.ts +++ b/js/net/src/track.test.ts @@ -169,6 +169,47 @@ test("multiple subscriber options aggregate like Rust", async () => { expect(await none).toBeUndefined(); }); +test("a publisher-selected start clears the aggregate explicit floor", () => { + const producer = new TrackProducer("test"); + producer.subscribe({ startGroup: 10 }); + producer.subscribe(); + + expect(producer.subscription.peek()?.startGroup).toBeUndefined(); +}); + +test("max latency resolves cached history while zero selects the live edge", async () => { + const replayBudget = 60_000; + const producer = new TrackProducer("test"); + producer.writeGroup(new GroupProducer(0)); + producer.writeGroup(new GroupProducer(1)); + + const live = producer.subscribe(); + expect((await live.recvGroup())?.sequence).toBe(1); + + const replay = producer.subscribe({ latencyMax: replayBudget }); + expect((await replay.recvGroup())?.sequence).toBe(0); + expect((await replay.recvGroup())?.sequence).toBe(1); + + const floored = producer.subscribe({ latencyMax: replayBudget, startGroup: 1 }); + expect((await floored.recvGroup())?.sequence).toBe(1); + + const bounded = new TrackProducer("bounded").accept({ latencyMax: 0 }); + bounded.writeGroup(new GroupProducer(0)); + bounded.writeGroup(new GroupProducer(1)); + expect((await bounded.subscribe({ latencyMax: 1000 }).recvGroup())?.sequence).toBe(1); +}); + +test("publisher latency repositions an on-demand subscriber before delivery", async () => { + const producer = new TrackProducer("test"); + producer.writeGroup(new GroupProducer(0)); + producer.writeGroup(new GroupProducer(1)); + + const subscriber = producer.subscribe({ latencyMax: 60_000 }); + producer.accept({ latencyMax: 0 }); + + expect((await subscriber.recvGroup())?.sequence).toBe(1); +}); + test("nextGroup skips late arrivals", async () => { const producer = new TrackProducer("test"); const track = producer.subscribe(); @@ -189,7 +230,7 @@ test("nextGroup skips late arrivals", async () => { test("nextGroup returns buffered groups in sequence", async () => { const producer = new TrackProducer("test"); - const track = producer.subscribe(); + const track = producer.subscribe({ latencyMax: 1 }); producer.writeGroup(new GroupProducer(3)); producer.writeGroup(new GroupProducer(5)); @@ -200,7 +241,7 @@ test("nextGroup returns buffered groups in sequence", async () => { test("local cursor bounds can skip, pause, and release buffered groups", async () => { const producer = new TrackProducer("test"); - const track = producer.subscribe(); + const track = producer.subscribe({ latencyMax: 1 }); for (let sequence = 0; sequence < 5; sequence++) producer.writeGroup(new GroupProducer(sequence)); @@ -223,7 +264,7 @@ test("local cursor bounds can skip, pause, and release buffered groups", async ( // deliver it; a sequence cursor would skip it permanently. test("recvGroup serves a late arrival after a newer group", async () => { const producer = new TrackProducer("test"); - const track = producer.subscribe(); + const track = producer.subscribe({ latencyMax: 1 }); producer.writeGroup(new GroupProducer(2)); expect((await track.recvGroup())?.sequence).toBe(2); @@ -242,7 +283,7 @@ test("recvGroup serves a late arrival after a newer group", async () => { // held, not dropped, and a raised cap re-offers them, even after a clean close. test("endAt parks recvGroup beyond the cap and a raised cap re-offers", async () => { const producer = new TrackProducer("test"); - const track = producer.subscribe(); + const track = producer.subscribe({ latencyMax: 1 }); for (let sequence = 0; sequence < 3; sequence++) producer.writeGroup(new GroupProducer(sequence)); @@ -268,7 +309,7 @@ test("endAt parks recvGroup beyond the cap and a raised cap re-offers", async () // a relay can ingest a burst micro-reordered (newest first). test("recvGroup serves in-range groups that arrive behind a capped one", async () => { const producer = new TrackProducer("test"); - const track = producer.subscribe(); + const track = producer.subscribe({ latencyMax: 1 }); track.endAt(1); @@ -373,7 +414,7 @@ test("closing the subscriber releases a recvGroup parked while the producer is l test("recvGroup after nextGroup still returns late arrivals", async () => { const producer = new TrackProducer("test"); - const track = producer.subscribe(); + const track = producer.subscribe({ latencyMax: 1 }); producer.writeGroup(new GroupProducer(5)); diff --git a/js/net/src/track.ts b/js/net/src/track.ts index 736554b624f..c25441bfd83 100644 --- a/js/net/src/track.ts +++ b/js/net/src/track.ts @@ -83,7 +83,13 @@ export interface Subscription { ordered?: boolean; /** Maximum age (milliseconds) of a non-latest group before it is skipped. Defaults to `0`. */ latencyMax?: number; - /** First group the publisher should deliver, or omit to start at the latest group. */ + /** + * Optional lower bound on the publisher-selected starting group. + * + * When omitted, the publisher chooses the start using {@link latencyMax} with + * an implicit floor of group 0. Supplying a value restricts that choice but + * does not request history by itself. + */ startGroup?: number; /** Last group the publisher should deliver (inclusive), or omit for no end. */ endGroup?: number; @@ -116,11 +122,12 @@ function combineSubscriptions(states: Iterable): Subscription | unde combined.ordered = (combined.ordered ?? false) && (subscription.ordered ?? false); combined.latencyMax = Math.max(combined.latencyMax ?? 0, subscription.latencyMax ?? 0); - if (subscription.startGroup !== undefined) { - combined.startGroup = - combined.startGroup === undefined - ? subscription.startGroup - : Math.min(combined.startGroup, subscription.startGroup); + // A floor only restricts. Any publisher-selected start clears the aggregate + // explicit floor; otherwise the loosest (lowest) floor wins. + 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) { @@ -237,6 +244,10 @@ export class Consumer { // wiring, unexported so it never appears in the published type declarations. class TrackState { groups = new Signal([]); + // Cache queue time for every mirrored group, including one already handed to + // the caller. This is the wall-clock approximation for subscriber max latency; + // the live edge is the highest retained sequence. + timeline = new Map(); /** Best-effort datagram channel, parallel to {@link groups}; an age-evicted send buffer per subscriber. */ datagrams = new Signal([]); latest?: number; @@ -244,6 +255,8 @@ class TrackState { update: Signal; /** Resolved once the producer commits the immutable properties. */ info = new Signal(undefined); + /** Recompute the subscriber start after immutable publisher properties resolve. */ + position?: () => void; constructor(subscription?: Subscription) { this.update = new Signal(subscription === undefined ? undefined : subscriptionDefaults(subscription)); @@ -369,7 +382,10 @@ export class Producer { const resolved = infoDefaults(info); this.#state.info.set(resolved); // Propagate to any sink handed out before accept (the on-demand path). - for (const sink of this.#sinks) sink.info.set(resolved); + for (const sink of this.#sinks) { + sink.info.set(resolved); + sink.position?.(); + } return this; } @@ -459,6 +475,7 @@ export class Producer { #mirror(entry: CachedGroup, sink: TrackState): void { const dst = entry.group.mirror(); entry.mirrors.set(sink, dst); + sink.timeline.set(dst.sequence, { group: dst, time: entry.time }); sink.latest = Math.max(sink.latest ?? 0, dst.sequence); sink.groups.mutate((groups) => { groups.push(dst); @@ -473,6 +490,7 @@ export class Producer { const i = groups.indexOf(mirror); if (i >= 0) groups.splice(i, 1); }); + if (sink.timeline.get(mirror.sequence)?.group === mirror) sink.timeline.delete(mirror.sequence); mirror.close(); } entry.mirrors.clear(); @@ -652,14 +670,46 @@ export class Subscriber { #state: TrackState; #nextSequence = 0; #cursor = new Signal<{ start: number; end?: number }>({ start: 0 }); + #startPinned = false; private constructor(name: string, state: TrackState) { this.name = name; this.#state = state; + this.#state.position = () => this.#position(); + this.#position(); + } + + // Resolve the publisher-selected cursor from the implicit or explicit floor + // and max latency. + #subscriptionStart(): number { + const subscription = this.#state.update.peek(); + const floor = subscription?.startGroup ?? 0; + const end = subscription?.endGroup; + const candidates = [...this.#state.timeline.values()] + .filter((entry) => !(entry.group.closed.peek() instanceof Error)) + .filter((entry) => end === undefined || entry.group.sequence <= end) + .sort((a, b) => a.group.sequence - b.group.sequence); + const latest = candidates.at(-1); + if (!latest || latest.group.sequence < floor) return floor; + + const requested = subscription?.latencyMax ?? 0; + const retained = this.#state.info.peek()?.latencyMax; + const budget = retained === undefined ? requested : Math.min(requested, retained); + for (const candidate of candidates) { + if (candidate.group.sequence < floor) continue; + if (candidate.group.sequence === latest.group.sequence) return candidate.group.sequence; + if (budget > 0 && latest.time - candidate.time <= budget) return candidate.group.sequence; + } + return floor; + } + + #position(announcedStart = 0): void { + this.#cursor.update((cursor) => ({ ...cursor, start: Math.max(this.#subscriptionStart(), announcedStart) })); } static { makeSubscriber = (name, state) => new Subscriber(name, state); + hooks.positionSubscriber = (subscriber, announcedStart) => subscriber.#position(announcedStart); } /** @@ -690,6 +740,7 @@ export class Subscriber { /** Start this subscriber's local read cursor at `sequence`, without changing its wire request. */ startAt(sequence: number): void { + this.#startPinned = true; this.#cursor.update((cursor) => ({ ...cursor, start: sequence })); } @@ -713,6 +764,7 @@ export class Subscriber { for (const group of groups) group.close(abort); groups.length = 0; }); + this.#state.timeline.clear(); } /** @@ -731,13 +783,17 @@ export class Subscriber { for (;;) { const groups = this.#state.groups.peek(); const { start, end } = this.#cursor.peek(); - while (groups.length > 0 && groups[0].sequence < start) groups.shift()?.close(); + if (this.#startPinned) { + while (groups.length > 0 && groups[0].sequence < start) groups.shift()?.close(); + } - // The buffer is sequence-sorted, so an in-range group that arrives behind a - // beyond-cap one sorts in front of it and is never blocked by it. - const group = groups[0]; + // Before SUBSCRIBE_START pins the resolved floor, keep older cached groups + // available in case a SUBSCRIBE_UPDATE widens the latency budget or removes + // an explicit floor. Once pinned, the loop above permanently rejects them. + const index = this.#startPinned ? 0 : groups.findIndex((candidate) => candidate.sequence >= start); + const group = index >= 0 ? groups[index] : undefined; if (group && (end === undefined || group.sequence <= end)) { - groups.shift(); + groups.splice(index, 1); return group; } diff --git a/js/watch/src/audio/decoder.ts b/js/watch/src/audio/decoder.ts index 6266bc264cd..26679279475 100644 --- a/js/watch/src/audio/decoder.ts +++ b/js/watch/src/audio/decoder.ts @@ -5,14 +5,13 @@ import type * as Moq from "@moq/net"; import { Time } from "@moq/net"; import { Effect, type Getter, getter, type Inputs, type Readonlys, readonlys, Signal } from "@moq/signals"; import { base64ToBytes } from "../base64"; - +import { subscribe } from "../subscription"; import { type Bound, latencyBounds, type Sync } from "../sync"; import { type AudioBuffer, createAudioBuffer } from "./buffer"; import { Handover } from "./handover"; // Compiled and inlined as a blob URL via vite-plugin-worklet. import RenderWorklet from "./render-worklet.ts?worklet"; import type { Source } from "./source"; -import { subscribe } from "./subscription"; import { type DecodedSpan, Terminal } from "./terminal"; import { unlockOnGesture } from "./unlock"; import { Warmup } from "./warmup"; @@ -267,8 +266,14 @@ export class Decoder { this.#handover.opened(); // The Sync ceiling is the maximum age of a non-latest group before both the network and - // container consumers skip it. Omitting startGroup keeps a new subscription at the live edge. - const sub = subscribe(effect, { broadcast: active, track, maxLatency: this.sync.out.maxBuffer }); + // container consumers skip it. With startGroup absent, the publisher uses this ceiling + // to choose a start no lower than the implicit floor of group 0. + const sub = subscribe(effect, { + broadcast: active, + track, + priority: Catalog.PRIORITY.audio, + maxLatency: this.sync.out.maxBuffer, + }); if (config.container.kind === "cmaf") { this.#runCmafDecoder(effect, sub, config); diff --git a/js/watch/src/audio/subscription.test.ts b/js/watch/src/audio/subscription.test.ts index 3cb575978c1..293c7083e5e 100644 --- a/js/watch/src/audio/subscription.test.ts +++ b/js/watch/src/audio/subscription.test.ts @@ -2,7 +2,7 @@ import { expect, test } from "bun:test"; import * as Catalog from "@moq/hang/catalog"; import { Broadcast, Time } from "@moq/net"; import { Effect, Signal } from "@moq/signals"; -import { subscribe } from "./subscription"; +import { subscribe } from "../subscription"; const settle = () => new Promise((resolve) => setTimeout(resolve, 0)); @@ -12,7 +12,12 @@ test("audio subscription tracks the playback latency ceiling without restarting" const broadcast = source.consume(); const maxLatency = new Signal(Time.Milli(38.75)); const effect = new Effect(); - const subscriber = subscribe(effect, { broadcast, track: "audio", maxLatency }); + const subscriber = subscribe(effect, { + broadcast, + track: "audio", + priority: Catalog.PRIORITY.audio, + maxLatency, + }); expect(subscriber.subscription.peek()).toEqual({ priority: Catalog.PRIORITY.audio, diff --git a/js/watch/src/audio/subscription.ts b/js/watch/src/subscription.ts similarity index 78% rename from js/watch/src/audio/subscription.ts rename to js/watch/src/subscription.ts index df4781f2c2f..87e9c11e44c 100644 --- a/js/watch/src/audio/subscription.ts +++ b/js/watch/src/subscription.ts @@ -1,22 +1,22 @@ -import * as Catalog from "@moq/hang/catalog"; import type * as Moq from "@moq/net"; import type { Time } from "@moq/net"; import type { Effect, Getter } from "@moq/signals"; -/** Opens a live-edge audio subscription and keeps its expiry budget aligned with playback. @internal */ +/** Opens a media subscription and keeps its expiry budget aligned with playback. @internal */ export function subscribe( effect: Effect, { broadcast, track, + priority, maxLatency, }: { broadcast: Moq.Broadcast.Consumer; track: string; + priority: number; maxLatency: Getter; }, ): Moq.Track.Subscriber { - const priority = Catalog.PRIORITY.audio; let latencyMax = Math.ceil(maxLatency.peek()); const subscriber = broadcast.track(track).subscribe({ priority, latencyMax }); effect.cleanup(() => subscriber.close()); diff --git a/js/watch/src/video/decoder.ts b/js/watch/src/video/decoder.ts index 0dcf32702d1..a74e4b110eb 100644 --- a/js/watch/src/video/decoder.ts +++ b/js/watch/src/video/decoder.ts @@ -15,7 +15,7 @@ import { Signal, } from "@moq/signals"; import { base64ToBytes } from "../base64"; - +import { subscribe } from "../subscription"; import type { Sync } from "../sync"; import { type DecoderConfig, @@ -305,8 +305,15 @@ class DecoderTrack { } #run(effect: Effect): void { - const sub = this.broadcast.track(this.track).subscribe({ priority: Catalog.PRIORITY.video }); - effect.cleanup(() => sub.close()); + // The Sync ceiling is also the network's maximum useful group age. With + // startGroup absent, the publisher chooses the live edge for zero and may + // choose retained history for a larger budget. + const sub = subscribe(effect, { + broadcast: this.broadcast, + track: this.track, + priority: Catalog.PRIORITY.video, + maxLatency: this.sync.out.maxBuffer, + }); const decoder = new VideoDecoder({ output: async (frame: VideoFrame) => { diff --git a/rs/moq-audio/src/decode/consumer.rs b/rs/moq-audio/src/decode/consumer.rs index 661fc395ebd..6a5a4f52360 100644 --- a/rs/moq-audio/src/decode/consumer.rs +++ b/rs/moq-audio/src/decode/consumer.rs @@ -61,10 +61,14 @@ impl Consumer { }; let name = name.into(); - let track = broadcast - .track(&name)? - .subscribe(moq_net::track::Subscription::default().with_priority(hang::catalog::PRIORITY.audio)) - .await?; + // The budget has to ride on the subscription, not just the container: it is what + // picks the join point, so a consumer that only sets it downstream starts live. + let mut subscription = + moq_net::track::Subscription::default().with_priority(hang::catalog::PRIORITY.audio); + if let Some(latency) = config.latency_max { + subscription = subscription.with_latency_max(latency); + } + let track = broadcast.track(&name)?.subscribe(subscription).await?; // The catalog says how the track is framed, and it is not always the legacy // wire: `moq import fmp4` publishes CMAF. Reading a moof+mdat fragment as a // varint timestamp plus a payload decodes to garbage rather than failing. diff --git a/rs/moq-audio/tests/roundtrip.rs b/rs/moq-audio/tests/roundtrip.rs index c362c1443ad..30da12a89fa 100644 --- a/rs/moq-audio/tests/roundtrip.rs +++ b/rs/moq-audio/tests/roundtrip.rs @@ -65,6 +65,9 @@ async fn opus_round_trip_48k_stereo() { let cfg = snapshot.audio.renditions.get("audio").expect("audio rendition"); let mut config = decode::Config::default(); config.format = Format::F32; + // Every chunk is already published, so the join point needs a budget wide enough to + // cover them; without one this subscribes at the live edge and decodes only the last. + config.latency_max = Some(Duration::from_millis(500)); let mut consumer = decode::Consumer::new(&broadcast_consumer, cfg, "audio", config) .await .unwrap(); diff --git a/rs/moq-net/src/lite/publisher.rs b/rs/moq-net/src/lite/publisher.rs index a7b0527a102..540daedfb30 100644 --- a/rs/moq-net/src/lite/publisher.rs +++ b/rs/moq-net/src/lite/publisher.rs @@ -1043,7 +1043,6 @@ impl Publisher { // run_track serves groups and best-effort datagrams off the one subscriber. sub.run_track( track, - subscribe.start_group, subscribe.end_group, &mut stream.reader, &mut stream.writer, @@ -1988,7 +1987,6 @@ impl Subscription { async fn run_track( mut self, mut track: track::Subscriber, - start_group: Option, initial_end_group: Option, reader: &mut crate::coding::Reader, writer: &mut Writer, @@ -1996,11 +1994,6 @@ impl Subscription { ) -> Result<(), Error> { let mut tasks: FuturesUnordered> = FuturesUnordered::new(); - // Start the consumer at the specified sequence, otherwise start at the latest group. - if let Some(start_group) = start_group.or_else(|| track.latest()) { - track.start_at(start_group); - } - // Apply the initial cap from the original Subscribe. Subsequent updates // flow through the SubscribeUpdate select arm below. track.end_at(initial_end_group); @@ -2010,6 +2003,7 @@ impl Subscription { // exclusive final sequence (which may be ahead of the live edge). let emit_range = self.version.has_track_stream(); let mut start_sent = false; + let mut announced_start = None; let mut end_sent = false; // Serve datagrams off this same subscriber, but only on lite-05 over a datagram-capable @@ -2058,6 +2052,7 @@ impl Subscription { Recv::Group(group) => { if emit_range && !start_sent { start_sent = true; + announced_start = Some(group.sequence); // SUBSCRIBE_OK promises nothing below this sequence will be // delivered. Arrival-order serving could later surface a // straggler below the first group, so pin the floor to what @@ -2101,16 +2096,24 @@ impl Subscription { } // Feed the full update into the model subscriber so the producer's // aggregate reflects it (and a relay re-forwards it upstream). - let _ = track.update(crate::track::Subscription { + let previous = track.subscription(); + let subscription = crate::track::Subscription { priority: upd.priority, ordered: upd.ordered, latency_max: upd.max_latency, group_start: upd.start_group, group_end: upd.end_group, ..Default::default() - }); - if let Some(start_group) = upd.start_group { - track.start_at(start_group); + }; + let reposition = previous.latency_max != subscription.latency_max + || previous.group_start != subscription.group_start + || previous.group_end != subscription.group_end; + let _ = track.update(subscription); + if reposition { + track.reposition(); + } + if let Some(start_group) = announced_start { + track.start_at_least(start_group); } track.end_at(upd.end_group); } diff --git a/rs/moq-net/src/model/resume.rs b/rs/moq-net/src/model/resume.rs index c274c035174..4262da63c9d 100644 --- a/rs/moq-net/src/model/resume.rs +++ b/rs/moq-net/src/model/resume.rs @@ -80,6 +80,16 @@ fn slice(prefs: &Subscription, start: Option, end: Option) -> Subscrip sub } +/// Resolve the logical live edge once across the segments for a zero-latency +/// join. Positive budgets remain per-segment in this backport because the +/// underlying caches do not expose one shared presentation timeline. +fn logical_join(state: &ResumeState, prefs: &Subscription) -> Option { + if !prefs.latency_max.is_zero() || prefs.group_end.is_some() { + return None; + } + Some(state.latest().unwrap_or(0).max(prefs.group_start.unwrap_or(0))) +} + /// How many segments a logical track keeps before pruning terminal ones from the /// front: the live segment plus a couple of predecessors still draining to slow /// readers. Without a bound, every failover leaves one dead segment (pinning a @@ -408,7 +418,8 @@ impl Consumer { /// /// The subscription's preferences are forwarded to each underlying track /// intersected with its segment bounds, so each serving session sees plain - /// demand for its own range. Demand registers as the subscriber is polled. + /// demand for its own range. Existing ready segments register immediately; + /// pending and future segments register as the subscriber is polled. /// Pass `None` for [`Subscription::default`]. #[cfg(test)] pub fn subscribe(&self, subscription: impl Into>) -> Subscriber { @@ -420,7 +431,8 @@ impl Consumer { /// [`track::SubscriberControl`]-style handle can update it. pub(crate) fn subscribe_shared(&self, prefs: kio::Producer) -> Subscriber { let last_prefs = prefs.read().clone(); - Subscriber { + let join_sequence = logical_join(&self.state.read(), &last_prefs); + let mut subscriber = Subscriber { state: self.state.clone(), prefs, last_prefs, @@ -433,7 +445,22 @@ impl Consumer { min_sequence: 0, end_sequence: None, reading: None, + initializing: true, + join_sequence, + }; + + // Resolve every already-ready segment now, so the publisher selects the + // starting position when the logical subscription opens rather than when + // its first group read happens. A segment still waiting for TRACK_INFO stays + // pending and is activated by the normal poll path later. + let waiter = kio::Waiter::noop(); + subscriber.sync(&waiter); + for segment in &mut subscriber.segments { + let _ = Subscriber::poll_activate(segment, &subscriber.last_prefs, subscriber.min_sequence, &waiter); } + subscriber.initializing = false; + + subscriber } /// Poll for the track's [`track::Info`], resolved from the first segment. @@ -612,6 +639,12 @@ struct SegmentSub { id: u64, start: Option, end: Option, + /// The segment appeared after this logical subscription opened, so it + /// continues at its splice floor instead of selecting a fresh live edge. + continuation: bool, + /// Logical join point shared by segments that existed when the subscription + /// opened. `None` for continuations and non-zero latency budgets. + join_sequence: Option, sub: SubState, /// Received groups held back by the subscriber's [`Subscriber::end_at`] cap, /// re-offered once the cap rises (arrival-order reads consume the underlying @@ -625,6 +658,14 @@ struct SegmentSub { } impl SegmentSub { + /// Combine the segment boundary, caller cursor, and initial logical join. + fn floor(&self, min_sequence: u64) -> u64 { + self.start + .unwrap_or(0) + .max(min_sequence) + .max(self.join_sequence.unwrap_or(0)) + } + /// Whether a pruned segment owes this reader nothing more, so its cursor can /// be dropped: an uncapped one was replaced before producing (its cursor holds /// nothing), and a capped one is kept until it drains through its cap and any @@ -685,6 +726,11 @@ pub struct Subscriber { /// The group currently being drained by [`Self::read_frame`]. reading: Option, + /// True only while the constructor snapshots the segments that already + /// existed when this logical subscription opened. + initializing: bool, + /// One publisher-selected join point across the segments present at open. + join_sequence: Option, } impl Subscriber { @@ -742,10 +788,24 @@ impl Subscriber { Poll::Ready(Err(_)) | Poll::Pending => break, } }; + let reposition = prefs.latency_max != self.last_prefs.latency_max + || prefs.group_start != self.last_prefs.group_start + || prefs.group_end != self.last_prefs.group_end; self.last_prefs = prefs; + if reposition { + self.join_sequence = logical_join(&self.state.read(), &self.last_prefs); + } for seg in &mut self.segments { + if reposition && !seg.continuation { + seg.join_sequence = self.join_sequence; + } + let floor = seg.floor(self.min_sequence); if let SubState::Active(sub) = &mut seg.sub { let _ = sub.update(slice(&self.last_prefs, seg.start, seg.end)); + if reposition { + sub.reposition(); + } + sub.start_at_least(floor); } } } @@ -811,12 +871,15 @@ impl Subscriber { Some(existing) => { if existing.end != segment.end { existing.end = segment.end; + let floor = existing.floor(self.min_sequence); if let SubState::Active(sub) = &mut existing.sub { // Shrink the demand so the session can cap upstream. The // read bounds stay on this subscriber (see `poll_recv_group`): // an inner `end_at` would park boundary-crossing groups in the // inner cursor, hiding the segment's completion. let _ = sub.update(slice(&self.last_prefs, segment.start, segment.end)); + sub.reposition(); + sub.start_at_least(floor); } // A still-pending subscription picks the moved boundary up // when it activates (see `poll_activate`). @@ -830,6 +893,8 @@ impl Subscriber { id: segment.id, start: segment.start, end: segment.end, + continuation: !self.initializing, + join_sequence: if self.initializing { self.join_sequence } else { None }, sub: SubState::Pending(sub), parked: BTreeMap::new(), pruned: false, @@ -843,7 +908,11 @@ impl Subscriber { /// `Active` or `Done`; a rejected or closed track becomes `Done` (stall, not /// error). Never consumes groups, so terminal-state pollers can share it. fn poll_activate(seg: &mut SegmentSub, prefs: &Subscription, min_sequence: u64, waiter: &kio::Waiter) -> Poll<()> { + let floor = seg.floor(min_sequence); if let SubState::Pending(pending) = &mut seg.sub { + // Apply moved boundaries and preference updates before resolving: a + // plain subscription chooses its max-latency start as it resolves. + let _ = pending.update(slice(prefs, seg.start, seg.end)); match pending.poll_ok(waiter) { Poll::Ready(Ok(mut sub)) => { // Enforce the floor on the read cursor, and re-slice demand in @@ -851,8 +920,11 @@ impl Subscriber { // 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.start.unwrap_or(0).max(min_sequence)); - let _ = sub.update(slice(prefs, seg.start, seg.end)); + if seg.continuation { + sub.start_at(floor); + } else { + sub.start_at_least(floor); + } seg.sub = SubState::Active(sub); } // The underlying track was rejected or closed: stall, not error. @@ -1162,6 +1234,41 @@ impl Subscriber { } } + /// Re-resolve every active segment's publisher-selected start from the + /// current preferences and retained groups. + pub(crate) fn reposition(&mut self) { + self.last_prefs = self.prefs.read().clone(); + self.join_sequence = logical_join(&self.state.read(), &self.last_prefs); + for seg in &mut self.segments { + if !seg.continuation { + seg.join_sequence = self.join_sequence; + } + let floor = seg.floor(self.min_sequence); + match &mut seg.sub { + SubState::Pending(pending) => { + let _ = pending.update(slice(&self.last_prefs, seg.start, seg.end)); + } + SubState::Active(sub) => { + let _ = sub.update(slice(&self.last_prefs, seg.start, seg.end)); + sub.reposition(); + sub.start_at_least(floor); + } + SubState::Done(_) => {} + } + } + } + + /// Raise the logical and active segment floors without lowering a later + /// resolved start. + pub(crate) fn start_at_least(&mut self, sequence: u64) { + self.min_sequence = self.min_sequence.max(sequence); + for seg in &mut self.segments { + if let SubState::Active(sub) = &mut seg.sub { + sub.start_at_least(seg.start.unwrap_or(0).max(sequence)); + } + } + } + /// Cap the subscriber at the specified sequence (inclusive), or remove the cap. /// /// Enforced on this subscriber's reads (see [`Self::poll_recv_group`]), never @@ -1201,6 +1308,7 @@ mod test { use crate::{Timestamp, broadcast}; use futures::FutureExt; use std::sync::Arc; + use std::time::Duration; fn track_pair(name: &str) -> (track::Producer, track::Consumer) { let producer = track::Producer::new(Arc::new(broadcast::Info::default()), name, None); @@ -1227,6 +1335,42 @@ mod test { assert!(sub.recv_group().now_or_never().is_none(), "should have blocked"); } + #[tokio::test] + async fn initial_segment_resolves_the_start_from_max_latency() { + tokio::time::pause(); + let (mut track, consumer) = track_pair("a"); + write_group(&mut track, 0, "a0"); + write_group(&mut track, 1, "a1"); + + let mut producer = Producer::new(); + producer.switch(&consumer, None).unwrap(); + + let mut live = producer.consume().subscribe(None); + assert_eq!(recv(&mut live), 1); + + let replay = Subscription::default().with_latency_max(Duration::from_secs(1)); + let mut replay = producer.consume().subscribe(replay); + assert_eq!(recv(&mut replay), 0); + assert_eq!(recv(&mut replay), 1); + } + + #[tokio::test] + async fn initial_zero_latency_join_uses_the_logical_live_edge() { + let (mut track_a, consumer_a) = track_pair("a"); + let (mut track_b, consumer_b) = track_pair("b"); + let mut producer = Producer::new(); + + producer.switch(&consumer_a, None).unwrap(); + write_group(&mut track_a, 0, "a0"); + write_group(&mut track_a, 1, "a1"); + producer.switch(&consumer_b, 2).unwrap(); + write_group(&mut track_b, 2, "b2"); + write_group(&mut track_b, 3, "b3"); + + let mut live = producer.consume().subscribe(None); + assert_eq!(recv(&mut live), 3); + } + /// A waker that counts its wakes, for asserting a pending poll left a live /// registration behind. struct CountWaker(std::sync::atomic::AtomicUsize); diff --git a/rs/moq-net/src/model/subscription.rs b/rs/moq-net/src/model/subscription.rs index be451e28ae9..13dd2ce3fc0 100644 --- a/rs/moq-net/src/model/subscription.rs +++ b/rs/moq-net/src/model/subscription.rs @@ -23,10 +23,12 @@ pub struct Subscription { /// cache. Receivers that buffer (e.g. a jitter buffer) enforce the same budget /// locally, and a group is skipped once either measure exceeds it. pub latency_max: Duration, - /// First group the publisher should deliver, or `None` to start at the latest group. + /// Optional lower bound on the publisher-selected starting group. /// - /// 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. + /// `None` lets the publisher choose using [`Self::latency_max`] with an implicit + /// floor of group 0. A supplied floor restricts that choice but does not request + /// history by itself. Any publisher-selected start clears the aggregate explicit + /// floor, 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). @@ -73,7 +75,7 @@ impl Subscription { self } - /// Set the first group to deliver, returning `self` for chaining. + /// Set the lowest group that may be delivered, returning `self` for chaining. pub fn with_group_start(mut self, group_start: impl Into>) -> Self { self.group_start = group_start.into(); self @@ -98,7 +100,7 @@ impl Subscription { // Sequence-first prioritization is enabled only when every subscriber wants it. ordered: self.ordered && combined.ordered, latency_max: self.latency_max.max(combined.latency_max), - group_start: min_some(self.group_start, combined.group_start), + group_start: min_floored(self.group_start, combined.group_start), group_end: max_unbounded(self.group_end, combined.group_end), }; @@ -119,6 +121,15 @@ pub(super) fn min_some(a: Option, b: Option) -> Option { } } +/// The lower of two optional floors, treating `None` as a publisher-selected +/// start with an implicit zero floor (and therefore absorbing). +fn min_floored(a: Option, b: Option) -> Option { + match (a, b) { + (Some(a), Some(b)) => Some(a.min(b)), + (None, _) | (_, None) => None, + } +} + fn max_unbounded(a: Option, b: Option) -> Option { match (a, b) { (Some(a), Some(b)) => Some(a.max(b)), @@ -160,14 +171,17 @@ mod tests { } #[test] - fn combined_group_start_uses_earliest_explicit_start() { - let live = Subscription::default().with_group_start(None); + fn combined_group_start_keeps_the_loosest_floor() { let catchup = Subscription::default().with_group_start(10); let older_catchup = Subscription::default().with_group_start(5); - let combined = combine(&[live, catchup, older_catchup]).unwrap(); + let combined = combine(&[catchup.clone(), older_catchup]).unwrap(); assert_eq!(combined.group_start, Some(5)); + + let publisher_selected = Subscription::default(); + let combined = combine(&[catchup, publisher_selected]).unwrap(); + assert_eq!(combined.group_start, None); } #[test] diff --git a/rs/moq-net/src/model/track.rs b/rs/moq-net/src/model/track.rs index 4486ccc6195..9a20a9b540d 100644 --- a/rs/moq-net/src/model/track.rs +++ b/rs/moq-net/src/model/track.rs @@ -226,6 +226,9 @@ pub(crate) struct TrackState { /// handle releases the bytes and the sample together. struct Slot { group: group::Producer, + // Queue time, kept separate from the coarse cache access stamp so a + // millisecond-scale subscriber latency remains precise. + inserted: web_async::time::Instant, // Incarnation stamp, echoed by this slot's arrival entry (if any). A re-served // sequence (an aborted group re-created by the publisher or re-fetched as @@ -271,6 +274,42 @@ impl TrackState { } } + /// Resolve a new subscriber's cursor from the publisher-selected start, its + /// implicit or explicit floor, and max latency. + fn subscription_start(&self, subscription: &Subscription) -> u64 { + let floor = subscription.group_start.unwrap_or(0); + let budget = self + .latency_bound() + .map_or(subscription.latency_max, |bound| subscription.latency_max.min(bound)); + let latest = self + .arrival + .iter() + .filter_map(|(sequence, stamp)| { + let slot = self.lookup.get(sequence)?; + (slot.stamp == *stamp && !slot.group.is_aborted()).then_some((*sequence, slot.inserted)) + }) + .filter(|(sequence, _)| subscription.group_end.is_none_or(|end| *sequence <= end)) + .max_by_key(|(sequence, _)| *sequence); + let Some((latest_sequence, latest_inserted)) = latest else { + return floor; + }; + self.arrival + .iter() + .filter_map(|(sequence, stamp)| { + let slot = self.lookup.get(sequence)?; + (slot.stamp == *stamp && !slot.group.is_aborted()).then_some((*sequence, slot.inserted)) + }) + .filter(|(sequence, inserted)| { + *sequence >= floor + && subscription.group_end.is_none_or(|end| *sequence <= end) + && (*sequence == latest_sequence + || (!budget.is_zero() && latest_inserted.saturating_duration_since(*inserted) <= budget)) + }) + .map(|(sequence, _)| sequence) + .min() + .unwrap_or(floor) + } + /// Find the next live group at or after `index` in arrival order. /// /// Returns the group and its absolute index so the consumer can advance past it. @@ -356,7 +395,6 @@ impl TrackState { // incarnation, delivered (if at all) at its own arrival position. continue; } - let mut consumer = slot.group.consume(); match consumer.poll_read_frame(waiter) { Poll::Ready(Ok(Some(frame))) => { @@ -642,6 +680,7 @@ impl TrackState { sequence, Slot { group: group.clone(), + inserted: web_async::time::Instant::now(), stamp, }, ); @@ -1184,7 +1223,10 @@ impl Producer { // requiring a live producer state. If the track already ended, the returned // 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 state = self.state.read(); + let info = state.info.clone().expect("producer always has info"); + let min_sequence = state.subscription_start(&preferences); + drop(state); let subscription = kio::Producer::new(preferences); register_subscription(self.state.read(), &subscription); @@ -1196,7 +1238,7 @@ impl Producer { subscription, index: 0, datagram_index: 0, - min_sequence: 0, + min_sequence, next_sequence: 0, end_sequence: None, parked: BTreeMap::new(), @@ -1893,6 +1935,7 @@ impl Subscribing { // Wait until the track info is available let info = ready!(state.poll(waiter, |state| state.poll_info())) .map_err(|e| e.abort.clone().unwrap_or(Error::Dropped))??; + let min_sequence = state.read().subscription_start(&self.subscription.read()); Poll::Ready(Ok(Subscriber { name: self.name.clone(), @@ -1902,7 +1945,7 @@ impl Subscribing { subscription: self.subscription.clone(), index: 0, datagram_index: 0, - min_sequence: 0, + min_sequence, next_sequence: 0, end_sequence: None, parked: BTreeMap::new(), @@ -2206,6 +2249,17 @@ struct PlainSubscriber { } impl PlainSubscriber { + /// Re-resolve the publisher-selected start from the current preferences and + /// retained groups. + fn reposition(&mut self) { + self.min_sequence = self.state.read().subscription_start(&self.subscription.read()); + } + + /// Raise the local floor without undoing a later publisher-selected start. + fn start_at_least(&mut self, sequence: u64) { + self.min_sequence = self.min_sequence.max(sequence); + } + // A helper to automatically apply Dropped if the state is closed without an error. fn poll(&self, waiter: &kio::Waiter, f: F) -> Poll> where @@ -2301,7 +2355,7 @@ impl PlainSubscriber { fn poll_read_frame(&mut self, waiter: &kio::Waiter) -> Poll>> { let lower = self.min_sequence.max(self.next_sequence); let Some((frame, found_index, sequence)) = - ready!(self.poll(waiter, |state| { state.poll_read_frame(self.index, lower, waiter) })?) + ready!(self.poll(waiter, |state| state.poll_read_frame(self.index, lower, waiter))?) else { return Poll::Ready(Ok(None)); }; @@ -2526,6 +2580,24 @@ impl Subscriber { } } + /// Re-resolve the publisher-selected start from this subscriber's current + /// preferences and retained groups. + pub(crate) fn reposition(&mut self) { + match &mut self.inner { + SubscriberKind::Plain(plain) => plain.reposition(), + SubscriberKind::Spliced(spliced) => spliced.reposition(), + } + } + + /// Raise the local floor without lowering an already resolved or announced + /// start. + pub(crate) fn start_at_least(&mut self, sequence: u64) { + match &mut self.inner { + SubscriberKind::Plain(plain) => plain.start_at_least(sequence), + SubscriberKind::Spliced(spliced) => spliced.start_at_least(sequence), + } + } + /// Cap this subscriber's read cursor at the given sequence (inclusive), or remove the /// cap entirely. /// @@ -2817,6 +2889,55 @@ mod test { .expect("track was closed") } + /// Helper: non-blocking group receive that must be ready with a group. + fn recv_group(subscriber: &mut Subscriber) -> group::Consumer { + subscriber + .recv_group() + .now_or_never() + .expect("group would have blocked") + .expect("would have errored") + .expect("track was closed") + } + + #[tokio::test] + async fn max_latency_resolves_cached_history_while_zero_selects_the_live_edge() { + tokio::time::pause(); + let mut producer = track_producer("test", None); + producer.create_group(group::Info { sequence: 0 }).unwrap(); + tokio::time::advance(Duration::from_millis(40)).await; + producer.create_group(group::Info { sequence: 1 }).unwrap(); + + let mut live = producer.subscribe(None); + assert_eq!(recv_group(&mut live).sequence, 1); + + let replay = Subscription::default().with_latency_max(Duration::from_millis(50)); + let mut replay = producer.subscribe(replay); + assert_eq!(recv_group(&mut replay).sequence, 0); + assert_eq!(recv_group(&mut replay).sequence, 1); + + let tight = Subscription::default().with_latency_max(Duration::from_millis(39)); + let mut tight = producer.subscribe(tight); + assert_eq!(recv_group(&mut tight).sequence, 1); + + let mut updated = producer.subscribe(Subscription::default().with_group_start(10)); + updated.update(Subscription::default()).unwrap(); + updated.reposition(); + assert_eq!(recv_group(&mut updated).sequence, 1); + + let floored = Subscription::default() + .with_latency_max(Duration::from_millis(50)) + .with_group_start(1); + let mut floored = producer.subscribe(floored); + assert_eq!(recv_group(&mut floored).sequence, 1); + + let mut bounded = track_producer("bounded", Info::default().with_latency_max(Duration::ZERO)); + bounded.create_group(group::Info { sequence: 0 }).unwrap(); + bounded.create_group(group::Info { sequence: 1 }).unwrap(); + let replay = Subscription::default().with_latency_max(Duration::from_secs(1)); + let mut bounded = bounded.subscribe(replay); + assert_eq!(recv_group(&mut bounded).sequence, 1); + } + #[tokio::test] async fn append_datagram_shares_group_sequence() { let mut producer = track_producer("test", None); @@ -5192,7 +5313,7 @@ mod test { producer.create_group(2u64.into()).unwrap().finish().unwrap(); producer.create_group(1u64.into()).unwrap().finish().unwrap(); - let mut subscriber = producer.subscribe(None); + let mut subscriber = producer.subscribe(Subscription::default().with_latency_max(Duration::from_millis(1))); assert_eq!(subscriber.assert_group().sequence, 0); assert_eq!(subscriber.assert_group().sequence, 2); assert_eq!( @@ -5313,7 +5434,7 @@ mod test { // The backfill serves by sequence, but never in arrival order. assert!(consumer.peek_group(1).is_some()); - let mut subscriber = producer.subscribe(None); + let mut subscriber = producer.subscribe(Subscription::default().with_latency_max(Duration::from_millis(1))); assert_eq!(subscriber.assert_group().sequence, 0); assert_eq!(subscriber.assert_group().sequence, 2); subscriber.assert_no_group(); @@ -5486,7 +5607,7 @@ mod test { assert!(consumer.peek_group(2).is_some(), "backfill is cached for later fetches"); // ...but an arrival-order subscriber only sees the live groups. - let mut subscriber = producer.subscribe(None); + let mut subscriber = producer.subscribe(Subscription::default().with_latency_max(Duration::from_millis(1))); assert_eq!(subscriber.assert_group().sequence, 5); assert_eq!(subscriber.assert_group().sequence, 6); subscriber.assert_no_group(); diff --git a/rs/moq-video/src/decode/consumer.rs b/rs/moq-video/src/decode/consumer.rs index bd753754752..bf454ea64bc 100644 --- a/rs/moq-video/src/decode/consumer.rs +++ b/rs/moq-video/src/decode/consumer.rs @@ -38,10 +38,14 @@ impl Consumer { let decoder = Sink::open(catalog, &config).await?; let name = name.into(); - let track = broadcast - .track(&name)? - .subscribe(moq_net::track::Subscription::default().with_priority(hang::catalog::PRIORITY.video)) - .await?; + // The budget has to ride on the subscription, not just the container: it is what + // picks the join point, so a consumer that only sets it downstream starts live. + let mut subscription = + moq_net::track::Subscription::default().with_priority(hang::catalog::PRIORITY.video); + if let Some(latency) = config.latency_max { + subscription = subscription.with_latency_max(latency); + } + let track = broadcast.track(&name)?.subscribe(subscription).await?; // The catalog says how the track is framed, and it is not always the legacy // wire: `moq import fmp4` publishes CMAF. Reading a moof+mdat fragment as a // varint timestamp plus a payload decodes to garbage rather than failing.