diff --git a/js/flate/src/snapshot/consumer.ts b/js/flate/src/snapshot/consumer.ts index 0a7a9ed281b..fe2258f2e99 100644 --- a/js/flate/src/snapshot/consumer.ts +++ b/js/flate/src/snapshot/consumer.ts @@ -5,6 +5,14 @@ import { Decoder as Flate } from "../codec.ts"; import { isDeflate } from "../compression.ts"; import type { Config as CodecConfig } from "./producer.ts"; +// Group errors that lose only that group, matching the JSON snapshot consumer. +const GAPS: Moq.StreamCode[] = [ + Moq.StreamCode.TooFarBehind, + Moq.StreamCode.Old, + Moq.StreamCode.Evicted, + Moq.StreamCode.GroupTooLarge, +]; + /** * Consumes an opaque value from a track, yielding each with the timestamp of its frame. * @@ -17,8 +25,8 @@ export class Consumer { #track: Moq.Track.Ordered; #decompress: boolean; - // The group the current window belongs to, so a boundary restarts it. - #group?: number; + // The group being read. + #group?: Moq.Group.Consumer; // The DEFLATE window for the current group, present while decompressing. A snapshot group is // normally one frame, but the window is per group either way. #flate?: Flate; @@ -44,9 +52,9 @@ export class Consumer { /** * Get the newest value, or `undefined` once the track ends. * - * Every group is a complete value, so any older group is already superseded. Raising the read - * floor to the newest sequence before each read does two things: it discards a backlog instead - * of decoding every superseded value in turn, and it abandons a group a newer one has + * Every group is a complete value, so any older group is already superseded. Jumping to the + * newest group the reader holds before each read does two things: it discards a backlog + * instead of decoding every superseded value in turn, and it abandons a group a newer one has * superseded rather than waiting out its close. A reader's latency therefore never grows with * the queue, and never depends on a stale group's FIN arriving. */ @@ -57,35 +65,53 @@ export class Consumer { async #read(skip: boolean): Promise | undefined> { for (;;) { if (skip) { - const latest = await this.#track.largest(); - if (latest !== undefined) this.#track.setGroups({ start: { included: latest.group } }); + // Jump to the newest group the reader already has; a newer one supersedes the rest. + // Taking groups, not the track's largest position, ignores datagrams (which share + // the sequence space) and stays inside any range the caller set on the reader. + // Mirrors the Rust consumer. + for (let group = this.#track.tryNextGroup(); group; group = this.#track.tryNextGroup()) { + this.#open(group); + } + } + + if (!this.#group) { + const group = await this.#track.nextGroup(); + if (!group) return undefined; + this.#open(group); } + const group = this.#group; + if (!group) continue; - let next: Awaited>; + let next: Moq.Group.Frame | undefined; try { - next = await this.#track.readFrame(); + next = await group.readFrame(); } catch (err) { - // Falling behind a group's eviction window is recoverable: the next group carries a - // complete value of its own, so resync there rather than surfacing a partial read. - // Anything else is the track's terminal error, which every later read would throw - // again; swallowing it would spin here instead of telling the caller the - // subscription died. - if (!(err instanceof Moq.Error.TooFarBehind)) throw err; + // Losing one group (reset, or fallen behind its eviction window) is recoverable: the + // next group carries a complete value of its own, so resync there rather than + // surfacing a partial read. Anything else is the track's terminal error, which every + // later read would throw again; swallowing it would spin here instead of telling the + // caller the subscription died. + if (!(err instanceof Moq.Error.Stream && GAPS.includes(err.code))) throw err; + this.#group = undefined; continue; } - if (!next) return undefined; - - // Each group is its own compressed stream, so a boundary starts a cold window. - if (next.group !== this.#group) { - this.#group = next.group; - this.#flate = this.#decompress ? new Flate() : undefined; + if (!next) { + this.#group = undefined; + continue; } return { value: this.#flate ? this.#flate.frame(next.payload) : next.payload, at: next.timestamp }; } } + // Each group is its own compressed stream, so a boundary starts a cold window. + #open(group: Moq.Group.Consumer): void { + this.#group?.close(); + this.#group = group; + this.#flate = this.#decompress ? new Flate() : undefined; + } + /** Iterate over every value in group order, as {@link next} yields them, until the track ends. */ async *[Symbol.asyncIterator](): AsyncIterator> { for (;;) { diff --git a/js/flate/src/snapshot/snapshot.test.ts b/js/flate/src/snapshot/snapshot.test.ts index 842c459a511..8e94be4bd12 100644 --- a/js/flate/src/snapshot/snapshot.test.ts +++ b/js/flate/src/snapshot/snapshot.test.ts @@ -159,6 +159,20 @@ test("latest lets a newer group preempt an open one", async () => { track.close(); }); +// Skipping to the head never widens the reader's range: a capped reader reads the newest value +// below its cap, and a datagram past every group does not strand it. +test("latest stays inside the reader's range", async () => { + const track = new Track.Producer("test"); + const producer = new Producer({ track }); + const subscriber = track.subscribe({ maxDelay: REPLAY_LATENCY }).withRange({ end: { excluded: 2 } }); + const consumer = new Consumer({ track: subscriber }); + + for (let n = 0; n < 4; n++) producer.update({ value: bytes(n) }); + track.appendDatagram(Time.Timestamp.now(), bytes(9)); + expect((await consumer.latest())?.value).toEqual(bytes(1)); + producer.finish(); +}); + test("an aborted track surfaces its error instead of spinning", async () => { // Every read after an abort throws the same terminal error, so swallowing it as if it were a // recoverable Lagged would loop forever on a rejected promise rather than telling the caller diff --git a/js/json/src/snapshot/consumer.ts b/js/json/src/snapshot/consumer.ts index a42a2a929ed..240508c214b 100644 --- a/js/json/src/snapshot/consumer.ts +++ b/js/json/src/snapshot/consumer.ts @@ -63,16 +63,16 @@ export class Consumer { async #read(skip: boolean): Promise | undefined> { for (;;) { if (skip) { - // A newer group supersedes everything the current one still holds: it restarts from a - // full snapshot, so switching mid-group loses nothing but stale state (mirrors the Rust - // consumer). Older groups only hold superseded state too, so raise the floor to the - // newest instead of replaying each one. - const latest = await this.#track.largest(); - if (this.#group !== undefined && latest !== undefined && latest.group > this.#group.sequence) { - this.#group.close(); - this.#group = undefined; + // Jump to the newest group the reader already has; a newer one supersedes the rest. + // Taking groups, not the track's largest position, ignores datagrams (which share + // the sequence space) and stays inside any range the caller set on the reader. + // Mirrors the Rust consumer. A newer group restarts from a full snapshot, so switching mid-group loses + // nothing but stale state. + for (let group = this.#track.tryNextGroup(); group; group = this.#track.tryNextGroup()) { + this.#group?.close(); + this.#group = group; + this.#framesRead = 0; } - if (!this.#group && latest !== undefined) this.#track.setGroups({ start: { included: latest.group } }); } if (!this.#group) { diff --git a/js/json/src/snapshot/snapshot.test.ts b/js/json/src/snapshot/snapshot.test.ts index 8de63fd99a8..cbe6ba971e7 100644 --- a/js/json/src/snapshot/snapshot.test.ts +++ b/js/json/src/snapshot/snapshot.test.ts @@ -149,6 +149,20 @@ test("latest abandons a held group when a newer snapshot group rolls", async () expect(await consumer.latest()).toBeUndefined(); }); +// Skipping to the head never widens the reader's range: a capped reader reads the newest state +// below its cap, and a datagram past every group does not strand it. +test("latest stays inside the reader's range", async () => { + const track = new Track.Producer("test"); + const producer = new Producer({ track, deltas: false }); + const subscriber = track.subscribe({ maxDelay: REPLAY_LATENCY }).withRange({ end: { excluded: 2 } }); + const consumer = new Consumer({ track: subscriber }); + + for (let n = 0; n < 4; n++) producer.update({ value: { a: n } }); + track.appendDatagram(Time.Timestamp.now(), new Uint8Array([0])); + expect((await consumer.latest())?.value).toEqual({ a: 1 }); + producer.finish(); +}); + // `next()` finishes the held group before the newer one, so a playhead sees every state. test("next reads a held group out before a newer snapshot group", async () => { const track = new Track.Producer("test"); diff --git a/js/json/src/window/window.test.ts b/js/json/src/window/window.test.ts index d7ce680bb3e..b5a08fb9c39 100644 --- a/js/json/src/window/window.test.ts +++ b/js/json/src/window/window.test.ts @@ -371,7 +371,7 @@ test("a lagging consumer is told what it missed", async () => { producer.push({ value: { n } }); producer.pop(1); } - subscriber.setGroups({ start: { included: (await subscriber.largest())?.group ?? 0 } }); + subscriber.withRange({ start: { included: (await subscriber.largest())?.group ?? 0 } }); const events = await live.finish(); const skipped = events.flatMap((e) => ("skip" in e ? span(e.skip) : [])); @@ -424,7 +424,7 @@ test("a fresh consumer adopts the current offset", async () => { producer.pop(3); const subscriber = track.subscribe(); - subscriber.setGroups({ start: { included: (await subscriber.largest())?.group ?? 0 } }); + subscriber.withRange({ start: { included: (await subscriber.largest())?.group ?? 0 } }); const consumer = new Consumer({ track: subscriber }); producer.finish(); const events: Event[] = []; @@ -594,7 +594,7 @@ test("events carry their frame's timestamp, and a header's restated records get producer.cut(); producer.push({ value: { n: 3 }, at: at(400) }); producer.finish(); - late.setGroups({ start: { included: 1 } }); + late.withRange({ start: { included: 1 } }); const events: Timed>[] = []; for await (const event of new Consumer({ track: late })) events.push(event); expect(events.map((event) => event.value)).toEqual([ diff --git a/js/net/bench/track.ts b/js/net/bench/track.ts index 63338262c55..2a2e00adbc2 100644 --- a/js/net/bench/track.ts +++ b/js/net/bench/track.ts @@ -2,9 +2,9 @@ import { Milli } from "@moq/clock"; import { type Consumer as GroupConsumer, Producer as GroupProducer } from "../src/group.ts"; -import { hooks } from "../src/internal.ts"; import { Timescale, Timestamp } from "../src/time.ts"; import { Producer, type Subscriber } from "../src/track.ts"; +import { untilGivenUp } from "../src/util/given_up.ts"; const retainedCounts = [25, 100, 400, 1500]; const subscriberCounts = [1, 4, 16]; @@ -82,10 +82,10 @@ async function measure( for (const consumer of received) { if (hold.operation === "read") reads.push(consumer.readFrame()); else { - // The guard a publisher holds while a group stream waits for credit. + // The watch a publisher holds while a group stream waits for credit. const opening = Promise.withResolvers(); opened.push(opening.resolve); - reads.push(hooks.guardGroup(consumer, () => opening.promise)); + reads.push(untilGivenUp(consumer, () => opening.promise)); } } } diff --git a/js/net/src/flate/group.test.ts b/js/net/src/flate/group.test.ts index 67f0e3ffab9..59dd9d40cb0 100644 --- a/js/net/src/flate/group.test.ts +++ b/js/net/src/flate/group.test.ts @@ -21,10 +21,9 @@ test("synchronous writers store slices; plain readers share one charged inflated expect(stored).toBeLessThan(payload.length); const inflating = spyOn(Decoder.prototype, "frame"); try { - const slice = await hooks.readGroupFrame(raw, undefined, true); + const slice = await hooks.readGroupFrame(raw, true); expect(slice?.inflated).toBe(payload.length); expect(inflating).toHaveBeenCalledTimes(0); - slice?.complete(); const a = await first.readFrame(); const b = await second.readFrame(); expect(a?.payload).toBe(b?.payload); @@ -46,9 +45,8 @@ test("received slices are forwarded byte-for-byte and exact declarations fail al const slice = new Encoder().frame(payload); hooks.writeGroupFrame(group, { payload: slice }, payload.length + 1); group.close(); - const raw = await hooks.readGroupFrame(group.mirror(), undefined, true); + const raw = await hooks.readGroupFrame(group.mirror(), true); expect(raw?.frame.payload).toBe(slice); - raw?.complete(); const bad = group.mirror(); await expect(bad.readFrame()).rejects.toThrow(/declared size/); expect(bad.closed.peek()).toBeInstanceOf(Error); diff --git a/js/net/src/group.ts b/js/net/src/group.ts index f3ea3604676..61edb18538a 100644 --- a/js/net/src/group.ts +++ b/js/net/src/group.ts @@ -421,6 +421,86 @@ interface Attempt { replacement?: Replacement; } +// `Consumer.expired`: judges the drift budget only while something listens, so racing it once +// per write leaks nothing, and a group nobody watches pays nothing. The verdict latches. +class Expired implements GetPromise { + #judge: () => Error | undefined; + #changed: () => readonly Getter[]; + #listeners = new Set<(value: Error | undefined) => void>(); + // The drift inputs watched while anything listens. + #unwatch?: Dispose[]; + + constructor(judge: () => Error | undefined, changed: () => readonly Getter[]) { + this.#judge = judge; + this.#changed = changed; + } + + peek(): Error | undefined { + return this.#judge(); + } + + subscribe(fn: (value: Error | undefined) => void): Dispose { + this.#listeners.add(fn); + this.#watch(); + return () => { + this.#listeners.delete(fn); + if (this.#listeners.size === 0) this.#stop(); + }; + } + + changed(): Promise; + changed(fn: (value: Error | undefined) => void): Dispose; + changed(fn?: (value: Error | undefined) => void): Promise | Dispose { + if (!fn) return new Promise((resolve) => this.changed(resolve)); + const dispose = this.subscribe((value) => { + dispose(); + fn(value); + }); + return dispose; + } + + // biome-ignore lint/suspicious/noThenProperty: Expired is intentionally awaitable. + then( + onFulfilled?: ((value: Error) => R1 | PromiseLike) | null, + onRejected?: ((reason: unknown) => R2 | PromiseLike) | null, + ): PromiseLike { + return new Promise((resolve) => { + const value = this.peek(); + if (value) resolve(value); + else this.changed((value) => value && resolve(value)); + }).then(onFulfilled, onRejected); + } + + // Watch the current drift inputs again, since an adopted copy brings its own. + refresh(): void { + if (!this.#unwatch) return; + this.#stop(); + this.#watch(); + } + + #watch(): void { + if (this.#unwatch) return; + this.#unwatch = this.#changed().map((changed) => changed.subscribe(() => this.#check())); + // Judging arms the wall-clock wakeup; a verdict already reached notifies after `subscribe` + // returns, as a signal would. + if (this.peek()) queueMicrotask(() => this.#check()); + } + + #check(): void { + const value = this.peek(); + if (!value) return; + this.#stop(); + const listeners = [...this.#listeners]; + this.#listeners.clear(); + for (const fn of listeners) fn(value); + } + + #stop(): void { + for (const dispose of this.#unwatch ?? []) dispose(); + this.#unwatch = undefined; + } +} + // A consumer can finish from its own expiry verdict or from the shared group state. Keep // one stable public handle while letting peek() observe either source synchronously, before // signal subscribers run in the next microtask. The source is re-read on every check, since a @@ -528,7 +608,7 @@ export class Consumer { #terminal?: Error; #verdict = new Once(); #closed?: CombinedClosed; - #pendingFrames = 0; + #expired?: Expired; // Closed by its reader, which ends it whatever is left unread. #released = false; @@ -547,13 +627,34 @@ export class Consumer { this.#verdict, () => this.#state.closed, (value) => - value instanceof Error - ? !this.#recovers(value) - : this.#released || (this.#bufferedFrames().length === 0 && this.#pendingFrames === 0), + value instanceof Error ? !this.#recovers(value) : this.#released || this.#bufferedFrames().length === 0, ); return this.#closed; } + /** + * Settles with a `StreamError` of code `Old` once the subscription's `maxDelay` gives up + * on this group, even after every frame was read or the group closed: a publisher still + * writing or draining it races its writes against this, and against {@link closed} + * settling with an error, and abandons the stream once either does. Peek it synchronously + * (`undefined` while within budget), or race it, which stops watching the budget once the + * race ends. + * + * @internal Wire publishers only. + */ + get expired(): GetPromise { + this.#expired ??= new Expired( + () => { + this.#expire(); + return this.#terminal instanceof StreamError && this.#terminal.code === StreamCode.Old + ? this.#terminal + : undefined; + }, + () => this.#expiry?.changed ?? [], + ); + return this.#expired; + } + // Whether a failure of the copy being read may still be continued from another route. #recovers(failed: Error): boolean { return !this.#terminal && this.#recover?.wants(failed) === true; @@ -588,8 +689,7 @@ export class Consumer { if (group.#closed?.peek() instanceof Error && group.#verdict.peek() === undefined) group.#closed = undefined; }; - hooks.guardGroup = (group, operation) => group.#guard(operation); - hooks.readGroupFrame = (group, from, compressed) => group.#readFramePosition(true, from, compressed); + hooks.readGroupFrame = (group, compressed) => group.#readFrame(0, compressed); hooks.evictGroup = (group) => { group.#evict(); }; @@ -614,40 +714,6 @@ export class Consumer { return true; } - // Takes a thunk rather than a started promise, so a group already past its budget - // never begins the write: an abandoned write would reject later with no handler. - #guard(operation: () => Promise): Promise { - this.#expire(); - if (this.#terminal) return Promise.reject(this.#terminal); - const expiry = this.#expiry; - if (!expiry) return operation(); - - return new Promise((resolve, reject) => { - let settled = false; - const disposes: Dispose[] = []; - const finish = (fn: () => void) => { - if (settled) return; - settled = true; - for (const dispose of disposes) dispose(); - fn(); - }; - const check = () => { - this.#expire(); - if (this.#terminal) { - const error = this.#terminal; - finish(() => reject(error)); - } - }; - - for (const changed of expiry.changed) disposes.push(changed.subscribe(check)); - operation().then( - (value) => finish(() => resolve(value)), - (error: unknown) => finish(() => reject(error)), - ); - check(); - }); - } - #evict() { const frames = this.#bufferedFrames(); if (frames.length > 0) { @@ -755,6 +821,7 @@ export class Consumer { this.#expiry = replacement.expiry; this.#skip = index; this.#closed?.refresh(); + this.#expired?.refresh(); } // The unread frames. Every look at the buffer goes through here, so readiness, reads and @@ -769,7 +836,7 @@ export class Consumer { return frames; } - #readBufferedFrame(pending = false, compressed = false): ReadGroupFrame | undefined { + #readBufferedFrame(compressed = false): ReadGroupFrame | undefined { const frames = this.#bufferedFrames(); const buffered = frames.shift(); if (!buffered) return undefined; @@ -786,19 +853,8 @@ export class Consumer { } if (frames.length === 0 && this.#state.closed.peek() !== undefined) this.#state.flate = undefined; const sequence = this.#state.start++; - if (pending) this.#pendingFrames++; - let completed = false; - return { - sequence, - frame, - inflated: slice?.inflated, - complete: () => { - if (completed) return; - completed = true; - if (pending) this.#pendingFrames--; - this.#closed?.refresh(); - }, - }; + this.#closed?.refresh(); + return { sequence, frame, inflated: slice?.inflated }; } /** True once no further frames can be read: the group has closed and every buffered frame is read. */ @@ -836,9 +892,7 @@ export class Consumer { */ tryReadFrame(): Frame | undefined { if (this.#terminal) return undefined; - const read = this.#readBufferedFrame(); - read?.complete(); - return read?.frame; + return this.#readBufferedFrame()?.frame; } /** Like {@link tryReadFrame} but also reports the frame's sequence number within the group. */ @@ -846,7 +900,6 @@ export class Consumer { if (this.#terminal) return undefined; const read = this.#readBufferedFrame(); if (!read) return undefined; - read.complete(); return { sequence: read.sequence, payload: read.frame.payload, timestamp: read.frame.timestamp }; } @@ -879,23 +932,29 @@ export class Consumer { * Treat the returned frame bytes as read-only; they are shared with other consumers. */ async readFrame(): Promise { - return (await this.#readFramePosition())?.frame; + return (await this.#readFrame(0))?.frame; + } + + /** + * Reads the next frame along with its sequence number within the group. + * Treat the returned frame bytes as read-only; they are shared with other consumers. + */ + async readFrameSequence(options?: ReadOptions): Promise<({ sequence: number } & Frame) | undefined> { + const read = await this.#readFrame(options?.from ?? 0); + if (!read) return undefined; + return { sequence: read.sequence, payload: read.frame.payload, timestamp: read.frame.timestamp }; } - async #readFramePosition(pending = false, from = 0, compressed = false): Promise { + async #readFrame(from: number, compressed = false): Promise { for (;;) { if (this.#terminal) { this.#abandon(); throw this.#terminal; } - const read = this.#readBufferedFrame(pending, compressed); + const read = this.#readBufferedFrame(compressed); if (read) { - if (read.sequence < from) { - read.complete(); - continue; - } - if (!pending) read.complete(); + if (read.sequence < from) continue; return read; } @@ -924,16 +983,6 @@ export class Consumer { } } - /** - * Reads the next frame along with its sequence number within the group. - * Treat the returned frame bytes as read-only; they are shared with other consumers. - */ - async readFrameSequence(options?: ReadOptions): Promise<({ sequence: number } & Frame) | undefined> { - const read = await this.#readFramePosition(false, options?.from ?? 0); - if (!read) return undefined; - return { sequence: read.sequence, payload: read.frame.payload, timestamp: read.frame.timestamp }; - } - /** Reads the next frame and decodes its payload as a UTF-8 string. */ async readString(): Promise { const frame = await this.readFrame(); diff --git a/js/net/src/ietf/publisher.test.ts b/js/net/src/ietf/publisher.test.ts index 9263e057a0c..b988e8e0481 100644 --- a/js/net/src/ietf/publisher.test.ts +++ b/js/net/src/ietf/publisher.test.ts @@ -3451,16 +3451,21 @@ test("draft-20: an inline terminal reset after its FIN falls back to a standalon const header = await GroupMessage.decode(reader, V20); for (let i = 0; i < 5; i++) await reader.decode((c) => Frame.decode(c, header.flags, undefined)); - // The group stream's close fails from here on, like a reset after its FIN. + // The group stream's close fails once it FINs, like a reset after its FIN. const closed = Object.getOwnPropertyDescriptor(Writer.prototype, "closed")?.get; if (!closed) throw new Error("Writer.closed is not a getter"); + const stream = opened[0]; + const fin = stream.close.bind(stream); let reset = false; - Object.defineProperty(opened[0], "closed", { + stream.close = () => { + reset = true; + fin(); + }; + Object.defineProperty(stream, "closed", { get(this: Writer) { return reset ? Promise.reject(new Error("reset after FIN")) : closed.call(this); }, }); - reset = true; track.finishAt({ group: 5, frame: 5 }); group.close(); diff --git a/js/net/src/ietf/publisher.ts b/js/net/src/ietf/publisher.ts index 4455b6e2b47..f368bfc8a84 100644 --- a/js/net/src/ietf/publisher.ts +++ b/js/net/src/ietf/publisher.ts @@ -33,6 +33,7 @@ import type { Groups, Info, Position as TrackPosition, Subscriber as TrackSubscr import { untilAborted } from "../util/abort.ts"; import { nextChange } from "../util/change.ts"; import { Deadline, REQUEST_TIMEOUT_MS, requestOptions } from "../util/deadline.ts"; +import { untilGivenUp } from "../util/given_up.ts"; import { LIMITS, type Limits, Slots } from "../util/limits.ts"; import { TimeoutError, withTimeout } from "../util/timeout.ts"; import * as Varint from "../varint.ts"; @@ -544,7 +545,7 @@ export class Publisher { // A range that resolves without the live edge has a fixed start, which is no join: // bound the subscription before subscribing so the refresh ratio never judges it. const fixed = subscribeRange(msg, {}, version); - return wireOf(source).subscribe(msg.trackName, { + return source.track(msg.trackName).subscribe({ priority: fromWire(msg.subscriberPriority), order: msg.groupOrder, // An absent budget preserves everything retained by the producer. @@ -770,7 +771,7 @@ export class Publisher { groups: rangeGroups(range), }); const startGroup = range.start ? Number(range.start.group) : hooks.latestSequence(track); - if (startGroup !== undefined) track.setGroups({ ...rangeGroups(range), start: { included: startGroup } }); + if (startGroup !== undefined) track.withRange({ ...rangeGroups(range), start: { included: startGroup } }); // A fill reads the group cache through its own consumer, independent of the // subscription's cursor. Forked from this subscriber rather than resolved through @@ -1082,11 +1083,9 @@ export class Publisher { // once the open settles. tryOpen owns resetting a slot that arrives too late. const opened = Promise.withResolvers(); let failure: Error | undefined; - const abandoned = hooks - .guardGroup(group, () => opened.promise) - .catch((err: unknown) => { - failure = error(err); - }); + const abandoned = untilGivenUp(group, () => opened.promise).then((stop) => { + failure = stop; + }); let stream: Writer | undefined; try { stream = await Writer.tryOpen(this.#quic, { @@ -1134,10 +1133,20 @@ export class Publisher { left = true; return undefined; }); + // The subscription's budget, or an eviction of what is left to read, may give up on the + // group mid-write, which abandons the stream. A group already given up never starts the write. + const write = async (op: () => Promise) => { + const stop = await untilGivenUp(group, op); + if (stop) throw stop; + }; + // Writing the group stops for the pause too; the drain below answers it without a reset. + const send = async (op: () => Promise) => { + await race([write(op), cancelled]); + if (left) throw new Error("unsubscribed while serving the group"); + }; try { - await race([hooks.guardGroup(group, () => header.encode(stream, this.#session.version)), cancelled]); - if (left) throw new Error("unsubscribed while serving the group"); + await send(() => header.encode(stream, this.#session.version)); // The first written object goes on the wire as its absolute id, so a trimmed // head shows the true numbering rather than a silently renumbered group. let first = true; @@ -1154,32 +1163,16 @@ export class Publisher { // Reading from the filter's start drops the objects below it: they are outside // the requested range, so skipping them is not a gap. - const read = await race([hooks.readGroupFrame(group, slice.skip), stream.closed, cancelled]); - if (left) { - read?.complete(); - throw new Error("unsubscribed while serving the group"); - } + const read = await race([group.readFrameSequence({ from: slice.skip }), stream.closed, cancelled]); + if (left) throw new Error("unsubscribed while serving the group"); if (!read) break; next = read.sequence + 1; - if (slice.until !== undefined && read.sequence >= slice.until) { - read.complete(); - break; - } + if (slice.until !== undefined && read.sequence >= slice.until) break; - try { - const obj = new Frame({ payload: read.frame.payload, timestamp: read.frame.timestamp }); - const delta = first ? read.sequence : 0; - first = false; - await race([ - hooks.guardGroup(group, () => - obj.encode(stream, header.flags, timescale, this.#session.version, delta), - ), - cancelled, - ]); - if (left) throw new Error("unsubscribed while serving the group"); - } finally { - read.complete(); - } + const obj = new Frame({ payload: read.payload, timestamp: read.timestamp }); + const delta = first ? read.sequence : 0; + first = false; + await send(() => obj.encode(stream, header.flags, timescale, this.#session.version, delta)); } // The track ends right after this group's last object, so the marker rides this @@ -1197,12 +1190,15 @@ export class Publisher { } stream.close(); + // The stream holds every byte it owes, so frames past a range's end failing upstream + // can no longer give it up: release the read, leaving the budget. + group.close(); // Its bytes still hold the connection until acknowledged, so a group gone stale // meanwhile is reset like one still serving, as the Rust `GroupServe` does. Awaited // even without a marker: PUBLISH_DONE waits on this group, so the track, whose // timeline judges the budget, stays open until the stream settles. const delivered = await race([ - hooks.guardGroup(group, () => stream.closed).then(() => true), + write(() => stream.closed).then(() => true), unsubscribed.then(() => false), ]); // Only a stream that closed cleanly delivered the marker: one reset after its FIN diff --git a/js/net/src/internal.ts b/js/net/src/internal.ts index 9a70079e402..648ccd58559 100644 --- a/js/net/src/internal.ts +++ b/js/net/src/internal.ts @@ -183,16 +183,14 @@ export type Recv = /** The track aborted. */ | { kind: "error"; error: Error }; -/** A package-internal frame read the wire publisher completes once written. */ +/** A package-internal frame read as the group stores it. */ export interface ReadGroupFrame { /** Frame sequence within the group. */ sequence: number; - /** Frame returned to the publisher. */ + /** The frame, holding its DEFLATE slice on a compressed read. */ frame: Frame; - /** The stored slice's declared plain size, on compressed wire reads. */ + /** The stored slice's declared plain size, on compressed reads. */ inflated?: number; - /** Mark the frame delivered or deliberately skipped by the wire publisher. */ - complete(): void; } /** One past the highest sequence written under a broadcast track's name, by any of its producers. */ @@ -490,16 +488,10 @@ export const hooks: { subscription: Subscription | undefined, source: (shell: ResumeShell) => ResumeSource, ) => Subscriber; - /** Wake once a subscriber's group cursor may read differently; assigned by `track.ts`. */ + /** Wake once a subscriber's group cursor may read differently, including when the track declares its end; assigned by `track.ts`. */ groupChanged: (subscriber: Subscriber, fn: () => void) => Dispose; /** Apply a FETCH reader budget without inheriting SUBSCRIBE's zero default. */ fetchBudget: (subscriber: Subscriber, maxDelay: Milli | undefined) => void; - /** - * Replace a serving cursor. An omitted start keeps the current floor; a provided start - * can lower it. Wire publishers apply SUBSCRIBE_UPDATE here rather than through - * `setGroups`, which never rewinds. - */ - replaceGroups: (subscriber: Subscriber, groups: Groups) => void; /** * Bind a group to its track's timedness, so a frame whose timestamp disagrees is refused. * Throws `TimestampMismatch` if a buffered frame already disagrees. @@ -545,10 +537,8 @@ export const hooks: { expireGroup: (group: GroupConsumer, expiry: Expiry) => void; /** Carry a handed-out group across its logical track's route changes. */ recoverGroup: (group: GroupConsumer, recover: GroupRecover) => void; - /** Start a group operation unless the handed-out group has expired, and stop it if the group expires mid-flight. */ - guardGroup: (group: GroupConsumer, operation: () => Promise) => Promise; - /** Read a frame the wire publisher completes (or skips) once written. */ - readGroupFrame: (group: GroupConsumer, from?: number, compressed?: boolean) => Promise; + /** Read the next frame, as its stored DEFLATE slice when `compressed`, so a lite-07 publisher forwards it without inflating. */ + readGroupFrame: (group: GroupConsumer, compressed: boolean) => Promise; /** Make an evicted mirror terminal while its track timeline still contains it. */ evictGroup: (group: GroupConsumer) => void; /** Attach the origin advertisement of a created broadcast. */ @@ -674,9 +664,6 @@ export const hooks: { fetchBudget: () => { throw new Error("track.ts not loaded"); }, - replaceGroups: () => { - throw new Error("track.ts not loaded"); - }, writeDatagram: () => { throw new Error("track.ts not loaded"); }, @@ -731,9 +718,6 @@ export const hooks: { recoverGroup: () => { throw new Error("group.ts not loaded"); }, - guardGroup: () => { - throw new Error("group.ts not loaded"); - }, readGroupFrame: () => { throw new Error("group.ts not loaded"); }, diff --git a/js/net/src/lite/publisher.test.ts b/js/net/src/lite/publisher.test.ts index 6d5bbe3c73b..b797842820c 100644 --- a/js/net/src/lite/publisher.test.ts +++ b/js/net/src/lite/publisher.test.ts @@ -14,6 +14,7 @@ import * as Path from "../path.ts"; import { sendOrder } from "../priority.ts"; import { Reader, Stream, Writer } from "../stream.ts"; import { Timescale, Timestamp } from "../time.ts"; +import { Subscriber as TrackSubscriber } from "../track.ts"; import { type AnnounceBroadcast, AnnounceOk, AnnounceRequest, decodeAnnounceBroadcast } from "./announce.ts"; import { Datagram as DatagramMessage } from "./datagram.ts"; import { Fetch } from "./fetch.ts"; @@ -594,7 +595,7 @@ const IDLE_MS = 500; const flush = () => new Promise((resolve) => setTimeout(resolve, 0)); function lastGroups(ranges: ReturnType) { - return ranges.mock.calls.at(-1)?.[1]; + return ranges.mock.calls.at(-1)?.[0]; } // Wraps a writable so its writes park until `release()`, giving a test a window inside @@ -1227,7 +1228,7 @@ test("lite draft-06: an omitted group start still serves a group below the first // to the next pop rather than reaching backward into this one. test("lite draft-05: a group popped before a cap update is still served", async () => { const sub = await servedSubscription({ startGroup: 1, gated: true }); - const ranges = spyOn(hooks, "replaceGroups"); + const ranges = spyOn(TrackSubscriber.prototype, "withRange"); try { sub.serve(1); await sub.parked; @@ -1255,7 +1256,7 @@ test("lite draft-05: a group popped before a cap update is still served", async // poll order. test("lite draft-06: a queued floor update applies before the next group pop", async () => { const sub = await servedSubscription({ version: Version.DRAFT_06, startGroup: 0, gated: true }); - const ranges = spyOn(hooks, "replaceGroups"); + const ranges = spyOn(TrackSubscriber.prototype, "withRange"); try { sub.serve(0); await sub.parked; @@ -1281,7 +1282,7 @@ test("lite draft-06: a queued floor update applies before the next group pop", a }); // SUBSCRIBE_START pins the floor to the first served group. A later update can still -// widen it: public setGroups would keep the pin, so serving uses replaceGroups. +// widen it, serving the cached groups below the old floor. test("lite draft-06: a widening update lowers the serving floor", async () => { const sub = await servedSubscription({ version: Version.DRAFT_06, startGroup: 10 }); try { @@ -1309,7 +1310,7 @@ test("lite draft-06: a queued frame floor applies before the next group pop", as frames: ["a", "b", "c"], gated: true, }); - const ranges = spyOn(hooks, "replaceGroups"); + const ranges = spyOn(TrackSubscriber.prototype, "withRange"); try { sub.serve(0); await sub.parked; @@ -1400,7 +1401,7 @@ test("lite draft-06: a burst of updates coalesces before the next group pop", as sub.serve(0); await sub.parked; sub.serve(1); - const ranges = spyOn(hooks, "replaceGroups"); + const ranges = spyOn(TrackSubscriber.prototype, "withRange"); try { // Two updates land back to back, the second superseding the first. @@ -1419,7 +1420,8 @@ test("lite draft-06: a burst of updates coalesces before the next group pop", as // Group 1 is popped under the latest state, with no application of the older one. expect(await sub.servedGroup()).toEqual({ sequence: 1, frameStart: 0, payloads: ["a"] }); expect(ranges).toHaveBeenCalledTimes(1); - expect(lastGroups(ranges)).toEqual({ start: undefined, end: { included: 1 } }); + // Draft-06 encodes a floor of group 0 as no floor, which assigns 0. + expect(lastGroups(ranges)).toEqual({ start: { included: 0 }, end: { included: 1 } }); } finally { ranges.mockRestore(); } @@ -1437,11 +1439,13 @@ test("lite draft-06: a newer update wins before a buffered group backlog drains" gated: true, }); let second!: Promise; - const replaceGroups = hooks.replaceGroups; - const ranges = spyOn(hooks, "replaceGroups").mockImplementation((subscriber, groups) => { - if (groups.start === undefined) - second ??= replayUpdate({ priority: 0, endGroup: 1 }).encode(sub.client.writer, Version.DRAFT_06); - return replaceGroups(subscriber, groups); + const withRange = TrackSubscriber.prototype.withRange; + const ranges = spyOn(TrackSubscriber.prototype, "withRange").mockImplementation(function ( + this: TrackSubscriber, + groups, + ) { + second ??= replayUpdate({ priority: 0, endGroup: 1 }).encode(sub.client.writer, Version.DRAFT_06); + return withRange.call(this, groups); }); try { @@ -1473,7 +1477,7 @@ test("lite draft-06: a newer update wins before a buffered group backlog drains" // The full update remains atomic to observers, while the local range cursor stays serialized. test("lite draft-06: scheduling updates apply while SUBSCRIBE_START is blocked", async () => { const sub = await servedSubscription({ version: Version.DRAFT_06, startGroup: 0, gated: true }); - const ranges = spyOn(hooks, "replaceGroups"); + const ranges = spyOn(TrackSubscriber.prototype, "withRange"); try { sub.serve(0); await sub.parked; @@ -1493,7 +1497,7 @@ test("lite draft-06: scheduling updates apply while SUBSCRIBE_START is blocked", sub.release(); expect(await sub.servedSequence()).toBe(0); while (ranges.mock.calls.length === 0) await flush(); - expect(lastGroups(ranges)).toEqual({ start: undefined, end: { included: 5 } }); + expect(lastGroups(ranges)).toEqual({ start: { included: 0 }, end: { included: 5 } }); } finally { ranges.mockRestore(); sub.release(); diff --git a/js/net/src/lite/publisher.ts b/js/net/src/lite/publisher.ts index a0d7180b5ef..089effdb8b6 100644 --- a/js/net/src/lite/publisher.ts +++ b/js/net/src/lite/publisher.ts @@ -20,6 +20,7 @@ import { type Timescale, Timestamp } from "../time.ts"; import type * as track from "../track.ts"; import { untilAborted } from "../util/abort.ts"; import { nextChange } from "../util/change.ts"; +import { untilGivenUp } from "../util/given_up.ts"; import { nextTask } from "../util/yield.ts"; import { type Advertised, type Advertisements, sameInstance, wireOf } from "../wire.ts"; import { AnnounceInit, AnnounceOk, type AnnounceRequest, encodeAnnounceBroadcast } from "./announce.ts"; @@ -177,7 +178,7 @@ type FrameBounds = { * The frames of `sequence` a subscription asked for, as a start index and an inclusive end. * * The frame bounds qualify the start and end group only; every other group is served whole. - * Which groups are served at all is the subscriber's read cursor (`replaceGroups`), + * Which groups are served at all is the subscriber's read cursor (`withRange`), * applied when a group is popped rather than re-checked here. * * The serving loop calls this synchronously after the pop, before any SUBSCRIBE_UPDATE can @@ -380,10 +381,10 @@ function carriesMaxDelay(version: Version): boolean { } /** - * Position a subscription's read cursor for the wire serving it. + * The floor of 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 delay decides what above the floor is worth delivering. + * On lite-06 it is the group the subscription named (or 0), and its max delay 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 @@ -391,11 +392,10 @@ function carriesMaxDelay(version: Version): boolean { * an unbounded budget so nothing is dropped under them (see {@link servingMaxDelay}), 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 = hooks.latestSequence(track); - if (latest !== undefined) hooks.replaceGroups(track, { start: { included: latest } }); +function cursorFloor(version: Version, startGroup: number | undefined, latest: number | undefined): number { + if (startGroup !== undefined) return startGroup; + if (resolvesStart(version)) return 0; + return latest ?? 0; } /** @@ -848,7 +848,7 @@ export class Publisher { } const endGroup = exclusiveGroupEnd(msg.endGroup); - const track = wireOf(front).subscribe(msg.track, { + const track = front.track(msg.track).subscribe({ priority: msg.priority, order: msg.order, maxDelay: Milli(servingMaxDelay(this.version, msg.maxDelay)), @@ -858,8 +858,11 @@ export class Publisher { }, }); serving(track); - positionCursor(track, this.version, msg.startGroup); - hooks.replaceGroups(track, { end: endGroup === undefined ? undefined : { excluded: endGroup } }); + const floor = cursorFloor(this.version, msg.startGroup, hooks.latestSequence(track)); + track.withRange({ + start: { included: floor }, + end: endGroup === undefined ? undefined : { excluded: endGroup }, + }); // The best-effort datagram loop, started once serving begins. It parks when the // track finishes (recvDatagram returns undefined), so #runTrack alone ends the @@ -958,6 +961,7 @@ export class Publisher { publisher, compress, served, + floor, bounds, }); @@ -1063,9 +1067,7 @@ export class Publisher { hold.abort(); } // A group that has not arrived yet holds this FETCH's slot until the requester leaves. - const fetchGroup = wireOf(front).fetchGroup; - if (!fetchGroup) throw new Error("fetch group is not supported by the serving route's version"); - group = await fetchGroup(msg.track, msg.group, { + group = await front.track(msg.track).fetchGroup(msg.group, { priority: msg.priority, maxDelay: msg.maxDelay, signal: left.signal, @@ -1122,10 +1124,25 @@ export class Publisher { publisher: number; compress: boolean; served: Run[] | undefined; + // The read cursor's floor; see {@link cursorFloor}. + floor: number; bounds: FrameBounds; }, ): Promise { const { sub, broadcast, stamp, publisher, compress, served, bounds } = serving; + // The read cursor's floor, assigned with the cap in {@link bounds} on every move. + let floor = serving.floor; + const moveCursor = () => + track.withRange({ + start: { included: floor }, + end: bounds.endGroup === undefined ? undefined : { included: bounds.endGroup }, + }); + // Raise the floor to `start`, keeping any higher floor already set. + const raiseFloor = (start: number) => { + if (start <= floor) return; + floor = start; + moveCursor(); + }; // 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 = hasTrackStream(this.version); @@ -1221,33 +1238,33 @@ export class Publisher { case "update": { const update = control.update; console.debug(`subscribe update: broadcast=${broadcast} track=${track.name}`); - // `positionCursor` pins an unfloored pre-06 SUBSCRIBE to the latest + // `cursorFloor` pins an unfloored pre-06 SUBSCRIBE to the latest // group, so an update that drops a named floor re-pins there too. On // an empty track the next group is the latest, whatever its sequence. + // Lite-06 encodes an absent start as no floor, so it drops back to 0: + // the cursor only rises on its own, and a finished group below the old + // floor (a quiet catalog) is never served otherwise. const requested = bounds.startGroup; const start = update.startGroup === undefined && requested !== undefined && !resolvesStart(this.version) ? (hooks.latestSequence(track) ?? 0) - : update.startGroup; - hooks.replaceGroups(track, { - start: start === undefined ? undefined : { included: start }, - end: update.endGroup === undefined ? undefined : { included: update.endGroup }, - }); - // Lite-06 encodes an absent start as no floor, so it drops back to 0. - const floor = start ?? (resolvesStart(this.version) ? 0 : undefined); - // Before SUBSCRIBE_START nothing is owed yet; the start accounts for it. - if (floor !== undefined && startSequence !== undefined) { - // A lowered floor owes the groups it newly asks for, so the end sweep covers them. - // A raised one sends no early drop: the subscriber already stops owing below - // its floor, and a later update may lower it again to reopen those groups. - startSequence = Math.min(startSequence, floor); + : (update.startGroup ?? (resolvesStart(this.version) ? 0 : undefined)); + if (start !== undefined) { + floor = start; + // Before SUBSCRIBE_START nothing is owed yet; the start accounts for it. + // A lowered floor owes the groups it newly asks for, so the end sweep + // covers them. A raised one sends no early drop: the subscriber already + // stops owing below its floor, and a later update may lower it again to + // reopen those groups. + if (startSequence !== undefined) startSequence = Math.min(startSequence, start); } bounds.startGroup = update.startGroup; bounds.startFrame = update.startFrame; bounds.endGroup = update.endGroup; bounds.endFrame = update.endFrame; + moveCursor(); // A microtask is too short: decoding one framed update crosses several // awaits, each of which can requeue behind the serving continuation. A // task boundary lets the decoder finish whatever the transport already @@ -1293,10 +1310,7 @@ export class Publisher { ) { startSent = true; startSequence = bounds.startGroup; - hooks.replaceGroups(track, { - start: { included: bounds.startGroup }, - end: bounds.endGroup === undefined ? undefined : { included: bounds.endGroup }, - }); + raiseFloor(bounds.startGroup); const start = new SubscribeStart(bounds.startGroup, largest); if ( !(await controls.response(encodeSubscribeResponse(stream, { start }, this.version))) @@ -1375,12 +1389,7 @@ export class Publisher { // A pre-06 subscribe that named no group is the exception: an absent // Group Start is the latest group, and this sequence becomes the floor. // Lite-06 encodes a floor of group 0 as 0, so an omitted start is not pinned. - if (bounds.startGroup === undefined && !resolvesStart(this.version)) { - hooks.replaceGroups(track, { - start: { included: startSequence }, - end: bounds.endGroup === undefined ? undefined : { included: bounds.endGroup }, - }); - } + if (bounds.startGroup === undefined && !resolvesStart(this.version)) raiseFloor(startSequence); if ( !(await controls.response( encodeSubscribeResponse( @@ -1664,16 +1673,15 @@ export class Publisher { // as `startFrame`. Skipping the head here is the only thing keeping those numbers // honest; a group that ends before we reach it can't be served at all. for (let i = 0; i < startFrame; i++) { - const skipped = await race([hooks.readGroupFrame(group, undefined, compress), stream.closed]); + const skipped = await race([hooks.readGroupFrame(group, compress), stream.closed]); if (!skipped) { throw new Error(`fetch group ended at frame ${i}, before the requested start ${startFrame}`); } - skipped.complete(); } let prevTs = 0n; for (let index = startFrame; endFrame === undefined || index <= endFrame; index++) { - const read = await race([hooks.readGroupFrame(group, undefined, compress), stream.closed]); + const read = await race([hooks.readGroupFrame(group, compress), stream.closed]); if (!read) break; const frame = read.frame; @@ -1686,7 +1694,6 @@ export class Publisher { if (read.inflated !== undefined) await stream.u53(read.inflated); await stream.u53(frame.payload.byteLength); if (frame.payload.length > 0) await stream.write(frame.payload); - read.complete(); } } @@ -1710,11 +1717,9 @@ export class Publisher { // once the open settles. tryOpen owns resetting a slot that arrives too late. const opened = Promise.withResolvers(); let failure: Error | undefined; - const abandoned = hooks - .guardGroup(group, () => opened.promise) - .catch((err: unknown) => { - failure = error(err); - }); + const abandoned = untilGivenUp(group, () => opened.promise).then((stop) => { + failure = stop; + }); let stream: Writer | undefined; try { stream = await Writer.tryOpen(this.#quic, { @@ -1749,6 +1754,12 @@ export class Publisher { // This model holds whole groups, so frame `startFrame` is always reachable unless // the group ends first. Declaring it up front keeps the stream self-describing. const msg = new GroupMessage({ subscribe: sub, sequence: group.sequence, frameStart: startFrame }); + // The subscription's budget, or an eviction of what is left to read, may give up on the + // group mid-write, which abandons the stream. A group already given up never starts the write. + const write = async (op: () => Promise) => { + const stop = await untilGivenUp(group, op); + if (stop) throw stop; + }; // Everything past this point runs inside the cleanup scope, so a failure never leaves // a finished group's stream being ranked. try { @@ -1756,7 +1767,7 @@ export class Publisher { // follows it too rather than keeping a stale rank until it finishes. priority.add(stream, group.sequence, startFrame); - await hooks.guardGroup(group, async () => { + await write(async () => { await stream.u53(0); // stream type await msg.encode(stream, this.version); }); @@ -1767,7 +1778,7 @@ export class Publisher { let reached = startFrame === 0; for (;;) { - const read = await race([hooks.readGroupFrame(group, undefined, compress), stream.closed]); + const read = await race([hooks.readGroupFrame(group, compress), stream.closed]); if (!read) { // The group ended before the frame the subscriber asked to start // at, so this publisher can't serve the range at all. FINning here @@ -1777,29 +1788,24 @@ export class Publisher { break; } - try { - // A group that ends exactly at the start is a valid, empty range. - if (read.sequence + 1 >= startFrame) reached = true; - // Frames below the requested start were excluded, and the receiver - // numbers what it gets from `startFrame`. - if (read.sequence < startFrame) continue; - if (endFrame !== undefined && read.sequence > endFrame) break; - - if (stamp !== undefined) { - // Convert each frame to the track's wire timescale. - const ts = BigInt(wireTime(read.frame.timestamp, stamp)); - await hooks.guardGroup(group, () => stream.u62(zigzag(ts - prevTs))); - prevTs = ts; - } - - const inflated = read.inflated; - if (inflated !== undefined) await hooks.guardGroup(group, () => stream.u53(inflated)); - await hooks.guardGroup(group, () => stream.u53(read.frame.payload.byteLength)); - if (read.frame.payload.length > 0) - await hooks.guardGroup(group, () => stream.write(read.frame.payload)); - } finally { - read.complete(); + // A group that ends exactly at the start is a valid, empty range. + if (read.sequence + 1 >= startFrame) reached = true; + // Frames below the requested start were excluded, and the receiver + // numbers what it gets from `startFrame`. + if (read.sequence < startFrame) continue; + if (endFrame !== undefined && read.sequence > endFrame) break; + + if (stamp !== undefined) { + // Convert each frame to the track's wire timescale. + const ts = BigInt(wireTime(read.frame.timestamp, stamp)); + await write(() => stream.u62(zigzag(ts - prevTs))); + prevTs = ts; } + + const inflated = read.inflated; + if (inflated !== undefined) await write(() => stream.u53(inflated)); + await write(() => stream.u53(read.frame.payload.byteLength)); + if (read.frame.payload.length > 0) await write(() => stream.write(read.frame.payload)); } stream.close(); @@ -1807,7 +1813,7 @@ export class Publisher { // A stream that fails after its FIN may have lost its header, so report it for a DROP. // Its bytes still hold the connection until acknowledged, so a group gone stale // meanwhile is reset like one still serving, as the Rust `GroupServe` does. - await hooks.guardGroup(group, () => stream.closed); + await write(() => stream.closed); return undefined; } catch (err: unknown) { const e = error(err); diff --git a/js/net/src/lite/subscribe.ts b/js/net/src/lite/subscribe.ts index d159d4fdd39..4226d40a518 100644 --- a/js/net/src/lite/subscribe.ts +++ b/js/net/src/lite/subscribe.ts @@ -156,7 +156,7 @@ async function encodeOrder(w: Writer, version: Version, order: Order) { /** * Exclusive model/local cap from a decoded inclusive last group. * - * The wire's `Group End` is inclusive once decoded; the track model and `setGroups` are + * The wire's `Group End` is inclusive once decoded; the track model and `withRange` are * exclusive. `undefined` stays unbounded. */ export function exclusiveGroupEnd(inclusive?: number): number | undefined { diff --git a/js/net/src/parked-expiry.test.ts b/js/net/src/parked-expiry.test.ts index d9f5ed0eb75..a30b7862e54 100644 --- a/js/net/src/parked-expiry.test.ts +++ b/js/net/src/parked-expiry.test.ts @@ -147,3 +147,99 @@ for (const protocol of protocols) { }, ); } + +for (const protocol of protocols) { + test(`${protocol.alpn}: a blocked group write ends when eviction takes what it has yet to read`, async () => { + const clock = new Manual(); + const installed = clock.install(); + const pair = createMockTransportPair(protocol.alpn); + const origin = new Origin(); + const broadcast = origin.createBroadcast(Path.from("parked")); + broadcast.announce(); + const track = broadcast.createTrack("video", { timescale: Timescale.MILLI }); + const write = (sequence: number, frames: number) => { + const group = new Group(sequence); + for (let frame = 0; frame < frames; frame++) { + group.writeFrame({ payload: new Uint8Array([frame]), timestamp: Timestamp.fromMillis(0) }); + } + group.close(); + track.writeGroup(group); + }; + + // Two frames, so the second is still unread while the stream's first write waits on credit. + write(0, 2); + + const blocked = Promise.withResolvers(); + const credit = Promise.withResolvers(); + let writes = 0; + let resets = 0; + const stalled = new WritableStream({ + write: async () => { + writes++; + blocked.resolve(); + await credit.promise; + }, + abort: () => { + resets++; + }, + }); + const opening = spyOn(pair.server, "createUnidirectionalStream").mockImplementationOnce(async () => stalled); + const client = await Stream.open(pair.client, { version: protocol.version }); + const server = await Stream.accept(pair.server, protocol.version); + if (!server) throw new Error("missing subscribe stream"); + // A budget past the eviction, so only the eviction can give the group up. + const budget = 60_000; + let running: Promise; + let close = () => {}; + if (protocol.kind === "lite") { + const publisher = new LitePublisher(pair.server, protocol.version, randomHop(), origin.consume()); + close = () => publisher.close(); + running = publisher.runSubscribe( + new LiteSubscribe({ + id: 0n, + broadcast: Path.from("parked"), + track: "video", + priority: 0, + maxDelay: budget, + }), + server, + ); + } else { + const publisher = new IetfPublisher({ + quic: pair.server, + session: new NativeSession(pair.server, protocol.version, true), + publish: origin.consume(), + requiresSolicitation: false, + }); + running = publisher.runSubscribe( + new IetfSubscribe({ + requestId: 0n, + trackNamespace: Path.from("parked"), + trackName: "video", + subscriberPriority: 0, + maxAge: budget, + }), + server, + ); + } + try { + await blocked.promise; + write(1, 1); + await clock.advance(Nano.fromMilli(Milli(33_750))); + // The write already handed to the stream finishes, and the stream is reset after it. + credit.resolve(); + await clock.advance(Nano.zero); + expect(writes).toBe(1); + expect(resets).toBe(1); + } finally { + credit.resolve(); + close(); + client.close(); + broadcast.close(); + origin.close(); + await running; + opening.mockRestore(); + installed.close(); + } + }); +} diff --git a/js/net/src/resume.test-util.ts b/js/net/src/resume.test-util.ts index 8599606f7fb..01bca3d581a 100644 --- a/js/net/src/resume.test-util.ts +++ b/js/net/src/resume.test-util.ts @@ -13,8 +13,6 @@ export function readsFrom(active: BroadcastConsumer | undefined, source: Broadca const sub = active.track(name).subscribe(); try { return sub.tryRecvGroup() !== undefined; - } catch { - return false; } finally { sub.close(); track.close(); diff --git a/js/net/src/resume.test.ts b/js/net/src/resume.test.ts index d8469cfc4f5..2593bc96c61 100644 --- a/js/net/src/resume.test.ts +++ b/js/net/src/resume.test.ts @@ -1710,13 +1710,13 @@ test("the largest honours the reader's bounds on the serving copy", async () => const capped = front.consumer .track("seq") .subscribe() - .withGroups({ end: { excluded: 3 } }); + .withRange({ end: { excluded: 3 } }); const floored = front.consumer.track("seq").subscribe({ groups: { start: { included: 8 } } }); for (let sequence = 0; sequence < 5; sequence++) ta.write(sequence); const next = capped.largest(); expect(await isPending(next)).toBe(true); - capped.setGroups({}); + capped.withRange({}); expect(await next).toEqual({ group: 4, frame: 0 }); const floor = floored.largest(); @@ -1822,6 +1822,58 @@ test.each(["lands", "dropped", "expired"])( }, ); +test("a group read whole still expires once the reader lets go of its copy", async () => { + const { clock, installed } = manual(); + const front = new Front(); + const a = new BroadcastProducer(); + const b = new BroadcastProducer(); + const ta = copy(a); + const tb = copy(b); + front.serve(a.consume()); + const sub = front.consumer.track("seq").subscribe({ maxDelay: SECOND }); + try { + ta.write(0); + const group = sub.tryRecvGroup(); + if (!group) throw new Error("expected group 0"); + // Read whole and released, as a publisher does before it drains the stream it wrote it to. + expect(dec.decode((await group.readFrame())?.payload)).toBe("0.0"); + expect(await group.readFrame()).toBeUndefined(); + group.close(); + + front.serve(b.consume()); + await settle(); + tb.write(2); + expect(drain(sub)).toEqual([2]); + // Its successor lands on the replaced copy, starting the budget there. + const half = Nano.fromMilli(Milli(SECOND / 2)); + await clock.advance(half); + ta.write(1); + drain(sub); + + let expired: Error | undefined; + void group.expired.then((err) => { + expired = err; + }); + // A budget after the swap, the next read lets go of the replaced copy, closing its subscription. + await clock.advance(half); + expect(drain(sub)).toEqual([]); + await settle(); + expect(ta.producer.demand().wanted.peek()).toBeUndefined(); + expect(expired).toBeUndefined(); + + await clock.advance(half); + await settle(); + expect(expired).toBeInstanceOf(StreamError); + expect((expired as StreamError).code).toBe(StreamCode.Old); + } finally { + sub.close(); + front.consumer.close(); + a.close(); + b.close(); + installed.close(); + } +}); + test("an ordered reader keeps no copy for a group it passed", async () => { const front = new Front(); const a = new BroadcastProducer(); @@ -1983,7 +2035,7 @@ test.each([false, true])( copy(b); front.serve(a.consume()); const sub = front.consumer.track("seq").subscribe({ maxDelay: Milli(10_000) }); - expect(sub.tryRecvGroup()).toBeUndefined(); + expect(hooks.tryRecvGroup(sub, false).kind).toBe("idle"); expect(hooks.tryRecvDatagram(sub).kind).toBe("idle"); ta.write(0); front.serve(b.consume()); @@ -2297,7 +2349,7 @@ test("a datagram below the group floor does not keep a finite track's copy", asy ta.producer.appendDatagram(undefined, enc.encode("d")); await settle(); // The floor passes the datagram: a datagram read would only discard it. - sub.setGroups({ start: { included: 1 } }); + sub.withRange({ start: { included: 1 } }); ta.write(1); ta.producer.finishAt({ group: 2, frame: 0 }); expect(drain(sub)).toEqual([1]); diff --git a/js/net/src/resume.ts b/js/net/src/resume.ts index 2846d5a6b9a..a6293169afe 100644 --- a/js/net/src/resume.ts +++ b/js/net/src/resume.ts @@ -455,7 +455,7 @@ class Reader implements ResumeSource { const start = Math.max(cursor.start, copy.floor ?? 0); const replaced = copyEnd(copy); const end = replaced === undefined ? cursor.end : Math.min(cursor.end ?? replaced, replaced); - hooks.replaceGroups(copy.sub, { + copy.sub.withRange({ start: { included: start }, end: end === undefined ? undefined : { excluded: end }, }); diff --git a/js/net/src/track.test.ts b/js/net/src/track.test.ts index 8d148cc0e2b..98712920dd3 100644 --- a/js/net/src/track.test.ts +++ b/js/net/src/track.test.ts @@ -1,10 +1,11 @@ import { expect, setSystemTime, spyOn, test } from "bun:test"; import { Manual, Milli, Nano } from "@moq/clock"; +import { race } from "@moq/signals"; import { Producer as BroadcastProducer } from "./broadcast.ts"; import { ProtocolViolation, StreamCode, StreamError, TimestampMismatch, TooFarBehind } from "./error.ts"; import { Decoder } from "./flate/decoder.ts"; import { Encoder } from "./flate/encoder.ts"; -import { Producer as GroupProducer, MAX_GROUP_FRAMES } from "./group.ts"; +import { type Consumer as GroupConsumer, Producer as GroupProducer, MAX_GROUP_FRAMES } from "./group.ts"; import { Version as IetfVersion } from "./ietf/version.ts"; import { hooks } from "./internal.ts"; import { textFrame } from "./mock.ts"; @@ -237,8 +238,7 @@ test("appendDatagram delivers to a subscriber", async () => { // range is what dropped the others. test("the group range bounds datagrams", async () => { const producer = new TrackProducer("test"); - const track = producer.subscribe({ groups: { start: { included: 5 } } }); - track.setGroups({ end: { excluded: 7 } }); + const track = producer.subscribe().withRange({ start: { included: 5 }, end: { excluded: 7 } }); for (const sequence of [4, 5, 7, 6]) { producer.insertDatagram(sequence, Timestamp.fromMillis(0), enc.encode("x")); } @@ -721,38 +721,40 @@ test("ordered frame reads follow the budget", async () => { expect(await live.readString()).toBe("2000"); }); -// Interleaving nextGroup with the frame helpers is still one cursor: a nextGroup that +// Interleaving a group take with the frame helpers is still one cursor: a take that // moves past the group the frame helpers were draining abandons it, so a later frame // read never runs backwards. -test("nextGroup abandons the frame helpers' group when it passes it", async () => { - const producer = new TrackProducer("test"); - const track = producer.subscribe({ maxDelay: Milli(5000) }).ordered(); - - const zero = new GroupProducer(0); - zero.writeFrame(textFrame("0.0")); - zero.writeFrame(textFrame("0.1")); - zero.close(); - producer.writeGroup(zero); - - const one = new GroupProducer(1); - one.writeFrame(textFrame("1.0")); - one.close(); - producer.writeGroup(one); - - const two = new GroupProducer(2); - two.writeFrame(textFrame("2.0")); - two.close(); - producer.writeGroup(two); - - // The frame path enters group 0; a direct nextGroup then takes group 1. - expect((await track.readFrame())?.group).toBe(0); - expect((await track.nextGroup())?.sequence).toBe(1); - - // The frame path must not resume group 0 behind the cursor: it continues at 2. - const next = await track.readFrame(); - expect(next?.group).toBe(2); - expect(dec.decode(next?.payload)).toBe("2.0"); -}); +for (const take of ["nextGroup", "tryNextGroup"] as const) { + test(`${take} abandons the frame helpers' group when it passes it`, async () => { + const producer = new TrackProducer("test"); + const track = producer.subscribe({ maxDelay: Milli(5000) }).ordered(); + + const zero = new GroupProducer(0); + zero.writeFrame(textFrame("0.0")); + zero.writeFrame(textFrame("0.1")); + zero.close(); + producer.writeGroup(zero); + + const one = new GroupProducer(1); + one.writeFrame(textFrame("1.0")); + one.close(); + producer.writeGroup(one); + + const two = new GroupProducer(2); + two.writeFrame(textFrame("2.0")); + two.close(); + producer.writeGroup(two); + + // The frame path enters group 0; a direct take then claims group 1. + expect((await track.readFrame())?.group).toBe(0); + expect((await track[take]())?.sequence).toBe(1); + + // The frame path must not resume group 0 behind the cursor: it continues at 2. + const next = await track.readFrame(); + expect(next?.group).toBe(2); + expect(dec.decode(next?.payload)).toBe("2.0"); + }); +} // The frame helpers ride the same sequence cursor as nextGroup: a lower group arriving // after a higher one was read is skipped, never fed to the caller backwards. @@ -1047,7 +1049,7 @@ test("committing track info wakes a group newly outside the retention window", a await expect(waiting).rejects.toMatchObject({ code: StreamCode.Old }); }); -test("a handed-out frame cancels its in-flight operation when it expires", async () => { +test("a handed-out group reports its expiry to a writer racing it", async () => { const producer = new TrackProducer("test").accept({ timescale: Timescale.MILLI, maxAge: Milli(5000) }); const track = producer.subscribe(); producer.writeFrame(textFrame("old")); @@ -1056,18 +1058,15 @@ test("a handed-out frame cancels its in-flight operation when it expires", async if (!group) throw new Error("missing group"); expect(await group.readString()).toBe("old"); - let release!: () => void; - const operation = new Promise((resolve) => { - release = resolve; - }); - const guarded = hooks.guardGroup(group, () => operation); + const write = new Promise(() => {}); + const raced = race([write, group.expired]); producer.writeFrame(textFrame("new")); - await expect(guarded).rejects.toThrow("max delay budget"); - release(); + expect(await raced).toMatchObject({ code: StreamCode.Old, message: expect.stringContaining("max delay budget") }); + expect(group.expired.peek()).toMatchObject({ code: StreamCode.Old }); }); -test("a guarded write keeps the position of the frame removed from the buffer", async () => { +test("a frame still being written is judged against the budget", async () => { const producer = new TrackProducer("test").accept({ timescale: Timescale.MILLI, maxAge: Milli(100) }); const track = producer.subscribe({ maxDelay: Milli(100) }); const source = producer.appendGroup(); @@ -1076,54 +1075,49 @@ test("a guarded write keeps the position of the frame removed from the buffer", const group = await track.recvGroup(); if (!group) throw new Error("missing group"); - const read = await hooks.readGroupFrame(group); - if (!read) throw new Error("missing frame"); - - let release!: () => void; - const operation = new Promise((resolve) => { - release = resolve; - }); - const guarded = hooks.guardGroup(group, () => operation); + expect(await group.readFrame()).toBeDefined(); + const raced = race([new Promise(() => {}), group.expired]); producer.writeFrame({ payload: enc.encode("edge"), timestamp: Timestamp.fromMillis(1_000) }); // A group beyond the edge, so group 0's reach (1s) is provably behind it: a group is // bounded by where its successor begins, so the successor alone never convicts it. producer.writeFrame({ payload: enc.encode("later"), timestamp: Timestamp.fromMillis(2_000) }); - await expect(guarded).rejects.toThrow("max delay budget"); - read.complete(); - release(); + expect(await raced).toMatchObject({ code: StreamCode.Old }); }); -test("clean source closure stays provisional while a frame write can expire", async () => { - const producer = new TrackProducer("test").accept({ timescale: Timescale.MILLI, maxAge: Milli(100) }); - const track = producer.subscribe({ maxDelay: Milli(100) }); - const source = producer.appendGroup(); - source.writeFrame({ payload: enc.encode("old"), timestamp: Timestamp.fromMillis(0) }); - source.close(); +// Mirrors the Rust `a_fully_read_group_still_reports_its_expiry`: a publisher still draining a +// group it read whole abandons the stream once the budget gives up on the group. +test("a fully read group still reports its expiry", async () => { + const clock = manualTime(10_000); + const producer = new TrackProducer("test").accept({ timescale: Timescale.MILLI }); + try { + const track = producer.subscribe({ maxDelay: Milli(1000) }); + const source = producer.appendGroup(); + source.writeFrame({ payload: enc.encode("a"), timestamp: Timestamp.fromMillis(0) }); + source.close(); - const group = await track.recvGroup(); - if (!group) throw new Error("missing group"); - const closed = group.closed; - expect(closed.peek()).toBeUndefined(); - - const read = await hooks.readGroupFrame(group); - if (!read) throw new Error("missing frame"); - let release!: () => void; - const operation = new Promise((resolve) => { - release = resolve; - }); - const guarded = hooks.guardGroup(group, () => operation); + const group = await track.recvGroup(); + if (!group) throw new Error("missing group"); + expect(await group.readFrame()).toBeDefined(); + expect(await group.readFrame()).toBeUndefined(); + expect(await group.closed).toBeNull(); + expect(group.expired.peek()).toBeUndefined(); - const edge = producer.appendGroup(); - edge.writeFrame({ payload: enc.encode("edge"), timestamp: Timestamp.fromMillis(1_000) }); - // See above: a group is bounded by where its successor begins, so convicting group 0 - // needs a group beyond that successor. - producer.writeFrame({ payload: enc.encode("later"), timestamp: Timestamp.fromMillis(2_000) }); - await expect(guarded).rejects.toThrow("max delay budget"); - expect(await closed).toBeInstanceOf(Error); + // Frozen media time, so only the wall clock since the successor arrived convicts it. + producer.writeFrame({ payload: enc.encode("b"), timestamp: Timestamp.fromMillis(0) }); + const raced = race([new Promise(() => {}), group.expired]); + await settle(); + clock.set(10_999); + await settle(); + expect(group.expired.peek()).toBeUndefined(); - read.complete(); - release(); + clock.set(11_000); + expect(await raced).toMatchObject({ code: StreamCode.Old }); + expect(group.expired.peek()).toMatchObject({ code: StreamCode.Old }); + } finally { + producer.close(); + clock.installed.close(); + } }); test("a drained group finishes cleanly after the live edge advances", async () => { @@ -1285,12 +1279,10 @@ test("an evicted successor with unread frames still starts the wall clock", asyn expect(await group.readString()).toBe("x"); let stale = false; - const guarded = hooks - .guardGroup(group, () => new Promise(() => {})) - .catch((err: unknown) => { - stale = true; - return err; - }); + const guarded = race([new Promise(() => {}), group.expired]).then((err) => { + stale = true; + return err; + }); write(); // the successor, left unread await settle(); // A later live edge, so the successor ages out of the cache. @@ -1325,12 +1317,10 @@ test("a failed successor hands the wall clock on after the cache evicts it", asy expect(await group.readString()).toBe("x"); let stale = false; - const guarded = hooks - .guardGroup(group, () => new Promise(() => {})) - .catch((err: unknown) => { - stale = true; - return err; - }); + const guarded = race([new Promise(() => {}), group.expired]).then((err) => { + stale = true; + return err; + }); const failed = producer.appendGroup(); await settle(); @@ -1743,11 +1733,11 @@ test("subscription updates bound each reader's datagrams", async () => { } }); -test("setGroups with an excluded end of 0 is the empty range and does not ride another subscriber's demand", async () => { +test("withRange with an excluded end of 0 is the empty range and does not ride another subscriber's demand", async () => { const producer = new TrackProducer("test"); const everything = producer.subscribe({ maxDelay: Milli(5000) }); const empty = producer.subscribe({ maxDelay: Milli(5000), groups: { end: { excluded: 0 } } }); - empty.setGroups({ end: { excluded: 0 } }); + empty.withRange({ end: { excluded: 0 } }); for (let sequence = 0; sequence < 3; sequence++) producer.writeGroup(new GroupProducer(sequence)); @@ -1755,34 +1745,34 @@ test("setGroups with an excluded end of 0 is the empty range and does not ride a const pending = empty.recvGroup(); expect(await Promise.race([pending, Promise.resolve("pending")])).toBe("pending"); - empty.setGroups({ end: { excluded: 2 } }); + empty.withRange({ end: { excluded: 2 } }); expect((await pending)?.sequence).toBe(0); expect((await empty.recvGroup())?.sequence).toBe(1); - empty.setGroups({}); + empty.withRange({}); expect((await empty.recvGroup())?.sequence).toBe(2); }); -test("setGroups caps the live edge used by the latency budget", async () => { +test("withRange caps the live edge used by the latency budget", async () => { const producer = new TrackProducer("test").accept({ timescale: Timescale.MILLI, maxAge: Milli(5000) }); const track = producer.subscribe(); - track.setGroups({ end: { excluded: 2 } }); + track.withRange({ end: { excluded: 2 } }); for (const timestamp of [0, 1000, 2000]) { producer.writeFrame({ payload: enc.encode(`${timestamp}`), timestamp: Timestamp.fromMillis(timestamp) }); } expect((await track.recvGroup())?.sequence).toBe(1); - track.setGroups({}); + track.withRange({}); expect((await track.recvGroup())?.sequence).toBe(2); }); // The frame helpers ride the group cursor, so its bounds apply to them too: a group // above the cap parks (surviving a clean close) until the cap admits it. -test("setGroups caps frame-level reads like the group cursor", async () => { +test("withRange caps frame-level reads like the group cursor", async () => { const producer = new TrackProducer("test").accept({ timescale: Timescale.MILLI, maxAge: Milli(5000) }); const track = producer.subscribe({ maxDelay: Milli(5000) }).ordered(); - track.setGroups({ end: { excluded: 1 } }); + track.withRange({ end: { excluded: 1 } }); producer.writeFrame({ payload: enc.encode("zero"), timestamp: Timestamp.fromMillis(0) }); producer.writeFrame({ payload: enc.encode("one"), timestamp: Timestamp.fromMillis(1) }); @@ -1796,7 +1786,7 @@ test("setGroups caps frame-level reads like the group cursor", async () => { expect(await Promise.race([parked, timeout])).toBe("pending"); // Raising the cap releases the parked group, frames intact. - track.setGroups({ end: { excluded: 2 } }); + track.withRange({ end: { excluded: 2 } }); expect((await parked)?.group).toBe(1); expect(await track.readFrame()).toBeUndefined(); }); @@ -1807,16 +1797,14 @@ test("local cursor bounds can skip, pause, and release buffered groups", async ( for (let sequence = 0; sequence < 5; sequence++) producer.writeGroup(new GroupProducer(sequence)); - track.setGroups({ start: { included: 1 } }); - track.setGroups({ end: { excluded: 3 } }); + track.withRange({ start: { included: 1 }, end: { excluded: 3 } }); expect((await track.nextGroup())?.sequence).toBe(1); expect((await track.nextGroup())?.sequence).toBe(2); const pending = track.nextGroup(); expect(await Promise.race([pending, Promise.resolve("pending")])).toBe("pending"); - track.setGroups({ start: { included: 4 } }); - track.setGroups({ end: { excluded: 5 } }); + track.withRange({ start: { included: 4 }, end: { excluded: 5 } }); expect((await pending)?.sequence).toBe(4); }); @@ -1840,15 +1828,15 @@ test("recvGroup serves a late arrival after a newer group", async () => { expect(await track.recvGroup()).toBeUndefined(); }); -// recvGroup honors the setGroups cap by parking, like nextGroup: beyond-cap groups are +// recvGroup honors the withRange cap by parking, like nextGroup: beyond-cap groups are // held, not dropped, and a raised cap re-offers them, even after a clean close. -test("setGroups parks recvGroup beyond the cap and a raised cap re-offers", async () => { +test("withRange parks recvGroup beyond the cap and a raised cap re-offers", async () => { const producer = new TrackProducer("test"); const track = producer.subscribe({ maxDelay: Milli(5000) }); for (let sequence = 0; sequence < 3; sequence++) producer.writeGroup(new GroupProducer(sequence)); - track.setGroups({ end: { excluded: 2 } }); + track.withRange({ end: { excluded: 2 } }); expect((await track.recvGroup())?.sequence).toBe(0); expect((await track.recvGroup())?.sequence).toBe(1); @@ -1861,7 +1849,7 @@ test("setGroups parks recvGroup beyond the cap and a raised cap re-offers", asyn "parked", ); - track.setGroups({}); + track.withRange({}); expect((await pending)?.sequence).toBe(2); expect(await track.recvGroup()).toBeUndefined(); }); @@ -1872,7 +1860,7 @@ test("recvGroup serves in-range groups that arrive behind a capped one", async ( const producer = new TrackProducer("test"); const track = producer.subscribe({ maxDelay: Milli(5000) }); - track.setGroups({ end: { excluded: 2 } }); + track.withRange({ end: { excluded: 2 } }); // Reordered burst: the beyond-cap group arrives first. producer.writeGroup(new GroupProducer(2)); @@ -1885,23 +1873,22 @@ test("recvGroup serves in-range groups that arrive behind a capped one", async ( const pending = track.recvGroup(); expect(await Promise.race([pending, Promise.resolve("pending")])).toBe("pending"); - track.setGroups({ end: { excluded: 3 } }); + track.withRange({ end: { excluded: 3 } }); expect((await pending)?.sequence).toBe(2); }); -// A raised setGroups drops parked groups it overtook instead of re-offering them -// once the cap rises. -test("setGroups drops groups recvGroup parked at the cap", async () => { +// A raised floor drops parked groups it overtook instead of re-offering them once the cap +// rises. +test("withRange drops groups recvGroup parked at the cap", async () => { const producer = new TrackProducer("test"); const track = producer.subscribe(); - track.setGroups({ end: { excluded: 1 } }); + track.withRange({ end: { excluded: 1 } }); producer.writeGroup(new GroupProducer(1)); const pending = track.recvGroup(); expect(await Promise.race([pending, Promise.resolve("pending")])).toBe("pending"); - track.setGroups({ start: { included: 2 } }); - track.setGroups({}); + track.withRange({ start: { included: 2 } }); producer.writeGroup(new GroupProducer(2)); // The overtaken parked group is dropped, not re-offered. @@ -1946,7 +1933,7 @@ test("closing the subscriber releases a recvGroup parked after a clean close", a const producer = new TrackProducer("test"); const track = producer.subscribe(); - track.setGroups({ end: { excluded: 1 } }); + track.withRange({ end: { excluded: 1 } }); producer.writeGroup(new GroupProducer(1)); const pending = track.recvGroup(); @@ -1963,7 +1950,7 @@ test("closing the subscriber releases a recvGroup parked while the producer is l const producer = new TrackProducer("test"); const track = producer.subscribe(); - track.setGroups({ end: { excluded: 1 } }); + track.withRange({ end: { excluded: 1 } }); producer.writeGroup(new GroupProducer(1)); const pending = track.recvGroup(); @@ -2049,7 +2036,7 @@ test("a closed track still delivers a group parked above the cap once the cap is producer.writeGroup(group); } - track.setGroups({ end: { excluded: 2 } }); + track.withRange({ end: { excluded: 2 } }); expect((await track.nextGroup())?.sequence).toBe(0); expect((await track.nextGroup())?.sequence).toBe(1); @@ -2060,7 +2047,7 @@ test("a closed track still delivers a group parked above the cap once the cap is expect(await Promise.race([parked, timeout])).toBe("pending"); // Raising the cap after close releases the buffered group, frames intact. - track.setGroups({ end: { excluded: 3 } }); + track.withRange({ end: { excluded: 3 } }); const released = await parked; expect(released?.sequence).toBe(2); expect(await released?.readString()).toBe("frame-2"); @@ -2273,17 +2260,17 @@ test("largest reports only within the bounds", async () => { const producer = new TrackProducer("test").accept({}); for (let sequence = 0; sequence < 6; sequence++) framedGroup(producer, sequence, 2); - const capped = producer.subscribe().withGroups({ end: { excluded: 3 } }); + const capped = producer.subscribe().withRange({ end: { excluded: 3 } }); expect(await isPending(capped.largest())).toBe(true); // An inclusive cap reports the group it names. const ordered = producer .subscribe() .ordered() - .withGroups({ end: { included: 5 } }); + .withRange({ end: { included: 5 } }); expect(await ordered.largest()).toEqual({ group: 5, frame: 1 }); - const floored = producer.subscribe().withGroups({ start: { included: 8 } }); + const floored = producer.subscribe().withRange({ start: { included: 8 } }); const next = floored.largest(); expect(await isPending(next)).toBe(true); framedGroup(producer, 8, 0); @@ -2300,23 +2287,23 @@ test("largest follows the bounds as they move", async () => { const reader = producer .subscribe() .ordered() - .withGroups({ end: { excluded: 3 } }); + .withRange({ end: { excluded: 3 } }); let next = reader.largest(); expect(await isPending(next)).toBe(true); - reader.setGroups({}); + reader.withRange({}); expect(await next).toEqual({ group: 5, frame: 0 }); next = reader.largest(); expect(await isPending(next)).toBe(true); - reader.setGroups({ end: { excluded: 2 } }); + reader.withRange({ end: { excluded: 2 } }); expect(await isPending(next)).toBe(true); // Lifting it again leaves the last report standing. - reader.setGroups({}); + reader.withRange({}); expect(await isPending(next)).toBe(true); framedGroup(producer, 6, 0); expect(await next).toEqual({ group: 6, frame: 0 }); - reader.setGroups({ start: { included: 3 } }); + reader.withRange({ start: { included: 3 } }); expect(await isPending(reader.largest())).toBe(true); producer.close(); }); @@ -2328,9 +2315,9 @@ test("largest stays ended when the bounds widen", async () => { framedGroup(producer, 5, 1).close(); producer.close(); - const reader = producer.subscribe().withGroups({ end: { excluded: 3 } }); + const reader = producer.subscribe().withRange({ end: { excluded: 3 } }); expect(await reader.largest()).toBeUndefined(); - reader.setGroups({}); + reader.withRange({}); expect(await reader.largest()).toBeUndefined(); }); @@ -2346,7 +2333,7 @@ test("a live-edge reader starts on an empty largest group", async () => { const reader = producer.subscribe({ maxDelay: Milli(30_000) }); const edge = await reader.largest(); expect(edge).toEqual({ group: 1, frame: 0 }); - reader.setGroups({ start: { included: edge?.group ?? 0 } }); + reader.withRange({ start: { included: edge?.group ?? 0 } }); empty.close(); const next = producer.appendGroup(); @@ -2381,39 +2368,87 @@ test("group ranges preserve progress and spell out inclusion", async () => { const producer = new TrackProducer("test"); const track = producer .subscribe({ maxDelay: Milli(5000) }) - .withGroups({ start: { included: 1 }, end: { included: 1 } }); + .withRange({ start: { included: 1 }, end: { included: 1 } }); for (let sequence = 0; sequence < 4; sequence++) producer.writeGroup(new GroupProducer(sequence)); expect(track.tryRecvGroup()?.sequence).toBe(1); expect(track.tryRecvGroup()).toBeUndefined(); - track.setGroups({ end: { excluded: 3 } }); + track.withRange({ start: { included: 1 }, end: { excluded: 3 } }); expect(track.tryRecvGroup()?.sequence).toBe(2); expect(track.tryRecvGroup()).toBeUndefined(); - track.setGroups({ start: { included: 0 } }); + track.withRange({ start: { included: 1 } }); expect(track.tryRecvGroup()?.sequence).toBe(3); track.close(); }); -test("serving replaceGroups can lower the floor that setGroups keeps", () => { +// Mirrors the Rust `a_lowered_range_reoffers_the_unread_cached_groups`. +test("a lowered range re-offers the unread cached groups", () => { const producer = new TrackProducer("test"); - const kept = producer.subscribe({ maxDelay: Milli(5000), groups: { start: { included: 10 } } }); - const lowered = producer.subscribe({ maxDelay: Milli(5000), groups: { start: { included: 10 } } }); + const track = producer.subscribe({ maxDelay: Milli(5000), groups: { start: { included: 10 } } }); for (const sequence of [5, 6, 10]) producer.writeGroup(new GroupProducer(sequence)); + expect(track.tryRecvGroup()?.sequence).toBe(10); + expect(track.tryRecvGroup()).toBeUndefined(); - kept.setGroups({ start: { included: 5 } }); - expect(kept.tryRecvGroup()?.sequence).toBe(10); + track.withRange({ start: { included: 6 } }); + expect(track.tryRecvGroup()?.sequence).toBe(6); + track.withRange({ end: { included: 5 } }); + expect(track.tryRecvGroup()?.sequence).toBe(5); + track.withRange({}); + expect(track.tryRecvGroup()).toBeUndefined(); + producer.writeGroup(new GroupProducer(11)); + expect(track.tryRecvGroup()?.sequence).toBe(11); + track.close(); +}); - hooks.replaceGroups(lowered, { start: { included: 5 } }); - expect(lowered.tryRecvGroup()?.sequence).toBe(5); - expect(lowered.tryRecvGroup()?.sequence).toBe(6); - kept.close(); - lowered.close(); +test("a lowered range re-offers a cached cut with its error", async () => { + const producer = new TrackProducer("test"); + const track = producer.subscribe({ maxDelay: Milli(5000), groups: { start: { included: 1 } } }); + const cut = new GroupProducer(0); + producer.writeGroup(cut); + const error = new StreamError(StreamCode(70), { message: "cut" }); + cut.close(error); + producer.writeGroup(new GroupProducer(1)); + expect(track.tryRecvGroup()?.sequence).toBe(1); + + track.withRange({}); + const group = track.tryRecvGroup(); + expect(group?.sequence).toBe(0); + await expect(group?.readString()).rejects.toBe(error); + track.close(); + producer.close(); }); +test("a lowered range still re-offers after the producer closes", () => { + const producer = new TrackProducer("test"); + const track = producer.subscribe({ maxDelay: Milli(5000), groups: { start: { included: 1 } } }); + for (const sequence of [0, 1]) producer.writeGroup(new GroupProducer(sequence)); + expect(track.tryRecvGroup()?.sequence).toBe(1); + producer.close(); + + track.withRange({}); + expect(track.tryRecvGroup()?.sequence).toBe(0); + expect(hooks.tryRecvGroup(track, false)).toEqual({ kind: "done" }); + track.close(); +}); + +for (const abort of [undefined, new Error("gone")]) { + test(`a lowered range offers nothing to a reader that ${abort ? "aborted" : "closed"}`, () => { + const producer = new TrackProducer("test"); + const track = producer.subscribe({ maxDelay: Milli(5000), groups: { start: { included: 1 } } }); + for (const sequence of [0, 1]) producer.writeGroup(new GroupProducer(sequence)); + expect(track.tryRecvGroup()?.sequence).toBe(1); + track.close(abort); + + track.withRange({}); + expect(hooks.tryRecvGroup(track, false)).toEqual(abort ? { kind: "error", error: abort } : { kind: "done" }); + producer.close(); + }); +} + test("malformed group bounds do not partially advance the cursor", () => { const producer = new TrackProducer("test"); const track = producer.subscribe({ maxDelay: Milli(5000) }); producer.writeGroup(new GroupProducer(0)); - expect(() => track.setGroups({ start: { included: 3 }, end: { excluded: -1 } })).toThrow(); + expect(() => track.withRange({ start: { included: 3 }, end: { excluded: -1 } })).toThrow(); expect(track.tryRecvGroup()?.sequence).toBe(0); track.close(); }); @@ -2752,7 +2787,7 @@ test("an abort leaves a group already taken readable, then reports the abort", a }); /** Every group a subscriber can take right now, by sequence. */ -function drain(track: { tryRecvGroup(): { sequence: number } | undefined }): number[] { +function drain(track: { tryRecvGroup(): GroupConsumer | undefined }): number[] { const sequences: number[] = []; for (let group = track.tryRecvGroup(); group; group = track.tryRecvGroup()) sequences.push(group.sequence); return sequences; @@ -2879,7 +2914,7 @@ test("an untimed subscriber without a start begins at the latest group under its const producer = untimedTrack(5); // As the lite publisher serves a SUBSCRIBE with an end and no start. const subscriber = producer.subscribe({ groups: { end: { excluded: 3 } } }); - subscriber.setGroups({ end: { excluded: 3 } }); + subscriber.withRange({ end: { excluded: 3 } }); expect(drain(subscriber)).toEqual([2]); }); @@ -2996,7 +3031,7 @@ test("a drop below the window is reported once the window lowers to it", () => { producer.dropGroups(2, 3, DROPPED); expect(hooks.tryRecvGroup(reader, true)).toEqual({ kind: "idle" }); - hooks.replaceGroups(reader, { start: { included: 0 } }); + reader.withRange({ start: { included: 0 } }); expect(hooks.tryRecvGroup(reader, true)).toEqual({ kind: "drop", start: 2, end: 3, error: DROPPED }); reader.close(); @@ -3071,7 +3106,7 @@ test("a mid-group end survives eviction and a filtered late reader", async () => await clock.advance(10_000 + CACHE_WINDOW_MS + 1); expect(await producer.subscribe().largest()).toEqual({ group: 5, frame: 4 }); // The cap excludes the only group, so nothing is within it. - const reader = producer.subscribe().withGroups({ end: { excluded: 5 } }); + const reader = producer.subscribe().withRange({ end: { excluded: 5 } }); expect(await reader.largest()).toBeUndefined(); expect(reader.end()).toEqual({ group: 5, frame: 5 }); reader.close(); diff --git a/js/net/src/track.ts b/js/net/src/track.ts index 1e825df913b..c82000211bf 100644 --- a/js/net/src/track.ts +++ b/js/net/src/track.ts @@ -46,6 +46,17 @@ import { type Broadcast as BroadcastWire, registerTrackConsumer } from "./wire.t export type { Datagram } from "./datagram.ts"; +// The group a non-blocking read takes, skipping drops and throwing the track's error; +// `undefined` when nothing is deliverable now. +function taken(read: () => Recv): GroupConsumer | undefined { + for (;;) { + const recv = read(); + if (recv.kind === "group") return recv.group; + if (recv.kind === "error") throw recv.error; + if (recv.kind !== "drop") return undefined; + } +} + // Wall-clock bound for idle cached content, matching Rust cache::DEFAULT_EXPIRY. // Media maxDelay only bounds how far behind the live edge a reader may fall. const CACHE_WINDOW = Nano.fromMilli(Milli(30_000)); @@ -624,6 +635,16 @@ let bindProducerSequence: (producer: Producer, sequence: TrackSequence) => void; let cachedMirror: (producer: Producer, sequence: number) => GroupConsumer | undefined; // Whether the producer still caches a group that has not failed; assigned in its static block. let cachedHolds: (producer: Producer, sequence: number) => boolean; +// Mirror the cached groups in `[start, end)` that `offer` accepts into a sink again, cut ones +// included as a fresh sink gets them, for a reader whose floor moved below them; assigned in +// the producer's static block. +let reofferCached: ( + producer: Producer, + sink: TrackState, + start: number, + end: number, + offer: (sequence: number) => boolean, +) => void; // Whether a group may still land on the producer's live feed; assigned in its static block. let mayLand: (producer: Producer, land: Land) => boolean; let sourceStart: (producer: Producer) => number | "pending" | undefined; @@ -634,6 +655,7 @@ let sourceStart: (producer: Producer) => number | "pending" | undefined; let makeOrdered: (subscriber: Subscriber) => Ordered; let ordered_: { nextGroup(subscriber: Subscriber): Promise; + tryNextGroup(subscriber: Subscriber): Recv; readFrame(subscriber: Subscriber): Promise<({ group: number; frame: number } & Frame) | undefined>; readString(subscriber: Subscriber): Promise; readJson(subscriber: Subscriber): Promise; @@ -843,6 +865,14 @@ export class Producer { hooks.arriveGroup(mirror, entry.arrived); return mirror; }; + reofferCached = (producer, sink, start, end, offer) => { + const held = new Set(sink.groups.peek().map((group) => group.sequence)); + for (const entry of producer.#cache) { + const sequence = entry.group.sequence; + if (sequence < start || sequence >= end || held.has(sequence) || !offer(sequence)) continue; + producer.#mirror(entry, sink); + } + }; mayLand = (producer, land) => producer.#mayLand(land); } @@ -1807,6 +1837,9 @@ export class Subscriber { // Every group sequence this reader handed out, so a re-created group or one a second route // delivers is handed out once. #delivered = new Delivered(); + // This reader closed itself, so lowering its floor offers nothing: a producer's clean close + // alone leaves the cache readable, but the reader leaving must stay terminal. + #closed = false; // What {@link largest} last reported, and whether it ended: moving the bounds afterwards // does not bring it back. #largestSeen?: Position; @@ -1837,6 +1870,10 @@ export class Subscriber { revision: new Signal(0), at: Number.POSITIVE_INFINITY, }; + // When each group the timeline held at close arrived, failed ones left out. A group handed + // out earlier can outlive this subscriber, as one a resumed reader still writes from a copy + // it let go of, and its budget still runs from its successor's arrival. + #arrivals?: { sequence: number; arrived: Instant }[]; #drift(): Drift { const { end } = this.#cursor.peek(); @@ -1925,15 +1962,20 @@ export class Subscriber { // group has no successor, so neither clock ever convicts it. `wake` arms a timer for the // wall deadline, for a held read that waits on it. // - // Judged by its successor alone, so the group need not be in this track: evicted, or held - // from another copy. + // Judged by its successor alone, so the group need not be in this track: evicted, held + // from another copy, or outliving this subscriber. Once closed, only the wall clock judges + // it, from the arrivals kept at close. #staleAt(sequence: number, drift: Drift, wake = false, held?: Superseded): boolean { - const arrived = this.#supersededAt(this.#arrival(sequence, drift.end), drift, held); + const arrived = this.#arrivals + ? this.#keptSupersededAt(sequence, drift, held) + : this.#supersededAt(this.#arrival(sequence, drift.end), drift, held); if (arrived === undefined) return false; // Plain arithmetic: an unenforced budget is infinite, which no duration brand holds. const deadline = arrived + drift.budget * 1_000_000; if (now() >= deadline) return true; if (wake) this.#wakeAt(deadline); + // A closed subscriber keeps no timeline to bound the reach with. + if (this.#arrivals) return false; const successor = this.#successor(sequence, drift.end); if (!successor) return false; @@ -1973,6 +2015,23 @@ export class Subscriber { return arrived; } + // {@link #supersededAt} for a closed subscriber, with the arrivals kept at close standing in + // for the timeline it cleared. + #keptSupersededAt(sequence: number, drift: Drift, held?: Superseded): Instant | undefined { + const covered = (candidate: number) => drift.end === undefined || candidate < drift.end; + const kept = this.#arrivals?.find((entry) => entry.sequence > sequence && covered(entry.sequence)); + const recorded = held?.successor; + if ( + recorded && + !failed(recorded) && + covered(recorded.sequence) && + (!kept || kept.sequence > recorded.sequence) + ) { + return recorded.arrived; + } + return kept?.arrived; + } + // Bump {@link #wall} at `at`, unless a wakeup is already armed sooner. Each held read // re-arms on the bump, so one timer covers every deadline this subscriber waits on. #wakeAt(at: number): void { @@ -2057,7 +2116,7 @@ export class Subscriber { if (start === undefined || start === "pending") return start; return Math.max(start, subscriber.#cursor.peek().start); }; - hooks.tryRecvGroup = (subscriber, started) => subscriber.#tryRecvGroup(started); + hooks.tryRecvGroup = (subscriber, dispositions) => subscriber.#tryRecvGroup(dispositions); hooks.tryNextGroup = (subscriber) => subscriber.#tryNextGroup(); hooks.peekGroup = (subscriber, ordered) => subscriber.#peekGroup(ordered); hooks.forgetPastBudget = (subscriber, delivered) => subscriber.#forgetPastBudget(delivered); @@ -2178,11 +2237,11 @@ export class Subscriber { hooks.fetchBudget = (subscriber, maxDelay) => { subscriber.#fetchBudget = maxDelay ?? Number.POSITIVE_INFINITY; }; - hooks.replaceGroups = (subscriber, groups) => subscriber.#replaceGroups(groups); // The sequence cursor lives here (it shares the buffer and the drift anchor with // the arrival cursor); `Ordered` is the handle that reaches it. ordered_ = { nextGroup: (subscriber) => subscriber.#nextGroup(), + tryNextGroup: (subscriber) => subscriber.#tryNextGroup(), readFrame: (subscriber) => subscriber.#readFrame(), readString: (subscriber) => subscriber.#readString(), readJson: (subscriber) => subscriber.#readJson(), @@ -2252,7 +2311,7 @@ export class Subscriber { } /** - * The largest location within {@link setGroups}: the current one at first, then each newer + * The largest location within {@link withRange}: the current one at first, then each newer * one (skipping any in between), and `undefined` once the track ends. * * The largest is the track's newest group or datagram at the newest frame (0 while empty), as @@ -2326,37 +2385,41 @@ export class Subscriber { return producer.subscribe(options); } - /** Limit subsequent reads to these groups and return this reader for chaining. */ - withGroups(groups: Groups): this { - this.setGroups(groups); - return this; - } - /** - * Limit subsequent reads without rewinding read progress or changing the wire request. - * An omitted start preserves the current floor; an omitted end removes the cap. - * Raising the end makes unread buffered groups available again. - * {@link largest} reports within these bounds. + * Limit subsequent reads to these groups and return this reader for chaining. Mirrors the + * Rust `with_range`. + * + * Both bounds are assigned, in either direction: an omitted start is group 0 and an + * omitted end removes the cap. Lowering the floor or raising the cap offers the groups it + * newly covers that the track still caches and this reader never handed out; a group is + * never handed out twice. A local filter, not a request: it leaves the wire subscription + * alone. {@link largest} reports within these bounds. */ - setGroups(groups: Groups): void { - const { start, end } = groupBounds(groups); - this.#cursor.update((cursor) => ({ start: Math.max(cursor.start, start), end })); - } - - // Serving counterpart of setGroups: a named start replaces the floor, matching - // Rust `start_at`. Local readers stay monotonic; only the wire publisher lowers. - #replaceGroups(groups: Groups): void { + withRange(groups: Groups): this { const { start, end } = groupBounds(groups); - this.#cursor.update((cursor) => ({ - start: groups.start === undefined ? cursor.start : start, - end, - })); + const before = this.#cursor.peek(); + this.#cursor.set({ start, end }); + const producer = this.#state.producer; + if (!this.#resume && !this.#closed && producer && start < before.start) { + // The ordered cursor let go of what it passed below the old floor; the arrival + // cursor keeps it buffered, which this skips. + reofferCached(producer, this.#state, start, before.start, (sequence) => !this.#delivered.has(sequence)); + } + return this; } /** Close the track (optionally with an error), closing any pending groups. Idempotent. */ close(abort?: Error) { + if (!this.#closed) { + const arrivals = this.#state.timeline.filter((group) => !(group.closed.peek() instanceof Error)); + this.#arrivals = arrivals.map((group) => ({ + sequence: group.sequence, + arrived: hooks.groupArrived(group), + })); + } + this.#closed = true; // Settle if we're first (the producer may already have); either way drop anything - // still buffered. Groups parked at the setGroups cap deliberately outlive a clean + // still buffered. Groups parked at the withRange cap deliberately outlive a clean // producer close, so the subscriber leaving is what must release them: closing // and clearing wakes a pending read to observe the end instead of hanging. closeTrackState(this.#state, abort); @@ -2370,6 +2433,8 @@ export class Subscriber { this.#state.timeline.length = 0; this.#wall.timer?.abort(); this.#wall.timer = undefined; + // A deadline kept in #arrivals may still arm a wakeup. + this.#wall.at = Number.POSITIVE_INFINITY; } /** @@ -2380,7 +2445,7 @@ export class Subscriber { * is still delivered. When several groups are buffered, the lowest sequence is * returned first. * - * Honors the range set by {@link setGroups}: a group + * Honors the range set by {@link withRange}: a group * beyond the cap stays buffered (not dropped) and is offered once the cap rises, even * after a clean close, without blocking in-range groups that arrive behind it. * A group whose presentation time is further behind the live edge than this @@ -2550,16 +2615,13 @@ export class Subscriber { * * Returns `undefined` when nothing is deliverable right now, which is not by itself the * end of the track: a group may still arrive, or one may be parked beyond the - * {@link setGroups} cap. Use it to drain what the retained window already holds, where + * {@link withRange} cap. Use it to drain what the retained window already holds, where * waiting for a sequence nothing will republish would park forever. */ tryRecvGroup(): GroupConsumer | undefined { this.#live(); this.#mode = "arrival"; - const recv = this.#tryRecvGroup(); - if (recv.kind === "group") return recv.group; - if (recv.kind === "error") throw recv.error; - return undefined; + return taken(() => this.#tryRecvGroup()); } /** @@ -2632,12 +2694,6 @@ export class Subscriber { const recv = this.#tryNextGroup(); switch (recv.kind) { case "group": - // One cursor: the frame helpers must not keep draining a group this - // read just moved past, or interleaved reads would run backwards. - if (this.#frameGroup && this.#frameGroup.sequence < recv.group.sequence) { - this.#frameGroup.close(); - this.#frameGroup = undefined; - } return recv.group; case "done": return undefined; @@ -2664,7 +2720,17 @@ export class Subscriber { // The synchronous half of #nextGroup. #tryNextGroup(): Recv { - if (this.#resume) return this.#tryResumed(true); + const recv = this.#resume ? this.#tryResumed(true) : this.#tryNextBuffered(); + // One cursor: the frame helpers must not keep draining a group this read just + // moved past, or interleaved reads would run backwards. + if (recv.kind === "group" && this.#frameGroup && this.#frameGroup.sequence < recv.group.sequence) { + this.#frameGroup.close(); + this.#frameGroup = undefined; + } + return recv; + } + + #tryNextBuffered(): Recv { const groups = this.#state.groups.peek(); const cursor = this.#cursor.peek(); const start = Math.max(cursor.start, this.#nextSequence); @@ -2849,7 +2915,7 @@ export class Ordered { return this.#subscriber.subscription; } - /** The largest location within {@link setGroups}; see {@link Subscriber.largest}. */ + /** The largest location within {@link withRange}; see {@link Subscriber.largest}. */ largest(): Promise { return this.#subscriber.largest(); } @@ -2864,17 +2930,16 @@ export class Ordered { return this.#subscriber.finished(); } - /** Limit subsequent reads to these groups and return this reader for chaining. */ - withGroups(groups: Groups): this { - this.setGroups(groups); + /** + * Limit subsequent reads to these groups and return this reader for chaining; see + * {@link Subscriber.withRange}. An ordered read never goes back, so lowering the floor + * below a group it already returned offers nothing. + */ + withRange(groups: Groups): this { + this.#subscriber.withRange(groups); return this; } - /** Limit subsequent reads to these groups; see {@link Subscriber.setGroups}. */ - setGroups(groups: Groups): void { - this.#subscriber.setGroups(groups); - } - /** Update this subscription's options; see {@link Subscriber.update}. */ update(options: Subscription) { this.#subscriber.update(options); @@ -2891,12 +2956,20 @@ export class Ordered { * Late arrivals (sequence at or below the last returned) are silently skipped, as is a * group whose every frame is further behind the live edge than `maxDelay` (the default of * zero keeps only what nothing newer has superseded). Honors the bounds set by - * {@link setGroups}. + * {@link withRange}. */ nextGroup(): Promise { return ordered_.nextGroup(this.#subscriber); } + /** + * Take the next group as {@link nextGroup} would, without waiting; see + * {@link Subscriber.tryRecvGroup}. Mirrors the Rust `poll_next_group`. + */ + tryNextGroup(): GroupConsumer | undefined { + return taken(() => ordered_.tryNextGroup(this.#subscriber)); + } + /** * Read the next frame across groups, in sequence order, with its group and frame numbers. * diff --git a/js/net/src/util/given_up.ts b/js/net/src/util/given_up.ts new file mode 100644 index 00000000000..3c9db18a2aa --- /dev/null +++ b/js/net/src/util/given_up.ts @@ -0,0 +1,27 @@ +import { race } from "@moq/signals"; +import type { Consumer as GroupConsumer } from "../group.ts"; + +// Why to stop writing `group`: the subscription's budget gave it up, or it failed for good +// before it was read whole (evicted, or its copy aborted with no route to continue it). +function reason(group: GroupConsumer): Error | undefined { + const closed = group.closed.peek(); + return group.expired.peek() ?? (closed instanceof Error ? closed : undefined); +} + +/** + * Run a publisher's write of `group`, settling with why to stop it instead if that comes + * first: `expired`, or `closed` with an error. A clean close is no reason, and a group + * already given up never starts the write. Rejects if the write does. Mirrors the Rust + * publishers' `poll_given_up`. + */ +export async function untilGivenUp(group: GroupConsumer, write: () => Promise): Promise { + let stop = reason(group); + if (stop) return stop; + const done = write().then(() => true as const); + for (;;) { + const closed = group.closed.peek() === undefined ? [group.closed] : []; + if ((await race([done, group.expired, ...closed])) === true) return undefined; + stop = reason(group); + if (stop) return stop; + } +} diff --git a/js/room/src/chat.ts b/js/room/src/chat.ts index 69193d60a39..a07d44ee924 100644 --- a/js/room/src/chat.ts +++ b/js/room/src/chat.ts @@ -88,7 +88,7 @@ export class Subscriber { this.#track = track; this.#consumer = new Json.Window.Consumer({ track }); this.#positioned = track.largest().then((largest) => { - if (largest) track.setGroups({ start: { included: largest.group } }); + if (largest) track.withRange({ start: { included: largest.group } }); }); } diff --git a/quest/m1/README.md b/quest/m1/README.md index 9525ce400bd..db621560e1f 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -147,6 +147,8 @@ Binding durations wait on Duration support in the generated C. - [TS fidelity and recovery](/quest/m1/ts-reliability/README.md) - both modes have explicit profiles, automated validation, loss tests, and a dedicated guide - [Encoders declare no reordering](/quest/m1/encoder-reorder.md) - moq-video encoders publish `reorder: 0` - [Rust resume checks compression](/quest/m1/resume-compress.md) - a same-epoch route copy with a different `compress` is refused instead of corrupting framing +- [JS resume reports drops](/quest/m1/resume-drops.md) - a routed JS subscriber reports its copies' dropped groups, so publishers forward SUBSCRIBE_DROP +- [Lowered resume floor](/quest/m1/resume-floor.md) - lowering a resumed reader's floor re-offers groups only a released copy cached - [WebGPU on Safari](/quest/m1/webgpu-safari.md) - the WebGPU renderer is verified on Safari 26 for macOS and iOS - [JSON encoder options without a downcast](/quest/m1/json-encoder-options.md) - moq-mux's `json_snapshot` takes its `deltas` switch through a typed path any custom catalog entry can use, not an `Any` downcast - [CI housekeeping](/quest/m1/ci-housekeeping.md) - validate queue nextest at 24 threads and remove the actionlint queue ignore after its release diff --git a/quest/m1/api-audit/README.md b/quest/m1/api-audit/README.md index 197ec219bac..81d53801b73 100644 --- a/quest/m1/api-audit/README.md +++ b/quest/m1/api-audit/README.md @@ -78,7 +78,6 @@ Rejected in planning: - [Transport config](/quest/m1/api-audit/transport-config.md) - moq-tokio and moq-quic configs have one meaning for unset, enums for modes, no order-dependent setters, and no leftover features - [Session-only items stay private](/quest/m1/api-audit/model-private.md) - model items only the built-in sessions use are private - [Only sessions accept a request](/quest/m1/api-audit/claim-request-type.md) - accepting an application claim's request fails to compile, and the peer-route hatches are crate-private -- [One range setter](/quest/m1/api-audit/serve.md) - `with_range` replaces seven cursor setters and nothing else of the serving cursor goes public - [A request's source enforces its validity](/quest/m1/api-audit/answer.md) - a stale source refuses new track requests by itself, with no public additions - [moq-transport stays private](/quest/m1/api-audit/ietf-private.md) - no public moq-net item exists only for moq-transport, and a client names its request target once as a URL - [One lifecycle vocabulary](/quest/m1/api-audit/lifecycle.md) - finish, abort, closed, and close mean one thing on every handle, and Rust and JS observers fire alike diff --git a/quest/m1/api-audit/serve.md b/quest/m1/api-audit/serve.md deleted file mode 100644 index 0cc48b9f85b..00000000000 --- a/quest/m1/api-audit/serve.md +++ /dev/null @@ -1,31 +0,0 @@ -# [M] One range setter - -## Goal - -A reader moves its cursor with one consuming `with_range(self, range)` (JS -`withRange`) on `track::Subscriber`, `track::Ordered`, `track::Subscription`, -and `group::Consumer`, replacing `set_groups`, `with_groups`, `start_at`, -`raise_start_to`, `end_at`, `subscription::Cap`, and -`group::Consumer::set_frames`. Nothing else becomes public. - -## Plan - -Decided 2026-10-23 (maintainer), reshaping -[moq-dev/moq#6138](https://github.com/moq-dev/moq/pull/6138) after the -public-model goal was dropped -([session-only items stay private](/quest/m1/api-audit/model-private.md)): - -- Keep `with_range` and the bug fixes #6138 carries: js/json and js/flate - `latest()` keeping the caller's cap, `group::Consumer::poll_finished` - ending cleanly at a frame cap, and a closed JS subscriber's groups still - expiring. -- Everything else #6138 made public for custom publishers stays internal: - `track::Subscriber::{poll_start, poll_drop}`, - `group::Consumer::poll_expired`, `Position::final_sequence`, - `Subscription::{start, end, with_start, with_end}`, and the JS `Recv` - union, `groupChanged`, `Ordered.tryNextGroup`, `finalSequence`, - `Consumer.info({ hold })`, and `Group.Consumer.expired`. The sessions call - them through `pub(crate)` and `@internal` (or the existing hooks). - -Public API: moq-net and `@moq/net` breaking (`with_range` replaces the -setters). Wire: none. diff --git a/quest/m1/resume-drops.md b/quest/m1/resume-drops.md new file mode 100644 index 00000000000..935a3fd283d --- /dev/null +++ b/quest/m1/resume-drops.md @@ -0,0 +1,32 @@ +# [S] JS resume reports drops + +## Goal + +The package-internal `hooks.tryRecvGroup(subscriber, true)` on a routed +(resumed) `@moq/net` `Track.Subscriber` reports the groups its copies gave up as a `drop`, as a +direct subscriber does and as the Rust resume reader forwards its serving +copy's `poll_drop`. A lite or IETF publisher serving a routed track then sends +`SUBSCRIBE_DROP` for them instead of leaving its peer waiting on groups that +never arrive. + +## Plan + +Found by Codex on [moq-dev/moq#6138](https://github.com/moq-dev/moq/pull/6138) +and present on `main` before it: `#tryRecvGroup` hands a resumed subscriber to +`#tryResumed`, and `resume.ts` `take()` reads each copy without `drops`, so an +upstream `SUBSCRIBE_DROP` or a budget skip on a copy is consumed silently. + +Open decisions, to settle before implementing: + +- Which copy reports drops across a switch. Recommended: the serving copy + only, as Rust does in `model/resume.rs`. +- Whether a group that failed on one copy but that another copy may still + deliver counts as a drop. Recommended: no, until no copy can deliver it. +- How a reported run joins the resumed reader's delivered record, so a later + copy never serves a group already reported dropped. + +Regression test: a resumed subscriber whose serving copy receives +`SUBSCRIBE_DROP` reports it through `hooks.tryRecvGroup(subscriber, true)`, and a +downstream lite-07 publisher forwards it. + +Public API: behavior only. Wire: none. diff --git a/quest/m1/resume-floor.md b/quest/m1/resume-floor.md new file mode 100644 index 00000000000..a31c0304b8c --- /dev/null +++ b/quest/m1/resume-floor.md @@ -0,0 +1,31 @@ +# [S] A lowered resume floor re-offers a released copy's groups + +## Goal + +Lowering a resumed reader's floor with `with_range` (JS `withRange`) offers +every group below the old floor that some route still caches and the reader +never read, as it does for a direct reader. Today, in Rust, a reader that +switches routes while its floor is high lets go of the replaced copy that +cached the lower groups, so a later lowering re-offers only what the serving +copy holds: `Copy::start` clamps the requested floor to that copy's resume +point. + +## Plan + +Found by Codex on [moq-dev/moq#6138](https://github.com/moq-dev/moq/pull/6138), +which made lowering a floor assign. Its Rust test covers one copy only. + +Open decision, to settle before implementing: + +- Recommended: once the floor drops below a released copy's groups, ask the + serving route for them on demand, rather than keeping every replaced copy + alive in case the floor drops later, which holds memory for a lowering that + may never come. +- Alternative: narrow the `with_range` contract to the copies the reader still + holds, and document it. + +Check the JS resume reader for the same gap, and cover both with a two-copy +test: switch routes with a high floor, release the old copy, lower the floor, +and expect the groups only it cached. + +Public API: behavior only. Wire: none. diff --git a/rs/moq-archive/src/producer/track.rs b/rs/moq-archive/src/producer/track.rs index 7059a8619c7..efd31c775fe 100644 --- a/rs/moq-archive/src/producer/track.rs +++ b/rs/moq-archive/src/producer/track.rs @@ -236,7 +236,7 @@ impl Track { self.push(sequence, 0, frame, true, now)?; self.next = Some(Position::group(sequence + 1)); } - Event::Next(Some((sequence, Item::Group(mut group)))) => { + Event::Next(Some((sequence, Item::Group(group)))) => { // A resumed group continues after its stored frames. The clamp also starts a // group whose head is held elsewhere at its first frame, rather than lagging // behind it. @@ -244,7 +244,7 @@ impl Track { .next .filter(|next| next.group == sequence) .map_or(0, |next| next.frame); - group.set_frames(stored..); + let group = Box::new(group.with_range(stored..)); self.next = Some(Position { group: sequence, frame: group.index(), diff --git a/rs/moq-archive/src/reader/tests.rs b/rs/moq-archive/src/reader/tests.rs index c2716fe5886..6f4e7c4613c 100644 --- a/rs/moq-archive/src/reader/tests.rs +++ b/rs/moq-archive/src/reader/tests.rs @@ -833,7 +833,7 @@ async fn benchmark_timeline_fetch_fanout() { broadcast.info().pool.poll(now, &kio::Waiter::noop()); } let subscription = moq_net::track::Subscription::default() - .with_groups(0..) + .with_range(0..) .with_max_delay(Duration::from_secs(60)); let mut retained = broadcast .consume() diff --git a/rs/moq-audio/src/decode/consumer.rs b/rs/moq-audio/src/decode/consumer.rs index 0e39c7aab22..cf157ebef02 100644 --- a/rs/moq-audio/src/decode/consumer.rs +++ b/rs/moq-audio/src/decode/consumer.rs @@ -207,7 +207,7 @@ impl Consumer { && warmup.is_zero() && let Some(live_edge) = subscriber.largest().await { - subscriber.set_groups(live_edge.group..); + subscriber = subscriber.with_range(live_edge.group..); } let track = subscriber; let retention = track.info().max_age; diff --git a/rs/moq-cli/src/play/media.rs b/rs/moq-cli/src/play/media.rs index 691db14fdc2..2f2cb9dbebb 100644 --- a/rs/moq-cli/src/play/media.rs +++ b/rs/moq-cli/src/play/media.rs @@ -256,7 +256,7 @@ impl Media { // once the feed is live, so wait for it rather than read the backlog of // a warm copy still waiting on its source; the wait ends with the track. if let Some(largest) = subscriber.largest().await { - subscriber.set_groups(largest.group..); + subscriber = subscriber.with_range(largest.group..); } let format = catalog::hang::Container::try_from(config)?; Ok::<_, anyhow::Error>((moq_mux::container::Consumer::new(subscriber, format), decoder)) diff --git a/rs/moq-flate/src/snapshot/consumer.rs b/rs/moq-flate/src/snapshot/consumer.rs index b9f6bcb2a8e..a815fce562e 100644 --- a/rs/moq-flate/src/snapshot/consumer.rs +++ b/rs/moq-flate/src/snapshot/consumer.rs @@ -229,7 +229,7 @@ mod timestamps { .create_track("data", moq_net::track::Info::default()) .unwrap(); let mut subscriber = track.subscribe(None); - subscriber.set_groups(..5); + subscriber = subscriber.with_range(..5); let config = crate::snapshot::Config::default(); let mut producer = crate::snapshot::Producer::new(track, config.clone()); let mut consumer = Consumer::new(subscriber, config); diff --git a/rs/moq-hls/src/export/archive_tests.rs b/rs/moq-hls/src/export/archive_tests.rs index d57ce54fb3e..7643e72c4b0 100644 --- a/rs/moq-hls/src/export/archive_tests.rs +++ b/rs/moq-hls/src/export/archive_tests.rs @@ -815,7 +815,7 @@ impl Expired { .pool .poll(now + Duration::from_secs(31), &kio::Waiter::noop()); let subscription = moq_net::track::Subscription::default() - .with_groups(0..) + .with_range(0..) .with_max_delay(Duration::from_millis((1_u64 << 62) - 1)); let mut retained = broadcast .consume() diff --git a/rs/moq-hls/src/export/history.rs b/rs/moq-hls/src/export/history.rs index 5586906f824..9b934662076 100644 --- a/rs/moq-hls/src/export/history.rs +++ b/rs/moq-hls/src/export/history.rs @@ -34,7 +34,7 @@ pub(super) async fn read( // Effectively unbounded, so no history group is skipped as late: 2^53 - 1 ms is the largest // delay every implementation decodes (js/net reads it as a safe integer). let subscription = moq_net::track::Subscription::default() - .with_groups(0..) + .with_range(0..) .with_max_delay(Duration::from_millis((1_u64 << 53) - 1)); let mut live = track.subscribe(subscription).await?.ordered(); let mut decoder = window::Decoder::::new(window::ConsumerConfig::default().with_compression(true)); diff --git a/rs/moq-hls/src/export/rendition.rs b/rs/moq-hls/src/export/rendition.rs index 3e9d66cbba7..247ab17c116 100644 --- a/rs/moq-hls/src/export/rendition.rs +++ b/rs/moq-hls/src/export/rendition.rs @@ -1354,7 +1354,7 @@ async fn fetch( match track.fetch_group(start.group, options).await { Ok(mut group) => { if let Some(end) = end { - group.set_frames(..end); + group = group.with_range(..end); } Ok(Ok(group)) } diff --git a/rs/moq-json/src/snapshot/consumer.rs b/rs/moq-json/src/snapshot/consumer.rs index defea94d42c..22bb2cbca8c 100644 --- a/rs/moq-json/src/snapshot/consumer.rs +++ b/rs/moq-json/src/snapshot/consumer.rs @@ -296,7 +296,7 @@ mod timestamps { .create_track("data", moq_net::track::Info::default()) .unwrap(); let mut subscriber = track.subscribe(None); - subscriber.set_groups(..5); + subscriber = subscriber.with_range(..5); let mut producer = crate::snapshot::Producer::new(track, crate::snapshot::Config::default()); let mut consumer = Consumer::::new(subscriber, Default::default()); let waiter = kio::Waiter::noop(); diff --git a/rs/moq-json/src/window/mod.rs b/rs/moq-json/src/window/mod.rs index 54eda8b8757..fbbbc8eca5c 100644 --- a/rs/moq-json/src/window/mod.rs +++ b/rs/moq-json/src/window/mod.rs @@ -129,7 +129,7 @@ mod test { .create_track("test", timed()) .unwrap(); let mut live = consumer(track.subscribe(None), false); - let mut late = track.subscribe(None); + let late = track.subscribe(None); let mut producer = Producer::new(track, ProducerConfig::default()); let at = |ms| moq_net::Timestamp::from_millis(ms).unwrap(); @@ -162,7 +162,7 @@ mod test { // gets the header frame's time rather than the record's original push time. producer.cut().unwrap(); producer.push(moq_net::Timed::from(&rec(3)).at(at(400))).unwrap(); - late.set_groups(1..); + let late = late.with_range(1..); let mut late = consumer(late, false); let events: Vec<_> = drain_timed(&mut late).into_iter().map(|e| (e.value, e.at)).collect(); assert_eq!( @@ -542,7 +542,7 @@ mod test { .flatten() .map(|position| position.group) .unwrap(); - subscriber.set_groups(largest..); + subscriber = subscriber.with_range(largest..); let mut fresh = consumer(subscriber, false); producer.finish().unwrap(); diff --git a/rs/moq-mux/src/container/consumer.rs b/rs/moq-mux/src/container/consumer.rs index 89bea924e73..8ebd1a83fd4 100644 --- a/rs/moq-mux/src/container/consumer.rs +++ b/rs/moq-mux/src/container/consumer.rs @@ -1194,7 +1194,7 @@ mod tests { let track = track_producer("data", info); let subscription = moq_net::track::Subscription::default() .with_max_delay(hour) - .with_groups(0..); + .with_range(0..); let mut reader = Consumer::new( track.subscribe(subscription), Container::Legacy(crate::container::Kind::Data), @@ -1224,7 +1224,7 @@ mod tests { let mut track = track_producer("data", hang::container::track_info(hang::catalog::PRIORITY.audio)); let subscription = moq_net::track::Subscription::default() .with_max_delay(Duration::from_secs(10)) - .with_groups(0..); + .with_range(0..); let mut reader = Consumer::new( track.subscribe(subscription), Container::Legacy(crate::container::Kind::Data), @@ -1382,7 +1382,7 @@ mod tests { let mut track = track_producer("data", hang::container::track_info(hang::catalog::PRIORITY.audio)); let subscription = moq_net::track::Subscription::default() .with_max_delay(Duration::from_secs(10)) - .with_groups(0..); + .with_range(0..); let mut reader = Consumer::new( track.subscribe(subscription), Container::Legacy(crate::container::Kind::Data), @@ -1442,7 +1442,7 @@ mod tests { let mut track = track_producer("data", hang::container::track_info(hang::catalog::PRIORITY.audio)); let subscription = moq_net::track::Subscription::default() .with_max_delay(Duration::from_secs(10)) - .with_groups(0..); + .with_range(0..); let mut reader = Consumer::new( track.subscribe(subscription), Container::Legacy(crate::container::Kind::Data), @@ -1669,7 +1669,7 @@ mod tests { _ => panic!("the empty group is the largest"), }; assert_eq!(edge.group, 1); - subscriber.set_groups(edge.group..); + subscriber = subscriber.with_range(edge.group..); let mut consumer = Consumer::new(subscriber, Container::Legacy(crate::container::Kind::Audio)); write_group(&mut track, 2, &[ts(1_000_000), ts(1_600_000)]); @@ -2606,7 +2606,7 @@ mod tests { let mut track = track_producer("test", hang::container::track_info(hang::catalog::PRIORITY.video)); let consumer_track = track.subscribe( moq_net::track::Subscription::default() - .with_groups(0..) + .with_range(0..) .with_max_delay(Duration::from_millis(500)), ); let mut consumer = Consumer::new(consumer_track, Container::Legacy(crate::container::Kind::Data)); diff --git a/rs/moq-mux/src/container/source.rs b/rs/moq-mux/src/container/source.rs index dae021f99d5..a64ca308277 100644 --- a/rs/moq-mux/src/container/source.rs +++ b/rs/moq-mux/src/container/source.rs @@ -508,7 +508,7 @@ impl ExportSource { } let mut subscription = moq_net::track::Subscription::default().with_max_delay(self.max_delay); if let Some(after) = self.after { - subscription = subscription.with_groups((Bound::Excluded(after), Bound::Unbounded)); + subscription = subscription.with_range((Bound::Excluded(after), Bound::Unbounded)); } let track = match broadcast.track(&name) { Ok(track) => track, diff --git a/rs/moq-mux/src/container/ts/export_test.rs b/rs/moq-mux/src/container/ts/export_test.rs index 765eaae1a29..d5a1f78a0fa 100644 --- a/rs/moq-mux/src/container/ts/export_test.rs +++ b/rs/moq-mux/src/container/ts/export_test.rs @@ -3123,7 +3123,7 @@ async fn read_si_groups(consumer: &moq_net::broadcast::Consumer, name: &str) -> .unwrap() .subscribe( moq_net::track::Subscription::default() - .with_groups(0..) + .with_range(0..) .with_max_delay(Duration::from_secs(5)), ) .await diff --git a/rs/moq-net/benches/group.rs b/rs/moq-net/benches/group.rs index 47968f7bf55..c553b159961 100644 --- a/rs/moq-net/benches/group.rs +++ b/rs/moq-net/benches/group.rs @@ -225,7 +225,7 @@ fn filled_track(n: usize, payload: &Bytes) -> TrackCtx { fn replay() -> track::Subscription { track::Subscription::default() .with_max_delay(Duration::MAX) - .with_groups(0..) + .with_range(0..) } /// Drain N cached groups from a track, in arrival order and in sequence order. diff --git a/rs/moq-net/benches/origin.rs b/rs/moq-net/benches/origin.rs index c74c16c81d4..a293163e86d 100644 --- a/rs/moq-net/benches/origin.rs +++ b/rs/moq-net/benches/origin.rs @@ -1572,12 +1572,12 @@ async fn resume_overlap(shape: ResumeShape, ordered: bool) -> ResumeOverlap { let subscription = track::Subscription::default().with_max_delay(Duration::from_secs(3600)); let mut subscribers = Vec::with_capacity(readers); for _ in 0..readers { - let mut subscriber = moq_clock::timeout(COPY_WAIT, track.subscribe(subscription.clone())) + let subscriber = moq_clock::timeout(COPY_WAIT, track.subscribe(subscription.clone())) .await .expect("track did not splice") .expect("subscribe failed"); // Held back until the drain, so every route's copy is kept for its unread groups. - subscriber.set_groups(..0); + let subscriber = subscriber.with_range(..0); subscribers.push(subscriber); } let waiter = kio::Waiter::noop(); @@ -1602,11 +1602,9 @@ async fn resume_overlap(shape: ResumeShape, ordered: bool) -> ResumeOverlap { ); } } - for subscriber in &mut subscribers { - subscriber.set_groups(..); - } let readers = subscribers .into_iter() + .map(|subscriber| subscriber.with_range(..)) .map(|subscriber| match ordered { true => ResumeReader::Sequence(subscriber.ordered()), false => ResumeReader::Arrival(subscriber), diff --git a/rs/moq-net/benches/track.rs b/rs/moq-net/benches/track.rs index 8b1651db802..93d9c01f2d7 100644 --- a/rs/moq-net/benches/track.rs +++ b/rs/moq-net/benches/track.rs @@ -850,14 +850,14 @@ fn bench_subscriber_join(c: &mut Criterion) { /// Each held reader asks for distinct values, so the aggregate's tables grow with the audience. fn bench_subscriber_preferences(c: &mut Criterion) { let ordinary = track::Subscription::default() - .with_groups(100..200) + .with_range(100..200) .with_order(track::Order::Ascending); let held = |i: usize| { let i = i as u64; track::Subscription::default() .with_priority(((i % 255) as i16 - 128) as i8) .with_max_delay(Duration::from_micros(i)) - .with_groups(100 + i..200 + i) + .with_range(100 + i..200 + i) .with_order(track::Order::Ascending) }; let extreme = track::Subscription::default() @@ -913,7 +913,7 @@ fn bench_range_demand(c: &mut Criterion) { // Far past every held range, so each move adds one run and removes another. let away = |offset: u64| { let group = (1 << 40) + offset; - track::Subscription::default().with_groups(group..=group) + track::Subscription::default().with_range(group..=group) }; let mut group = c.benchmark_group("track_range_demand"); for steady in STEADY { @@ -925,7 +925,7 @@ fn bench_range_demand(c: &mut Criterion) { // Overlapping, so the held ranges union into one run. let start = (i % distinct) as u64 * 10; subscriber - .update(track::Subscription::default().with_groups(start..start + 1000)) + .update(track::Subscription::default().with_range(start..start + 1000)) .unwrap(); } let mut viewer = setup.track.subscribe(away(0)); @@ -952,7 +952,7 @@ fn bench_subscription_ranges(c: &mut Criterion) { let viewers: Vec<_> = (0..ranges) .map(|i| { let start = i * (span + 1); - track.subscribe(track::Subscription::default().with_groups(start..start + span)) + track.subscribe(track::Subscription::default().with_range(start..start + span)) }) .collect(); assert_eq!(track.subscription().unwrap().ranges.len(), ranges as usize); @@ -1534,7 +1534,7 @@ fn bench_range_widening(c: &mut Criterion) { } let narrow = track::Subscription::default() .with_max_delay(AGED_BUDGET) - .with_groups(0..1); + .with_range(0..1); let mid = cached / 2; let wide = narrow .clone() diff --git a/rs/moq-net/src/ietf/publisher.rs b/rs/moq-net/src/ietf/publisher.rs index 56cf6572f10..5a54502fbb1 100644 --- a/rs/moq-net/src/ietf/publisher.rs +++ b/rs/moq-net/src/ietf/publisher.rs @@ -4550,21 +4550,18 @@ struct TrackServe { impl TrackServe { fn new( session: Transport, - mut track: track::Subscriber, + track: track::Subscriber, request_id: RequestId, version: Version, range: ServeRange, timescale: Option, ) -> Self { - match range.start { - Some(start) => track.start_at(start.group), - None => { - if let Some(latest) = track.latest_sequence() { - track.start_at(latest); - } - } - } - track.end_at(range.end.map_or(Bound::Unbounded, |end| Bound::Included(end.group))); + let floor = match range.start { + Some(start) => start.group, + None => track.latest_sequence().unwrap_or(0), + }; + let end = range.end.map_or(Bound::Unbounded, |end| Bound::Included(end.group)); + let track = track.with_range((Bound::Included(floor), end)); let datagrams = session.max_datagram_size() > 0; // A Timestamp whose units were not declared is worse than none. Drafts 14-16 // never write TIMESCALE, whatever the caller passed in, so datagrams and group @@ -5159,6 +5156,22 @@ impl Queued { } } +/// Why to stop writing `group` while the transport parks it: the subscription's budget gave +/// it up, or the frames this cursor has yet to read are gone with no route to continue them. +/// A clean finish is no reason. +/// +/// Waking on every frame written to a parked group costs what a reader parked at the live +/// edge already pays: each of its pending reads judges the budget too. +fn poll_given_up(group: &mut group::Consumer, waiter: &kio::Waiter) -> Option { + if group.poll_expired(waiter) { + return Some(Error::Old); + } + match group.poll_finished(waiter) { + Poll::Ready(Err(err)) => Some(err), + _ => None, + } +} + /// Serves one group on its own unidirectional stream in the moq-transport /// subgroup format. struct GroupServe { @@ -5229,8 +5242,10 @@ impl GroupServe { slice: GroupSlice, ) -> Self { if group.wire().is_none() { + // Only the end: a start would clamp past a prefix the group never held, + // which `skip_to` leaves to fail as `Lagged`. group.skip_to(slice.skip); - group.end_at(slice.until.map_or(Bound::Unbounded, Bound::Excluded)); + group = group.with_end(slice.until); } Self { session, @@ -5268,7 +5283,7 @@ impl GroupServe { if !matches!(self.state, GroupState::Open) { return Poll::Ready(Ok(())); } - if let Some(err) = self.group.poll_abandoned(waiter, false) { + if let Some(err) = poll_given_up(&mut self.group, waiter) { self.state = GroupState::Done; return Poll::Ready(Err(err)); } @@ -5336,10 +5351,9 @@ impl GroupServe { // Parking on the transport is the one stall the group cursor cannot // see, and the only place a served group applies the drift budget: // flow control must not pin a stream that has gone stale, or one - // whose unread rest the cache evicted. `true` because the transport - // still owns bytes the cursor has released. + // whose unread rest the cache evicted. Poll::Pending => { - if let Some(err) = self.group.poll_abandoned(waiter, true) { + if let Some(err) = poll_given_up(&mut self.group, waiter) { break 'serve Err(err); } return Poll::Pending; @@ -5356,10 +5370,9 @@ impl GroupServe { // Parking on the transport is the one stall the group cursor cannot // see, and the only place a served group applies the drift budget: // flow control must not pin a stream that has gone stale, or one - // whose unread rest the cache evicted. `true` because the transport - // still owns bytes the cursor has released. + // whose unread rest the cache evicted. Poll::Pending => { - if let Some(err) = self.group.poll_abandoned(waiter, true) { + if let Some(err) = poll_given_up(&mut self.group, waiter) { break 'serve Err(err); } return Poll::Pending; @@ -5544,7 +5557,7 @@ impl GroupServe { // Those bytes still hold the connection until acknowledged, so a // group gone stale meanwhile releases them like one still serving: // dropping the writer resets the stream. - Poll::Pending if self.group.poll_expired_while_pending(waiter, true) => { + Poll::Pending if self.group.poll_expired(waiter) => { self.state = GroupState::Done; return Poll::Ready(Err(Error::Old)); } @@ -6499,6 +6512,45 @@ mod group_priority_test { assert!(matches!(serving.await, Err(Error::Old))); } + /// A local group that never held the requested prefix fails rather than serving its + /// tail as the whole group, with or without an end inside it. + #[moq_clock::test] + async fn a_group_missing_its_prefix_fails() { + for until in [None, Some(5)] { + let track = track::Producer::new( + std::sync::Arc::new(crate::broadcast::Info::default()), + "test", + crate::track::Info::timed(), + ); + let mut subscriber = track.subscribe(None); + let mut producer = track.create_group(group::Info { sequence: 0 }).unwrap(); + producer.start_at(1).unwrap(); + producer + .write_frame(crate::Timestamp::ZERO, b"tail".as_slice()) + .unwrap(); + producer.finish().unwrap(); + let group = subscriber.recv_group().await.unwrap().expect("the group"); + + let mut serve = GroupServe::new( + crate::driver::Transport::new(SinkSession::new(Default::default())), + ietf::GroupHeader { + track_alias: 0, + group_id: 0, + sub_group_id: 0, + publisher_priority: 0, + flags: Default::default(), + }, + Rank::solo(kio::Producer::new(0).consume()), + group, + Some(Timescale::MILLI), + Version::Draft19, + GroupSlice { skip: 0, until }, + ); + let served = kio::wait(|waiter| serve.poll_serve(waiter)).await; + assert!(matches!(served, Err(Error::Lagged)), "until {until:?}: {served:?}"); + } + } + /// A FIN holds the subgroup's bytes until the peer acknowledges it, so a subgroup /// that goes stale while waiting still expires instead of pinning them. #[moq_clock::test] @@ -16924,16 +16976,15 @@ struct ServeRange { impl ServeRange { /// Bound `subscription` to this range. fn apply(&self, subscription: &mut Subscription) { - subscription.set_bounds( - self.start.map(|start| track::Position { + *subscription = std::mem::take(subscription) + .with_start(self.start.map(|start| track::Position { group: start.group, frame: start.object, - }), - self.end.and_then(|end| match end.object { + })) + .with_end(self.end.and_then(|end| match end.object { Some(object) => track::Position::after(end.group, object), None => track::Position::after_group(end.group), - }), - ); + })); } } @@ -17127,7 +17178,7 @@ mod range_tests { // Next Group against a live edge of 8 asks for 9, which does not exist yet. let mut subscriber = track.subscribe(None); - subscriber.start_at(9); + subscriber.set_range(9..); assert!( futures::poll!(std::pin::pin!(subscriber.recv_group())).is_pending(), "a future start must wait for its group rather than serving the live edge" diff --git a/rs/moq-net/src/ietf/subscriber.rs b/rs/moq-net/src/ietf/subscriber.rs index 05a080104cb..6296918585a 100644 --- a/rs/moq-net/src/ietf/subscriber.rs +++ b/rs/moq-net/src/ietf/subscriber.rs @@ -14938,8 +14938,12 @@ mod stitch_tests { let mut whole = h.stream().await; h.subscriber.clone().recv_group(&mut whole).await.expect("the group"); - let mut group = consumer.recv_group().await.unwrap().expect("the group arrived"); - group.start_at(0); + let mut group = consumer + .recv_group() + .await + .unwrap() + .expect("the group arrived") + .with_range(0..); assert_eq!(group.index(), 2, "the group starts where the subscription asked"); assert_eq!(&group.read_frame().await.unwrap().unwrap().payload[..], b"2"); assert!(group.read_frame().await.unwrap().is_none()); @@ -14966,8 +14970,12 @@ mod stitch_tests { h.subscriber.clone().recv_fill(&mut fill).await.expect("fill"); h.subscriber.clone().recv_group(&mut tail).await.expect("tail"); - let mut group = consumer.recv_group().await.unwrap().expect("the group arrived"); - group.start_at(0); + let mut group = consumer + .recv_group() + .await + .unwrap() + .expect("the group arrived") + .with_range(0..); assert_eq!(group.index(), 2, "the group starts where the subscription asked"); let mut frames = Vec::new(); while let Some(frame) = group.read_frame().await.unwrap() { diff --git a/rs/moq-net/src/lite/publisher.rs b/rs/moq-net/src/lite/publisher.rs index 88a457de7e8..e5158c62a6b 100644 --- a/rs/moq-net/src/lite/publisher.rs +++ b/rs/moq-net/src/lite/publisher.rs @@ -109,7 +109,7 @@ fn serving_max_delay(version: Version, requested: Duration) -> Duration { } } -/// Position a subscription's read cursor for the wire serving it. +/// The floor of 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 delay still considers fresh, floored @@ -123,14 +123,11 @@ fn serving_max_delay(version: Version, requested: Duration) -> Duration { /// /// `latest` is the newest group when the SUBSCRIBE arrived, not once the subscription /// resolved: anything written in between is newer, so it is delivered. -fn position_cursor(track: &mut track::Subscriber, version: Version, start_group: Option, latest: Option) { +fn cursor_floor(version: Version, start_group: Option, latest: Option) -> u64 { if version.resolves_start() || start_group.is_some() { - return; - } - - if let Some(latest) = latest { - track.start_at(latest); + return 0; } + latest.unwrap_or(0) } impl Shared { @@ -1925,7 +1922,7 @@ enum SubscribeServe { /// Boxed: the request is far larger than the other states' handles. msg: Box>, subscribing: track::Subscribing, - /// The newest group when the SUBSCRIBE arrived; see [`position_cursor`]. + /// The newest group when the SUBSCRIBE arrived; see [`cursor_floor`]. latest: Option, update: Option, }, @@ -2000,7 +1997,7 @@ impl Request for SubscribeServe { match self { Self::Confirm { subscribing, .. } => { let ietf = ready!(shared.peer_setup.poll_ietf(waiter)); - let mut track = ready!(subscribing.poll_ok(waiter))?; + let track = ready!(subscribing.poll_ok(waiter))?; crate::ietf::flate::egress(track.info(), shared.version.has_compression())?; let Self::Confirm { msg, latest, update, .. @@ -2064,8 +2061,8 @@ impl Request for SubscribeServe { }; let bounds = Bounds::from(msg.as_ref()); - position_cursor(&mut track, shared.version, bounds.start_group, latest); - let mut run = TrackRun::new(sub, track, bounds, steer_tx); + let floor = cursor_floor(shared.version, bounds.start_group, latest); + let mut run = TrackRun::new(sub, track, bounds, floor, steer_tx); if let Some(update) = update { run.update(update); } @@ -2178,7 +2175,7 @@ impl Request for FetchServe { Self::Fetch { msg, fetching } => { // Before the group: a fetched group polled while this waited would be lost. let ietf = ready!(shared.peer_setup.poll_ietf(waiter)); - let mut group = ready!(kio::Task::poll(fetching, waiter))?; + let group = ready!(kio::Task::poll(fetching, waiter))?; // The response carries no header, so a short run is indistinguishable // from one that started elsewhere: only serve a range we can cover @@ -2189,8 +2186,9 @@ impl Request for FetchServe { } // The end is a serving cap only: the cached group runs to the end of // the group so it stays usable for anyone else (see - // `group::Fetch::frame_start`). - group.end_at(msg.end_frame.map_or(Bound::Unbounded, Bound::Included)); + // `group::Fetch::frame_start`). Only the end, so the start stays where + // the check above found it. + let mut group = group.with_end(msg.end_frame.and_then(|end| end.checked_add(1))); // Matches the timescale TRACK_INFO declared for the track. let stamp = Stamp::new(shared.version, group.lite_timescale(ietf)); @@ -2351,21 +2349,21 @@ mod test { "the unbounded budget alone resolves to the whole cache" ); - let mut legacy = served(Version::Lite01); - position_cursor(&mut legacy, Version::Lite01, None, producer.latest_sequence()); + let legacy = served(Version::Lite01); + let mut legacy = legacy.with_range(cursor_floor(Version::Lite01, None, producer.latest_sequence())..); 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 = + let tolerant = producer.subscribe(track::Subscription::default().with_max_delay(std::time::Duration::from_secs(5))); - position_cursor(&mut tolerant, Version::Lite05, None, producer.latest_sequence()); + let mut tolerant = tolerant.with_range(cursor_floor(Version::Lite05, None, producer.latest_sequence())..); assert_eq!(drain(&mut tolerant), vec![2]); // On lite-06 the declared budget is what resolves the start, so it stands. - let mut declared = + let declared = producer.subscribe(track::Subscription::default().with_max_delay(std::time::Duration::from_secs(5))); - position_cursor(&mut declared, Version::Lite06, None, producer.latest_sequence()); + let mut declared = declared.with_range(cursor_floor(Version::Lite06, None, producer.latest_sequence())..); assert_eq!(drain(&mut declared), vec![0, 1, 2]); } @@ -2393,7 +2391,7 @@ mod test { match recv_next(&mut subscriber, false, false).await.unwrap() { Recv::Group(group) => { assert_eq!(group.sequence, 7); - subscriber.start_at(group.sequence); + subscriber.set_range(group.sequence..); } _ => panic!("expected the first group"), } @@ -3394,33 +3392,31 @@ async fn recv_next(track: &mut track::Subscriber, datagrams: bool, emit_boundary kio::wait(|waiter| poll_recv_next(track, true, datagrams, emit_boundary, waiter)).await } -/// Bound `group` to what this subscription asked for, reporting whether it can be served +/// Bound `group` to what this subscription asked for, or `None` when it cannot be served /// at all. /// /// Frame bounds qualify the start and end group only; everything in between is served -/// whole. `false` means the group's head is missing and the subscriber never asked for a +/// whole. `None` means the group's head is missing and the subscriber never asked for a /// partial group, so it must be skipped: a group is the unit of decodability, and only /// the subscriber knows whether a partial one is any use to it. -fn position_group(group: &mut group::Consumer, start: Option<(u64, u64)>, end: Option<(u64, u64)>) -> bool { +fn position_group( + group: group::Consumer, + start: Option<(u64, u64)>, + end: Option<(u64, u64)>, +) -> Option { let expected = match start { Some((sequence, frame)) if sequence == group.sequence => frame, _ => 0, }; + let end = match end { + Some((sequence, frame)) if sequence == group.sequence => Bound::Included(frame), + _ => Bound::Unbounded, + }; - // `start_at` clamps up to the first frame the group still holds, so landing higher + // The start clamps up to the first frame the group still holds, so landing higher // than asked means the frames below it are gone. - group.start_at(expected); - if group.index() != expected { - return false; - } - - if let Some((sequence, frame)) = end - && sequence == group.sequence - { - group.end_at(Bound::Included(frame)); - } - - true + let group = group.with_range((Bound::Included(expected), end)); + (group.index() == expected).then_some(group) } /// A subscription's requested delivery range, exactly as it arrived on the wire. @@ -3694,6 +3690,9 @@ impl Subscription { struct TrackRun { ctx: Subscription, track: track::Subscriber, + // The read cursor's floor and cap, assigned together on every move. + floor: u64, + cap: Bound, /// Broadcasts SUBSCRIBE_UPDATE priorities to the in-flight group machines. steer_tx: kio::Producer, // Frame bounds qualify the start and end group only; everything in between is @@ -3732,10 +3731,17 @@ struct TrackRun { } impl TrackRun { - fn new(ctx: Subscription, mut track: track::Subscriber, bounds: Bounds, steer_tx: kio::Producer) -> Self { + fn new( + ctx: Subscription, + track: track::Subscriber, + bounds: Bounds, + floor: u64, + steer_tx: kio::Producer, + ) -> Self { // Apply the initial cap from the original Subscribe. Subsequent updates // flow through the SUBSCRIBE_UPDATE arm below. - track.end_at(bounds.end_group.map_or(Bound::Unbounded, Bound::Included)); + let cap = bounds.end_group.map_or(Bound::Unbounded, Bound::Included); + let track = track.with_range((Bound::Included(floor), cap)); let emit_range = ctx.version.has_track_stream(); let datagrams = ctx.version.has_datagrams() && ctx.session.max_datagram_size() > 0; @@ -3747,6 +3753,8 @@ impl TrackRun { end_frame: bounds.end_frame(), ctx, track, + floor, + cap, steer_tx, emit_range, start: None, @@ -3827,7 +3835,7 @@ impl TrackRun { floor => floor, }; if let Some(start) = floor { - self.track.start_at(start); + self.floor = start; // Before SUBSCRIBE_START nothing is owed yet; the start accounts for it. if let Some(resolved) = self.start { // A lowered floor owes the groups it newly asks for, so the end sweep covers them. @@ -3836,12 +3844,25 @@ impl TrackRun { self.start = Some(resolved.min(start)); } } - self.track - .end_at(upd.end_group.map_or(Bound::Unbounded, Bound::Included)); + self.cap = upd.end_group.map_or(Bound::Unbounded, Bound::Included); + self.move_cursor(); self.start_frame = bounds.start_frame(); self.end_frame = bounds.end_frame(); } + /// Apply [`Self::floor`] and [`Self::cap`] to the read cursor. + fn move_cursor(&mut self) { + self.track.set_range((Bound::Included(self.floor), self.cap)); + } + + /// Raise the read cursor's floor to `start`, keeping any higher floor already set. + fn raise_floor(&mut self, start: u64) { + if start > self.floor { + self.floor = start; + self.move_cursor(); + } + } + /// Serve until the live edge reaches the track's boundary. #[cfg(test)] fn poll( @@ -3934,7 +3955,7 @@ impl TrackRun { group: start.group, largest: Some(largest), }))?; - self.track.raise_start_to(start.group); + self.raise_floor(start.group); return Poll::Ready(Ok(ControlFlow::Continue(()))); } @@ -3946,7 +3967,7 @@ impl TrackRun { let groups = self.opening.is_none(); if let Poll::Ready(res) = poll_recv_next(&mut self.track, groups, self.datagrams, emit_boundary, waiter) { match res? { - Recv::Group(mut group) => { + Recv::Group(group) => { // Never a second stream for a sequence this subscription already accounted // for (served, sent as a datagram, or dropped): a group re-created after its // DROP stays dropped, since the subscriber may settle before it arrives. @@ -3957,24 +3978,25 @@ impl TrackRun { { return Poll::Ready(Ok(ControlFlow::Continue(()))); } - if !position_group(&mut group, self.start_frame, self.end_frame) { + let sequence = group.sequence; + let Some(group) = position_group(group, self.start_frame, self.end_frame) else { // Its head is gone, and this subscriber didn't ask for a // partial group. Skip it rather than open a stream that can // only be reset; the next servable group resolves the start. - tracing::debug!(subscribe = self.ctx.id, track = %self.ctx.track_name, sequence = group.sequence, "skipping group with a missing head"); + tracing::debug!(subscribe = self.ctx.id, track = %self.ctx.track_name, sequence, "skipping group with a missing head"); if self.emit_range && self.start.is_none() { // At u64::MAX no later group can resolve a start past this one. - if let Some(end) = group.sequence.checked_add(1) { - self.skipped.insert(group.sequence..end, StreamError::NotFound); + if let Some(end) = sequence.checked_add(1) { + self.skipped.insert(sequence..end, StreamError::NotFound); } } else if self.start.is_some() - && let Some(end) = group.sequence.checked_add(1) + && let Some(end) = sequence.checked_add(1) { // Lite-05+ names it now; a no-op on other versions. - self.drop_range(group.sequence..end, &StreamError::NotFound, writer)?; + self.drop_range(sequence..end, &StreamError::NotFound, writer)?; } return Poll::Ready(Ok(ControlFlow::Continue(()))); - } + }; match self.emit_range && self.start.is_none() { true => self.first = Some(group), false => self.serve(group), @@ -4158,7 +4180,7 @@ impl TrackRun { // that 0 is group 0, so it is not pinned. Raised, not assigned: an update that // landed while the group was held may already have raised it past. if self.track.subscription().start().is_none() && !self.ctx.version.resolves_start() { - self.track.raise_start_to(start); + self.raise_floor(start); } self.serve(group); Ok(()) @@ -4209,6 +4231,22 @@ enum Rank { Queue(PriorityHandle), } +/// Why to stop writing `group` while the transport parks it: the subscription's budget gave +/// it up, or the frames this cursor has yet to read are gone with no route to continue them. +/// A clean finish is no reason. +/// +/// Waking on every frame written to a parked group costs what a reader parked at the live +/// edge already pays: each of its pending reads judges the budget too. +fn poll_given_up(group: &mut group::Consumer, waiter: &kio::Waiter) -> Option { + if group.poll_expired(waiter) { + return Some(Error::Old); + } + match group.poll_finished(waiter) { + Poll::Ready(Err(err)) => Some(err), + _ => None, + } +} + /// Serves one group on its own unidirectional stream: the header, then every /// frame, applying queue and SUBSCRIBE_UPDATE priority changes as they land. struct GroupServe { @@ -4304,7 +4342,7 @@ impl GroupServe { if !matches!(self.state, GroupState::Open) { return Poll::Ready(Ok(())); } - if let Some(err) = self.group.poll_abandoned(waiter, false) { + if let Some(err) = poll_given_up(&mut self.group, waiter) { self.settle_open(false); self.state = GroupState::Done; return Poll::Ready(Err(err)); @@ -4431,10 +4469,9 @@ impl GroupServe { // Parking on the transport is the one stall the group cursor cannot // see, and the only place a served group applies the drift budget: // flow control must not pin a stream that has gone stale, or one - // whose unread rest the cache evicted. `true` because the transport - // still owns bytes the cursor has released. + // whose unread rest the cache evicted. Poll::Pending => { - if let Some(err) = self.group.poll_abandoned(waiter, true) { + if let Some(err) = poll_given_up(&mut self.group, waiter) { break 'serve Err(err); } return Poll::Pending; @@ -4451,10 +4488,9 @@ impl GroupServe { // Parking on the transport is the one stall the group cursor cannot // see, and the only place a served group applies the drift budget: // flow control must not pin a stream that has gone stale, or one - // whose unread rest the cache evicted. `true` because the transport - // still owns bytes the cursor has released. + // whose unread rest the cache evicted. Poll::Pending => { - if let Some(err) = self.group.poll_abandoned(waiter, true) { + if let Some(err) = poll_given_up(&mut self.group, waiter) { break 'serve Err(err); } return Poll::Pending; @@ -4597,7 +4633,7 @@ impl GroupServe { Poll::Ready(res) => res, // Those bytes still hold the connection until acknowledged, so a // group gone stale meanwhile releases them like one still serving. - Poll::Pending if self.group.poll_expired_while_pending(waiter, true) => { + Poll::Pending if self.group.poll_expired(waiter) => { let GroupState::Closed { writer } = std::mem::replace(&mut self.state, GroupState::Done) else { unreachable!() @@ -4707,23 +4743,19 @@ mod serve_group_test { group.write_frame(Timestamp::ZERO, b"tail".to_vec()).unwrap(); // Asked for whole groups, so the missing frames 0..5 make this unservable. - let mut consumer = group.consume(); - assert!(!position_group(&mut consumer, None, None)); + assert!(position_group(group.consume(), None, None).is_none()); // Asked for exactly where it starts: servable, and positioned there. - let mut consumer = group.consume(); - assert!(position_group(&mut consumer, Some((3, 5)), None)); + let consumer = position_group(group.consume(), Some((3, 5)), None).unwrap(); assert_eq!(consumer.index(), 5); // Asked for an earlier frame than the group holds: still a hole, still skipped. - let mut consumer = group.consume(); - assert!(!position_group(&mut consumer, Some((3, 2)), None)); + assert!(position_group(group.consume(), Some((3, 2)), None).is_none()); // The offset belongs to the start group only; a later group is served whole. let mut other = track.create_group(group::Info { sequence: 4 }).unwrap(); other.write_frame(Timestamp::ZERO, b"whole".to_vec()).unwrap(); - let mut consumer = other.consume(); - assert!(position_group(&mut consumer, Some((3, 5)), None)); + let consumer = position_group(other.consume(), Some((3, 5)), None).unwrap(); assert_eq!(consumer.index(), 0); } @@ -4741,8 +4773,7 @@ mod serve_group_test { } group.finish().unwrap(); - let mut consumer = group.consume(); - assert!(position_group(&mut consumer, None, Some((7, 1)))); + let mut consumer = position_group(group.consume(), None, Some((7, 1))).unwrap(); assert_eq!( consumer.read_frame().now_or_never().unwrap().unwrap().unwrap().payload[0], 0 @@ -4757,8 +4788,7 @@ mod serve_group_test { ); // A cap naming another group leaves this one uncapped. - let mut consumer = group.consume(); - assert!(position_group(&mut consumer, None, Some((8, 1)))); + let mut consumer = position_group(group.consume(), None, Some((8, 1))).unwrap(); for i in 0..4u8 { assert_eq!( consumer.read_frame().now_or_never().unwrap().unwrap().unwrap().payload[0], @@ -5449,7 +5479,7 @@ mod serve_group_test { end_group: None, end_frame: None, }; - (TrackRun::new(ctx, track, bounds, steer), writer, log) + (TrackRun::new(ctx, track, bounds, 0, steer), writer, log) } #[moq_clock::test] @@ -6129,7 +6159,7 @@ mod serve_group_test { .unwrap() .subscribe( track::Subscription::default() - .with_groups(0..) + .with_range(0..) .with_max_delay(Duration::from_secs(60)), ) .await @@ -6150,7 +6180,7 @@ mod serve_group_test { let mut live = remote .track("test") .unwrap() - .subscribe(track::Subscription::default().with_groups(0..)) + .subscribe(track::Subscription::default().with_range(0..)) .await .unwrap(); assert_eq!(live.recv_group().await.unwrap().unwrap().sequence, 2); @@ -6594,7 +6624,7 @@ mod serve_group_test { end_frame: None, }; Self { - run: TrackRun::new(ctx, subscriber, bounds, steer), + run: TrackRun::new(ctx, subscriber, bounds, 0, steer), writer, session, outcomes, diff --git a/rs/moq-net/src/lite/subscriber.rs b/rs/moq-net/src/lite/subscriber.rs index a4436f442e7..74c50f59a2d 100644 --- a/rs/moq-net/src/lite/subscriber.rs +++ b/rs/moq-net/src/lite/subscriber.rs @@ -2221,7 +2221,7 @@ mod tests { } moq_clock::sleep(crate::tail::GRACE * 2).await; - let lowered = Some(Subscription::default().with_groups(2..)); + let lowered = Some(Subscription::default().with_range(2..)); // The SUBSCRIBE in force, already answered. let floor = Position::group(if update { 5 } else { 2 }); let mut sub = Sub::Active(SubStream { @@ -6293,10 +6293,8 @@ impl TrackServe { // subscriber holds, so ask from the head of its group instead: the first frame then // arrives at once and says where the live feed is. if !self.subscriber.version.has_largest() { - subscription.set_bounds( - subscription.start().map(|start| Position::group(start.group)), - subscription.end(), - ); + let start = subscription.start().map(|start| Position::group(start.group)); + *subscription = std::mem::take(subscription).with_start(start); } if self.subscriber.version.has_frame_bounds() { return; @@ -6320,7 +6318,7 @@ impl TrackServe { "widening frame bounds to whole groups for an older peer" ); } - subscription.set_bounds(start, end); + *subscription = std::mem::take(subscription).with_start(start).with_end(end); } /// Apply a subscription-demand change: hand back an [`Establish`] to open the @@ -6345,7 +6343,8 @@ impl TrackServe { Some(mut subscription) => { // The wire carries one range: the span of every range asked for, which the // subscribers' own reads narrow again. - subscription.set_bounds(subscription.start(), subscription.end()); + let start = subscription.start(); + subscription = subscription.with_start(start); producer.widen_compressed(&mut subscription); self.widen_frame_bounds(&mut subscription); match sub { @@ -6354,7 +6353,7 @@ impl TrackServe { // the subscriber has no start of its own: a quiet track (a catalog) sends // that group again, which says the cache is current. if subscription.start().is_none() { - subscription.set_bounds(producer.idle_newest().map(Position::group), subscription.end()); + subscription = subscription.with_start(producer.idle_newest().map(Position::group)); } // Open an upstream SUBSCRIBE for the first subscriber. Ok(Begin::Establish(self.prepare_establish(producer, subscription))) diff --git a/rs/moq-net/src/model/group.rs b/rs/moq-net/src/model/group.rs index dcbb7898125..d81618e75f9 100644 --- a/rs/moq-net/src/model/group.rs +++ b/rs/moq-net/src/model/group.rs @@ -10,18 +10,18 @@ //! Frames are numbered from 0 in write order. A group can be short at its front or its //! back but never in the middle: [Producer::start_at] starts it later, so a handle can //! carry the tail of a group whose leading frames came from somewhere else, and -//! [Producer::finish] ends it wherever writing stopped. [Consumer::set_frames] bounds a reader to a sub-range the same way [`track::Subscriber`] +//! [Producer::finish] ends it wherever writing stopped. [Consumer::with_range] bounds a reader to a sub-range the same way [`track::Subscriber`] //! bounds group sequences. //! //! The stream is closed with [Error] when all writers or readers are dropped. use super::flate; use crate::cache; use crate::frame::{self, Frame, FrameBuf}; -use crate::{Cap, Timescale, stats, track}; +use crate::{Timescale, stats, track}; use bytes::Bytes; use std::collections::VecDeque; use std::mem::MaybeUninit; -use std::ops::{Bound, RangeBounds}; +use std::ops::RangeBounds; use std::sync::atomic::{AtomicBool, AtomicUsize, Ordering}; use std::sync::{Arc, Mutex, MutexGuard, OnceLock, PoisonError, Weak}; use std::task::{Poll, ready}; @@ -1188,7 +1188,7 @@ impl Producer { /// head of the group, typically another route serving the same track (see /// [`crate::track::Subscriber`]). /// - /// The counterpart of [`Consumer::set_frames`], which positions a *reader* the same + /// The counterpart of [`Consumer::with_range`], which positions a *reader* the same /// way. Where the group begins is part of its shape, so this must come before the /// first frame; afterwards it returns [`Error::Closed`]. pub fn start_at(&mut self, index: u64) -> Result<()> { @@ -2464,7 +2464,7 @@ struct Cursor { // NOTE: Cloned readers inherit this offset, but then run in parallel. index: usize, - // Exclusive cap on `index`, set by [`Consumer::set_frames`]. Reads end cleanly at it. + // Exclusive cap on `index`, set by [`Consumer::with_range`]. Reads end cleanly at it. end: Option, // A batch of completed frames drained ahead under one lock (whole-frame reads only). @@ -2698,9 +2698,16 @@ impl Consumer { } } - /// Check the parent subscription while a wire publisher drains detached payload. + /// Whether the subscription this group was handed out under has given up on it, waking + /// once it does. + /// + /// A publisher still writing the group polls this while it waits on its own transport, + /// which the group's reads cannot see: once the subscription's + /// [`max_delay`](crate::track::Subscription::max_delay) expires the group, it abandons + /// the stream, even with every frame already read off. It abandons it too once + /// [`Self::poll_finished`] fails. Stays `true` once set. pub(crate) fn poll_expired(&mut self, waiter: &kio::Waiter) -> bool { - self.poll_expired_while_pending(waiter, false) + self.poll_expiry(waiter, true) } /// Apply the drift budget to a read that found nothing and is about to park, failing @@ -2720,16 +2727,17 @@ impl Consumer { /// policy walks the track's group cache under its lock, which is shared by every /// subscriber of that track. fn poll_expired_if_blocked(&mut self, waiter: &kio::Waiter, res: Poll>) -> Poll> { - match res.is_pending() && self.poll_expired(waiter) { + match res.is_pending() && self.poll_expiry(waiter, false) { true => Poll::Ready(Err(Error::Old)), false => res, } } - /// Keep checking expiry while a wire publisher still owns buffered group data. - pub(crate) fn poll_expired_while_pending(&mut self, waiter: &kio::Waiter, pending: bool) -> bool { + /// Apply the drift budget, judging even a group whose cursor has nothing left to + /// discard when `held`, since its reader still holds data from it. + fn poll_expiry(&mut self, waiter: &kio::Waiter, held: bool) -> bool { if !self.expired - && (pending || self.expiry_pending()) + && (held || self.expiry_pending()) && self.expiry.as_ref().is_some_and(|expiry| { let budget = self.recover.as_ref().and_then(|recover| recover.poll_budget(waiter)); expiry.is_expired(budget, waiter) @@ -2742,44 +2750,6 @@ impl Consumer { self.expired } - /// Why a wire publisher waiting on the transport, for stream credit or to drain, should - /// give up on this group: the drift budget convicted it ([`Error::Old`]), or its copy - /// was aborted (evicted, cut, or failed upstream) before this cursor read it all and no - /// route will continue it. `pending` as in [`Self::poll_expired_while_pending`]. - /// - /// A machine parked on stream credit reads nothing, so without this an aborted group, - /// which never expires, would wait for credit it could only spend on a reset. - #[cfg(feature = "async")] - pub(crate) fn poll_abandoned(&mut self, waiter: &kio::Waiter, pending: bool) -> Option { - if self.poll_expired_while_pending(waiter, pending) { - return Some(Error::Old); - } - // Registered on the close alone: an abort closes the channel, and waking on every - // frame written to a parked group would cost a stalled subscriber per frame. - if self.cursor.state.poll_closed(waiter).is_pending() { - return None; - } - let aborted = { - let state = self.cursor.state.read(); - let unread = !self.cursor.capped() && state.fin.is_none_or(|fin| self.cursor.index < fin); - match &state.abort { - // The rest of the group is gone; what was read already is not. - Some(err) if unread => err.clone(), - // Read to its end, or finished and closed with its last producer: still servable. - _ => return None, - } - }; - // A front's reader may continue the group from another route's copy when it reads. - if self - .recover - .as_mut() - .is_some_and(|recover| recover.wants(Some(&aborted), waiter)) - { - return None; - } - Some(aborted) - } - /// Whether expiry can still discard content or unblock a group that may grow. fn expiry_pending(&self) -> bool { self.cursor.expiry_pending() @@ -2817,56 +2787,45 @@ impl Consumer { /// The index of the next frame this consumer will return. /// - /// Starts at 0, or at the group's first available frame once [`Self::set_frames`] has + /// Starts at 0, or at the group's first available frame once [`Self::with_range`] has /// clamped it, and advances by one per frame read. pub fn index(&self) -> u64 { self.cursor.index as u64 } - /// Limit subsequent reads to these frame indices without rewinding read progress. + /// Limit subsequent reads to these frame indices without rewinding read progress, + /// returning `self` for chaining. /// - /// `2..=5` includes frames 2 through 5; `2..5` excludes frame 5. An omitted - /// start preserves read progress, and an omitted end removes the cap. - /// Raising the cap makes unread cached frames available again. - pub fn set_frames(&mut self, frames: impl RangeBounds) { + /// `2..=5` includes frames 2 through 5; `2..5` excludes frame 5, and `..0` is the empty + /// range. The start skips ahead, clamped *up* to the group's first available frame: + /// frames the group never held (see [`Producer::start_at`]) can't be returned, so read + /// [`Self::index`] back to learn where the cursor landed. A start below the cursor is + /// ignored, since those frames may already have been handed out. The end is assigned: + /// reads past it end cleanly (`None`), as if the group finished there, and an omitted + /// end removes the cap. Raising the cap re-offers frames that are still cached. + pub fn with_range(mut self, frames: impl RangeBounds) -> Self { let (start, end) = super::subscription::sequence_bounds(frames); - self.start_at(start); - self.end_at(end.map_or(Bound::Unbounded, Bound::Excluded)); + self.cursor.start_at(start); + self.cursor.end = end.map(|end| usize::try_from(end).unwrap_or(usize::MAX)); + self } - /// Skip ahead so the next frame returned is `index`, discarding anything buffered - /// below it. - /// - /// Clamped *up* to the group's first available frame: frames the group never held - /// (see [`Producer::start_at`]) can't be returned, so asking for one just starts at - /// the first that exists. Read [`Self::index`] back to learn where the cursor - /// actually landed. - /// Only moves forward; a lower `index` is ignored, since the frames behind the - /// cursor may already have been handed out. - pub(crate) fn start_at(&mut self, index: u64) { - self.cursor.start_at(index); + /// Cap reads before frame `end`, or remove the cap with `None`, without moving the + /// start, which [`Self::with_range`] would clamp up to the first available frame. + pub(crate) fn with_end(mut self, end: impl Into>) -> Self { + self.cursor.end = end.into().map(|end| usize::try_from(end).unwrap_or(usize::MAX)); + self } /// Advance the read cursor to `index`, skipping every frame below it. /// - /// Unlike [`Self::set_frames`], this does not clamp past a requested frame the group + /// Unlike [`Self::with_range`], this does not clamp past a requested frame the group /// never held. A [`Producer::start_at`] floor above `index` still surfaces as /// [`Error::Lagged`]. pub fn skip_to(&mut self, index: u64) { self.cursor.skip_to(index); } - /// Stop reading at `end`, or remove the cap with `..`. - /// - /// `..=2` reads through frame 2, `..2` stops before it, and `..0` is the empty range: - /// no frame is delivered. Reads past the cap end cleanly (`None`), as if the group - /// finished there. The cap can move in either direction: raising it re-offers - /// frames that are still cached. - pub(crate) fn end_at(&mut self, end: impl Into) { - let end = end.into().exclusive(); - self.cursor.end = end.map(|end| usize::try_from(end).unwrap_or(usize::MAX)); - } - /// The number of frames written so far (completed plus any in-flight), independent of /// how many this consumer has read. The final total once the group is finished. pub fn frame_count(&self) -> usize { @@ -2883,7 +2842,7 @@ impl Consumer { /// Poll for the next frame, without blocking. /// /// Returns None if the group is finished and the index is out of range, or the cursor - /// passed the [`Self::set_frames`] cap. + /// passed the [`Self::with_range`] cap. pub fn poll_next_frame(&mut self, waiter: &kio::Waiter) -> Poll>> { if self.recover.is_none() { return self.poll_next_frame_once(waiter); @@ -3000,7 +2959,11 @@ impl Consumer { Ok(out.filled_mut()) } - /// Poll until the group terminates, returning this cursor's next frame index. + /// Poll until the group terminates, or this cursor reaches the end of its range, returning + /// its next frame index. + /// + /// An error means the frames this cursor has yet to read are gone (evicted, cut, or + /// failed upstream) and no route will continue them. pub fn poll_finished(&mut self, waiter: &kio::Waiter) -> Poll> { if self.recover.is_none() { return self.poll_finished_once(waiter); @@ -3016,6 +2979,10 @@ impl Consumer { return Poll::Ready(Err(Error::Old)); } let index = self.cursor.index; + // Reads end cleanly at the range's end, whatever becomes of the frames past it. + if self.cursor.capped() { + return Poll::Ready(Ok(index as u64)); + } let res = self .cursor .poll(waiter, |state| state.poll_end(index)) @@ -3023,7 +2990,8 @@ impl Consumer { self.poll_expired_if_blocked(waiter, res) } - /// Block until the group terminates, returning this cursor's next frame index. + /// Block until the group terminates, or this cursor reaches the end of its range, returning + /// its next frame index. /// /// This answers for the cursor, not the group: a reader that drained every frame gets the /// clean end even if the group was aborted afterwards to release its cache, while one that @@ -3258,7 +3226,7 @@ pub struct Fetch { /// cached locally and only the tail is missing. /// /// There is no matching end: a fetch always runs to the end of the group, and a - /// caller wanting less caps the returned consumer with [`Consumer::set_frames`]. Stopping + /// caller wanting less caps the returned consumer with [`Consumer::with_range`]. Stopping /// the *fetch* short would put a group in the cache that is indistinguishable from a /// complete one, so a later fetch of the whole group would resolve from it and come /// up short. @@ -3662,10 +3630,10 @@ mod test { group }) .collect(); - subscriber.set_groups(..0); + subscriber.set_range(..0); let waiter = kio::Waiter::noop(); assert!(subscriber.poll_recv_group(&waiter).is_pending()); - subscriber.set_groups(..1); + subscriber.set_range(..1); let _unrelated = groups[2].handle.state.read(); let Poll::Ready(Ok(Some(group))) = subscriber.poll_recv_group(&waiter) else { panic!("group zero is in range") @@ -3883,8 +3851,7 @@ mod test { if wired_first { tail.set_wire(wire.clone()).unwrap(); } - let mut reader = tail.consume(); - reader.start_at(2); + let mut reader = tail.consume().with_range(2..); let before = pool.used(); tail.handle.adopt_head(&head); assert!(pool.used() >= before + 2, "the adopted frames are charged"); @@ -4482,8 +4449,7 @@ mod test { producer.write_frame(Timestamp::ZERO, Bytes::from_static(b"d")).unwrap(); producer.finish().unwrap(); - let mut consumer = producer.consume(); - consumer.start_at(1); + let mut consumer = producer.consume().with_range(1..); assert_eq!(consumer.index(), 3, "clamped up to the first frame that exists"); assert_eq!( consumer.read_frame().now_or_never().unwrap().unwrap().unwrap().payload, @@ -4503,7 +4469,7 @@ mod test { producer.finish().unwrap(); let mut consumer = producer.consume(); - consumer.set_frames(..2); + consumer = consumer.with_range(..2); assert_eq!( consumer.read_frame().now_or_never().unwrap().unwrap().unwrap().payload[0], 0 @@ -4517,7 +4483,7 @@ mod test { "capped reads end cleanly" ); - consumer.set_frames(..); + consumer = consumer.with_range(..); assert_eq!( consumer.read_frame().now_or_never().unwrap().unwrap().unwrap().payload[0], 2 @@ -4533,19 +4499,19 @@ mod test { } producer.finish().unwrap(); let mut consumer = producer.consume(); - consumer.set_frames(1..=1); + consumer = consumer.with_range(1..=1); assert_eq!( consumer.read_frame().now_or_never().unwrap().unwrap().unwrap().payload[0], 1 ); assert!(consumer.read_frame().now_or_never().unwrap().unwrap().is_none()); - consumer.set_frames(..3); + consumer = consumer.with_range(..3); assert_eq!( consumer.read_frame().now_or_never().unwrap().unwrap().unwrap().payload[0], 2 ); assert!(consumer.read_frame().now_or_never().unwrap().unwrap().is_none()); - consumer.set_frames(0..=3); + consumer = consumer.with_range(0..=3); assert_eq!( consumer.read_frame().now_or_never().unwrap().unwrap().unwrap().payload[0], 3 @@ -4562,13 +4528,13 @@ mod test { producer.finish().unwrap(); let mut consumer = producer.consume(); - consumer.set_frames(..0); + consumer = consumer.with_range(..0); assert!( consumer.read_frame().now_or_never().unwrap().unwrap().is_none(), "empty cap delivers nothing" ); - consumer.set_frames(..1); + consumer = consumer.with_range(..1); assert_eq!( consumer.read_frame().now_or_never().unwrap().unwrap().unwrap().payload, Bytes::from_static(b"x") @@ -5049,8 +5015,7 @@ mod test { group.write_frame(None, verbose(1)).unwrap(); group.finish().unwrap(); - let mut consumer = group.consume(); - consumer.set_frames(1..); + let mut consumer = group.consume().with_range(1..); assert!(matches!(read_plain(&mut consumer), Err(Error::Lagged))); assert!(matches!(read_plain(&mut consumer), Err(Error::Lagged))); } @@ -5131,4 +5096,53 @@ mod test { assert!(matches!(next.poll_next_frame(&waiter), Poll::Ready(Err(Error::Old)))); assert!(matches!(finished.poll_finished(&waiter), Poll::Ready(Err(Error::Old)))); } + + /// A reader capped by its range finishes there cleanly whatever becomes of the frames past + /// it, so a publisher that served the range keeps its stream when the rest fails upstream. + #[test] + fn a_capped_reader_finishes_at_its_range_end() { + let mut producer = Info { sequence: 0 }.produce(); + for payload in [b"a", b"b"] { + producer + .write_frame(crate::Timestamp::ZERO, Bytes::from_static(payload)) + .unwrap(); + } + let waiter = kio::Waiter::noop(); + let mut capped = producer.consume().with_range(..1); + let mut whole = producer.consume(); + assert!(capped.poll_finished(&waiter).is_pending(), "its frame is still unread"); + for reader in [&mut capped, &mut whole] { + assert!(matches!(reader.poll_read_frame(&waiter), Poll::Ready(Ok(Some(_))))); + } + + producer.abort(Error::Cancel).unwrap(); + assert!(matches!(capped.poll_finished(&waiter), Poll::Ready(Ok(1)))); + assert!(matches!(whole.poll_finished(&waiter), Poll::Ready(Err(Error::Cancel)))); + } + + /// A publisher that read every frame of a finished group still learns when the budget + /// gives up on it, so it can abandon the stream it is still writing. + #[test] + fn a_fully_read_group_still_reports_its_expiry() { + let mut producer = Info { sequence: 0 }.produce(); + producer + .write_frame(crate::Timestamp::ZERO, Bytes::from_static(b"a")) + .unwrap(); + producer.finish().unwrap(); + + let expired = Arc::new(AtomicBool::new(false)); + let mut group = producer.consume().with_expiry(Arc::new(Switch(expired.clone()))); + let waiter = kio::Waiter::noop(); + assert!(matches!(group.poll_read_frame(&waiter), Poll::Ready(Ok(Some(_))))); + assert!( + matches!(group.poll_read_frame(&waiter), Poll::Ready(Ok(None))), + "read whole" + ); + assert!(!group.poll_expired(&waiter)); + + expired.store(true, Ordering::Relaxed); + assert!(group.poll_expired(&waiter), "the writer abandons its stream"); + expired.store(false, Ordering::Relaxed); + assert!(group.poll_expired(&waiter), "and the verdict stands"); + } } diff --git a/rs/moq-net/src/model/mod.rs b/rs/moq-net/src/model/mod.rs index 8fa42f263fa..48101f0b509 100644 --- a/rs/moq-net/src/model/mod.rs +++ b/rs/moq-net/src/model/mod.rs @@ -39,7 +39,6 @@ use requests::Requests; use weak_cache::{WeakCache, WeakEntry}; pub use bytes::*; -pub(crate) use subscription::Cap; // Datagram stays flat at the crate root (a small track-adjacent wire type), // not under a role module. pub use datagram::*; diff --git a/rs/moq-net/src/model/resume.rs b/rs/moq-net/src/model/resume.rs index 01b37ab920e..811e1193f4a 100644 --- a/rs/moq-net/src/model/resume.rs +++ b/rs/moq-net/src/model/resume.rs @@ -29,6 +29,7 @@ use crate::sync::{Mutex, MutexGuard}; use std::collections::{BTreeSet, VecDeque}; +use std::ops::Bound; use std::sync::{Arc, PoisonError, Weak}; use std::task::{Poll, ready}; use std::time::Duration; @@ -37,7 +38,7 @@ use crate::time::Instant; use crate::{Error, Result, StreamError, group, stats, track}; use super::delivered::Delivered; -use super::subscription::{Anchor, Cap, Position, Resolved, Subscription, Unheld, Window}; +use super::subscription::{Anchor, Position, Resolved, Subscription, Unheld, Window}; use crate::ledger; /// What the front says about a logical track: the copy to read now, and how it ended. @@ -262,7 +263,7 @@ impl Consumer { newest: None, window, datagrams: Datagrams::default(), - groups: (floor, Cap::from(..)), + groups: (floor, None), groups_read: false, out: Vec::new(), peeked: None, @@ -436,18 +437,26 @@ impl Copy { } /// The subscription, once the copy answered. `Err` once it refused. - fn poll_ready(&mut self, groups: (u64, Cap), waiter: &kio::Waiter) -> Poll> { + fn poll_ready(&mut self, groups: (u64, Option), waiter: &kio::Waiter) -> Poll> { if let Sub::Pending(pending) = &self.sub { - let mut sub = ready!(pending.poll_ok(waiter))?; + let sub = ready!(pending.poll_ok(waiter))?; // An anchor the wire kept may resolve below where the reader got to. - sub.raise_start_to(self.floor.map_or(groups.0, |floor| groups.0.max(floor.group))); - sub.end_at(groups.1); + let sub = sub.with_range(( + Bound::Included(self.start(groups.0)), + groups.1.map_or(Bound::Unbounded, Bound::Excluded), + )); self.sub = Sub::Ready(Box::new(sub)); } let Sub::Ready(sub) = &mut self.sub else { unreachable!() }; Poll::Ready(Ok(sub)) } + /// The local floor `start` as this copy applies it: never below its own resume point, + /// since groups under it were handed out by an earlier route, or never owed. + fn start(&self, start: u64) -> u64 { + self.floor.map_or(start, |floor| start.max(floor.group)) + } + /// Whether `within` passed since this copy was superseded; see [`Self::since`]. Parks /// `waiter` until it has, so a reader waiting on the copy looks again then. fn expired(&self, within: Duration, waiter: &kio::Waiter) -> bool { @@ -535,7 +544,7 @@ impl Copy { /// What [`Copy::retains`] judges a replaced copy by: its reader, as it lets copies go. struct Retain<'a> { - groups: (u64, Cap), + groups: (u64, Option), window: &'a Window, groups_read: bool, /// The newest group the serving copy has. @@ -681,21 +690,9 @@ impl Subscriber { } } - /// Raise the local read floor; see [`track::Subscriber::set_groups`]. - pub(super) fn raise_start_to(&mut self, start: u64) { - self.reader().raise_start_to(start) - } - - /// Move the local read floor to `start`, including downward. - /// See [`track::Subscriber::start_at`]. - #[cfg_attr(not(feature = "async"), allow(dead_code, reason = "async-only"))] - pub(super) fn start_at(&mut self, start: u64) { - self.reader().start_at(start) - } - - /// Cap local reads at `end`; see [`track::Subscriber::set_groups`]. - pub(super) fn end_at(&mut self, end: Cap) { - self.reader().end_at(end) + /// Assign the local read floor and exclusive cap; see [`track::Subscriber::with_range`]. + pub(super) fn set_range(&mut self, start: u64, end: Option) { + self.reader().set_range(start, end) } /// Whether any subscribed copy still has a group matching `unread`. @@ -726,10 +723,7 @@ impl Subscriber { /// The local group filter, as [`track::Subscriber::poll_largest`] reports within it. pub(super) fn bounds(&self) -> track::Bounds { let (start, end) = self.reader().groups; - track::Bounds { - start, - end: end.exclusive(), - } + track::Bounds { start, end } } /// The groups the copies' drift budget skipped since the last call, counted against @@ -829,8 +823,8 @@ struct Reader { window: Window, /// Identities handed out within the reader's budget, by Group and Object ID, and the highest ever. datagrams: Datagrams, - /// The local group filter; see [`track::Subscriber::set_groups`]. - groups: (u64, Cap), + /// The local floor and exclusive cap; see [`track::Subscriber::with_range`]. + groups: (u64, Option), /// Whether groups were ever asked for; until then the reader keeps no replaced copy. groups_read: bool, /// The groups handed out, by sequence, held while each is read. @@ -987,8 +981,12 @@ impl Reader { // Resume where a fresh copy would: a group it buffered while replaced, below the // newest another route handed out, is not handed out. copy.floor = copy.floor.max(self.newest.map(Position::group)); - if let (Sub::Ready(sub), Some(floor)) = (&mut copy.sub, copy.floor) { - sub.raise_start_to(floor.group); + let start = copy.start(self.groups.0); + if let (Sub::Ready(sub), Some(_)) = (&mut copy.sub, copy.floor) { + sub.set_range(( + Bound::Included(start), + self.groups.1.map_or(Bound::Unbounded, Bound::Excluded), + )); } copy.update(&self.mirrored); self.copies.push(copy); @@ -1264,7 +1262,7 @@ impl Reader { .declared .filter(|end| end.frame != 0 && end.group == group.sequence) { - group.end_at(..end.frame); + group = group.with_end(end.frame); } let group = self.hand_out(index, group); Some(Poll::Ready(Ok(Some(group)))) @@ -1568,37 +1566,15 @@ impl Reader { } } - fn raise_start_to(&mut self, start: u64) { - self.peeked = None; - self.groups.0 = self.groups.0.max(start); - for copy in &mut self.copies { - if let Sub::Ready(sub) = &mut copy.sub { - sub.raise_start_to(start); - } - } - } - - /// Assign the local floor. A copy still waiting on its info takes the floor - /// from the mirrored subscription when it resolves; one already reading has - /// to be moved, or a group it skipped stays skipped. Never below a copy's own - /// resume point: groups under it were handed out by an earlier route, or never owed. - #[cfg_attr(not(feature = "async"), allow(dead_code, reason = "async-only"))] - fn start_at(&mut self, start: u64) { - self.peeked = None; - self.groups.0 = start; - for copy in &mut self.copies { - if let Sub::Ready(sub) = &mut copy.sub { - sub.start_at(copy.floor.map_or(start, |floor| start.max(floor.group))); - } - } - } - - fn end_at(&mut self, end: Cap) { + /// Assign the local floor and cap. A copy still waiting on its info takes them when it + /// resolves; one already reading has to be moved, or a group it skipped stays skipped. + fn set_range(&mut self, start: u64, end: Option) { self.peeked = None; - self.groups.1 = end; + self.groups = (start, end); for copy in &mut self.copies { + let start = copy.start(start); if let Sub::Ready(sub) = &mut copy.sub { - sub.end_at(end); + sub.set_range((Bound::Included(start), end.map_or(Bound::Unbounded, Bound::Excluded))); } } } @@ -1795,9 +1771,9 @@ impl Recover { if copy.generation == self.generation { return None; } - let mut group = copy.track.peek_group(self.sequence)?; + let group = copy.track.peek_group(self.sequence)?; lend_head(&self.handoff, self.sequence, ©.track, &group); - group.start_at(index); + let group = group.with_range(index..); (group.index() == index).then(|| Replacement { group, generation: copy.generation, @@ -1819,9 +1795,9 @@ impl Recover { // failed delivered it already, so its subscription will not again. let same = generation == self.generation; match serving.poll_group(self.sequence, waiter) { - Poll::Ready(Ok(Some(mut group))) if !same => { + Poll::Ready(Ok(Some(group))) if !same => { lend_head(&self.handoff, self.sequence, serving, &group); - group.start_at(index); + let group = group.with_range(index..); if group.index() == index { return Poll::Ready(Ok(Replacement { group, @@ -1858,9 +1834,9 @@ impl Recover { Fetch::Refused(err) if route_failed(err) || copy_failed(serving) => return Poll::Pending, Fetch::Refused(err) => err.clone(), Fetch::Pending(pending) => match ready!(kio::Task::poll(&mut **pending, waiter)) { - Ok(mut group) => { + Ok(group) => { lend_head(&self.handoff, self.sequence, serving, &group); - group.start_at(index); + let group = group.with_range(index..); if group.index() == index { return Poll::Ready(Ok(Replacement { group, @@ -2965,9 +2941,9 @@ mod test { for sequence in 0..5 { write(&a, sequence); } - sub.set_groups(..3); + sub.set_range(..3); assert!(sub.largest().now_or_never().is_none(), "the largest is past the cap"); - sub.set_groups(..); + sub.set_range(..); assert_eq!(sub.largest().now_or_never(), Some(Some(Position::group(4)))); } @@ -2980,7 +2956,7 @@ mod test { let logical = logical(&routes); let a = copy(); routes.serve(a.consume()); - let subscription = Subscription::default().with_max_delay(HOUR).with_groups(8..); + let subscription = Subscription::default().with_max_delay(HOUR).with_range(8..); let mut sub = logical .consume() .subscribe(subscription) @@ -3066,6 +3042,27 @@ mod test { } } + /// Lowering a front reader's local floor offers the cached groups below the old one it + /// passed over, as a plain reader does. + #[test] + fn a_lowered_range_reoffers_the_unread_cached_groups() { + let routes = Producer::new(); + let logical = logical(&routes); + let a = copy(); + routes.serve(a.consume()); + let mut sub = subscribe(&logical, HOUR).with_range(4..); + for sequence in 0..6 { + write(&a, sequence); + } + assert_eq!(drain(&mut sub, false), vec![4, 5]); + + let mut sub = sub.with_range(1..); + assert_eq!(drain(&mut sub, false), vec![1, 2, 3], "passed below the floor"); + let mut sub = sub.with_range(..); + assert_eq!(drain(&mut sub, false), vec![0]); + assert_eq!(drain(&mut sub, false), Vec::::new(), "nothing goes out twice"); + } + #[test] fn a_fresh_nested_reader_ends_after_its_outer_reader_already_passed_its_groups() { let routes = Producer::new(); @@ -3111,7 +3108,7 @@ mod test { let a = copy(); routes.serve(a.consume()); let mut sub = subscribe(if nested { &outer } else { &inner }, HOUR); - sub.set_groups(..0); + sub.set_range(..0); for sequence in 0..4 { write(&a, sequence); } @@ -3128,7 +3125,7 @@ mod test { let c = track::Request::new(Arc::new(broadcast::Info::default()), "video"); routes.serve(c.consume()); assert!(drain(&mut sub, true).is_empty()); - sub.set_groups(..); + sub.set_range(..); assert_eq!(drain(&mut sub, true), [0, 1, 2, 3], "nested={nested}"); { let readers = routes.readers.lock().unwrap(); @@ -3733,7 +3730,7 @@ mod test { let a = copy(); routes.serve(a.consume()); let mut sub = subscribe(&logical, HOUR); - sub.end_at(Cap::from(..=0)); + sub.set_range(..=0); let mut held = a.create_group(group::Info { sequence: 0 }).unwrap(); held.write_frame(ts(0), b"a".as_ref()).unwrap(); let Poll::Ready(Ok(Some(reading))) = sub.poll_recv_group(&kio::Waiter::noop()) else { @@ -3751,11 +3748,11 @@ mod test { } assert_eq!(drain(&mut sub, false), Vec::::new()); - sub.end_at(Cap::from(..)); + sub.set_range(..); let mut seen = drain(&mut sub, false); seen.sort_unstable(); assert_eq!(seen, [1, 2, 3]); - sub.start_at(0); + sub.set_range(..); assert_eq!(drain(&mut sub, false), Vec::::new()); // The replaced copy ends with the held group, declaring no end: another route continues the track. @@ -3830,7 +3827,7 @@ mod test { group.finish().unwrap(); } - sub.start_at(0); + sub.set_range(..); assert_eq!(recv(&mut sub).sequence, 6); } @@ -3908,7 +3905,7 @@ mod test { assert!(matches!(copy.sub, Sub::Pending(_))); copy.update(&updated); assert_eq!(copy.wire(&updated).ranges, ranges); - assert!(copy.poll_ready((0, Cap::from(..)), &kio::Waiter::noop()).is_ready()); + assert!(copy.poll_ready((0, None), &kio::Waiter::noop()).is_ready()); assert_eq!(copy.wire(&updated).ranges, ranges); } @@ -5322,9 +5319,9 @@ mod test { routes.serve(b.consume()); assert!(sub.recv_datagram().now_or_never().is_none()); if raise_floor { - sub.set_groups(1..); + sub.set_range(1..); } else { - sub.set_groups(..0); + sub.set_range(..0); } assert!( if ordered { @@ -5335,7 +5332,7 @@ mod test { .is_pending() ); if !raise_floor { - sub.set_groups(..); + sub.set_range(..); let next = if ordered { sub.poll_next_group(&kio::Waiter::noop()) } else { diff --git a/rs/moq-net/src/model/subscription.rs b/rs/moq-net/src/model/subscription.rs index 59ce5256b83..85c7bccf93a 100644 --- a/rs/moq-net/src/model/subscription.rs +++ b/rs/moq-net/src/model/subscription.rs @@ -1,5 +1,5 @@ use std::{ - ops::{Bound, RangeBounds, RangeFull, RangeTo, RangeToInclusive}, + ops::{Bound, RangeBounds}, time::Duration, }; @@ -78,7 +78,7 @@ pub struct Subscription { /// A request to the publisher, aggregated across every live subscriber as the union of /// their ranges, and this subscriber's read filter: it reads only the groups and frames /// its own ranges cover, whatever another subscriber widens the union to. - /// [`crate::track::Subscriber::set_groups`] narrows the reads further. See [Local cursor + /// [`crate::track::Subscriber::with_range`] narrows the reads further. See [Local cursor /// vs wire preference](crate::track::Subscriber#local-cursor-vs-wire-preference). pub ranges: Vec, /// Which pending group the publisher sends first; see [`Order`]. @@ -306,7 +306,7 @@ impl Subscription { /// Request the whole groups in `groups` as the only range; see [`Range::groups`]. /// Returns `self` for chaining. - pub fn with_groups(self, groups: impl RangeBounds) -> Self { + pub fn with_range(self, groups: impl RangeBounds) -> Self { self.with_ranges([Range::groups(groups)]) } @@ -348,28 +348,28 @@ impl Subscription { end } - /// Replace the ranges with one from `start` (or [`Range::oldest`]'s) to `end`: the form - /// a wire without ranges carries. + /// Replace the ranges with one from `start` (or [`Range::oldest`]'s) up to [`Self::end`], + /// returning `self` for chaining: the form a wire without ranges carries. #[cfg(any(feature = "async", test))] - pub(crate) fn set_bounds(&mut self, start: Option, end: Option) { - self.ranges = vec![Range { - start: start.map_or(Range::oldest().start, Anchor::Absolute), - end: end.map(Anchor::Absolute), - }]; + pub(crate) fn with_start(self, start: impl Into>) -> Self { + let end = self.end(); + self.with_span(start.into(), end) } - /// Replace the start of [`Self::set_bounds`]'s one range, keeping its end. - #[cfg(feature = "async")] - pub(crate) fn with_start(mut self, start: impl Into>) -> Self { - self.set_bounds(start.into(), self.end()); - self + /// Replace the ranges with one from [`Self::start`] up to the exclusive `end`, or onward + /// for `None`, returning `self` for chaining: the form a wire without ranges carries. + #[cfg(any(feature = "async", test))] + pub(crate) fn with_end(self, end: impl Into>) -> Self { + let start = self.start(); + self.with_span(start, end.into()) } - /// Replace the end of [`Self::set_bounds`]'s one range, keeping its start. #[cfg(any(feature = "async", test))] - pub(crate) fn with_end(mut self, end: impl Into>) -> Self { - self.set_bounds(self.start(), end.into()); - self + fn with_span(self, start: Option, end: Option) -> Self { + self.with_ranges([Range { + start: start.map_or(Range::oldest().start, Anchor::Absolute), + end: end.map(Anchor::Absolute), + }]) } /// These preferences with every range raised to start no earlier than `floor` and @@ -520,7 +520,7 @@ impl Position { } /// The bound this exclusive end puts on a group cursor, for - /// [`crate::track::Subscriber::set_groups`]. + /// [`crate::track::Subscriber::with_range`]. /// /// A head-of-group end excludes its group. A mid-group end includes it, so a frame /// cap can apply within that group. @@ -532,54 +532,21 @@ impl Position { } } - /// The first group this exclusive end excludes whole, `None` past the last group. + /// The first group this exclusive end excludes whole, `None` past the last group: the + /// boundary a wire that cannot name a frame carries as the track's end. pub(crate) fn final_sequence(self) -> Option { self.group.checked_add(u64::from(self.frame != 0)) } } -/// Where a read cursor stops: a group sequence or frame index it will not deliver. -/// -/// Built from a range so the call site says whether its bound is delivered: `..5` stops -/// before 5, `..=5` reads through it, and `..` removes the cap. A [`Bound`] converts -/// too, for callers holding one (a decoded wire field, or [`Position::group_end`]). -#[derive(Clone, Copy, Debug, PartialEq, Eq)] -pub(crate) struct Cap(Option); - -impl Cap { - /// The first index withheld, or `None` for no cap. Cursors store this form and - /// compare with [`before_end`]. An inclusive bound at `u64::MAX` has nothing above - /// it, so it is no cap at all. - pub(super) fn exclusive(self) -> Option { - self.0 - } -} - -impl From> for Cap { - fn from(bound: Bound) -> Self { - Self(match bound { - Bound::Included(index) => index.checked_add(1), - Bound::Excluded(index) => Some(index), - Bound::Unbounded => None, - }) - } -} - -impl From> for Cap { - fn from(range: RangeTo) -> Self { - Self(Some(range.end)) - } -} - -impl From> for Cap { - fn from(range: RangeToInclusive) -> Self { - Bound::Included(range.end).into() - } -} - -impl From for Cap { - fn from(_: RangeFull) -> Self { - Self(None) +/// The first index an end bound withholds, or `None` for no cap: the form cursors store +/// and compare with [`before_end`]. An inclusive bound at `u64::MAX` has nothing above it, +/// so it is no cap at all. +fn exclusive_end(bound: Bound<&u64>) -> Option { + match bound { + Bound::Included(index) => index.checked_add(1), + Bound::Excluded(&index) => Some(index), + Bound::Unbounded => None, } } @@ -593,7 +560,7 @@ pub(super) fn sequence_bounds(range: impl RangeBounds) -> (u64, Option }, Bound::Unbounded => 0, }; - (start, Cap::from(range.end_bound().cloned()).exclusive()) + (start, exclusive_end(range.end_bound())) } /// Whether `sequence` is strictly below an exclusive cap. `None` is unbounded. @@ -637,7 +604,7 @@ mod tests { // Through the last group is unbounded, as `after_group` spells it. assert_eq!(Range::groups(..=u64::MAX).end, None); - let sub = Subscription::default().with_groups(2..=5).with_groups(..); + let sub = Subscription::default().with_range(2..=5).with_range(..); assert_eq!(sub, Subscription::default()); } @@ -659,12 +626,14 @@ mod tests { // A cursor cap is the first index it withholds; an inclusive bound at the last // index withholds nothing. - assert_eq!(Cap::from(..0).exclusive(), Some(0)); - assert_eq!(Cap::from(..=5).exclusive(), Some(6)); - assert_eq!(Cap::from(..=u64::MAX).exclusive(), None); - assert_eq!(Cap::from(..).exclusive(), None); - assert_eq!(Cap::from(Bound::Included(5)), Cap::from(..6)); - assert_eq!(Cap::from(Bound::Unbounded), Cap::from(..)); + assert_eq!(sequence_bounds(..0), (0, Some(0))); + assert_eq!(sequence_bounds(..=5), (0, Some(6))); + assert_eq!(sequence_bounds(..=u64::MAX), (0, None)); + assert_eq!(sequence_bounds(..), (0, None)); + assert_eq!( + sequence_bounds((Bound::Unbounded, Bound::Included(5))), + sequence_bounds(..6) + ); } /// A relative start counts back from the latest group and clamps at group 0. Before any @@ -709,7 +678,7 @@ mod tests { ); // An explicit group 0 is a floor, unlike the default. - let sub = Subscription::default().with_groups(0..); + let sub = Subscription::default().with_range(0..); assert_eq!((sub.start(), sub.end()), (Some(Position::group(0)), None)); let sub = Subscription::default().with_ranges([Range::groups(2..4), Range::live()]); @@ -722,14 +691,14 @@ mod tests { let sub = Subscription::default().with_ranges([]); assert_eq!(sub.end(), Some(Position::group(0))); - let mut sub = Subscription::default(); - sub.set_bounds(Some(Position { group: 5, frame: 2 }), Position::after_group(9)); + let sub = Subscription::default() + .with_start(Position { group: 5, frame: 2 }) + .with_end(Position::after_group(9)); assert_eq!( (sub.start(), sub.end()), (Some(Position { group: 5, frame: 2 }), Some(Position::group(10))) ); - sub.set_bounds(None, None); - assert_eq!(sub, Subscription::default()); + assert_eq!(sub.with_start(None).with_end(None), Subscription::default()); } /// The aggregate is the union: overlapping and adjacent absolute ranges merge, an open diff --git a/rs/moq-net/src/model/track.rs b/rs/moq-net/src/model/track.rs index 7c58c1e0736..e955ac46f15 100644 --- a/rs/moq-net/src/model/track.rs +++ b/rs/moq-net/src/model/track.rs @@ -21,7 +21,6 @@ use super::delivered::Delivered; use super::{Datagram, Requests}; use crate::ledger::{self, Ledger}; -use super::Cap; pub use super::subscription::{Anchor, Order, Position, Range, Subscription}; use super::subscription::{Containing, Held, Holdings, Resolved, Window, later}; use rangemap::{RangeInclusiveSet, RangeMap, RangeSet}; @@ -1231,7 +1230,7 @@ impl TrackState { /// would make walking a backlog of N groups off in one poll cost O(N^2). /// /// Bounded because a group can only be late relative to data that would actually be - /// served in its place: a reader capped by [`Subscriber::set_groups`] can't jump past + /// served in its place: a reader capped by [`Subscriber::with_range`] can't jump past /// the cap, and one reading disjoint ranges never reads the gap between them, so the /// groups it still wants aren't stale just because the track ran on. /// Fetched backfill is absent from `arrival`, so it cannot age subscription content @@ -5223,9 +5222,11 @@ impl kio::Task for Fetching { max_delay: self.max_delay, superseded: Superseded::default(), }); - let resolve = |mut group: group::Consumer| { - group.start_at(frame_start); - group.with_meter(self.stats.meter()).with_expiry(expiry.clone()) + let resolve = |group: group::Consumer| { + group + .with_range(frame_start..) + .with_meter(self.stats.meter()) + .with_expiry(expiry.clone()) }; if let Some(group) = &self.hit { return Poll::Ready(Ok(resolve((**group).clone()))); @@ -5312,7 +5313,7 @@ impl kio::Task for Fetching { /// every live subscriber, but each subscriber reads only the groups its own ranges cover, /// resolved where it is served: a relative anchor counted back from the latest group (or /// the first to arrive, before any exists), again whenever the ranges are replaced. -/// - [`Self::set_groups`] narrows **this subscriber's reads** further, without changing the +/// - [`Self::with_range`] narrows **this subscriber's reads** further, without changing the /// publisher's demand. /// /// A group outside either is held rather than skipped past, so widening either one later @@ -5648,7 +5649,7 @@ struct Cursor { index: usize, /// Arrival-order cursor used by `recv_datagram`, independent of groups. datagram_index: usize, - /// Minimum sequence to return from any `recv` method. Set by `start_at`. + /// Minimum sequence to return from any `recv` method. Set by `set_range`. min_sequence: u64, /// This subscriber's own ranges, resolved. Boxed: every reader embeds a cursor. filter: Box, @@ -5659,8 +5660,8 @@ struct Cursor { /// The exact candidate a route-copy selection inspected, including its arrival /// position. Consuming it must not look up a different group after eviction. peeked: Option>, - /// Exclusive upper sequence bound for `next_group` and `recv_group`, in the form - /// [`Cap::exclusive`] produces. `None` means no cap. Set by `end_at`; + /// Exclusive upper sequence bound for `next_group` and `recv_group`. `None` means no + /// cap. Set by `set_range`; /// can be raised, lowered, or unset at any time. Groups at or past the cap stay in /// the producer's cache and become eligible again when the cap rises (or is removed). /// `Some(0)` is the empty range. @@ -6182,7 +6183,7 @@ impl Cursor { let (start, end) = self.filter.window.frames(group.sequence); group.skip_to(start); if let Some(end) = end { - group.end_at(Bound::Excluded(end)); + group = group.with_end(end); } } let sequence = group.sequence; @@ -6481,7 +6482,7 @@ impl Cursor { /// the entry waits in [`Self::seek_pending`], where a delivered group removes itself /// (see [`Self::poll_next_group`]). `committed` must be the sequence watermark (one /// past the last delivery), which only rises. The seek's floor is NOT that: it - /// includes `start_at`, which can be lowered again, and a conviction it flushed could + /// includes the local floor, which can be lowered again, and a conviction it flushed could /// then be delivered after all. fn commit_seek_stale(&mut self, committed: u64) { let keep = self.seek_pending.split_off(&committed); @@ -6649,7 +6650,7 @@ impl Subscriber { /// one that has drifted further behind the live edge than the budget tolerates is /// skipped rather than handed over, so a single poll walks off a whole backlog. The /// default is [`Duration::ZERO`], which takes the live - /// edge and writes the rest off; raise it to read history. [`Self::set_groups`] and + /// edge and writes the rest off; raise it to read history. [`Self::with_range`] and /// [`Subscription::ranges`] are filters, not exemptions: backfill needs a budget that /// covers it. [`Consumer::fetch_group`] is the way to ask for one old group outright. /// Across same-epoch route copies, the lowest next buffered group is delivered @@ -6657,7 +6658,7 @@ impl Subscriber { /// The budget remains attached to a returned group: if it stalls while newer data /// advances, its pending frame read ends with [`Error::Old`]. /// - /// Honors the group range set by [`Self::set_groups`]: a group beyond the cap is + /// Honors the group range set by [`Self::with_range`]: a group beyond the cap is /// passed without blocking in-range groups that arrive behind it, and holds nothing /// here. Raising the cap, or widening the ranges, offers the groups it newly covers /// that the cache still holds, lowest sequence first. Once the track finishes, a @@ -6818,7 +6819,7 @@ impl Subscriber { /// Every group sequence is returned at most once, in the order it landed on the wire, which may /// be out of sequence due to network reordering or loss. Use [`Self::ordered`] if you /// only want groups whose sequence number is higher than any previously returned. - /// See [`Self::poll_recv_group`] for how [`Self::set_groups`] applies. + /// See [`Self::poll_recv_group`] for how [`Self::with_range`] applies. #[cfg(feature = "async")] pub async fn recv_group(&mut self) -> Result> { kio::wait(|waiter| self.poll_recv_group(waiter)).await @@ -6925,8 +6926,8 @@ impl Subscriber { } /// Poll for where the source's feed starts, raised to this cursor's floor, once - /// resolved; see [`Subscriber::poll_start`]. A feed starting below the floor serves the - /// floor's group too. `None` when the source declares none. + /// resolved: the first group a publisher tells its peer it serves. A feed starting + /// below the floor serves the floor's group too. `None` when the source declares none. #[cfg_attr(not(feature = "async"), allow(dead_code, reason = "async-only"))] pub(crate) fn poll_start(&mut self, waiter: &kio::Waiter) -> Poll> { let cursor = match &mut self.inner { @@ -6939,7 +6940,7 @@ impl Subscriber { } /// The lowest group this subscriber's ranges name, as resolved here when it last read, - /// raised to the start of [`Self::set_groups`]: `None` while one reaches back to the + /// raised to the start of [`Self::with_range`]: `None` while one reaches back to the /// oldest group still around, or a relative start still waits on the first group from /// the live feed. /// @@ -6954,7 +6955,7 @@ impl Subscriber { } /// The lowest group at or above `from` this subscriber's ranges and - /// [`Self::set_groups`] floor cover, `None` when none does: the groups between are + /// [`Self::with_range`] floor cover, `None` when none does: the groups between are /// never read, so a reader waiting on each group in sequence need not wait for them. /// `Some` from there while a relative anchor waits on the first group, which can't /// say yet. @@ -7003,11 +7004,11 @@ impl Subscriber { } } - /// Poll for sequences this subscription gave up without serving, with the error each - /// run was given up with. + /// Poll for a run of sequences this subscription gave up without serving, with the + /// error it was given up with, so a publisher can tell its peer not to wait for them. /// - /// Stale skips are recorded only once this has been polled, so a cursor no wire - /// publisher forwards drops for keeps none. + /// Stale skips are recorded only once this has been polled, so a reader that never + /// forwards drops keeps none. #[cfg_attr(not(feature = "async"), allow(dead_code, reason = "async-only"))] pub(crate) fn poll_drop(&mut self, waiter: &kio::Waiter) -> Poll<(ops::Range, StreamError)> { match &mut self.inner { @@ -7057,74 +7058,36 @@ impl Subscriber { kio::wait(|waiter| self.poll_finished(waiter)).await } - /// Limit subsequent reads to these group sequences without rewinding read progress. + /// Limit subsequent reads to these group sequences, returning `self` for chaining. /// - /// `2..=5` includes groups 2 through 5; `2..5` excludes group 5. An omitted - /// start preserves the current floor, and an omitted end removes the cap. - /// Groups above the end stay cached and can be read after raising the cap. - /// [`Self::poll_largest`] reports within these bounds. - /// This narrows only local delivery, within [`Subscription::ranges`]; use those and - /// [`Self::update`] to change the requested groups. - pub fn set_groups(&mut self, groups: impl RangeBounds) { - let (start, end) = super::subscription::sequence_bounds(groups); - self.raise_start_to(start); - self.end_at(end.map_or(Bound::Unbounded, Bound::Excluded)); - } - - /// Start this subscriber's read cursor at the given sequence. + /// `2..=5` includes groups 2 through 5; `2..5` excludes group 5, and `..0` is the + /// empty range. Both bounds are assigned, in either direction: an omitted start is + /// group 0 and an omitted end removes the cap. Lowering the floor or raising the cap + /// offers the groups it newly covers that the cache still holds and this reader never + /// handed out, lowest first; a group is never handed out twice. Groups past the cap + /// stay cached, and lowering the cap below the cursor waits until it rises again or + /// the track finishes. [`Self::poll_largest`] reports within these bounds. /// - /// A local filter, not a request: it doesn't tell the publisher anything, so the - /// skipped groups are still delivered and simply not returned. To ask the publisher - /// to start there too, set [`Subscription::ranges`] via [`Self::update`]. - /// See [Local cursor vs wire preference](Self#local-cursor-vs-wire-preference). - #[cfg_attr(not(feature = "async"), allow(dead_code, reason = "async-only"))] - pub(crate) fn start_at(&mut self, sequence: u64) { - match &mut self.inner { - Inner::Plain(cursor) => { - cursor.peeked = None; - cursor.min_sequence = sequence; - } - // Assigns, including downward. A front serves every viewer of a path, - // and a later SUBSCRIBE_UPDATE can widen the floor; raising only would - // leave a finished group below the old floor unread. - Inner::Resume(resume, _) => resume.start_at(sequence), - } - self.largest.bounds_moved(); - } - - /// Raise the read cursor's floor to `sequence`, keeping any higher floor already set. - pub(crate) fn raise_start_to(&mut self, sequence: u64) { - match &mut self.inner { - Inner::Plain(cursor) => { - cursor.peeked = None; - cursor.min_sequence = cursor.min_sequence.max(sequence); - } - Inner::Resume(resume, _) => resume.raise_start_to(sequence), - } - self.largest.bounds_moved(); + /// A local filter, not a request: it tells the publisher nothing, so groups outside it + /// are still delivered and simply not returned. To change what is requested, set + /// [`Subscription::ranges`] via [`Self::update`]. See [Local cursor vs wire + /// preference](Self#local-cursor-vs-wire-preference). + pub fn with_range(mut self, groups: impl RangeBounds) -> Self { + self.set_range(groups); + self } - /// Cap this subscriber's read cursor at `end`, or remove the cap with `..`. - /// - /// The range says whether its sequence is delivered: `..=5` serves through group 5, - /// `..5` stops before it. `..0` is the empty range: no group is delivered. - /// [`Position::group_end`] translates a range's absolute end. - /// - /// A local filter, not a request; [`Subscription::ranges`] are the wire-level - /// counterpart. See [Local cursor vs wire preference](Self#local-cursor-vs-wire-preference). - /// - /// Groups beyond the cap stay in the cache, so a later call to [`Self::set_groups`] - /// with a higher bound (or unbounded) offers the ones still cached. Lowering the cap - /// below the consumer's current cursor waits until the cap is raised, or the track - /// finishes. - pub(crate) fn end_at(&mut self, end: impl Into) { + /// [`Self::with_range`] on a reader held in place. + pub(crate) fn set_range(&mut self, groups: impl RangeBounds) { + let (start, end) = super::subscription::sequence_bounds(groups); match &mut self.inner { Inner::Plain(cursor) => { cursor.peeked = None; - cursor.end_sequence = end.into().exclusive(); + cursor.min_sequence = start; + cursor.end_sequence = end; cursor.update_servable(); } - Inner::Resume(resume, _) => resume.end_at(end.into()), + Inner::Resume(resume, _) => resume.set_range(start, end), } self.largest.bounds_moved(); } @@ -7168,7 +7131,7 @@ impl Subscriber { Ok(()) } - /// Poll for the track's largest location within [`Self::set_groups`]: the current one, then each newer one, and `None` once the track ends. + /// Poll for the track's largest location within [`Self::with_range`]: the current one, then each newer one, and `None` once the track ends. /// /// The largest is the newest group or datagram at the newest frame (0 while empty), as /// the source reported it and its live feed delivered since, so nothing reports until @@ -7212,13 +7175,13 @@ impl Subscriber { } } - /// The largest location within [`Self::set_groups`]; see [`Self::poll_largest`]. + /// The largest location within [`Self::with_range`]; see [`Self::poll_largest`]. #[cfg(feature = "async")] pub async fn largest(&mut self) -> Option { kio::wait(|waiter| self.poll_largest(waiter)).await } - /// The track's largest location known now, ignoring [`Self::set_groups`], without waiting + /// The track's largest location known now, ignoring [`Self::with_range`], without waiting /// or moving [`Self::poll_largest`] on: past what the cache holds once the source /// reported a newer one. #[cfg_attr(not(feature = "async"), allow(dead_code, reason = "async-only"))] @@ -7306,7 +7269,7 @@ impl Ordered { /// Poll for the next group with a higher sequence number than any previously /// returned, without blocking. /// - /// Honors the group range set by [`Self::set_groups`]: + /// Honors the group range set by [`Self::with_range`]: /// a group past the cap stays in the producer's cache and becomes eligible again if /// the cap rises or is removed. /// @@ -7347,11 +7310,18 @@ impl Ordered { kio::wait(|waiter| self.poll_recv_datagram(waiter)).await } - /// Limit subsequent reads to these group sequences without rewinding read progress. + /// Limit subsequent reads to these group sequences, returning `self` for chaining. /// - /// See [`Subscriber::set_groups`] for inclusive, exclusive, and omitted bounds. - pub fn set_groups(&mut self, groups: impl RangeBounds) { - self.inner.set_groups(groups); + /// See [`Subscriber::with_range`] for how the bounds apply. An ordered read never goes + /// back, so lowering the floor below a group it already returned offers nothing. + pub fn with_range(mut self, groups: impl RangeBounds) -> Self { + self.set_range(groups); + self + } + + /// [`Self::with_range`] on a reader held in place. + fn set_range(&mut self, groups: impl RangeBounds) { + self.inner.set_range(groups); } /// Create a handle for updating this subscriber's delivery preferences without @@ -7386,12 +7356,12 @@ impl Ordered { kio::wait(|waiter| self.poll_finished(waiter)).await } - /// Poll for the largest location within [`Self::set_groups`]; see [`Subscriber::poll_largest`]. + /// Poll for the largest location within [`Self::with_range`]; see [`Subscriber::poll_largest`]. pub fn poll_largest(&mut self, waiter: &kio::Waiter) -> Poll> { self.inner.poll_largest(waiter) } - /// The largest location within [`Self::set_groups`]; see [`Subscriber::poll_largest`]. + /// The largest location within [`Self::with_range`]; see [`Subscriber::poll_largest`]. #[cfg(feature = "async")] pub async fn largest(&mut self) -> Option { kio::wait(|waiter| self.poll_largest(waiter)).await @@ -7984,7 +7954,7 @@ mod test { panic!("the empty group is the largest"); }; assert_eq!(edge, Position::group(1)); - reader.set_groups(edge.group..); + reader.set_range(edge.group..); empty.finish().unwrap(); let mut next = producer.append_group().unwrap(); @@ -8210,24 +8180,22 @@ mod test { /// The floor a reader waiting on each group starts at is the higher of its ranges' and /// its local one, so it never waits on a group the local floor withholds. #[test] - fn floor_honors_set_groups() { + fn floor_honors_with_range() { let producer = track_producer("test", Info::default()); let _groups: Vec<_> = (0..6).map(|sequence| framed(&producer, sequence, 2)).collect(); - let mut reader = producer.subscribe(replay().with_groups(2..)); + let reader = producer.subscribe(replay().with_range(2..)); assert_eq!((reader.floor(), reader.next_in_range(0)), (Some(2), Some(2))); - reader.set_groups(4..); + let reader = reader.with_range(4..); assert_eq!((reader.floor(), reader.next_in_range(0)), (Some(4), Some(4))); assert_eq!(reader.next_in_range(5), Some(5)); // Below the ranges' floor, the ranges still decide. - let mut reader = producer.subscribe(replay().with_groups(3..)); - reader.set_groups(1..); + let reader = producer.subscribe(replay().with_range(3..)).with_range(1..); assert_eq!((reader.floor(), reader.next_in_range(0)), (Some(3), Some(3))); // A floor reaching back to the oldest group stays unknown. - let mut reader = producer.subscribe(replay()); - reader.set_groups(4..); + let reader = producer.subscribe(replay()).with_range(4..); assert_eq!(reader.floor(), None); } @@ -8240,19 +8208,19 @@ mod test { let _groups: Vec<_> = (0..6).map(|sequence| framed(&producer, sequence, 2)).collect(); let mut capped = producer.subscribe(replay()); - capped.set_groups(..3); + capped.set_range(..3); assert!(capped.poll_largest(&noop).is_pending(), "the largest is past the cap"); // An inclusive cap reports the group it names. let mut ordered = producer.subscribe(replay()).ordered(); - ordered.set_groups(..=5); + ordered.set_range(..=5); assert_eq!( ordered.poll_largest(&noop), Poll::Ready(Some(Position { group: 5, frame: 1 })) ); let mut floored = producer.subscribe(replay()); - floored.set_groups(8..); + floored.set_range(8..); assert!( floored.poll_largest(&noop).is_pending(), "the largest is below the floor" @@ -8270,27 +8238,27 @@ mod test { let _groups: Vec<_> = (0..6).map(|sequence| framed(&producer, sequence, 1)).collect(); let mut reader = producer.subscribe(replay()).ordered(); - reader.set_groups(..3); + reader.set_range(..3); let (flag, waiter) = Flag::waiter(); assert!(reader.poll_largest(&waiter).is_pending()); - reader.set_groups(..); + reader.set_range(..); assert!(flag.take(), "lifting the cap woke the reader"); assert_eq!(reader.poll_largest(&noop), Poll::Ready(Some(Position::group(5)))); assert!(reader.poll_largest(&waiter).is_pending()); - reader.set_groups(..2); + reader.set_range(..2); assert!(flag.take(), "lowering the cap woke the reader"); assert!( reader.poll_largest(&noop).is_pending(), "the largest is past the new cap" ); - reader.set_groups(..); + reader.set_range(..); assert!( reader.poll_largest(&noop).is_pending(), "lifting it again leaves the last report standing" ); - reader.set_groups(3..); + reader.set_range(3..); assert!( reader.poll_largest(&noop).is_pending(), "a floor below the largest leaves it where it was" @@ -8307,9 +8275,9 @@ mod test { let noop = kio::Waiter::noop(); let mut reader = producer.subscribe(replay()); - reader.set_groups(..3); + reader.set_range(..3); assert_eq!(reader.poll_largest(&noop), Poll::Ready(None)); - reader.set_groups(..); + reader.set_range(..); assert_eq!( reader.poll_largest(&noop), Poll::Ready(None), @@ -8325,7 +8293,7 @@ mod test { let (flag, waiter) = Flag::waiter(); assert!(reader.poll_largest(&waiter).is_pending()); drop(waiter); - reader.set_groups(..); + reader.set_range(..); assert!(!flag.take(), "the dropped poll was not woken"); } @@ -8337,11 +8305,11 @@ mod test { let mut reader = producer.subscribe(replay()); let (flag, waiter) = Flag::waiter(); assert_eq!(reader.poll_largest(&waiter), Poll::Ready(Some(Position::group(0)))); - reader.set_groups(..); + reader.set_range(..); assert!(!flag.take(), "the finished poll was not woken"); assert!(reader.poll_largest(&waiter).is_pending()); - reader.set_groups(..); + reader.set_range(..); assert!(flag.take(), "the parked poll was woken"); } @@ -8356,7 +8324,7 @@ mod test { let mut reader = producer.subscribe(replay()); assert_eq!(reader.poll_largest(&noop), Poll::Ready(Some(Position::group(2)))); producer.set_idle(); - reader.set_groups(..); + reader.set_range(..); assert!(reader.poll_largest(&noop).is_pending(), "the copy is idle"); producer.set_live(Some(Position::group(2)), None); @@ -8754,7 +8722,7 @@ mod test { drop(group); // The writer gave the group up: a reader gets it, to read why it ended. - let mut reader = producer.subscribe(Subscription::default().with_groups(0..)); + let mut reader = producer.subscribe(Subscription::default().with_range(0..)); let Poll::Ready(Ok(Some(mut cut))) = reader.poll_recv_group(&kio::Waiter::noop()) else { panic!("the cut group is handed out"); }; @@ -8769,7 +8737,7 @@ mod test { .write_frame(Timestamp::ZERO, bytes::Bytes::from_static(b"head")) .unwrap(); replacement.finish().unwrap(); - let mut later = producer.subscribe(Subscription::default().with_groups(0..)); + let mut later = producer.subscribe(Subscription::default().with_range(0..)); assert!(matches!( later.poll_recv_group(&kio::Waiter::noop()), Poll::Ready(Ok(Some(_))) @@ -9065,7 +9033,7 @@ mod test { fn the_group_range_bounds_datagrams() { let mut producer = track_producer("test", Info::timed()); let mut subscriber = producer.subscribe(Subscription::default().with_start(Position::group(5))); - subscriber.set_groups(..7); + subscriber.set_range(..7); for sequence in [4, 5, 7, 6] { producer .insert_datagram(sequence, Timestamp::ZERO, bytes::Bytes::from_static(b"x")) @@ -9117,12 +9085,12 @@ mod test { .unwrap(); } - subscriber.set_groups(2..4); + subscriber.set_range(2..4); assert_eq!(recv_datagram(&mut subscriber).sequence, 2); assert_eq!(recv_datagram(&mut subscriber).sequence, 3); assert!(subscriber.poll_recv_datagram(&kio::Waiter::noop()).is_pending()); - subscriber.set_groups(..); + subscriber.set_range(..); assert!(subscriber.poll_recv_datagram(&kio::Waiter::noop()).is_pending()); producer .insert_datagram(5, Timestamp::ZERO, bytes::Bytes::from_static(b"x")) @@ -9412,7 +9380,7 @@ mod test { async fn parked_reoffer_restarts_the_expiry_clock() { let producer = track_producer("test", Info::timed()); let mut subscriber = producer.subscribe(None); - subscriber.set_groups(..1); + subscriber.set_range(..1); for seq in 0..2u64 { let mut group = producer.create_group(seq.into()).unwrap(); @@ -9426,7 +9394,7 @@ mod test { // Just inside the window, the cap rises and the re-offer stamps group 1. elapse(&producer, cache::DEFAULT_EXPIRY - Duration::from_secs(1)); - subscriber.set_groups(..2); + subscriber.set_range(..2); let mut reading = subscriber.assert_group(); assert_eq!(reading.sequence, 1); @@ -9860,10 +9828,7 @@ mod test { let budget = cache::DEFAULT_EXPIRY * 2; let mut subscriber = producer.subscribe(Subscription::default().with_max_delay(budget)); let waiter = kio::Waiter::noop(); - let expired = |held: &mut [group::Consumer; 2]| { - held.each_mut() - .map(|group| group.poll_expired_while_pending(&waiter, true)) - }; + let expired = |held: &mut [group::Consumer; 2]| held.each_mut().map(|group| group.poll_expired(&waiter)); // Frozen timestamps, so the wall clock alone convicts. append_at(&mut producer, 0); @@ -9910,7 +9875,7 @@ mod test { newest = subscriber.assert_group(); } elapse(&producer, budget * 2); - assert!(!newest.poll_expired_while_pending(&waiter, true), "the newest group"); + assert!(!newest.poll_expired(&waiter), "the newest group"); } /// A recorded successor that failed hands the clock on to the next live group even once @@ -9922,10 +9887,7 @@ mod test { let budget = cache::DEFAULT_EXPIRY * 2; let mut subscriber = producer.subscribe(Subscription::default().with_max_delay(budget)); let waiter = kio::Waiter::noop(); - let expired = |held: &mut [group::Consumer; 2]| { - held.each_mut() - .map(|group| group.poll_expired_while_pending(&waiter, true)) - }; + let expired = |held: &mut [group::Consumer; 2]| held.each_mut().map(|group| group.poll_expired(&waiter)); append_at(&mut producer, 0); let fetch = group::Fetch::default().with_max_delay(budget); @@ -9981,10 +9943,7 @@ mod test { pool.step(Duration::from_secs(1)); append_at(&mut producer, 0); // the successor - assert!( - !held.poll_expired_while_pending(&waiter, true), - "the successor is recorded" - ); + assert!(!held.poll_expired(&waiter), "the successor is recorded"); let state = producer.state.downgrade(); producer.finish().unwrap(); drop(producer); @@ -9999,13 +9958,10 @@ mod test { Some(true), "expired in place" ); - assert!(!held.poll_expired_while_pending(&waiter, true), "early"); + assert!(!held.poll_expired(&waiter), "early"); pool.step(budget - idle); - assert!( - held.poll_expired_while_pending(&waiter, true), - "the successor arrived a budget ago" - ); + assert!(held.poll_expired(&waiter), "the successor arrived a budget ago"); } /// Empty groups are handed out like any other and retired by the wall clock like an @@ -11271,7 +11227,7 @@ mod test { // Asking to start at the beginning is a filter, not a request for reliability. // Backfill needs a budget that covers it; without one the live edge still wins. let mut subscriber = producer.subscribe(Subscription::default().with_start(Position::group(0))); - subscriber.start_at(0); + subscriber.set_range(0..); assert_eq!(drain(&mut subscriber), vec![3]); let mut patient = producer.subscribe( @@ -11279,7 +11235,7 @@ mod test { .with_start(Position::group(0)) .with_max_delay(Duration::from_secs(10)), ); - patient.start_at(0); + patient.set_range(0..); assert_eq!(drain(&mut patient), vec![0, 1, 2, 3]); } @@ -11434,7 +11390,7 @@ mod test { } let mut subscriber = producer.subscribe(Subscription::default().with_end(Position::group(3))); - subscriber.end_at(Position::group(3).group_end()); + subscriber.set_range((Bound::Unbounded, Position::group(3).group_end())); assert_eq!(drain(&mut subscriber), vec![2]); } @@ -11879,9 +11835,9 @@ mod test { // Drift is measured under where the range ends, so with no budget its own newest // group is still fresh: the groups past it are not ones it reads. - let mut subscriber = producer.subscribe(Subscription::default().with_groups(0..2)); + let mut subscriber = producer.subscribe(Subscription::default().with_range(0..2)); assert_eq!(drain(&mut subscriber), vec![1]); - let mut subscriber = producer.subscribe(Subscription::default().with_groups(0..2)).ordered(); + let mut subscriber = producer.subscribe(Subscription::default().with_range(0..2)).ordered(); let next = subscriber.next_group().now_or_never().unwrap().unwrap().unwrap(); assert_eq!(next.sequence, 1); @@ -11930,7 +11886,7 @@ mod test { let mut held = subscriber.recv_group().await.unwrap().expect("group 0"); assert!(held.read_frame().await.unwrap().is_some()); - subscriber.update(budget.with_groups(10..20)).unwrap(); + subscriber.update(budget.with_range(10..20)).unwrap(); for (sequence, millis) in [(1, 1000), (10, 10_000), (19, 19_000)] { let mut group = producer.create_group(group::Info { sequence }).unwrap(); group.write_frame(at(millis), bytes::Bytes::from_static(b"x")).unwrap(); @@ -11991,7 +11947,7 @@ mod test { let current = cursor.published.read(); (current.servable.clone(), current.cap) }; - let ranges = Subscription::default().with_groups(10..20); + let ranges = Subscription::default().with_range(10..20); // Nothing in 10..20 sits below a cap at 5. let expected = (Servable::NONE, Some(5)); for order in ["ranges first", "cap first", "cap between"] { @@ -12001,15 +11957,15 @@ mod test { match order { "ranges first" => { control.update(ranges.clone()).unwrap(); - subscriber.set_groups(..5); + subscriber.set_range(..5); } "cap first" => { - subscriber.set_groups(..5); + subscriber.set_range(..5); control.update(ranges.clone()).unwrap(); } _ => { control.subscription.update(ranges.clone()).unwrap(); - subscriber.set_groups(..5); + subscriber.set_range(..5); control.republish.as_ref().unwrap().publish(&control.subscription); } } @@ -12078,7 +12034,7 @@ mod test { let mut held = subscriber.recv_group().await.unwrap().expect("group 0"); assert!(held.read_frame().await.unwrap().is_some()); - subscriber.control().update(budget.with_groups(10..20)).unwrap(); + subscriber.control().update(budget.with_range(10..20)).unwrap(); for (sequence, millis) in [(1, 1000), (10, 10_000), (19, 19_000)] { let mut group = producer.create_group(group::Info { sequence }).unwrap(); group.write_frame(at(millis), bytes::Bytes::from_static(b"x")).unwrap(); @@ -12101,12 +12057,12 @@ mod test { // Capped at group 0: the route running on past the cap is data this subscriber // can never be served, so it isn't a live edge to be late against. let mut subscriber = producer.subscribe(Subscription::default()); - subscriber.set_groups(..1); + subscriber.set_range(..1); assert_eq!(drain(&mut subscriber), vec![0]); // Raising the cap re-offers the parked group, now measured against the wider // edge it just admitted. - subscriber.set_groups(..); + subscriber.set_range(..); assert_eq!(drain(&mut subscriber), vec![1]); } @@ -12647,7 +12603,7 @@ mod test { pool.sweep(); assert!(consumer.peek_group(5).is_none(), "payload cache expired"); let mut sub = consumer.subscribe(replay()).now_or_never().unwrap().unwrap(); - sub.end_at(Bound::Excluded(5)); + sub.set_range(..5); assert_eq!( sub.poll_finished(&kio::Waiter::noop()).map(|result| result.unwrap()), Poll::Ready(end) @@ -13482,7 +13438,7 @@ mod test { producer.finish_at(Position::group(2)).unwrap(); producer.abort(Error::Timeout).unwrap(); - consumer.set_groups(..1); + consumer.set_range(..1); assert_eq!(drain_ordered(&mut consumer), [0]); let end = consumer .next_group() @@ -13506,7 +13462,7 @@ mod test { producer.finish_at(Position::group(3)).unwrap(); producer.abort(Error::Timeout).unwrap(); - consumer.set_groups(..2); + consumer.set_range(..2); assert_eq!(drain_ordered(&mut consumer), [0]); let end = consumer .next_group() @@ -13711,15 +13667,15 @@ mod test { Poll::Ready(Some(1)) ); if raise_floor { - subscriber.set_groups(2..); + subscriber.set_range(2..); let Poll::Ready(Ok(Some(group))) = subscriber.poll_group(ordered, &waiter) else { panic!("group 2 is inside the new floor"); }; assert_eq!(group.sequence, 2); } else { - subscriber.set_groups(..0); + subscriber.set_range(..0); assert!(subscriber.poll_group(ordered, &waiter).is_pending()); - subscriber.set_groups(..); + subscriber.set_range(..); let Poll::Ready(Ok(Some(group))) = subscriber.poll_group(ordered, &waiter) else { panic!("group 1 was parked, not consumed"); }; @@ -13762,7 +13718,7 @@ mod test { fn peeking_keeps_a_re_offered_group_owed() { let producer = track_producer("test", Info::timed()); let mut subscriber = producer.subscribe(replay()); - subscriber.set_groups(..0); + subscriber.set_range(..0); for sequence in [1, 2] { producer .create_group(group::Info { sequence }) @@ -13772,7 +13728,7 @@ mod test { } let waiter = kio::Waiter::noop(); assert!(subscriber.poll_group(false, &waiter).is_pending()); - subscriber.set_groups(..); + subscriber.set_range(..); for _ in 0..2 { assert_eq!( subscriber.poll_peek_group(false, &waiter).map(Result::unwrap), @@ -13811,9 +13767,9 @@ mod test { }; assert_eq!(group.sequence, first); let second = if ordered { 2 } else { 1 }; - subscriber.set_groups(..0); + subscriber.set_range(..0); assert!(subscriber.poll_peek_group(ordered, &waiter).is_pending()); - subscriber.set_groups(..); + subscriber.set_range(..); assert_eq!( subscriber.poll_peek_group(ordered, &waiter).map(Result::unwrap), Poll::Ready(Some(second)) @@ -13868,7 +13824,7 @@ mod test { .unwrap(); } - consumer.set_groups(..3); + consumer.set_range(..3); // Groups 0, 1, 2 are within the cap. assert_eq!( @@ -13905,7 +13861,7 @@ mod test { .unwrap(); } - consumer.set_groups(..2); + consumer.set_range(..2); assert_eq!( consumer.next_group().now_or_never().unwrap().unwrap().unwrap().sequence, 0 @@ -13917,7 +13873,7 @@ mod test { assert!(consumer.next_group().now_or_never().is_none(), "capped at 2"); // Raise the cap; previously-blocked cached groups become available again. - consumer.set_groups(..5); + consumer.set_range(..5); assert_eq!( consumer.next_group().now_or_never().unwrap().unwrap().unwrap().sequence, 2 @@ -13933,7 +13889,7 @@ mod test { assert!(consumer.next_group().now_or_never().is_none(), "capped at 5"); // Remove the cap; everything remaining flows. - consumer.set_groups(..); + consumer.set_range(..); assert_eq!( consumer.next_group().now_or_never().unwrap().unwrap().unwrap().sequence, 5 @@ -13970,7 +13926,7 @@ mod test { ); // Lower the cap below the cursor. New groups beyond the cap are blocked. - consumer.set_groups(..2); + consumer.set_range(..2); producer .create_group(group::Info { sequence: 3 }) .unwrap() @@ -13987,7 +13943,7 @@ mod test { ); // Restoring the cap to no-limit (or any value >= cursor) releases them. - consumer.set_groups(..); + consumer.set_range(..); assert_eq!( consumer.next_group().now_or_never().unwrap().unwrap().unwrap().sequence, 3 @@ -14004,7 +13960,7 @@ mod test { let producer = track_producer("test", Info::timed()); let mut consumer = producer.subscribe(replay()).ordered(); - consumer.set_groups(..6); + consumer.set_range(..6); // Out-of-order arrivals all within the cap. producer @@ -14055,7 +14011,7 @@ mod test { assert!(consumer.next_group().now_or_never().is_none()); // Raise the cap; cached seq 8 is finally served. - consumer.set_groups(..11); + consumer.set_range(..11); assert_eq!( consumer.next_group().now_or_never().unwrap().unwrap().unwrap().sequence, 8 @@ -14079,7 +14035,7 @@ mod test { .unwrap(); } - consumer.set_groups(..2); + consumer.set_range(..2); assert_eq!( consumer.recv_group().now_or_never().unwrap().unwrap().unwrap().sequence, 0 @@ -14090,13 +14046,13 @@ mod test { ); assert!(consumer.recv_group().now_or_never().is_none(), "capped at 2"); - consumer.set_groups(..); + consumer.set_range(..); assert_eq!( consumer.recv_group().now_or_never().unwrap().unwrap().unwrap().sequence, 2 ); - consumer.set_groups(..3); + consumer.set_range(..3); let _open = producer.create_group(group::Info { sequence: 3 }).unwrap(); assert!(consumer.recv_group().now_or_never().is_none(), "capped at 3"); producer.finish().unwrap(); @@ -14114,7 +14070,7 @@ mod test { let producer = track_producer("test", Info::timed()); let mut consumer = producer.subscribe(replay()); - consumer.set_groups(..2); + consumer.set_range(..2); // Reordered burst: the beyond-cap group arrives first. producer @@ -14143,7 +14099,7 @@ mod test { ); assert!(consumer.recv_group().now_or_never().is_none(), "capped at 2"); - consumer.set_groups(..3); + consumer.set_range(..3); assert_eq!( consumer.recv_group().now_or_never().unwrap().unwrap().unwrap().sequence, 2 @@ -14155,14 +14111,14 @@ mod test { async fn group_ranges_preserve_the_floor_when_the_cap_changes() { let producer = track_producer("test", Info::timed()); let mut consumer = producer.subscribe(None); - consumer.set_groups(2..=2); + consumer.set_range(2..=2); producer .create_group(group::Info { sequence: 2 }) .unwrap() .finish() .unwrap(); assert_eq!(consumer.recv_group().await.unwrap().unwrap().sequence, 2); - consumer.set_groups(..4); + consumer.set_range(..4); producer .create_group(group::Info { sequence: 1 }) .unwrap() @@ -14174,7 +14130,7 @@ mod test { .finish() .unwrap(); assert_eq!(consumer.recv_group().await.unwrap().unwrap().sequence, 3); - consumer.set_groups(0..=4); + consumer.set_range(0..=4); producer .create_group(group::Info { sequence: 0 }) .unwrap() @@ -14192,11 +14148,11 @@ mod test { /// them once the cap rises. #[test] #[cfg(feature = "async")] - fn start_at_drops_parked_recv_groups() { + fn a_raised_floor_drops_parked_recv_groups() { let producer = track_producer("test", Info::timed()); let mut consumer = producer.subscribe(None); - consumer.set_groups(..1); + consumer.set_range(..1); producer .create_group(group::Info { sequence: 1 }) .unwrap() @@ -14207,8 +14163,7 @@ mod test { "group 1 parked at the cap" ); - consumer.start_at(2); - consumer.set_groups(..); + consumer.set_range(2..); producer .create_group(group::Info { sequence: 2 }) .unwrap() @@ -14240,7 +14195,7 @@ mod test { 0 ); - consumer.set_groups(..1); + consumer.set_range(..1); let straggler = producer.create_group(group::Info { sequence: 1 }).unwrap(); assert!( consumer.recv_group().now_or_never().is_none(), @@ -14251,7 +14206,7 @@ mod test { straggler.abort(Error::Old).unwrap(); producer.finish().unwrap(); - consumer.set_groups(..); + consumer.set_range(..); assert!( matches!(consumer.recv_group().now_or_never(), Some(Ok(None))), "a dead parked group must not be delivered or hold the stream open" @@ -14275,13 +14230,13 @@ mod test { .finish() .unwrap(); - consumer.set_groups(..0); + consumer.set_range(..0); assert!( consumer.recv_group().now_or_never().is_none(), "empty cap delivers nothing" ); - consumer.set_groups(..1); + consumer.set_range(..1); assert_eq!( consumer.recv_group().now_or_never().unwrap().unwrap().unwrap().sequence, 0 @@ -14297,7 +14252,7 @@ mod test { let producer = track_producer("test", Info::timed()); let mut everything = producer.subscribe(replay()); let mut empty = producer.subscribe(replay()); - empty.set_groups((Bound::Unbounded, Position::group(0).group_end())); + empty.set_range((Bound::Unbounded, Position::group(0).group_end())); for s in 0..3 { producer @@ -14322,12 +14277,12 @@ mod test { "local empty cap must not ride the unbounded aggregate" ); - empty.set_groups(..2); + empty.set_range(..2); assert_eq!(empty.recv_group().now_or_never().unwrap().unwrap().unwrap().sequence, 0); assert_eq!(empty.recv_group().now_or_never().unwrap().unwrap().unwrap().sequence, 1); assert!(empty.recv_group().now_or_never().is_none(), "still capped at 2"); - empty.set_groups(..); + empty.set_range(..); assert_eq!(empty.recv_group().now_or_never().unwrap().unwrap().unwrap().sequence, 2); } @@ -14338,7 +14293,7 @@ mod test { let producer = track_producer("test", Info::timed()); let mut consumer = producer.subscribe(replay()).ordered(); let end = Position::after(1, 1).unwrap(); - consumer.set_groups((Bound::Unbounded, end.group_end())); + consumer.set_range((Bound::Unbounded, end.group_end())); for s in 0..3u64 { let mut group = producer.create_group(group::Info { sequence: s }).unwrap(); @@ -14354,7 +14309,7 @@ mod test { ); let mut last = consumer.next_group().now_or_never().unwrap().unwrap().unwrap(); assert_eq!(last.sequence, 1); - last.set_frames(..end.frame); + last = last.with_range(..end.frame); assert_eq!( last.read_frame().now_or_never().unwrap().unwrap().unwrap().payload[0], 0 @@ -14379,7 +14334,7 @@ mod test { fn end_at_maximum_group_is_unbounded() { let producer = track_producer("test", Info::timed()); let mut consumer = producer.subscribe(replay()).ordered(); - consumer.set_groups(..=u64::MAX); + consumer.set_range(..=u64::MAX); producer .create_group(group::Info { sequence: 0 }) @@ -14854,9 +14809,9 @@ mod test { live.write_frame(Timestamp::ZERO, bytes::Bytes::from_static(b"delta2")) .unwrap(); let mut sub = producer.subscribe(None); - let mut group = sub.recv_group().now_or_never().unwrap().unwrap().unwrap(); + let group = sub.recv_group().now_or_never().unwrap().unwrap().unwrap(); // Positioning at the start clamps up to the live group's first frame. - group.start_at(0); + let mut group = group.with_range(0..); assert_eq!(group.index(), 1); assert_eq!( group.read_frame().await.unwrap().unwrap().payload, @@ -14963,11 +14918,11 @@ mod test { let producer = track_producer("test", Info::timed()); let (live, _head) = live_group_with_head(&producer).await; let mut subscriber = producer.subscribe(replay()); - subscriber.set_groups(..0); + subscriber.set_range(..0); assert!(subscriber.poll_recv_group(&kio::Waiter::noop()).is_pending()); live.abort(Error::Cancel).unwrap(); assert!(subscriber.poll_recv_group(&kio::Waiter::noop()).is_pending()); - subscriber.set_groups(..); + subscriber.set_range(..); let mut group = subscriber.recv_group().await.unwrap().unwrap(); assert_eq!( group.read_frame().await.unwrap().unwrap().payload, @@ -16322,7 +16277,7 @@ mod test { let dynamic = producer.dynamic(); let consumer = producer.consume(); producer.create_group(5u64.into()).unwrap().finish().unwrap(); - let mut subscriber = producer.subscribe(replay().with_groups(5..)); + let mut subscriber = producer.subscribe(replay().with_range(5..)); assert_eq!(subscriber.assert_group().sequence, 5); let pending = consumer.fetch_group(2, None); @@ -16339,15 +16294,15 @@ mod test { pending.await.unwrap(); let _frameless = producer.create_group(group::Info { sequence: 3 }).unwrap(); - subscriber.update(replay().with_groups(0..)).unwrap(); + subscriber.update(replay().with_range(0..)).unwrap(); assert_eq!(subscriber.assert_group().sequence, 3, "offered before its first frame"); subscriber.assert_no_group(); // A cursor floor lowered before the next read counts only walked groups as unread. let mut lowered = producer.subscribe(replay()); - lowered.start_at(5); + lowered.set_range(5..); assert_eq!(lowered.assert_group().sequence, 5); - lowered.start_at(0); + lowered.set_range(0..); let delivered = super::super::delivered::Delivered::default(); let unread = Unread { start: 0, @@ -16546,7 +16501,7 @@ mod test { fn a_fixed_start_is_no_join() { let producer = track_producer("test", Info::default().with_refresh(1)); refresh_group(&producer, 4); - let _subscriber = producer.subscribe(Subscription::default().with_groups(0..)); + let _subscriber = producer.subscribe(Subscription::default().with_range(0..)); assert_eq!(producer.demand().wanted(), Some(0)); } @@ -16996,7 +16951,7 @@ mod test { #[cfg(feature = "async")] fn a_live_range_merged_with_one_above_the_live_edge_gets_the_newest_group() { let mut producer = quiet_track(3); - let mut ahead = producer.subscribe(replay().with_groups(4..)); + let mut ahead = producer.subscribe(replay().with_range(4..)); let mut live = producer.subscribe(replay().with_ranges([Range::live()])); assert_eq!( producer.subscription().unwrap().ranges, @@ -17105,7 +17060,7 @@ mod test { #[cfg(feature = "async")] fn a_buffering_range_merged_with_one_above_the_live_edge_keeps_its_backlog() { let mut producer = quiet_track(5); - let mut ahead = producer.subscribe(replay().with_groups(8..)); + let mut ahead = producer.subscribe(replay().with_range(8..)); let buffering = Range { start: Anchor::Relative(2), end: None, @@ -17151,7 +17106,7 @@ mod test { elapse(&producer, Duration::from_secs(1)); } let budget = Duration::from_millis(1500); - let mut subscriber = producer.subscribe(Subscription::default().with_max_delay(budget).with_groups(0..)); + let mut subscriber = producer.subscribe(Subscription::default().with_max_delay(budget).with_range(0..)); assert_eq!(drain(&mut subscriber), vec![3, 4]); } @@ -17367,17 +17322,17 @@ mod test { #[cfg(feature = "async")] fn replaced_ranges_resolve_again() { let mut producer = track_producer("test", Info::timed()); - let mut subscriber = producer.subscribe(replay().with_groups(0..2)); + let mut subscriber = producer.subscribe(replay().with_range(0..2)); for second in 0..4 { append_at(&mut producer, second * 1000); } assert_eq!(drain(&mut subscriber), vec![0, 1]); - subscriber.update(replay().with_groups(0..)).unwrap(); + subscriber.update(replay().with_range(0..)).unwrap(); assert_eq!(drain(&mut subscriber), vec![2, 3], "held back, now in range"); // The latest group is 3 now, so one back is 2, already read: only new groups follow. - let mut late = producer.subscribe(replay().with_groups(..1)); + let mut late = producer.subscribe(replay().with_range(..1)); assert_eq!(drain(&mut late), vec![0]); late.update(replay().with_ranges([Range { start: Anchor::Relative(1), @@ -17397,7 +17352,7 @@ mod test { fn a_narrow_reader_holds_nothing_for_excluded_groups() { let producer = track_producer("test", Info::timed()); let _wide = producer.subscribe(replay()); - let mut narrow = producer.subscribe(replay().with_groups(0..2)); + let mut narrow = producer.subscribe(replay().with_range(0..2)); for sequence in 0..1000 { producer .create_group(group::Info { sequence }) @@ -17416,10 +17371,10 @@ mod test { .update(replay().with_ranges([Range::groups(0..2), Range::groups(5..8)])) .unwrap(); assert_eq!(drain(&mut narrow), vec![5, 6, 7]); - narrow.set_groups(..9); - narrow.update(replay().with_groups(0..)).unwrap(); + narrow.set_range(..9); + narrow.update(replay().with_range(0..)).unwrap(); assert_eq!(drain(&mut narrow), vec![2, 3, 4, 8]); - narrow.set_groups(..); + narrow.set_range(..); assert_eq!(drain(&mut narrow), (9..1000).collect::>()); } @@ -17432,28 +17387,50 @@ mod test { for second in 0..6 { append_at(&mut producer, second * 1000); } - let mut subscriber = producer.subscribe(replay().with_groups(5..)); + let mut subscriber = producer.subscribe(replay().with_range(5..)); assert_eq!(drain(&mut subscriber), vec![5]); - subscriber.update(replay().with_groups(2..)).unwrap(); + subscriber.update(replay().with_range(2..)).unwrap(); assert_eq!( drain(&mut subscriber), vec![2, 3, 4], "passed below the floor, now in range" ); - subscriber.update(replay().with_groups(0..)).unwrap(); + subscriber.update(replay().with_range(0..)).unwrap(); assert_eq!(drain(&mut subscriber), vec![0, 1]); // Raising and lowering it again re-offers only what is cached in between, and // nothing already served goes out twice. - subscriber.update(replay().with_groups(4..)).unwrap(); + subscriber.update(replay().with_range(4..)).unwrap(); assert_eq!(drain(&mut subscriber), Vec::::new()); - subscriber.update(replay().with_groups(0..)).unwrap(); + subscriber.update(replay().with_range(0..)).unwrap(); assert_eq!(drain(&mut subscriber), Vec::::new()); append_at(&mut producer, 6000); assert_eq!(drain(&mut subscriber), vec![6]); } + /// Lowering a reader's local floor offers the cached groups below the old one that it + /// passed over, lowest first, and never a group twice. + #[test] + #[cfg(feature = "async")] + fn a_lowered_range_reoffers_the_unread_cached_groups() { + let mut producer = track_producer("test", Info::timed()); + for second in 0..6 { + append_at(&mut producer, second * 1000); + } + let mut subscriber = producer.subscribe(replay()).with_range(4..); + assert_eq!(drain(&mut subscriber), vec![4, 5]); + + let mut subscriber = subscriber.with_range(1..); + assert_eq!(drain(&mut subscriber), vec![1, 2, 3], "passed below the floor"); + let mut subscriber = subscriber.with_range(..=1); + assert_eq!(drain(&mut subscriber), vec![0], "the floor and the cap both assign"); + let mut subscriber = subscriber.with_range(..); + assert_eq!(drain(&mut subscriber), Vec::::new(), "nothing goes out twice"); + append_at(&mut producer, 6000); + assert_eq!(drain(&mut subscriber), vec![6]); + } + /// Datagrams outside a subscriber's ranges are dropped like the groups. #[test] #[cfg(feature = "async")] @@ -17658,10 +17635,8 @@ mod test { #[cfg(feature = "async")] fn a_raised_cap_reoffers_a_cut() { let producer = track_producer("test", Info::timed()); - let mut arrival = producer.subscribe(replay()); - let mut ordered = producer.subscribe(replay()).ordered(); - arrival.set_groups(..1); - ordered.set_groups(..1); + let mut arrival = producer.subscribe(replay()).with_range(..1); + let mut ordered = producer.subscribe(replay()).ordered().with_range(..1); producer .create_group(group::Info { sequence: 0 }) .unwrap() @@ -17673,7 +17648,7 @@ mod test { assert_eq!(arrival.assert_group().sequence, 0); assert!(arrival.recv_group().now_or_never().is_none(), "capped"); - arrival.set_groups(..); + arrival = arrival.with_range(..); let mut reoffered = arrival.assert_group(); assert_eq!(reoffered.sequence, 1); assert!(matches!( @@ -17682,7 +17657,7 @@ mod test { )); assert_eq!(drain_ordered(&mut ordered), [0]); - ordered.set_groups(..); + ordered = ordered.with_range(..); let mut reoffered = ordered.next_group().now_or_never().unwrap().unwrap().unwrap(); assert_eq!(reoffered.sequence, 1); assert!(matches!( diff --git a/rs/moq-net/src/model/track/demand.rs b/rs/moq-net/src/model/track/demand.rs index 80618c813b2..796b065bd1b 100644 --- a/rs/moq-net/src/model/track/demand.rs +++ b/rs/moq-net/src/model/track/demand.rs @@ -374,7 +374,7 @@ mod tests { assert!(producer.poll_subscription_changed(&waiter).is_pending()); let mut weak = producer.subscribe( Subscription::default() - .with_groups(100..200) + .with_range(100..200) .with_order(Order::Ascending), ); weak.update(Subscription::default().with_priority(5)).unwrap(); diff --git a/rs/moq-net/tests/integration/announce_to_serve.rs b/rs/moq-net/tests/integration/announce_to_serve.rs index ddc00e258a2..eb71f54291c 100644 --- a/rs/moq-net/tests/integration/announce_to_serve.rs +++ b/rs/moq-net/tests/integration/announce_to_serve.rs @@ -78,7 +78,7 @@ fn outcome(result: &Result) -> String { /// group's frames and then how the subscription ended. Read continuously, as a /// real subscriber would, so the subscription is driven the whole time. async fn read(broadcast: &moq_net::broadcast::Consumer, name: &str) -> mpsc::UnboundedReceiver { - let subscription = moq_net::track::Subscription::default().with_groups(0..); + let subscription = moq_net::track::Subscription::default().with_range(0..); let mut sub = broadcast .track(name) .unwrap() diff --git a/rs/moq-net/tests/integration/finished_broadcast_mock.rs b/rs/moq-net/tests/integration/finished_broadcast_mock.rs index cec34b90745..7c8701f3e6d 100644 --- a/rs/moq-net/tests/integration/finished_broadcast_mock.rs +++ b/rs/moq-net/tests/integration/finished_broadcast_mock.rs @@ -60,7 +60,7 @@ async fn round(finish_broadcast: bool) -> (Vec>, Option) .expect("broadcast resolves"); let reader = moq_clock::sim::spawn(async move { - let subscription = moq_net::track::Subscription::default().with_groups(0..); + let subscription = moq_net::track::Subscription::default().with_range(0..); let mut sub = remote .track("video") .unwrap() diff --git a/rs/moq-net/tests/integration/finite_relay.rs b/rs/moq-net/tests/integration/finite_relay.rs index 2ec6bc63e75..ff700f21e43 100644 --- a/rs/moq-net/tests/integration/finite_relay.rs +++ b/rs/moq-net/tests/integration/finite_relay.rs @@ -88,7 +88,7 @@ async fn round(name: &str, arrival: Arrival) -> (Vec, Result<(), moq_net::E let (mut heads, mut opened) = futures::channel::mpsc::unbounded(); let reader = moq_clock::sim::spawn(async move { - let subscription = Subscription::default().with_max_delay(MAX_DELAY).with_groups(0..); + let subscription = Subscription::default().with_max_delay(MAX_DELAY).with_range(0..); let mut sub = remote .track("tail") .unwrap() diff --git a/rs/moq-net/tests/integration/group_order.rs b/rs/moq-net/tests/integration/group_order.rs index 36a4197d418..581fe3c63bc 100644 --- a/rs/moq-net/tests/integration/group_order.rs +++ b/rs/moq-net/tests/integration/group_order.rs @@ -57,7 +57,7 @@ fn read_arrivals(origin: moq_net::origin::Producer, order: Order) -> moq_clock:: .expect("broadcast resolves"); let subscription = Subscription::default() .with_max_delay(FOREVER) - .with_groups(0..) + .with_range(0..) .with_order(order); let mut sub = remote .track("ordered") diff --git a/rs/moq-net/tests/integration/history_groups.rs b/rs/moq-net/tests/integration/history_groups.rs index a70687b8a5f..e7ada798343 100644 --- a/rs/moq-net/tests/integration/history_groups.rs +++ b/rs/moq-net/tests/integration/history_groups.rs @@ -82,7 +82,7 @@ async fn round(version: &str, relay: bool, newest_first: bool) -> Vec<(u64, usiz .expect("broadcast resolves"); let reader = moq_clock::sim::spawn(async move { - let subscription = Subscription::default().with_max_delay(FOREVER).with_groups(0..); + let subscription = Subscription::default().with_max_delay(FOREVER).with_range(0..); let mut sub = remote .track("history") .unwrap() @@ -223,7 +223,7 @@ async fn a_late_subscriber_receives_the_relays_cached_history() { let consumer = first.consume(); consumer.routed("bcast").await.unwrap(); let remote = consumer.request_broadcast("bcast", None).await.unwrap(); - let subscription = Subscription::default().with_max_delay(FOREVER).with_groups(0..); + let subscription = Subscription::default().with_max_delay(FOREVER).with_range(0..); let first_subscription = subscription.clone(); let first_reader = moq_clock::sim::spawn(async move { let mut sub = remote diff --git a/rs/moq-net/tests/integration/partial_group.rs b/rs/moq-net/tests/integration/partial_group.rs index 54c35c6f7e6..609ee7e5462 100644 --- a/rs/moq-net/tests/integration/partial_group.rs +++ b/rs/moq-net/tests/integration/partial_group.rs @@ -102,7 +102,7 @@ async fn round(version: &str) -> Option, moq_net::Error>> { remote.track("data").unwrap().subscribe( Subscription::default() .with_max_delay(Duration::from_secs(3600)) - .with_groups(0..), + .with_range(0..), ), ) .await diff --git a/rs/moq-net/tests/integration/quiet_catalog.rs b/rs/moq-net/tests/integration/quiet_catalog.rs index b5254bc2740..dab2e9e4a32 100644 --- a/rs/moq-net/tests/integration/quiet_catalog.rs +++ b/rs/moq-net/tests/integration/quiet_catalog.rs @@ -174,7 +174,7 @@ async fn resume_then_fresh(version: Version, in_process: bool) -> Result<(), Str let _sub = resume_remote .track("catalog.json") .unwrap() - .subscribe(track::Subscription::default().with_groups(1..)) + .subscribe(track::Subscription::default().with_range(1..)) .await .expect("resume subscribe"); moq_clock::sleep(Duration::from_secs(60)).await; diff --git a/rs/moq-net/tests/integration/received_rewind.rs b/rs/moq-net/tests/integration/received_rewind.rs index 913d91a3de4..6b8bd7cda19 100644 --- a/rs/moq-net/tests/integration/received_rewind.rs +++ b/rs/moq-net/tests/integration/received_rewind.rs @@ -74,7 +74,7 @@ async fn relay( .expect("resolve timeout") .expect("broadcast resolves"); - let subscription = Subscription::default().with_max_delay(BUDGET).with_groups(0..); + let subscription = Subscription::default().with_max_delay(BUDGET).with_range(0..); let reader = moq_clock::sim::spawn(async move { let mut sub = remote .track("data") diff --git a/rs/moq-net/tests/integration/settled_end_survives_abort.rs b/rs/moq-net/tests/integration/settled_end_survives_abort.rs index 0c4658610b7..090336763ea 100644 --- a/rs/moq-net/tests/integration/settled_end_survives_abort.rs +++ b/rs/moq-net/tests/integration/settled_end_survives_abort.rs @@ -32,7 +32,7 @@ async fn round(abort: bool, ordered: bool) -> (Vec, Option) { // From the first group with a replay window: a late reader is owed the whole track, // not the live edge. let subscription = moq_net::track::Subscription::default() - .with_groups(0..) + .with_range(0..) .with_max_delay(std::time::Duration::from_secs(30)); let mut consumer = track.subscribe(subscription); diff --git a/rs/moq-net/tests/integration/subscribe_ranges.rs b/rs/moq-net/tests/integration/subscribe_ranges.rs index e998f67226e..7375b7f8eb7 100644 --- a/rs/moq-net/tests/integration/subscribe_ranges.rs +++ b/rs/moq-net/tests/integration/subscribe_ranges.rs @@ -105,7 +105,7 @@ async fn ahead_then_live(version: Option<&str>, relay: bool) -> (Vec, Vec (Vec>, Option) { let (go_tx, go_rx) = futures::channel::oneshot::channel::<()>(); let reader = moq_clock::sim::spawn(async move { - let subscription = moq_net::track::Subscription::default().with_groups(0..); + let subscription = moq_net::track::Subscription::default().with_range(0..); let mut sub = remote .track("video") .unwrap() @@ -225,7 +225,7 @@ async fn killed(version: &str, local: bool) -> (Option, Option Outcome { } = connect(version).await; let reader = moq_clock::sim::spawn(async move { - let subscription = moq_net::track::Subscription::default().with_groups(0..); + let subscription = moq_net::track::Subscription::default().with_range(0..); let mut sub = remote .track("video") .unwrap() @@ -279,7 +279,7 @@ async fn ietf_leaving_cancels_a_blocked_end_of_track() { _keep, } = connect(version).await; - let subscription = moq_net::track::Subscription::default().with_groups(0..); + let subscription = moq_net::track::Subscription::default().with_range(0..); let mut sub = remote .track("video") .unwrap() @@ -335,7 +335,7 @@ async fn a_lost_datagram_delays_the_end() { } = connect(version).await; let reader = moq_clock::sim::spawn(async move { - let subscription = moq_net::track::Subscription::default().with_groups(0..); + let subscription = moq_net::track::Subscription::default().with_range(0..); let mut sub = remote .track("video") .unwrap() @@ -395,7 +395,7 @@ async fn a_group_whose_first_frame_trails_its_header_is_delivered() { let reader = moq_clock::sim::spawn(async move { let subscription = moq_net::track::Subscription::default() - .with_groups(0..) + .with_range(0..) .with_max_delay(TIMEOUT); let mut sub = remote .track("video") diff --git a/rs/moq-net/tests/integration/untimed.rs b/rs/moq-net/tests/integration/untimed.rs index 6338e5adb6d..8f933122a1c 100644 --- a/rs/moq-net/tests/integration/untimed.rs +++ b/rs/moq-net/tests/integration/untimed.rs @@ -187,7 +187,7 @@ async fn an_explicit_start_holds_on_an_untimed_track() { let consumer = chain.nodes[1].consume().request_broadcast("room", None).await.unwrap(); let subscription = track::Subscription::default() - .with_groups(2..) + .with_range(2..) .with_max_delay(Duration::from_secs(30)); let mut subscriber = moq_clock::timeout(TIMEOUT, consumer.track("data").unwrap().subscribe(subscription)) .await diff --git a/rs/moq-net/tests/loom.rs b/rs/moq-net/tests/loom.rs index 6992c1fac2c..a5a567ac5fd 100644 --- a/rs/moq-net/tests/loom.rs +++ b/rs/moq-net/tests/loom.rs @@ -98,7 +98,7 @@ fn back_to_back_groups_arrive_in_order() { let consumer = broadcast.consume(); let track = broadcast.create_track("video", None).expect("create track"); let from_start = moq_net::track::Subscription::default() - .with_groups(0..) + .with_range(0..) .with_max_delay(std::time::Duration::MAX); let subscribing = consumer.track("video").expect("track").subscribe(from_start); @@ -598,8 +598,8 @@ fn an_aborted_parked_group_releases_a_finished_track() { let track = broadcast.create_track("parked", timed()).unwrap(); let mut group = track.append_group().unwrap(); group.finish().unwrap(); - let mut subscriber = track.subscribe(moq_net::track::Subscription::default().with_groups(0..)); - subscriber.set_groups(..0); + let mut subscriber = track.subscribe(moq_net::track::Subscription::default().with_range(0..)); + subscriber = subscriber.with_range(..0); track.finish().unwrap(); let aborting = thread::spawn(move || group.abort(Error::Old).unwrap()); assert!(block_on(subscriber.recv_group()).unwrap().is_none()); diff --git a/rs/moq-room/src/chat.rs b/rs/moq-room/src/chat.rs index 7d9e63bb809..82b6c807e43 100644 --- a/rs/moq-room/src/chat.rs +++ b/rs/moq-room/src/chat.rs @@ -159,11 +159,12 @@ impl Subscriber { // The newest window is known only once the feed is live: a relay copy still waiting // on its source reports nothing yet, so wait rather than replay its backlog. The // wait ends with the track. - if let Some(largest) = ready!(track.poll_largest(waiter)) { - track.set_groups(largest.group..); + let largest = ready!(track.poll_largest(waiter)); + let mut track = *pending.take().expect("positioning holds the track"); + if let Some(largest) = largest { + track = track.with_range(largest.group..); } - let track = pending.take().expect("positioning holds the track"); - self.state = State::Reading(Box::new(moq_json::window::Consumer::new(*track, Default::default()))); + self.state = State::Reading(Box::new(moq_json::window::Consumer::new(track, Default::default()))); } let State::Reading(consumer) = &mut self.state else { unreachable!("positioned above"); diff --git a/rs/moq-stats/src/produce.rs b/rs/moq-stats/src/produce.rs index a66576138ba..cb056c7b9ef 100644 --- a/rs/moq-stats/src/produce.rs +++ b/rs/moq-stats/src/produce.rs @@ -1663,7 +1663,7 @@ mod tests { let subscribing = consumer .track(name) .unwrap() - .subscribe(track::Subscription::default().with_groups(floor..)); + .subscribe(track::Subscription::default().with_range(floor..)); family.adopt_pair( &broadcast, &mut requested, diff --git a/rs/moq-tokio/tests/integration/broadcast.rs b/rs/moq-tokio/tests/integration/broadcast.rs index 4480e2330e1..22d82e94874 100644 --- a/rs/moq-tokio/tests/integration/broadcast.rs +++ b/rs/moq-tokio/tests/integration/broadcast.rs @@ -1089,7 +1089,7 @@ async fn broadcast_route_migration() { // Resolve and subscribe: the cheaper route (A) serves the track. let subscription = moq_net::track::Subscription::default() - .with_groups(1..) + .with_range(1..) .with_max_delay(Duration::from_secs(10)); let broadcast = tokio::time::timeout(TIMEOUT, sub_consumer.request_broadcast("test", None)) .await diff --git a/rs/moq-video/src/decode/consumer.rs b/rs/moq-video/src/decode/consumer.rs index 4bbc5e1948f..44d43038daf 100644 --- a/rs/moq-video/src/decode/consumer.rs +++ b/rs/moq-video/src/decode/consumer.rs @@ -336,7 +336,7 @@ impl Reader { if options.start == Start::Latest && let Some(live_edge) = subscriber.largest().await { - subscriber.set_groups(live_edge.group.saturating_sub(lookback)..); + subscriber = subscriber.with_range(live_edge.group.saturating_sub(lookback)..); } let track = subscriber; // The catalog says how the track is framed, and it is not always the legacy diff --git a/test/interop/clients/rust/finish.rs b/test/interop/clients/rust/finish.rs index 4fdd6b69ff6..0cc2eb2b8a4 100644 --- a/test/interop/clients/rust/finish.rs +++ b/test/interop/clients/rust/finish.rs @@ -131,7 +131,7 @@ async fn main() -> anyhow::Result<()> { .subscribe(Some( moq_net::track::Subscription::default() .with_max_delay(args.timeout) - .with_groups(0..), + .with_range(0..), )) .await?; let format = moq_mux::catalog::hang::Container::try_from(config)?; diff --git a/test/interop/clients/rust/tail.rs b/test/interop/clients/rust/tail.rs index 6ce1d06b186..ac55b7946bd 100644 --- a/test/interop/clients/rust/tail.rs +++ b/test/interop/clients/rust/tail.rs @@ -144,7 +144,7 @@ async fn main() -> anyhow::Result<()> { } let options = moq_net::track::Subscription::default() .with_max_delay(Duration::from_secs(if drop { 60 } else { 5 })) - .with_groups(0..); + .with_range(0..); let mut track = remote.subscribe(Some(options)).await?; if datagram { println!("datagram ready");