diff --git a/js/net/MIGRATE.md b/js/net/MIGRATE.md index f5cbe4360c1..85a6485f847 100644 --- a/js/net/MIGRATE.md +++ b/js/net/MIGRATE.md @@ -4,6 +4,16 @@ How to update your code for each breaking change, newest first. ## Unreleased +### Stage a requested track before subscribers see it (#6111) + +`Track.Request.stage(info)` returns a `Track.Staged` whose `producer` writes while subscribers waiting on the request stay pending; `commit()` publishes it with everything written so far and returns the `Producer`. +Disposing a `Staged` uncommitted (`using`, or `[Symbol.dispose]()`) rejects the request. `accept(info)` is unchanged and equals `stage(info).commit()`. + +### A frameless group is not a successor (#6111) + +A group followed by a frameless one is judged stale against the next group that has a frame, where the frameless group used to count. +`Track.Producer.dropGroups(start, end, error)` marks groups `[start, end)` the peer said it skipped; a reader holding one of them rejects with `error`. + ### Priorities are signed (#6142) `Track.Info.priority`, `Track.Subscription.priority`, and a fetch's `priority` take `-128..=127`, higher first, and 0 is the unset midpoint; anything outside throws a `RangeError`. diff --git a/js/net/src/broadcast.test.ts b/js/net/src/broadcast.test.ts index 979a94343ec..efbbe4411ad 100644 --- a/js/net/src/broadcast.test.ts +++ b/js/net/src/broadcast.test.ts @@ -58,6 +58,48 @@ test("consumer dedupes repeat subscriptions onto one upstream request", async () expect((await pendingRequest(consumer))?.name).toBe("video"); }); +test("a staged track resolves its subscribers at commit, with what was written", async () => { + const consumer = new TestConsumer(); + const track = consumer.track("video"); + const reader = track.subscribe().ordered(); + const request = await pendingRequest(consumer); + if (!request) throw new Error("expected request"); + + const staged = request.stage({ timescale: Timescale.MILLI }); + staged.producer.writeFrame(textFrame("hello")); + const pending = Symbol("pending"); + expect(await Promise.race([track.info(), Promise.resolve(pending)])).toBe(pending); + + staged.commit(); + expect((await track.info()).timescale).toBe(Timescale.MILLI); + expect(await reader.readString()).toBe("hello"); +}); + +test("disposing an uncommitted staged track rejects the request", async () => { + const consumer = new TestConsumer(); + const info = consumer.track("video").info(); + const request = await pendingRequest(consumer); + if (!request) throw new Error("expected request"); + + { + using staged = request.stage({ timescale: Timescale.MILLI }); + staged.producer.writeFrame(textFrame("hello")); + } + await expect(info).rejects.toThrow(); +}); + +test("a disposed staged track refuses a later commit", async () => { + const consumer = new TestConsumer(); + const info = consumer.track("video").info(); + const request = await pendingRequest(consumer); + if (!request) throw new Error("expected request"); + + const staged = request.stage({ timescale: Timescale.MILLI }); + staged[Symbol.dispose](); + expect(() => staged.commit()).toThrow("staged track already committed or dropped"); + await expect(info).rejects.toThrow("staged track dropped"); +}); + // A replacement continues the name's timeline, so its groups can't start before the highest one an // earlier producer checked, while a new broadcast starts over. test("a replacement producer refuses a rewind past its predecessor", () => { diff --git a/js/net/src/group.ts b/js/net/src/group.ts index 1d4909ade67..4612ae1005c 100644 --- a/js/net/src/group.ts +++ b/js/net/src/group.ts @@ -568,6 +568,7 @@ export class Consumer { group.#state.unverified = true; }; hooks.groupArrived = (group) => group.#state.arrived; + hooks.groupStarted = (group) => group.#state.total.peek() > 0 || group.#state.closed.peek() !== undefined; hooks.arriveGroup = (group, at) => { group.#state.arrived = at; }; diff --git a/js/net/src/ietf/subscriber.test.ts b/js/net/src/ietf/subscriber.test.ts index 2c29c7712e2..b6e33b75668 100644 --- a/js/net/src/ietf/subscriber.test.ts +++ b/js/net/src/ietf/subscriber.test.ts @@ -1288,15 +1288,15 @@ test.each(["acceptance", "timeout"])("returning demand preserves pending setup u const subscriber = new Subscriber({ session }); const opening = spyOn(session, "openBi"); const broadcast = subscriber.consume(Path.from("room")); - const pending = hooks.pendingTrackProducer; + const make = hooks.makeRequest; let returned: track.Subscriber | undefined; const resumed = Promise.withResolvers(); const waiting = Promise.withResolvers(); const unwanted = demandUtil.unwanted; const unwantedSpy = spyOn(demandUtil, "unwanted"); - const captured = spyOn(hooks, "pendingTrackProducer").mockImplementationOnce((request) => { - const producer = pending(request); - const demand = producer.demand(); + const captured = spyOn(hooks, "makeRequest").mockImplementationOnce((options) => { + const request = make(options); + const demand = request.demand(); let returnedOnce = false; unwantedSpy.mockImplementation(async (watched) => { if (watched !== demand) return unwanted(watched); @@ -1319,7 +1319,7 @@ test.each(["acceptance", "timeout"])("returning demand preserves pending setup u return used; }); }); - return producer; + return request; }); const first = broadcast.track("video").subscribe(); // Restore real timers even if an injection promise outlives the test. @@ -1366,13 +1366,13 @@ test("setup abandonment closes before a queued viewer can attach", async () => { const session = new NativeSession(pair.server, VERSION, true); const subscriber = new Subscriber({ session }); const broadcast = subscriber.consume(Path.from("room")); - const pending = hooks.pendingTrackProducer; + const make = hooks.makeRequest; const resumed = Promise.withResolvers(); const unwanted = demandUtil.unwanted; const unwantedSpy = spyOn(demandUtil, "unwanted"); - const captured = spyOn(hooks, "pendingTrackProducer").mockImplementationOnce((request) => { - const producer = pending(request); - const demand = producer.demand(); + const captured = spyOn(hooks, "makeRequest").mockImplementationOnce((options) => { + const request = make(options); + const demand = request.demand(); unwantedSpy.mockImplementationOnce(async (watched) => { await unwanted(watched); const peek = demand.wanted.peek.bind(demand.wanted); @@ -1388,7 +1388,7 @@ test("setup abandonment closes before a queued viewer can attach", async () => { return used; }); }); - return producer; + return request; }); const first = broadcast.track("video").subscribe(); let returned: track.Subscriber | undefined; @@ -1433,13 +1433,19 @@ test("abandonment cancels once and a late acceptance cannot capture a reused ali peer.reader.version = version; peer.writer.version = version; const broadcast = subscriber.consume(Path.from("room")); - const pending = hooks.pendingTrackProducer; - let producer: track.Producer | undefined; + const make = hooks.makeRequest; let oldRequest: track.Request | undefined; - const captured = spyOn(hooks, "pendingTrackProducer").mockImplementationOnce((request) => { + // The error the abandoned request is rejected with. + const rejected = Promise.withResolvers(); + const captured = spyOn(hooks, "makeRequest").mockImplementationOnce((options) => { + const request = make(options); + const reject = request.reject.bind(request); + spyOn(request, "reject").mockImplementation((err) => { + rejected.resolve(err); + reject(err); + }); oldRequest = request; - producer = pending(request); - return producer; + return request; }); const decoded = Promise.withResolvers(); const release = Promise.withResolvers(); @@ -1455,13 +1461,13 @@ test("abandonment cancels once and a late acceptance cannot capture a reused ali try { expect(await peer.reader.u53()).toBe(Subscribe.id); const request = await Subscribe.decode(peer.reader, version); - if (!producer || !oldRequest) throw new Error("missing pending track"); + if (!oldRequest) throw new Error("missing pending track"); const accepted = spyOn(oldRequest, "accept"); await peer.writer.u53(SubscribeOk.id); await new SubscribeOk({ requestId: request.requestId, trackAlias: ALIAS }).encode(peer.writer, version); await decoded.promise; first.close(); - expect(await producer.closed).toBeInstanceOf(Error); + expect(await rejected.promise).toBeInstanceOf(Error); expect(await peer.reader.u53()).toBe(Unsubscribe.id); expect((await Unsubscribe.decode(peer.reader, version)).requestId).toBe(request.requestId); diff --git a/js/net/src/ietf/subscriber.ts b/js/net/src/ietf/subscriber.ts index 614b3125702..ff46861e506 100644 --- a/js/net/src/ietf/subscriber.ts +++ b/js/net/src/ietf/subscriber.ts @@ -101,6 +101,8 @@ type Subscription = { // before the setup promise settles. type SubscribeSetupState = { stream?: RequestStream; + // The accepted subscription, which a registered alias names. + subscription?: Subscription; registeredAlias?: bigint; /** * Whether the caller has given up. Setup checks this once the stream exists so a request @@ -812,26 +814,24 @@ export class Subscriber { // Keep the request pending until SUBSCRIBE_OK supplies immutable track metadata. // Group streams already wait on the alias, so early data stays behind this response. - const producer = hooks.pendingTrackProducer(request); - const subscription: Subscription = { track: producer, tail: new Tail() }; - // Open the stream and wait for SUBSCRIBE_OK under a timeout. State // flows back via `state` so the timeout path can clean up the stream // and any registration if setup eventually finishes. const state: SubscribeSetupState = {}; const deadline = new Deadline(); - const setup = this.#openSubscribe(state, broadcast, request, subscription, requestId, deadline, epoch); + const setup = this.#openSubscribe(state, broadcast, request, requestId, deadline, epoch); // The publisher can be serving before it answers, so waiting only on the response // would miss the local side going away and leave it serving a track nobody reads. // Demand returning before we commit is not abandonment, matching the serving loop. - const demand = producer.demand(); + const demand = request.demand(); const waitAbandoned = async (): Promise => { await demandAbandoned(demand); return null; }; let stream: RequestStream; + let subscription: Subscription; let trackAlias: bigint; // The SUBSCRIBER_PRIORITY the request went out with. let priority: number; @@ -844,6 +844,7 @@ export class Subscriber { const result = await untilAborted(race([accepted, waitAbandoned()]), valid); if (result !== null) { stream = result.stream; + subscription = result.subscription; trackAlias = result.alias; priority = result.priority; maxAge = result.maxAge; @@ -869,7 +870,11 @@ export class Subscriber { const cleanup = async (afterSetup: boolean) => { state.cancelled = true; - if (state.registeredAlias !== undefined && this.#aliases.retire(state.registeredAlias, subscription)) { + if ( + state.registeredAlias !== undefined && + state.subscription && + this.#aliases.retire(state.registeredAlias, state.subscription) + ) { this.#timescales.delete(state.registeredAlias); } @@ -903,6 +908,7 @@ export class Subscriber { return; } + const producer = subscription.track; let disposeGrant: Dispose | undefined; try { // Which terminal fired decides whether we owe the publisher a cancellation, so @@ -1136,11 +1142,16 @@ export class Subscriber { state: SubscribeSetupState, broadcast: Path.Valid, request: track.Request, - subscription: Subscription, requestId: bigint, deadline: Deadline, epoch: Epoch.Valid | undefined, - ): Promise<{ stream: RequestStream; alias: bigint; priority: number; maxAge?: number }> { + ): Promise<{ + stream: RequestStream; + subscription: Subscription; + alias: bigint; + priority: number; + maxAge?: number; + }> { const version = this.#session.version; const legacy = version === Version.DRAFT_14 || version === Version.DRAFT_15 || version === Version.DRAFT_16; @@ -1213,7 +1224,12 @@ export class Subscriber { if (maxCacheDuration !== undefined && maxCacheDuration > BigInt(Number.MAX_SAFE_INTEGER)) { throw new RangeError("max cache duration exceeds safe milliseconds"); } - request.accept({ + if (ok.largest && ok.largest.groupId > BigInt(Number.MAX_SAFE_INTEGER)) { + throw new RangeError("largest group exceeds safe integers"); + } + // Staged until the answer is written in below, so no reader sees the track before its + // Largest and start. + const staged = request.stage({ // No TIMESCALE (always so on drafts 14-16, which can't carry it) means no timeline, // and the track must not claim one when served onward. timescale: ok.properties.timescale, @@ -1222,22 +1238,23 @@ export class Subscriber { // A moq-transport peer may stamp arrival times, and nothing on the wire says it didn't. unchecked: ok.properties.timescale != null, }); - if (ok.largest && ok.largest.groupId > BigInt(Number.MAX_SAFE_INTEGER)) { - throw new RangeError("largest group exceeds safe integers"); + const producer = staged.producer; + const subscription: Subscription = { track: producer, tail: new Tail() }; + state.subscription = subscription; + if (ok.largest) { + // Object IDs can start past zero or skip, while readers see frame ordinals, so only + // the group carries over: its first frame is the edge a reader can count on. + hooks.reportedLargest(producer, { group: Number(ok.largest.groupId), frame: 0 }); } // The live join starts at the publisher's edge, whatever floor the demand asked for. // With no Largest it skips nothing, so every group is owed: a lower one's stream may // still arrive after a higher one's. const groups = request.subscription.groups; - hooks.startTrack(subscription.track, { + hooks.startTrack(producer, { start: ok.largest ? Number(ok.largest.groupId) : 0, requested: groups?.start === undefined ? undefined : groupBounds(groups).start, }); - if (ok.largest) { - // Object IDs can start past zero or skip, while readers see frame ordinals, so only - // the group carries over: its first frame is the edge a reader can count on. - hooks.reportedLargest(subscription.track, { group: Number(ok.largest.groupId), frame: 0 }); - } + staged.commit(); try { this.#aliases.set(ok.trackAlias, subscription, { broadcast, name: request.name, epoch }); @@ -1253,7 +1270,13 @@ export class Subscriber { throw err; } state.registeredAlias = ok.trackAlias; - return { stream: state.stream, alias: ok.trackAlias, priority: msg.subscriberPriority, maxAge: msg.maxAge }; + return { + stream: state.stream, + subscription, + alias: ok.trackAlias, + priority: msg.subscriberPriority, + maxAge: msg.maxAge, + }; } /** diff --git a/js/net/src/internal.ts b/js/net/src/internal.ts index 9a82687e71c..0c5764c540f 100644 --- a/js/net/src/internal.ts +++ b/js/net/src/internal.ts @@ -400,7 +400,7 @@ export const hooks: { * end may refine the group boundary it falls just before. Throws `ProtocolViolation` on * any other second end. Readers then hold at a hole below it until the hole fills, folds * past the grace, or the track closes, since QUIC may deliver a lower group's stream after - * a higher one. Mirrors the Rust `finish_at_pending`; assigned by `track.ts`. + * a higher one. Mirrors the Rust `finish_at` on a `received()` copy; assigned by `track.ts`. */ endTrack: (producer: Producer, end: Location) => void; // private: capability gap @@ -424,9 +424,6 @@ export const hooks: { startTrack: (producer: Producer, served: { start?: number; requested?: number }) => void; /** Mint a track {@link Request}; assigned by `track.ts`. */ makeRequest: (options: TrackRequestOptions) => Request; - // pending: /quest/m1/public-model/ingest.md - /** Access the existing producer while a request awaits immutable wire metadata. */ - pendingTrackProducer: (request: Request) => Producer; /** Have a producer write through a broadcast's sequence namespace for its name. */ bindSequence: (producer: Producer, sequence: TrackSequence) => void; /** The newest frame a producer's cache holds, read without subscribing; assigned by `track.ts`. */ @@ -453,12 +450,6 @@ export const hooks: { bufferedLargest: (subscriber: Subscriber) => Location | undefined; /** Call `fn` with a group's frame count now and on every change; assigned by `group.ts`. */ groupProgress: (group: GroupProducer, fn: (total: number) => void) => Dispose; - // pending: /quest/m1/public-model/ingest.md - /** - * Record sequences `[start, end)` an upstream publisher explicitly gave up with `error`, - * ending the groups still arriving in them with it. - */ - dropTrackGroups: (producer: Producer, start: number, end: number, error: Error) => void; // pending: /quest/m1/public-model/serve.md /** * Take the next group the subscriber's cursor allows, without waiting; assigned by `track.ts`. @@ -553,6 +544,8 @@ export const hooks: { groupLatest: (group: GroupConsumer) => Timestamp | undefined; /** Return when a group joined its track at this hop, on the installed clock. */ groupArrived: (group: GroupConsumer) => Instant; + /** Whether a group counts as content: its first frame landed, or it ended. */ + groupStarted: (group: GroupConsumer) => boolean; /** Record when a track's mirror of a group joined that track at this hop. */ arriveGroup: (group: GroupConsumer, at: Instant) => void; /** Keep applying a subscription's drift policy after it hands a group out. */ @@ -601,9 +594,6 @@ export const hooks: { makeRequest: () => { throw new Error("track.ts not loaded"); }, - pendingTrackProducer: () => { - throw new Error("track.ts not loaded"); - }, bindSequence: () => { throw new Error("track.ts not loaded"); }, @@ -628,9 +618,6 @@ export const hooks: { groupProgress: () => { throw new Error("group.ts not loaded"); }, - dropTrackGroups: () => { - throw new Error("track.ts not loaded"); - }, tryRecvGroup: () => { throw new Error("track.ts not loaded"); }, @@ -730,6 +717,9 @@ export const hooks: { groupArrived: () => { throw new Error("group.ts not loaded"); }, + groupStarted: () => { + throw new Error("group.ts not loaded"); + }, expireGroup: () => { 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 e7d620bff4f..f1d8b554a66 100644 --- a/js/net/src/lite/publisher.test.ts +++ b/js/net/src/lite/publisher.test.ts @@ -1106,7 +1106,7 @@ for (const skipped of ["failed", "stale"] as const) { group.writeFrame(textFrame("old", Timestamp.fromMillis(5))); sub.track.writeGroup(group); group.close(skipped === "failed" ? new Error("cut") : undefined); - if (skipped === "failed") hooks.dropTrackGroups(sub.track, 7, 8, new Error("cut")); + if (skipped === "failed") sub.track.dropGroups(7, 8, new Error("cut")); sub.serve(6); const response = await decodeSubscribeResponse(sub.client.reader, Version.DRAFT_06); if (!("start" in response)) throw new Error("expected SUBSCRIBE_START"); diff --git a/js/net/src/lite/subscriber.ts b/js/net/src/lite/subscriber.ts index cdffbf67c95..bf08a2dff9e 100644 --- a/js/net/src/lite/subscriber.ts +++ b/js/net/src/lite/subscriber.ts @@ -1431,7 +1431,7 @@ export class Subscriber { // The publisher will never send these groups, so they are accounted for without a // stream, and a reader of one still arriving ends with the drop's error now. entry.tail.account(resp.drop.start, resp.drop.end + 1); - hooks.dropTrackGroups(entry.track, resp.drop.start, resp.drop.end + 1, resp.drop.cause(this.version)); + entry.track.dropGroups(resp.drop.start, resp.drop.end + 1, resp.drop.cause(this.version)); } } } diff --git a/js/net/src/resume.test.ts b/js/net/src/resume.test.ts index 90062b70346..71f27a1753b 100644 --- a/js/net/src/resume.test.ts +++ b/js/net/src/resume.test.ts @@ -802,7 +802,7 @@ for (const fails of [true, false]) { expect(tb.producer.demand().wanted.peek()).not.toBeUndefined(); const cut = new StreamError(StreamCode(70), { message: "cut" }); - hooks.dropTrackGroups(tb.producer, 0, 1, cut); + tb.producer.dropGroups(0, 1, cut); await expect(read).rejects.toBe(cut); sub.close(); @@ -1529,7 +1529,7 @@ test.each(["lands", "dropped", "expired"])( expect(drain(sub)).toEqual([]); expect(ta.producer.demand().wanted.peek()).toBeDefined(); - if (outcome === "dropped") hooks.dropTrackGroups(ta.producer, 1, 2, new NotFound("group")); + if (outcome === "dropped") ta.producer.dropGroups(1, 2, new NotFound("group")); if (outcome === "expired") await clock.advance(Nano.fromMilli(SECOND)); if (outcome !== "lands") { // The groups drained above are released once their close settles. diff --git a/js/net/src/track.test.ts b/js/net/src/track.test.ts index 96a58cdedc2..2f2d226625e 100644 --- a/js/net/src/track.test.ts +++ b/js/net/src/track.test.ts @@ -624,10 +624,10 @@ test("the latency budget skips a buffered timeline on either cursor", async () = expect((await replay.nextGroup())?.sequence).toBe(2); }); -// An unstamped immediate successor leaves a group's reach unbounded: a later stamped -// group proves nothing about where the successor will begin, and shrinking the bound -// is the unsafe direction. -test("an unstamped immediate successor leaves reach unbounded", async () => { +// A frameless successor is not content, so the next started group bounds the group before +// it. That bound is sound: the frameless group's first frame is checked to start at or below +// the next group's, so the true reach can only be earlier. +test("a frameless successor leaves the next started group as the bound", async () => { const producer = new TrackProducer("test").accept({ timescale: Timescale.MILLI, maxAge: Milli(5000) }); // Any budget, so only media time judges: the wall clock barely moves here. const track = producer.subscribe({ maxDelay: Milli(500) }); @@ -637,9 +637,8 @@ test("an unstamped immediate successor leaves reach unbounded", async () => { producer.writeFrame({ payload: enc.encode("2"), timestamp: Timestamp.fromMillis(10_000) }); producer.writeFrame({ payload: enc.encode("3"), timestamp: Timestamp.fromMillis(11_000) }); - // Group 1's reach is group 2's start, a second behind the edge: stale. - // Group 0's reach is unknown until group 1 presents its first frame, so it is kept. - expect(drain(track)).toEqual([0, 2, 3]); + // Groups 0 and 1 both reach at most group 2's start, a second behind the edge: stale. + expect(drain(track)).toEqual([2, 3]); }); // Groups can arrive out of sequence order; the immediate successor bounds reach even when it @@ -2683,7 +2682,7 @@ const DROPPED = new StreamError(StreamCode.NotFound, { message: "dropped" }); test("explicit and producer-cut drops survive outside the group cache", async () => { const producer = new TrackProducer("video").accept({}); const reader = producer.subscribe({ maxDelay: Milli(60_000) }); - hooks.dropTrackGroups(producer, 3, 4, DROPPED); + producer.dropGroups(3, 4, DROPPED); expect(hooks.tryRecvGroup(reader, true)).toEqual({ kind: "drop", start: 3, end: 4, error: DROPPED }); const group = new GroupProducer(4); @@ -2734,7 +2733,7 @@ test("an upstream drop ends a group still arriving with its error", async () => expect(group?.sequence).toBe(3); expect(await group?.readString()).toBe("3"); const cut = new StreamError(StreamCode(70), { message: "cut" }); - hooks.dropTrackGroups(producer, 3, 5, cut); + producer.dropGroups(3, 5, cut); // Settled by the drop itself, not a later reset; the finished group stays whole. await expect(group?.readString()).rejects.toBe(cut); const whole = await reader.recvGroup(); @@ -2748,7 +2747,7 @@ test("an upstream drop ends a group still arriving with its error", async () => test("a drop below the window is reported once the window lowers to it", () => { const producer = new TrackProducer("video").accept({}); const reader = producer.subscribe({ maxDelay: Milli(60_000), groups: { start: { included: 5 } } }); - hooks.dropTrackGroups(producer, 2, 3, DROPPED); + producer.dropGroups(2, 3, DROPPED); expect(hooks.tryRecvGroup(reader, true)).toEqual({ kind: "idle" }); hooks.replaceGroups(reader, { start: { included: 0 } }); @@ -2779,12 +2778,12 @@ test("a re-created cut group is served, not dropped", async () => { test("a wide drop is held and reported as one run", () => { const producer = new TrackProducer("video").accept({}); const reader = producer.subscribe({ maxDelay: Milli(60_000) }); - hooks.dropTrackGroups(producer, 2, 2 ** 40, DROPPED); + producer.dropGroups(2, 2 ** 40, DROPPED); expect(hooks.tryRecvGroup(reader, true)).toEqual({ kind: "drop", start: 2, end: 2 ** 40, error: DROPPED }); // A wider drop reports only what this cursor has not reported yet, with its own error. const wider = new StreamError(StreamCode.Old, { message: "old" }); - hooks.dropTrackGroups(producer, 1, 2 ** 40 + 2, wider); + producer.dropGroups(1, 2 ** 40 + 2, wider); expect(hooks.tryRecvGroup(reader, true)).toEqual({ kind: "drop", start: 1, end: 2, error: wider }); expect(hooks.tryRecvGroup(reader, true)).toEqual({ kind: "drop", @@ -2803,12 +2802,7 @@ test("adjacent drops with the same code merge into one run", () => { const reader = producer.subscribe({ maxDelay: Milli(60_000) }); // Each DROP decodes to its own error, so runs must merge by code, not identity. for (let sequence = 2; sequence < 5; sequence++) { - hooks.dropTrackGroups( - producer, - sequence, - sequence + 1, - new StreamError(StreamCode.NotFound, { message: "dropped" }), - ); + producer.dropGroups(sequence, sequence + 1, new StreamError(StreamCode.NotFound, { message: "dropped" })); } const recv = hooks.tryRecvGroup(reader, true); expect(recv.kind === "drop" ? [recv.start, recv.end, recv.error] : recv).toEqual([2, 5, DROPPED]); @@ -3326,7 +3320,7 @@ for (const abort of [false, true]) { const next = reader.recvGroup(); expect(await settled(next)).toBe(false); - hooks.dropTrackGroups(producer, 0, 2, DROPPED); + producer.dropGroups(0, 2, DROPPED); if (abort) producer.close(new Error("dropped")); expect(await next).toBeUndefined(); if (abort) expect(await reader.closed).toBeNull(); diff --git a/js/net/src/track.ts b/js/net/src/track.ts index 8c65a991c0f..8d1a6b2f085 100644 --- a/js/net/src/track.ts +++ b/js/net/src/track.ts @@ -336,7 +336,6 @@ export class Request { static { hooks.makeRequest = (options) => new Request(options); - hooks.pendingTrackProducer = (request) => request.#producer; } /** Watch the subscribers waiting for this request. */ @@ -356,24 +355,77 @@ export class Request { /** * Accept the request, committing the track's immutable {@link Info}. Throws, rejecting the - * request, if `info` is invalid. + * request, if `info` is invalid. The same as {@link stage} followed by {@link Staged.commit}. */ accept(info: Partial = {}): Producer { + return this.stage(info).commit(); + } + + /** + * Take the track's {@link Producer} without resolving any subscriber yet, so content written + * through {@link Staged.producer} is there when the first reader looks. For a relay that + * already holds groups of the track: write them, then {@link Staged.commit}. Disposing the + * {@link Staged} uncommitted rejects the request. + */ + stage(info: Partial = {}): Staged { + this.#pending.delete(this); + bindProducerSequence(this.#producer, this.#sequences.get(this.name)); + return new Staged(this.#producer, info); + } + + /** Reject the request, closing the track optionally with an error. */ + reject(err?: Error): void { this.#pending.delete(this); + this.#producer.close(err); + } +} + +/** + * A requested track being written before any subscriber sees it; see {@link Request.stage}. + * + * Write through {@link producer}. Subscribers waiting on the request resolve only at + * {@link commit}, with everything written by then. Disposing it uncommitted rejects the request, + * so hold it with `using` or commit it. + * + * @public + */ +export class Staged { + /** The track's writer. */ + readonly producer: Producer; + + #info: Partial; + #done = false; + + /** @internal */ + constructor(producer: Producer, info: Partial) { + this.producer = producer; + this.#info = info; + } + + /** + * Publish the track: every waiting subscriber resolves now, with what was written. Throws, + * rejecting the request, if the info is invalid or something written does not match it. + * Throws without publishing once committed or disposed. + */ + commit(): Producer { + // Rust's `commit(self)` consumes the handle; here a disposed one has already rejected + // its subscribers, and accepting a closed producer would silently do nothing. + if (this.#done) throw new Error("staged track already committed or dropped"); + this.#done = true; try { - bindProducerSequence(this.#producer, this.#sequences.get(this.name)); - return this.#producer.accept(info); + return this.producer.accept(this.#info); } catch (err) { // Refused, so its subscribers see the error instead of waiting on an open request. - this.#producer.close(err instanceof Error ? err : new Error(String(err))); + this.producer.close(err instanceof Error ? err : new Error(String(err))); throw err; } } - /** Reject the request, closing the track optionally with an error. */ - reject(err?: Error): void { - this.#pending.delete(this); - this.#producer.close(err); + /** Reject the request unless it was committed. */ + [Symbol.dispose](): void { + if (this.#done) return; + this.#done = true; + this.producer.close(new Error("staged track dropped")); } } @@ -821,10 +873,19 @@ export class Producer { hooks.arriveGroup(mirror, entry.arrived); return mirror; }; - hooks.dropTrackGroups = (producer, start, end, error) => producer.#drop(start, end, error, true); mayLand = (producer, land) => producer.#mayLand(land); } + /** + * Record that the publisher gave up the groups `[start, end)` with `error`, mirroring the + * Rust `drop_groups`: none will arrive, so a reader waiting on one moves past it, a group + * still arriving in them ends with `error`, the declared end does not wait for them, and a + * relay serving this track forwards the drop. + */ + dropGroups(start: number, end: number, error: Error): void { + this.#drop(start, end, error, true); + } + // Whether a group may still land from the live feed, by the rule a pending tail is judged // by; see {@link Land}. Mirrors the Rust `TrackState::may_land`. #mayLand(land: Land): boolean { @@ -1548,7 +1609,7 @@ export class Producer { } // The wire's end: repeating it is a no-op, and a mid-group end may refine the group - // boundary it falls just before. Mirrors the Rust `finish_at_pending`. + // boundary it falls just before. Mirrors the Rust `finish_at` on a `received()` copy. #endPending(end: Location): void { const declared = this.#state.end.peek(); if (declared === undefined) { @@ -1789,21 +1850,37 @@ export class Subscriber { }; } - // The group after `sequence` that bounds it: the first servable one below `end`, - // stamped or not, empty or not. + // The group after `sequence` that bounds it: the first servable one below `end` that + // counts as content (its first frame landed, or it ended), stamped or not. // // Its first timestamp is the furthest presentation time `sequence` could still reach. // An upper bound, deliberately: a frame's duration is not on the wire, so a group's own - // last timestamp says where it starts presenting, not where it ends. The bound is the - // *immediate* successor's start, so an unstamped successor leaves the reach unbounded - // until it presents a frame. + // last timestamp says where it starts presenting, not where it ends. A group whose header + // landed without a frame is not content yet, so the next one is the bound; an unstamped + // successor leaves the reach unbounded. #successor(sequence: number, end?: number): GroupConsumer | undefined { + return this.#after(sequence, end, hooks.groupStarted); + } + + // The group after `sequence` that starts its wall clock: like {@link #successor}, but + // counting a group before its first frame. Its header arrived, so a relay ages the group + // before it as the origin does, even if its first frame never comes. + #arrival(sequence: number, end?: number): GroupConsumer | undefined { + return this.#after(sequence, end, () => true); + } + + // The first servable group after `sequence` below `end` that `counts`. + #after( + sequence: number, + end: number | undefined, + counts: (group: GroupConsumer) => boolean, + ): GroupConsumer | undefined { const timeline = this.#state.timeline; for (let i = timelineIndex(timeline, sequence + 1); i < timeline.length; i++) { const successor = timeline[i]; if (end !== undefined && successor.sequence >= end) break; if (successor.closed.peek() instanceof Error) continue; - return successor; + if (counts(successor)) return successor; } return undefined; } @@ -1836,13 +1913,15 @@ export class Subscriber { // The drift verdict for `sequence` by its successor alone, whether or not this track holds it. #staleAt(sequence: number, drift: Drift, wake = false): boolean { - const successor = this.#successor(sequence, drift.end); - if (!successor) return false; + const arrival = this.#arrival(sequence, drift.end); + if (!arrival) return false; // Plain arithmetic: an unenforced budget is infinite, which no duration brand holds. - const deadline = hooks.groupArrived(successor) + drift.budget * 1_000_000; + const deadline = hooks.groupArrived(arrival) + drift.budget * 1_000_000; if (now() >= deadline) return true; if (wake) this.#wakeAt(deadline); + const successor = this.#successor(sequence, drift.end); + if (!successor) return false; const reach = hooks.groupTimestamp(successor)?.asMillis(); return ( drift.presentation !== undefined && diff --git a/quest/m1/public-model/README.md b/quest/m1/public-model/README.md index a1c82a05e45..4e28d52ecf6 100644 --- a/quest/m1/public-model/README.md +++ b/quest/m1/public-model/README.md @@ -35,7 +35,9 @@ Rules every child follows: that change cost, never behavior a third party can observe. - "capability gap": a built-in behavior a third party can observe but not reproduce yet, kept private by a recorded decision that names what - would close it (the idle copy in [ingest](/quest/m1/public-model/ingest.md)). + would close it (the idle copy, `track::Producer::set_idle` and `set_live`: + a custom subscriber ends its track when its upstream subscription ends + instead of keeping a lingering copy). - "plumbing" (JS only): session or wire plumbing hosted beside the model, such as `wire.ts` `Established`, `wireOf`, `tail.ts`, `consume.ts`, and `priority.ts`. @@ -60,7 +62,7 @@ Inventory on `main` at b4eab0db1: - Rust has 347 `pub(crate)` items in `model/` and no `#[doc(hidden)]` model item. 106 are reached by session code, 16 only by session tests, and 225 only inside `model/`. -- The 106 split into [ingest](/quest/m1/public-model/ingest.md), +- The 106 split into ingest (landed in [moq-dev/moq#6111](https://github.com/moq-dev/moq/pull/6111)), [serving](/quest/m1/public-model/serve.md), [routes and answering](/quest/m1/public-model/answer.md), and the passthrough carve-out (listed in each child where it shares a type). @@ -101,7 +103,6 @@ Work owned by this README, after the children land: ## Required - [Claim request type](/quest/m1/public-model/claim-request-type.md) - accepting an application claim's request fails to compile instead of panicking -- [Public ingest](/quest/m1/public-model/ingest.md) - a custom subscriber writes received groups, frames, starts, and ends into a track through public calls - [Public serving](/quest/m1/public-model/serve.md) - a custom publisher reads a track's start, cursor, and group expiry for its wire through public calls - [Public routes and answering](/quest/m1/public-model/answer.md) - a custom relay ingests routes, answers broadcast and track requests on demand, and advertises without echoing a peer's routes back - [Public model after ranges, handover, and the JS tail](/quest/m1/public-model/deferred.md) - fetch and track-info answering, the cache peeks, JS `fork`/`mirror`, and JS `endTrack`, once the quests that reshape them land diff --git a/quest/m1/public-model/deferred.md b/quest/m1/public-model/deferred.md index 87c752e6700..97b9c5a6ae4 100644 --- a/quest/m1/public-model/deferred.md +++ b/quest/m1/public-model/deferred.md @@ -10,7 +10,7 @@ info, and declares a received end in JS, through public calls only. ## Plan -Split from the [ingest](/quest/m1/public-model/ingest.md), +Split from the ingest ([moq-dev/moq#6111](https://github.com/moq-dev/moq/pull/6111)), [serving](/quest/m1/public-model/serve.md), and [answering](/quest/m1/public-model/answer.md) quests in review of #5717, so those three do not wait on the large quests that replace these items. @@ -37,8 +37,9 @@ the prerequisites will have deleted or renamed most of these. requests that Model ranges defines, completing the answering quest's `Broadcast.requested` decision. - JS `hooks.endTrack` and `hooks.startTrack` (the JS `finish_at_pending` and - `start_at`): public under the received-end shape the ingest quest settles in - Rust. + `start_at`): public under the received-end shape Rust settled in + [moq-dev/moq#6111](https://github.com/moq-dev/moq/pull/6111): `finish_at` + on a `received()` copy, and `start_at` after `track::Request::request_start`. Tests: as in the other children, mock time in each language, with the built-in sessions moved onto the public calls. @@ -46,6 +47,5 @@ built-in sessions moved onto the public calls. ## Required - [Dynamic range requests](/quest/m1/subscribe-ranges/dynamic.md) - replaces per-group fetch requests, the peeks, and `fork` -- [Public ingest](/quest/m1/public-model/ingest.md) - settles the received-end shape JS mirrors - [JS ranges](/quest/m1/subscribe-ranges/js.md) - the JS `Track.Request`/`Track.Dynamic` range requests that answer track info and fetches - [Public routes and answering](/quest/m1/public-model/answer.md) - the public `Broadcast.requested` handout this completes diff --git a/quest/m1/public-model/ingest.md b/quest/m1/public-model/ingest.md deleted file mode 100644 index 2f7305125d3..00000000000 --- a/quest/m1/public-model/ingest.md +++ /dev/null @@ -1,214 +0,0 @@ -# [L] Public ingest - -## Goal - -A custom subscriber writes what it receives into a track through public -moq-net and @moq/net calls only: groups whose header lands before their first -frame, frames streamed across polls with peer-declared sizes, the start its -peer resolves, a received end with groups still in flight, and the session -ending. The built-in lite and IETF subscribers use the same calls. - -## Plan - -Rules, carve-outs, and the inventory method are in the -[epic](/quest/m1/public-model/README.md). Rerun the inventory first; the -recommendations below are the planning quest's, and the ones marked -**decision** were settled by the maintainer on 2026-10-16 (#5717). - -Rust items (`rs/moq-net/src/model/`), as they stood at b4eab0db1: - -- **Withheld groups** (`track::Producer::receive_group`, `reveal_group`, - `group::Producer::is_started`; lite subscriber). **Decision**, reopened - in review and settled 2026-10-16: - - ~~`create_group` withholds every group until its first frame or end.~~ - It deadlocks a publisher that creates a group and waits on - `group::Producer::demand()` before encoding, since no reader can reach - a withheld group to demand it. - - A public `receive_group` that reveals itself on its first frame or end. - - A public `receive_group` and `reveal_group` pair, as today. - - ✅ Drop withholding. Hiding a group from readers was never what fixed - #4914's rejoin bug: the model's judgments must not count a frameless - group as content. Derive that from each group's own state (first frame - opened, or ended) for every group, wherever the model asks it: the live - edge, successor and staleness, the rejoin wait (`shows`), `newest` and - `largest`, and `set_idle`. Every group joins arrival order when created, - so readers and group demand reach it before its first frame. - `create_group` is the only call; `receive_group`, `reveal_group`, and - `is_started` go. The group wakes its track once, on its first frame or - end, as `reveal` does today. Verified on a scratch branch at dd95d5804 - for received groups: with arrival order immediate and the judgments - gated, the whole moq-net suite passes except the two tests that assert - the old design. Consequences: - - The cache's internal largest stops reporting a frameless newest group - as (N, 0) and reports the last frame that exists. The public - `largest()` stream (#5725) deliberately does not: the maintainer - decided on 2026-10-17 that it counts every sequence seen, an empty - group at its head, so a late group below it never moves it. - - Regression guard: `rejoin_waits_for_the_answers_first_frame` - (`rs/moq-net/tests/integration/rejoin.rs`, fails when the judgments count a - frameless group) and - `revealing_a_presented_group_wakes_a_read_it_expires` stay; - `a_withheld_group_holds_the_end` and - `a_withheld_group_that_ends_empty_releases_the_end` are rewritten to - "a frameless group does not count as content" rather than "a reader - cannot see it". - - Unverified: app-created groups on the derived path, and the JS - mirror. Check both here before landing. -- **Owned frame writer** (`group::Producer::create_frame_owned`, - `frame::ProducerOwned`; both subscribers, `coding/reader.rs`). A - poll-driven wire driver cannot hold the borrowing `frame::Producer<'a>` - across polls. **Decision**, reopened in review and settled 2026-10-16: - - One owned `frame::Producer` guarded only by the runtime - `Error::FrameOpen` refusal. - - A second, public owned type (AGENTS.md's no-twins rule argues against - it). - - ✅ Make one open frame per group a compile-time guarantee. Drop public - `Clone` from `group::Producer`; the model and sessions keep a - crate-private non-writing handle. The chunked writer is owned: - `group::Producer::create_frame(self, info) -> Result` - aborts the group with the error on failure (an oversized frame, a - timestamp mismatch, or a closed group are bugs or protocol errors), - `frame::Producer::finish(self) -> Result` hands it - back, and `frame.group()` gives read access (demand, info, closed) - while the frame is open. `write_frame(&mut self)` stays for one-shot - frames. The borrowing `create_frame` and `ProducerOwned` go, with the - stale "caller's promise" doc. `track::Producer` keeps `Clone`: several - writers creating groups is legitimate, and `claim_sequence` already - refuses a duplicate sequence. - - #6020 dropped `Clone`, added the crate-private non-writing - `group::Handle`, and deleted `FrameOpen` (decided 2026-10-18, #5892), - so the backstop above goes. This item keeps the - public owned chunked writer. Its callers that hold a - `&mut group::Producer` (hang's `Frame::write_to`, moq-mux's LOC and - fMP4 encoders) cannot call a consuming `create_frame(self)`; weigh - that before landing it. - - Compile probe at dd95d5804: 26 `group::Producer` clone sites, 16 - model-internal and 7 in the sessions (kept by the crate-private - duplicate), and 3 outside the crate (2 in - `rs/moq-net/benches/track.rs`, 1 moq-ffi test), all trivial. - - The sessions clone to abort a group held elsewhere and to watch - demand or closure. If a third-party session needs to abort without - owning the writer, add a non-writing abort handle rather than - `Clone`. - - Pitfall: `group::Producer` derefs to the `Copy` `group::Info`, so a - downstream `producer.clone()` silently copies the `Info` and fails - later with a confusing "no method on `Info`" error. Say so in the - changelog, or drop the `Deref` for an `info()` getter. -- The frame writer's write without a wake (today - `frame::ProducerOwned::write`) and `notify`: stay private, "tunes the - built-in sessions" (batches wakes per poll turn). -- **Allocation budget** (`frame::Budget`; both subscribers): remove the - caller-supplied argument, but keep the aggregate bound. Today one 16 MiB - budget is shared by every frame a lite or IETF subscriber session - receives, so a peer that opens many streams declaring maximum-size frames - gets lazy growth past it, not memory. A per-producer budget would lose - that, and so would the origin's cache pool, which is unbounded by - default. Recommended: the budget lives on the origin producer handle a - session ingests through (the one that already carries its stats and - identity), with the same default, and is shared by every source, track, - and group minted from that handle. A frame whose declared size does not - fit grows with the bytes received, as today. The alternative is no - up-front allocation at all (always lazy), which needs no budget but pays - a reallocation per doubling on every large frame. Measure it against the - ingest benchmarks before choosing it. -- `group::Producer::info` (IETF subscriber): public, mirroring - `track::Producer::info`. -- **Received end** (`track::Producer::finish_at_pending`, `set_tail_pending`; - both subscribers). Without it, a custom subscriber over unordered streams - ends readers at a hole. **Decision**: - - Public after Tail arrivals, as one call that returns a handle the - session settles when its tail is in. - - Keep it private. - - ✅ Public after Tail arrivals, with the shape left to that quest. Once - the model records arrivals per track bounded by the subscription's - grace, it may own the grace timer itself, so a plain `finish_at` on a - received track could be enough and no settle handle is needed. - - Tail arrivals landed the record (`TrackState::arrivals`) without a - timer: the model folds a gap only on a write, so the session still - settles the tail with `set_tail_pending(false)`. The shape is this - quest's to settle. -- **Session end** (`track::Producer::close`, `abort_session`; both - subscribers): public. Fold `abort_session` into the public `abort` (abort - open groups too) unless the implementer finds a reader-visible difference, - and expose `close` as "end without declaring an end, so a reader resumes - from another route". -- **Resolved start** (`track::Request::resolving_start`, - `track::Producer::request_start`; both subscribers): replace with one - public way to accept a request whose start the peer resolves later. It - must be set before any reader sees the track, so it lives on - `track::Request` (for example a pre-accept `request_start(floor)`), with - the public `start_at` resolving it. - Decided 2026-10-19 by the maintainer (#5862): the same shape must let a - lazily served relay track be accepted with content it already holds, so - no reader observes it accepted but empty and IETF SUBSCRIBE_OK never omits - Largest Location. Accept it idle (the `Feed::Idle` gate `poll_live` - already waits on), let the caller write its retained groups, then go - live. Not a closure: #5862's `accept_with(info, |producer| …)` is - rejected, as callback parameters are. Fix the IETF subscriber's own - TRACK_STATUS `accept` → `set_idle` race with it. Regression test: accept, - replay a retained group on the same task, and SUBSCRIBE_OK carries - Largest Location on a multi-thread runtime over many runs. -- **Idle copy** (`track::Producer::set_idle`, `set_live`, `is_live`, - `idle_newest`, `track::IDLE_LINGER`, `poll_past`; lite subscriber, - `set_idle`, `set_live`, and `poll_past` also IETF). They keep a lingering copy's cache from serving stale groups - between subscriptions. **Decision**: - - ✅ Stay private, marked as a known capability gap rather than tuning: - the staleness they prevent is observable, so "tunes the built-in - sessions" does not fit. A custom subscriber that ends its track when - its upstream subscription ends is correct, but cannot keep a lingering - copy. When designing the resolved start below, check whether idle folds - into it (re-subscribing a lingering copy is a request whose start the - peer resolves later); if it does, the gap closes there. - - Public as an idle handle whose `live(largest)` resumes readers. - - `track::Producer::poll_past` (IETF resume: a group past the answer's - Largest marks the copy live) belongs to this item and shares its fate: - private while the idle copy is, public only with it. Fix it either way: - it reads `max_sequence`, which a frameless group header advances, so it - must wait for a later group that has started (a frame landed or it - ended), the gating rule above. -- Fetch ingest (`group::Request` fields `state` and `result`, - `track::TrackState`, `track::FetchOutcome`, `finish_track_at`, - `poll_landed`): moved to [the deferred quest](/quest/m1/public-model/deferred.md), - which waits on Model ranges. -- `track::Info::unchecked` (JS `Info.unchecked`, `@internal`) marks a - track whose timestamps arrived over moq-transport, so no group is checked - and moq-lite serves it untimed. A custom session's copies stay checked; - expose it with the other ingest calls only if one must ingest arrival - times. -- Passthrough, stay private and marked: `group::Producer::wire`, - `set_wire`, `mark_gap`, `set_end_object`, `group::Wire`, the `object` and - `datagram` modules, `track::Producer::insert_wire_datagram`, - `frame::Header`. -- Test-only: `track::Producer::new`, `publisher_priority`, `start_sequence`, - `group::Producer::is_aborted`, `is_finished`, `group::Info::produce`, - `track::Info::timed` (see the epic). - -JS items (`js/net/src/`): mirror each Rust decision under the same name. - -- `hooks.endTrack` (`internal.ts`, IETF subscriber; the JS - `finish_at_pending`): moved to the deferred quest, which waits on JS - pending tail. -- `hooks.pendingTrackProducer` (IETF subscriber) reaches the producer behind - an unaccepted request so objects landing before SUBSCRIBE_OK are kept. - Replace it with the resolved-start shape above: the request is accepted - with its start pending, so early data has a public producer to land in. -- `Group.Producer.mirror` (`@internal`, lite subscriber fetch coalescing): - moved to the deferred quest, which waits on Model ranges and JS track - handover. -- `internal.ts` `finalSequence` (IETF subscriber) is public with the serving - quest's `Position::final_sequence`. -- `tail.ts` `Tail` and `TAIL_GRACE_MS`, `consume.ts` `BroadcastCache`: stay - private. They are session plumbing in both languages (Rust's `tail.rs` and - consume cache sit outside `model/`). - -Tests: each public call gets a mock-time test in its language, and the -built-in subscribers move onto the public calls, so their existing suites -cover the behavior. - -## Closes - -- [#5862](https://github.com/moq-dev/moq/issues/5862) - no way to accept a track::Request with content - -## Related - -- [Public model after ranges, handover, and the JS tail](/quest/m1/public-model/deferred.md) - the fetch ingest, `mirror`, and `endTrack` items split out of this quest diff --git a/quest/m2/perf/ingest-batch.md b/quest/m2/perf/ingest-batch.md index 3714694ee29..2d7dfd1db53 100644 --- a/quest/m2/perf/ingest-batch.md +++ b/quest/m2/perf/ingest-batch.md @@ -2,7 +2,7 @@ ## Goal -Relay ingest pays two group lock acquisitions (`create_frame_owned`, then +Relay ingest pays two group lock acquisitions (`create_object`, then `frame_commit`), a waiter-list wake, and a clock read for every received frame. A frame's payload chunks are already amortized per poll, but a burst of small whole frames is not. Egress is already amortized (the `Prefetch` @@ -24,7 +24,7 @@ Where the path stands: - The batched machinery exists but is unused here: `group::Producer::write_frames` takes a `frame::Buffer` and pays one lock per batch, while the ingest path (lite's `FrameIngest`, the IETF - subscriber's object loop) creates each frame through `create_frame_owned` + subscriber's object loop) creates each frame through `create_object` instead. The `group_write_frames` bench in `rs/moq-net/benches/group.rs` compares the two as `single` against `batch32`, a `frame::Buffer::<32>` flushed through `write_frames`; take the before number from there. @@ -35,7 +35,7 @@ are already amortized): - Where whole frames are available in one poll turn, feed them through `write_frames`/`frame::Buffer` instead of frame-at-a-time creation. This is the larger half: a small frame that arrives whole still pays a - `create_frame_owned` plus a `frame_commit`, two lock acquisitions where the + `create_object` plus a `frame_commit`, two lock acquisitions where the batch API pays one for the whole burst. - The per-chunk `stats` bumps on the same loop, which `write` still pays individually. diff --git a/rs/hang/src/container/frame.rs b/rs/hang/src/container/frame.rs index 8b7c16d8af8..560f1132947 100644 --- a/rs/hang/src/container/frame.rs +++ b/rs/hang/src/container/frame.rs @@ -92,28 +92,19 @@ impl Frame { /// Write the frame to `group` as a single moq-lite frame, in the [`Self::encode`] format. /// - /// Prefer this over [`Self::encode`] when writing to a group: it streams the header and - /// payload as separate chunks rather than copying the payload into one buffer, and stamps - /// the moq-net frame timestamp so moq-lite-05 and later can delta-encode it on the wire - /// independently of the container-level prefix. + /// Prefer this over [`Self::encode`] when writing to a group: it stamps the moq-net frame + /// timestamp so moq-lite-05 and later can delta-encode it on the wire independently of the + /// container-level prefix. pub fn write_to(&self, group: &mut moq_net::group::Producer) -> Result<(), Error> { - let mut header = BytesMut::new(); - self.encode_header(&mut header)?; - let header = header.freeze(); + // The header and payload share one buffer: a frame written in chunks is copied into + // one anyway, so building it here costs the same copy. + let mut buf = BytesMut::with_capacity(8 + self.payload.len()); + self.encode_header(&mut buf)?; + buf.extend_from_slice(&self.payload); - let size = (header.len() + self.payload.len()) as u64; - - // `create_frame` converts the timestamp into the track's timescale; older drafts + // `write_frame` converts the timestamp into the track's timescale; older drafts // simply don't put it on the wire. - let info = moq_net::frame::Info { - size, - timestamp: Some(self.timestamp), - }; - let mut chunked = group.create_frame(info)?; - chunked.write(header)?; - chunked.write(self.payload.clone())?; - chunked.finish()?; - + group.write_frame(self.timestamp, buf.freeze())?; Ok(()) } diff --git a/rs/moq-ffi/src/test.rs b/rs/moq-ffi/src/test.rs index 1a1ff215d64..2917ee817bb 100644 --- a/rs/moq-ffi/src/test.rs +++ b/rs/moq-ffi/src/test.rs @@ -1819,14 +1819,9 @@ fn write_legacy(group: &mut moq_net::group::Producer, transport_us: u64, media_u } fn write_raw(group: &mut moq_net::group::Producer, transport_us: u64, payload: bytes::Bytes) { - let mut frame = group - .create_frame(moq_net::frame::Info { - size: payload.len() as u64, - timestamp: Some(moq_net::Timestamp::from_micros(transport_us).unwrap()), - }) + group + .write_frame(moq_net::Timestamp::from_micros(transport_us).unwrap(), payload) .unwrap(); - frame.write(payload).unwrap(); - frame.finish().unwrap(); } /// A broadcast with one legacy-container track, and a raw consumer subscribed to it. diff --git a/rs/moq-mux/src/container/fmp4/export_test.rs b/rs/moq-mux/src/container/fmp4/export_test.rs index e88d2732f66..277f72226a5 100644 --- a/rs/moq-mux/src/container/fmp4/export_test.rs +++ b/rs/moq-mux/src/container/fmp4/export_test.rs @@ -2190,14 +2190,9 @@ async fn cmaf_source_exports_at_the_frame_timestamp() { let fragment = super::encode_fragment(info, &samples).unwrap(); let mut group = track.append_group().unwrap(); - let mut frame = group - .create_frame(moq_net::frame::Info { - size: fragment.len() as u64, - timestamp: Some(moq_net::Timestamp::from_secs(10).unwrap()), - }) + group + .write_frame(moq_net::Timestamp::from_secs(10).unwrap(), fragment) .unwrap(); - frame.write(fragment).unwrap(); - frame.finish().unwrap(); group.finish().unwrap(); track.finish().unwrap(); diff --git a/rs/moq-mux/src/container/fmp4/import.rs b/rs/moq-mux/src/container/fmp4/import.rs index a383e9eebe5..881fd9fd8fd 100644 --- a/rs/moq-mux/src/container/fmp4/import.rs +++ b/rs/moq-mux/src/container/fmp4/import.rs @@ -1221,12 +1221,7 @@ impl Passthrough { self.estimator.cut(Some(timestamp)); } let fragment_len = fragment.len(); - let mut frame = group.create_frame(moq_net::frame::Info { - size: fragment_len as u64, - timestamp: Some(timestamp), - })?; - frame.write(fragment)?; - frame.finish()?; + group.write_frame(timestamp, fragment)?; // Only once published, so a rejected fragment is never indexed. Audio is always // independently decodable; video says whether this fragment really begins on an IDR, diff --git a/rs/moq-mux/src/container/fmp4/mod.rs b/rs/moq-mux/src/container/fmp4/mod.rs index f7202402b35..c0aa07bdee5 100644 --- a/rs/moq-mux/src/container/fmp4/mod.rs +++ b/rs/moq-mux/src/container/fmp4/mod.rs @@ -613,12 +613,7 @@ fn encode(group: &mut moq_net::group::Producer, frames: &[Frame], info: Fragment let timestamp = Timestamp::new(timestamp_ticks(earliest, info.timescale)?, info.timescale)?; let bytes = encode_fragment(info, frames)?; - let mut writer = group.create_frame(moq_net::frame::Info { - size: bytes.len() as u64, - timestamp: Some(timestamp), - })?; - writer.write(bytes)?; - writer.finish()?; + group.write_frame(timestamp, bytes)?; Ok(()) } diff --git a/rs/moq-mux/src/container/loc/mod.rs b/rs/moq-mux/src/container/loc/mod.rs index 2d42df2072d..16b53cc5dd1 100644 --- a/rs/moq-mux/src/container/loc/mod.rs +++ b/rs/moq-mux/src/container/loc/mod.rs @@ -31,12 +31,7 @@ impl Container for Wire { // Carry the timestamp on the net frame too (converted to the track's // timescale), so a relay sees it without parsing the LOC payload. - let mut chunked = group.create_frame(moq_net::frame::Info { - size: data.len() as u64, - timestamp: Some(frame.timestamp), - })?; - chunked.write(data)?; - chunked.finish()?; + group.write_frame(frame.timestamp, data)?; } Ok(()) } diff --git a/rs/moq-net/Cargo.toml b/rs/moq-net/Cargo.toml index ae52af6e34b..3be1efaaaae 100644 --- a/rs/moq-net/Cargo.toml +++ b/rs/moq-net/Cargo.toml @@ -143,11 +143,10 @@ required-features = ["async"] name = "tracks" harness = false -# Declares a pending tail through the hidden `fuzz` module. [[bench]] name = "tail" harness = false -required-features = ["fuzz"] +required-features = ["async"] [[bench]] name = "priority" diff --git a/rs/moq-net/MIGRATE.md b/rs/moq-net/MIGRATE.md index 6023c18cb9e..f60898f5f5a 100644 --- a/rs/moq-net/MIGRATE.md +++ b/rs/moq-net/MIGRATE.md @@ -4,6 +4,56 @@ How to update your code for each breaking change, newest first. ## Unreleased +### Stage a requested track before subscribers see it (#6111) + +`track::Request::stage(info)` returns a `track::Staged` that derefs to the track's `Producer` while subscribers waiting on the request stay pending; `commit()` publishes it with everything written so far and returns the `Producer`. +A relay that holds groups of a lazily served track writes them before committing, so the first reader (and an IETF `SUBSCRIBE_OK`'s Largest Location) sees them. +Dropping a `Staged` uncommitted rejects the request with `Error::Dropped`. `accept(info)` is unchanged and equals `stage(info).commit()`. + +```rust +let mut staged = request.stage(info); +for group in retained { /* staged.create_group(..), write, finish */ } +let producer = staged.commit(); +``` + +### Frame writers own their group (#6111) + +`group::Producer::create_frame` now takes the writer by value and returns an owned `frame::Producer` with no lifetime. +`frame::Producer::finish` hands the group writer back, and `frame::Producer::group()` returns `&group::Producer` instead of a `group::Info` copy. +A frame the group refuses (closed, or past its size) now aborts the group. + +```rust +// Before +let mut frame = group.create_frame(info)?; +frame.write(payload)?; +frame.finish()?; +// After +let mut frame = group.create_frame(info)?; +frame.write(payload)?; +group = frame.finish()?; +``` + +A caller that holds the group behind `&mut` can write a whole frame with `write_frame` instead. + +### A received track's end waits for groups in flight (#6111) + +Call `track::Producer::received()` before writing what a peer sends into a track, then declare the peer's end with `finish_at`. +On a received copy, readers wait at a hole below that end for the subscription's max delay (or one second) in case its group is still in flight; `drop_groups(range, err)` marks groups the peer said it skipped, so readers stop waiting for them and a group still arriving there ends with `err`. +`finish_at` now accepts a repeat of the same end and a refinement within the last group; any other second end fails with `Error::ProtocolViolation`. + +`track::Request::request_start(floor)` leaves an accepted copy's start pending at `floor` until `track::Producer::start_at` resolves it, for a subscriber whose peer reports the start after accepting. + +### A frameless group is not the live edge (#6111) + +Every group reaches readers as soon as it is created, but the live edge, `largest()`, and the judgment of whether a group was succeeded count a group only once its first frame opens or it finishes. +A group followed by a frameless one is judged against the next group that has a frame. + +### Ending a track aborts its open groups (#6111) + +Aborting a track (`abort` or `abort_unused`) now aborts its unfinished groups with the same error, so their readers end with it and their writers fail. +Dropping the last `track::Producer` without a finish aborts them with `Error::Dropped`, and `close` with `Error::SessionClosed`. +`track::Producer::close`, `track::Producer::received`, and `group::Producer::info` are now public. + ### Priorities are signed, with 0 unset (#6142) `track::Info::priority`, `track::Subscription::priority`, `group::Fetch::priority`, and `group::Request::priority()` are `i8`, higher first, and 0 is the unset midpoint. diff --git a/rs/moq-net/benches/tail.rs b/rs/moq-net/benches/tail.rs index 4c76c9325be..3ca1d3ca13a 100644 --- a/rs/moq-net/benches/tail.rs +++ b/rs/moq-net/benches/tail.rs @@ -5,7 +5,7 @@ //! check is judged by the track's record of arrivals, so a cost that grows with the groups //! cached or the tracks held shows up as a slope over either axis. //! -//! Run with `cargo bench -p moq-net --features fuzz --bench tail`. +//! Run with `cargo bench -p moq-net --bench tail`. use std::{hint::black_box, task::Poll, time::Duration}; @@ -38,7 +38,8 @@ impl Held { track.subscribe(track::Subscription::default().with_max_delay(Duration::from_secs(3600))); track.start_at(0).unwrap(); let end = track::Position::group(groups as u64 + 1); - moq_net::fuzz::finish_at_pending(&mut track, end).unwrap(); + track.received(); + track.finish_at(end).unwrap(); // Group 0 never arrives: the hole that holds the reader. for sequence in 1..=groups as u64 { track.create_group(group::Info { sequence }).unwrap().finish().unwrap(); diff --git a/rs/moq-net/src/coding/reader.rs b/rs/moq-net/src/coding/reader.rs index d61f6f411e8..4c8da6624c3 100644 --- a/rs/moq-net/src/coding/reader.rs +++ b/rs/moq-net/src/coding/reader.rs @@ -211,14 +211,14 @@ impl Reader { /// hands over everything it has already buffered in one turn, and each wake pays a /// group lock and a clock read, so the intermediate ones mostly publish bytes the /// consumer is about to be handed anyway. Pairing the deferred - /// [`frame::ProducerOwned::write`] with its wake is this function's job precisely + /// [`frame::Producer::write_deferred`] with its wake is this function's job precisely /// because it owns the only `Pending` it can return; the other two exits are woken /// by the caller's `finish` (which stamps and publishes the frame) or `abort` (which /// fails the group). [`WAKE_BUDGET`] bounds the wait in between. pub(crate) fn poll_read_frame( &mut self, cx: &mut Context<'_>, - frame: &mut crate::frame::ProducerOwned, + frame: &mut crate::frame::Producer, ) -> Poll> { let mut owed = 0; @@ -236,7 +236,7 @@ impl Reader { } Poll::Ready(Ok(Some(chunk))) if !chunk.is_empty() => { owed += chunk.len(); - if let Err(err) = frame.write(chunk) { + if let Err(err) = frame.write_deferred(chunk) { break Err(err); } if owed >= WAKE_BUDGET { @@ -423,7 +423,7 @@ mod tests { fn parked_frame( size: usize, ) -> ( - crate::frame::ProducerOwned, + crate::frame::Producer, crate::frame::Consumer, kio::Waiter, Arc, @@ -431,13 +431,10 @@ mod tests { let group = crate::group::Info { sequence: 0 }.produce(); let mut consumer = group.consume(); let frame = group - .create_frame_owned( - crate::frame::Info { - size: size as u64, - timestamp: Some(crate::Timestamp::ZERO), - }, - &Default::default(), - ) + .create_frame(crate::frame::Info { + size: size as u64, + timestamp: Some(crate::Timestamp::ZERO), + }) .unwrap(); let payload = consumer.next_frame().now_or_never().unwrap().unwrap().unwrap(); diff --git a/rs/moq-net/src/fuzz.rs b/rs/moq-net/src/fuzz.rs index 60fc8c4a6cc..720a9fad46c 100644 --- a/rs/moq-net/src/fuzz.rs +++ b/rs/moq-net/src/fuzz.rs @@ -65,7 +65,7 @@ pub fn object_group(frames: usize, properties: bool) -> (broadcast::Producer, tr fields, inflated: None, }; - let mut frame = group.create_frame_owned(header, &frame::Budget::default()).unwrap(); + let mut frame = group.create_object(header).unwrap(); frame.write(payload.clone()).unwrap(); group = frame.finish().unwrap(); } @@ -73,12 +73,6 @@ pub fn object_group(frames: usize, properties: bool) -> (broadcast::Producer, tr (broadcast, track, group) } -/// Declare a received track's end while the wire may still owe groups below it, as a -/// subscriber does on SUBSCRIBE_END, for the pending-tail benchmark. -pub fn finish_at_pending(track: &mut track::Producer, end: track::Position) -> crate::Result<()> { - track.finish_at_pending(end) -} - /// Every target, keyed by the name of its `fuzz_targets/.rs` shim. pub const TARGETS: &[(&str, Target)] = &[ ("lite", lite_wire), @@ -1207,7 +1201,7 @@ pub fn seeds() -> Vec { /// every declared size when the first byte lands and `Some(0)` grows every buffer with /// the bytes received. pub struct FrameRecv { - streams: Vec, frame::ProducerOwned)>>, + streams: Vec, frame::Producer)>>, // Keeps the groups' track alive. _track: track::Producer, _broadcast: broadcast::Producer, @@ -1220,6 +1214,7 @@ impl FrameRecv { // Unbounded, so eviction never aborts a group mid-frame. let mut info = broadcast::Info::new(); info.pool = cache::Pool::unbounded(); + info.frames = budget.map(frame::Budget::new).unwrap_or_default(); let broadcast = info.produce(); let track = broadcast .create_track( @@ -1227,7 +1222,6 @@ impl FrameRecv { crate::track::Info::default().with_timescale(crate::Timescale::MILLI), ) .unwrap(); - let budget = budget.map(frame::Budget::new).unwrap_or_default(); let payload = bytes::Bytes::from(vec![0u8; size]); let streams = (0..streams) @@ -1237,7 +1231,7 @@ impl FrameRecv { size: size as u64, timestamp: Some(crate::Timestamp::ZERO), }; - let frame = group.create_frame_owned(info, &budget).unwrap(); + let frame = group.create_frame(info).unwrap(); let stream = Chunks { payload: payload.clone(), chunk, diff --git a/rs/moq-net/src/ietf/object.rs b/rs/moq-net/src/ietf/object.rs index 2445f7b7ffc..3853f24194e 100644 --- a/rs/moq-net/src/ietf/object.rs +++ b/rs/moq-net/src/ietf/object.rs @@ -884,10 +884,7 @@ mod compression_tests { fields: None, inflated: inflated(Some(crate::group::MAX_CACHE_BYTES + 1), true).unwrap(), }; - assert!(matches!( - group.create_frame_owned(header, &crate::frame::Budget::default()), - Err(Error::FrameTooLarge) - )); + assert!(matches!(group.create_object(header), Err(Error::FrameTooLarge))); } fn property(id: u64, value: u64) -> Property { diff --git a/rs/moq-net/src/ietf/publisher.rs b/rs/moq-net/src/ietf/publisher.rs index d697db48076..0bca2db91b2 100644 --- a/rs/moq-net/src/ietf/publisher.rs +++ b/rs/moq-net/src/ietf/publisher.rs @@ -6406,7 +6406,7 @@ mod group_priority_test { crate::track::Info::timed(), ); let mut subscriber = track.subscribe(None); - let mut old = track.append_group().unwrap(); + let old = track.append_group().unwrap(); let mut frame = old .create_frame(frame::Info { timestamp: Some(crate::Timestamp::ZERO), @@ -6440,8 +6440,7 @@ mod group_priority_test { *open = false; drop(open); frame.write(b"b".as_slice()).unwrap(); - frame.finish().unwrap(); - old.finish().unwrap(); + frame.finish().unwrap().finish().unwrap(); assert!( futures::poll!(serving.as_mut()).is_pending(), "the final byte is transport-blocked" @@ -7244,7 +7243,7 @@ mod serve_tests { /// inside it and the group stream waits for object 1. async fn fail_update_mid_flight(version: Version) -> Wire { let h = serve(version); - let mut group = h.track.create_group(group::Info { sequence: 0 }).unwrap(); + let group = h.track.create_group(group::Info { sequence: 0 }).unwrap(); let mut frame = group .create_frame(frame::Info { timestamp: Some(timestamp()), @@ -7275,7 +7274,6 @@ mod serve_tests { .expect("the failed update ends the subscription") .ok(); drop(frame); - drop(group); let wire = Wire::read(&h.log, version); let error = wire @@ -16421,6 +16419,37 @@ mod range_tests { ); } + /// A relay holding groups of a requested track stages them before committing, so the + /// Largest Location that SUBSCRIBE_OK snapshots as soon as the subscribe resolves always + /// names the replayed group (#5862). Raced on real threads, many times. + #[test] + fn subscribe_ok_reports_a_staged_replay() { + for _ in 0..500 { + let broadcast = crate::broadcast::Info::new().produce(); + let request = broadcast.reserve_track("video").unwrap(); + let cache = broadcast.consume().track("video").unwrap(); + let snapshot = std::thread::spawn(move || { + futures::executor::block_on(async { + let mut track = cache.subscribe(None).await.unwrap(); + kio::wait(|waiter| track.poll_live(waiter)).await; + live_edge(&cache).largest + }) + }); + let staged = request.stage(crate::track::Info::timed()); + for sequence in 0..3 { + let mut group = staged.create_group(group::Info { sequence }).unwrap(); + for _ in 0..2 { + group + .write_frame(crate::Timestamp::from_millis(sequence).unwrap(), b"frame".as_slice()) + .unwrap(); + } + group.finish().unwrap(); + } + let _track = staged.commit(); + assert_eq!(snapshot.join().unwrap(), Some(Location { group: 2, object: 1 })); + } + } + /// Group numbering may legally skip sequences, so the walk follows the cache's own /// order rather than decrementing by one. #[test] diff --git a/rs/moq-net/src/ietf/subscriber.rs b/rs/moq-net/src/ietf/subscriber.rs index 2dbe854771a..037ebc96c13 100644 --- a/rs/moq-net/src/ietf/subscriber.rs +++ b/rs/moq-net/src/ietf/subscriber.rs @@ -187,14 +187,14 @@ impl State { request.reject(err.clone()); } if let Some(producer) = track.producer { - let _ = producer.abort_session(err.clone()); + let _ = producer.abort(err.clone()); } if let Fill::Ready { producer, .. } = &*track.fill.read() { let _ = producer.handle().abort(err.clone()); } } for (_, producer) in self.lingering.drain() { - let _ = producer.abort_session(err.clone()); + let _ = producer.abort(err.clone()); } } fn close(&mut self) { @@ -777,8 +777,6 @@ pub(super) struct Subscriber { going_away: crate::goaway::GoingAway, // Our grant (MoQ Auth): a subscription it stops covering is cancelled. auth: crate::auth::Handle, - // What this session may allocate up front for objects still arriving. - frames: frame::Budget, // Namespaces the peer may have announced at once (`session::Limits::announces`). pub(super) announces: crate::session::Slots, } @@ -860,7 +858,8 @@ where Self { runtime, session, - origin, + // Its own frame budget, so a peer's declared sizes crowd out no other session. + origin: origin.with_own_frames(), control, session_origin: peer_hop.unwrap_or(crate::Hop::UNKNOWN), self_origin, @@ -872,7 +871,6 @@ where version, going_away, auth: crate::auth::Handle::new(false), - frames: Default::default(), announces: Default::default(), validity: Default::default(), epoch: None, @@ -3062,6 +3060,9 @@ where frame: largest.object, }) }); + // A fresh copy is staged until the answer is written in below, so no reader sees it + // before its Largest and start. + let mut staged = None; let (mut track, dynamic) = match resumed { Some(idle) => { if !self.state.lock().subscribes.contains_key(&request_id) { @@ -3076,23 +3077,19 @@ where self.remove_subscribe(request_id); return None; }; - let request = match live { - true => request.resolving_start(), - false => request, - }; + // Pending until the answer is written in below, so a relay serving the copy + // never reads the requested floor as where the feed starts. + let request = request.request_start(start.map(|start| start.group)); // Serves cache misses with a group FETCH. Registered before accepting, so a // miss queued meanwhile waits for it rather than failing for want of a handler. let dynamic = request.dynamic(); - (request.accept(info), dynamic) + let copy = request.stage(info); + let track = track::Producer::clone(©); + staged = Some(copy); + (track, dynamic) } }; - // A live join starts at the publisher's edge; an absolute one where it asked. With - // no Largest the join skips nothing, so every group is owed: a lower one's stream - // may still arrive after a higher one's. - let _ = match live { - true => track.start_at(largest.map_or(0, |largest| largest.group)), - false => track.start_at(start.map(|start| start.group)), - }; + track.received(); // Object IDs can start past zero or skip, while readers see frame ordinals, so only // the group carries over: its first frame is the edge a reader can count on. if let Some(largest) = largest { @@ -3101,6 +3098,16 @@ where frame: 0, }); } + // A live join starts at the publisher's edge; an absolute one where it asked. With + // no Largest the join skips nothing, so every group is owed: a lower one's stream + // may still arrive after a higher one's. This resolves the pending start. + let _ = match live { + true => track.start_at(largest.map_or(0, |largest| largest.group)), + false => track.start_at(start.map(|start| start.group)), + }; + if let Some(staged) = staged { + staged.commit(); + } let mut fetching: Option = None; { let mut state = self.state.lock(); @@ -3336,9 +3343,8 @@ where fill.end(); } } - // The tail settled, so readers may end at an END_OF_TRACK's boundary. - track.set_tail_pending(false); - // A no-op once an END_OF_TRACK declared the end. + // A no-op once an END_OF_TRACK declared the end, whose readers wait + // for a missing group only as long as the grace. let _ = track.finish(); } Err(err) => { @@ -4004,9 +4010,10 @@ where tracing::debug!(broadcast = %self.origin.absolute(broadcast_path), track = %track_name, "track status known"); let dynamic = request.dynamic(); - let mut track = request.accept(accepted_info(&ok.properties, self.version)); - // Nothing feeds this copy live: what it caches is fetched, never the live edge. - track.set_idle(); + // Nothing feeds this copy live: what it caches is fetched, never the live edge. Idle + // from the accept, so no reader takes it as live in between. + let track = request.idle().accept(accepted_info(&ok.properties, self.version)); + track.received(); Some(Idle { demand: track.demand(), track, @@ -4303,8 +4310,9 @@ fn end_track(track: &mut track::Producer, end: track::Position, properties: bool let _ = track.clone().abort(Error::Unsupported); return Err(Error::Unsupported); } - // Lower groups may still be on the wire, behind the one that carried the end. - if let Err(err) = track.finish_at_pending(end) { + // Lower groups may still be on the wire, behind the one that carried the end: the + // received copy holds readers at a hole for the grace. + if let Err(err) = track.finish_at(end) { tracing::warn!(%err, ?end, "invalid END_OF_TRACK"); let _ = track.clone().abort(Error::ProtocolViolation); return Err(Error::ProtocolViolation); @@ -4569,7 +4577,6 @@ struct GroupIngest { /// The object being read is one the group started past, so it is read and dropped. dropping: bool, phase: IngestPhase, - budget: frame::Budget, } enum IngestPhase { @@ -4584,7 +4591,7 @@ enum IngestPhase { /// Reading the status of an empty object. Status { timestamp: Option }, /// Streaming the object payload. - Payload { frame: frame::ProducerOwned }, + Payload { frame: frame::Producer }, /// Discarding a dropped object's payload: the bytes of it still to read. Skip { size: usize }, /// An explicit end-of-group or end-of-track status arrived. @@ -4610,7 +4617,6 @@ impl GroupIngest { inflated: None, dropping: false, phase: IngestPhase::Delta, - budget: subscriber.frames.clone(), } } } @@ -4992,7 +4998,7 @@ where fields, inflated: super::object::inflated(decoded.inflated, producer.compressed())?, }; - let mut frame = producer.create_frame_owned(header, &self.frames)?; + let mut frame = producer.create_object(header)?; if let Err(err) = std::future::poll_fn(|cx| stream.poll_read_frame(cx, &mut frame)).await { let _ = frame.abort(err.clone()); return Err(err); @@ -5812,12 +5818,12 @@ impl GroupIngest { self.phase = IngestPhase::Skip { size }; continue; } - // `create_frame_owned` is the allocation chokepoint: it rejects an - // oversized `size` and allocates up front only within the budget, so - // no pre-check is needed. + // `create_object` is the allocation chokepoint: it rejects an oversized + // `size` and allocates up front only within the origin's budget, so no + // pre-check is needed. let timestamp = object_time(self.timescale, *timestamp)?; let header = self.header(group, frame::Info { size, timestamp })?; - let frame = group.create_frame_owned(header, &self.budget)?; + let frame = group.create_object(header)?; self.phase = IngestPhase::Payload { frame }; } IngestPhase::Status { timestamp } => { @@ -5826,7 +5832,7 @@ impl GroupIngest { if !self.dropping { let timestamp = object_time(self.timescale, *timestamp)?; let header = self.header(group, frame::Info { size: 0, timestamp })?; - let frame = group.create_frame_owned(header, &self.budget)?; + let frame = group.create_object(header)?; group.restore(frame.finish()?); } self.phase = IngestPhase::Delta; diff --git a/rs/moq-net/src/model/ledger.rs b/rs/moq-net/src/ledger.rs similarity index 98% rename from rs/moq-net/src/model/ledger.rs rename to rs/moq-net/src/ledger.rs index 85de2455a08..ab6be5a69c8 100644 --- a/rs/moq-net/src/model/ledger.rs +++ b/rs/moq-net/src/ledger.rs @@ -12,12 +12,10 @@ use crate::time::Instant; /// /// Bounds the wait on IETF, and on moq-lite when the subscription has no max delay to bound /// it with. Matches `@moq/net`, so a reader cannot tell which side it is talking to. -// pending: /quest/m1/public-model/ingest.md pub(crate) const GRACE: Duration = Duration::from_secs(1); /// The grace for a subscription with `max_delay`: how long the subscriber was willing to /// wait for a late group anyway, or [`GRACE`] without one. -// pending: /quest/m1/public-model/ingest.md pub(crate) fn grace(max_delay: Duration) -> Duration { match max_delay.is_zero() { true => GRACE, @@ -35,7 +33,6 @@ struct Run { /// The sequences accounted for, and how late each gap between them is. #[derive(Debug)] -// pending: /quest/m1/public-model/ingest.md pub(crate) struct Ledger { // Disjoint, sorted, non-adjacent runs of accounted sequences. A gap older than the grace // can no longer be waited for, so it folds into the runs around it, which bounds this by @@ -114,6 +111,11 @@ impl Ledger { self.runs.first().map(|run| run.groups.start) } + /// One past the highest sequence accounted for. + pub fn end(&self) -> Option { + self.runs.last().map(|run| run.groups.end) + } + /// The exclusive end of the accounted run holding `sequence`, `None` while it is not. pub fn run_end(&self, sequence: u64) -> Option { let run = self diff --git a/rs/moq-net/src/lib.rs b/rs/moq-net/src/lib.rs index b7388952407..61865593607 100644 --- a/rs/moq-net/src/lib.rs +++ b/rs/moq-net/src/lib.rs @@ -99,6 +99,7 @@ pub mod goaway; #[doc(hidden)] pub mod fuzz; mod ietf; +mod ledger; mod lite; mod model; pub mod path; diff --git a/rs/moq-net/src/lite/ietf.rs b/rs/moq-net/src/lite/ietf.rs index e1541398bb0..83b88b2843a 100644 --- a/rs/moq-net/src/lite/ietf.rs +++ b/rs/moq-net/src/lite/ietf.rs @@ -1105,17 +1105,14 @@ mod hop_tests { payload: &[u8], ) -> group::Producer { let mut frame = group - .create_frame_owned( - frame::Header { - info: frame::Info { - size: payload.len() as u64, - timestamp: Some(ts(millis)), - }, - fields: fields.map(Arc::new), - inflated: None, + .create_object(frame::Header { + info: frame::Info { + size: payload.len() as u64, + timestamp: Some(ts(millis)), }, - &frame::Budget::default(), - ) + fields: fields.map(Arc::new), + inflated: None, + }) .unwrap(); frame.write(Bytes::copy_from_slice(payload)).unwrap(); frame.finish().unwrap() diff --git a/rs/moq-net/src/lite/publisher.rs b/rs/moq-net/src/lite/publisher.rs index 168aff54b6e..0b4a3aa7909 100644 --- a/rs/moq-net/src/lite/publisher.rs +++ b/rs/moq-net/src/lite/publisher.rs @@ -5021,7 +5021,7 @@ mod serve_group_test { crate::track::Info::timed(), ); let mut subscriber = track.subscribe(None); - let mut old = track.append_group().unwrap(); + let old = track.append_group().unwrap(); let mut frame = old .create_frame(frame::Info { timestamp: Some(Timestamp::ZERO), @@ -5044,8 +5044,7 @@ mod serve_group_test { *open = false; drop(open); frame.write(b"b".as_slice()).unwrap(); - frame.finish().unwrap(); - old.finish().unwrap(); + frame.finish().unwrap().finish().unwrap(); assert!( futures::poll!(serve.as_mut()).is_pending(), "the final byte is transport-blocked" diff --git a/rs/moq-net/src/lite/subscriber.rs b/rs/moq-net/src/lite/subscriber.rs index f4d0dc49550..748a8426cca 100644 --- a/rs/moq-net/src/lite/subscriber.rs +++ b/rs/moq-net/src/lite/subscriber.rs @@ -86,8 +86,6 @@ pub(super) struct Subscriber { sources: kio::Queue, going_away: crate::goaway::GoingAway, auth: crate::auth::Handle, - /// What this session may allocate up front for frames still arriving. - frames: frame::Budget, /// Broadcasts the peer may have announced at once (`session::Limits::announces`). pub(super) announces: crate::session::Slots, } @@ -112,7 +110,8 @@ impl Subscriber { Self { session: config.session, runtime: config.runtime, - origin: config.origin, + // Its own frame budget, so a peer's declared sizes crowd out no other session. + origin: config.origin.with_own_frames(), recv_bandwidth: config.recv_bandwidth, self_origin, session_origin: config.peer_hop.unwrap_or(crate::Hop::UNKNOWN), @@ -126,7 +125,6 @@ impl Subscriber { sources: kio::Queue::new(), going_away: config.going_away, auth: config.auth, - frames: Default::default(), announces: Default::default(), } } @@ -576,7 +574,7 @@ impl SubscriptionCleanup { /// their cleanup independently; this records the track's terminal state. fn abort(&self, err: &Error) { for (_, entry) in self.0.lock().drain() { - let _ = entry.producer.abort_session(err.clone()); + let _ = entry.producer.abort(err.clone()); } } fn close(&self) { @@ -947,8 +945,6 @@ enum GroupRecvState { group: crate::recv::Group, track: track::Producer, ingest: FrameIngest, - /// Whether readers see the group yet; see [`track::Producer::receive_group`]. - shown: bool, _reading: Reading, }, Done, @@ -984,9 +980,9 @@ impl GroupRecv { let group_info = group::Info { sequence: hdr.sequence }; // Stats (groups/frames/bytes) are counted in the model as the group - // is written, through the tagged `track::Producer`. Withheld from - // readers until its first frame lands. - let received = entry.producer.receive_group(group_info); + // is written, through the tagged `track::Producer`. The track counts + // it as content once its first frame lands. + let received = entry.producer.create_group(group_info); // The subscription's end waits until this stream is read. Counted // whatever the cache said, since the publisher counts every stream it // opens (a resubscribe resends a cached group), and only after the @@ -1040,17 +1036,12 @@ impl GroupRecv { self.state = GroupRecvState::Serve { group: crate::recv::Group::new(group), track, - ingest: FrameIngest::new(&self.subscriber, framing, ietf, hdr.frame_start), - shown: false, + ingest: FrameIngest::new(framing, self.subscriber.version, ietf, hdr.frame_start), _reading: reading, }; } GroupRecvState::Serve { - group, - track, - ingest, - shown, - .. + group, track, ingest, .. } => { // The track or group dying cancels the stream; the peer's own close // arrives through the ingest's reads. @@ -1061,13 +1052,7 @@ impl GroupRecv { if let Poll::Ready(err) = group.handle().poll_closed(waiter) { break 'serve Err(err); } - let res = ingest.poll(&mut self.reader, group, waiter); - // Shown once its first frame opens, even mid-payload. - if !*shown && group.handle().is_started() { - track.reveal_group(group.handle()); - *shown = true; - } - match res { + match ingest.poll(&mut self.reader, group, waiter) { Poll::Ready(res) => break 'serve res, Poll::Pending => return Poll::Pending, } @@ -1077,16 +1062,13 @@ impl GroupRecv { // short drops into an already-aborted group instead of reporting a loss. let GroupRecvState::Serve { group, - track, ingest: _ingest, - shown, _reading, + .. } = std::mem::replace(&mut self.state, GroupRecvState::Done) else { unreachable!() }; - // A group that ended without a frame shows once it settles. - let handle = (!shown).then(|| group.handle().clone()); let res = match res { Ok(()) => { let _ = group.finish(); @@ -1102,9 +1084,6 @@ impl GroupRecv { Err(err) } }; - if let Some(handle) = handle { - track.reveal_group(&handle); - } return Poll::Ready(res); } GroupRecvState::Done => return Poll::Ready(Ok(())), @@ -1123,7 +1102,6 @@ struct FrameIngest { /// zigzag-delta decode. The first frame's delta is absolute (prev = 0). prev_ts: u64, phase: IngestPhase, - budget: frame::Budget, /// Where the stream's frames start, the first Object ID until a record names it. frame_start: u64, /// `Some` once the Group State of the `ietf` extension arrived: every frame follows an @@ -1172,17 +1150,12 @@ enum IngestPhase { inflated: Option, }, /// Streaming the frame payload. - Payload { frame: frame::ProducerOwned }, + Payload { frame: frame::Producer }, } impl FrameIngest { /// `ietf` when the session negotiated the extension, so the stream starts with a Group State. - fn new( - subscriber: &Subscriber, - framing: lite::Framing, - ietf: bool, - frame_start: u64, - ) -> Self { + fn new(framing: lite::Framing, version: Version, ietf: bool, frame_start: u64) -> Self { Self { framing, prev_ts: 0, @@ -1190,10 +1163,9 @@ impl FrameIngest { true => IngestPhase::State, false => IngestPhase::Timing, }, - budget: subscriber.frames.clone(), frame_start, records: None, - media_time: subscriber.version.has_media_time(), + media_time: version.has_media_time(), } } @@ -1358,20 +1330,16 @@ impl FrameIngest { } None => None, }; - // `create_frame_owned` is the allocation chokepoint: it rejects an - // oversized `size` and allocates up front only within the budget, so - // no pre-check is needed. No wire timestamp (pre-lite-05) means an - // untimed frame. - // A compressed frame stores the slice as it arrives, its inflated size - // checked against the same limits before anything inflates. - let frame = group.create_frame_owned( - frame::Header { - info: frame::Info { size, timestamp }, - fields, - inflated, - }, - &self.budget, - )?; + // `create_object` is the allocation chokepoint: it rejects an oversized + // `size` and allocates up front only within the origin's budget, so no + // pre-check is needed. No wire timestamp (pre-lite-05) means an untimed + // frame. A compressed frame stores the slice as it arrives, its inflated + // size checked against the same limits before anything inflates. + let frame = group.create_object(frame::Header { + info: frame::Info { size, timestamp }, + fields, + inflated, + })?; self.phase = IngestPhase::Payload { frame }; } IngestPhase::Payload { frame } => { @@ -2136,7 +2104,7 @@ mod tests { /// A group arriving at the relay as its header lands: cached, then accounted for. fn arrive(track: &track::Producer, tail: &kio::Producer, sequence: u64, now: crate::time::Instant) { - let mut group = track.receive_group(group::Info { sequence }).unwrap(); + let mut group = track.create_group(group::Info { sequence }).unwrap(); group.write_frame(None, &b"x"[..]).unwrap(); group.finish().unwrap(); let Ok(mut ledger) = tail.write() else { @@ -2221,7 +2189,7 @@ mod tests { let h = Harness::new(Version::Lite04); let (mut track, fetching, req) = feed_fetch(3); for sequence in [5, 6] { - let mut group = track.receive_group(group::Info { sequence }).unwrap(); + let mut group = track.create_group(group::Info { sequence }).unwrap(); group.write_frame(None, &b"x"[..]).unwrap(); group.finish().unwrap(); } @@ -2264,7 +2232,7 @@ mod tests { "group 3 was asked for just now (update: {update})" ); - let mut group = track.receive_group(group::Info { sequence: 3 }).unwrap(); + let mut group = track.create_group(group::Info { sequence: 3 }).unwrap(); group.write_frame(None, &b"x"[..]).unwrap(); group.finish().unwrap(); fetches.poll(&sub, now, &kio::Waiter::noop()); @@ -3243,7 +3211,7 @@ mod tests { "video", crate::track::Info::timed(), ); - let mut cached = track.receive_group(group::Info { sequence: 3 }).unwrap(); + let mut cached = track.create_group(group::Info { sequence: 3 }).unwrap(); cached.write_frame(Timestamp::ZERO, &b"x"[..]).unwrap(); cached.finish().unwrap(); let tail = kio::Producer::new(Tail::default()); @@ -4531,7 +4499,7 @@ mod tests { let established = h.wire().len(); let arrive = |serving: &ServeLoop, sequence| { - let mut group = serving.serving.receive_group(group::Info { sequence }).unwrap(); + let mut group = serving.serving.create_group(group::Info { sequence }).unwrap(); for frame in [&b"key"[..], b"abc", b"d"] { group.write_frame(None, frame).unwrap(); } @@ -6269,11 +6237,6 @@ impl TrackServe { if subscription.start().is_none() { subscription.set_bounds(producer.idle_newest().map(Position::group), subscription.end()); } - // The track's arrivals outlive a subscription, and this one asks for - // its groups only now. - if let Some(start) = subscription.start() { - producer.demand_arrivals(start.group..u64::MAX); - } // Open an upstream SUBSCRIBE for the first subscriber. Ok(Begin::Establish(self.prepare_establish(producer, subscription))) } @@ -6284,15 +6247,13 @@ impl TrackServe { active.priority = subscription.priority; active.order = subscription.order; active.max_delay = subscription.max_delay; - // A lowered floor owes groups nobody asked for until now, in the track's - // arrivals that held fetches read as well as in the session's tail. + // A lowered floor owes groups nobody asked for until now, in the session's + // tail as well as in the track's arrivals, which its start declaration + // restarts. let lowered = subscription.start().map(|start| { let floor = active.start.map(|start| start.group).or(active.served); start.group..floor.unwrap_or(u64::MAX) }); - if let Some(groups) = &lowered { - producer.demand_arrivals(groups.clone()); - } if let Ok(mut tail) = active.tail.write() { tail.set_grace(tail::grace(subscription.max_delay)); if let Some(groups) = lowered { @@ -6741,7 +6702,6 @@ impl kio::Task for TrackServeRun { } }, ServeEnd::Finished => { - serve_loop.serving.set_tail_pending(false); let _ = serve_loop.serving.finish(); } ServeEnd::GiveBack(err) => { @@ -7136,10 +7096,11 @@ impl ServeLoop { // Lite-06+ resolves each subscription's start from its budget, so the floor // the SUBSCRIBE asks for is not where delivery begins until SUBSCRIBE_START says. let request = match serve.subscriber.version.resolves_start() { - true => request.resolving_start(), + true => request.request_start(None), false => request, }; let serving = request.accept(info); + serving.received(); Self { largest: None, demand: serving.demand(), @@ -7330,14 +7291,14 @@ impl ServeLoop { // then finds the track already finished. lite::SubscribeResponse::End(end) => { // Lower groups may still be on the wire, behind a higher - // one, so the end holds readers at a hole until the tail - // settles. finish_at rejects a boundary at or below a group + // one, so the end holds readers at a hole until it fills or + // its grace passes. finish_at rejects a boundary at or below a group // already received. lite-05 specified an inclusive end, // and `@moq/net` 0.1.3 to 0.1.9 sent one, so there it // only costs the early boundary: warn, and let the FIN // finish the track. Later drafts made it exclusive, so // the publisher contradicted its own end. - if let Err(err) = self.serving.finish_at_pending(Position::group(end.group)) { + if let Err(err) = self.serving.finish_at(Position::group(end.group)) { match serve.subscriber.version { Version::Lite05 => { tracing::warn!(track = %serve.name, group = end.group, %err, "invalid subscribe end") @@ -7747,8 +7708,8 @@ impl kio::Task for FetchServeRun { producer: crate::recv::Group::new(producer), joined, ingest: Box::new(FrameIngest::new( - &self.serve.subscriber, lite::Framing::new(&self.info, self.serve.subscriber.version), + self.serve.subscriber.version, ietf, frame_start, )), diff --git a/rs/moq-net/src/model/broadcast.rs b/rs/moq-net/src/model/broadcast.rs index b23f019d3f1..07e34532d8a 100644 --- a/rs/moq-net/src/model/broadcast.rs +++ b/rs/moq-net/src/model/broadcast.rs @@ -65,6 +65,11 @@ pub struct Info { /// Stamped on every [`Consumer`] an origin resolves, like [`Self::path`]. `None` for a /// route without an epoch and for a handle not resolved through an origin. pub epoch: Option, + + // What the frames this broadcast's groups are still receiving may allocate up front, + // inherited from the origin handle that created it. + // private: tuning + pub(crate) frames: super::frame::Budget, } impl Default for Info { @@ -74,6 +79,7 @@ impl Default for Info { cache_duration: std::time::Duration::MAX, path: crate::PathOwned::default(), epoch: None, + frames: Default::default(), } } } @@ -2145,6 +2151,57 @@ mod test { assert!(stale.append_group().is_err()); } + /// A staged track resolves no subscriber until it commits, and then with what was + /// written meanwhile. + #[moq_clock::test] + #[cfg(feature = "async")] + async fn a_staged_track_resolves_subscribers_at_commit() { + let producer = Info::new().produce(); + let request = producer.reserve_track("track1").unwrap(); + let track = producer.consume().track("track1").unwrap(); + let mut subscribing = std::pin::pin!(track.subscribe(None)); + assert!(futures::poll!(subscribing.as_mut()).is_pending()); + + let mut staged = request.stage(crate::track::Info::timed()); + staged.write_frame(crate::Timestamp::ZERO, b"x".as_slice()).unwrap(); + moq_clock::sim::yield_now().await; + assert!(futures::poll!(subscribing.as_mut()).is_pending(), "still staged"); + + let _track = staged.commit(); + let mut subscriber = subscribing.await.unwrap(); + assert_eq!(subscriber.recv_group().await.unwrap().unwrap().sequence, 0); + } + + /// Dropping a staged track uncommitted rejects the request, so its subscribers fail + /// rather than wait on a track nobody will publish. + #[moq_clock::test] + #[cfg(feature = "async")] + async fn dropping_a_staged_track_rejects_the_request() { + let producer = Info::new().produce(); + let request = producer.reserve_track("track1").unwrap(); + let track = producer.consume().track("track1").unwrap(); + let subscribing = track.subscribe(None); + + let mut staged = request.stage(crate::track::Info::timed()); + staged.write_frame(crate::Timestamp::ZERO, b"x".as_slice()).unwrap(); + drop(staged); + assert!(matches!(subscribing.await, Err(Error::Dropped))); + } + + /// Dropping a staged track uncommitted aborts a group still being written through it, so + /// its writer fails rather than fill a track nobody will read. + #[moq_clock::test] + #[cfg(feature = "async")] + async fn dropping_a_staged_track_aborts_its_open_groups() { + let producer = Info::new().produce(); + let request = producer.reserve_track("track1").unwrap(); + let staged = request.stage(crate::track::Info::timed()); + let mut group = staged.append_group().unwrap(); + drop(staged); + let write = group.write_frame(crate::Timestamp::ZERO, b"x".as_slice()); + assert!(matches!(write, Err(Error::Dropped)), "{write:?}"); + } + /// Ending the broadcast doesn't cascade into a track someone is publishing: it keeps /// its cache and its publisher decides when it ends. Only a new lookup is refused. #[moq_clock::test] diff --git a/rs/moq-net/src/model/cache.rs b/rs/moq-net/src/model/cache.rs index e3a7cd3a076..70e3b01917a 100644 --- a/rs/moq-net/src/model/cache.rs +++ b/rs/moq-net/src/model/cache.rs @@ -699,6 +699,10 @@ pub(super) struct Track { // Here rather than on the track state so a frame write advances it without the track // lock, and wakes only the readers following it. largest: kio::Shared, + + // What the frames this track's groups are still receiving may allocate up front, + // shared with every track minted from the same origin handle. + frames: super::frame::Budget, } /// The greatest location a track has written or its source reported, followed by the track @@ -785,10 +789,12 @@ impl Track { next } - /// Open an account against `pool` for the track behind `state`. - pub(super) fn new(pool: Pool, state: kio::Weak) -> Arc { + /// Open an account against `pool` for the track behind `state`, its frames + /// allocating up front within `frames`. + pub(super) fn new(pool: Pool, frames: super::frame::Budget, state: kio::Weak) -> Arc { let track = Arc::new(Self { pool, + frames, written: AtomicU64::new(0), next_expiry: AtomicU64::new(0), expiry_cursor: AtomicUsize::new(0), @@ -809,6 +815,11 @@ impl Track { &self.pool } + /// What this track's frames may allocate up front. + pub(super) fn frames(&self) -> &super::frame::Budget { + &self.frames + } + /// The track holding this account's groups, while it is still open. pub(super) fn track(&self) -> Option> { self.state.upgrade() @@ -1274,7 +1285,7 @@ mod test { fn charge(pool: &Pool) -> Charge { // No track behind the account: nothing here settles debt, it just accounts. - Track::new(pool.clone(), kio::Weak::new()).charge() + Track::new(pool.clone(), Default::default(), kio::Weak::new()).charge() } fn bounded(capacity: u64) -> Pool { @@ -1302,7 +1313,7 @@ mod test { #[test] fn wall_deadlines_wake_the_driver_and_then_the_read() { let pool = Pool::unbounded(); - let track = Track::new(pool.clone(), kio::Weak::new()); + let track = Track::new(pool.clone(), Default::default(), kio::Weak::new()); let now = super::super::clock::wall(); let at = now + Duration::from_secs(1); let (read, reading) = flag(); @@ -1334,7 +1345,7 @@ mod test { let pool = Pool::unbounded(); let now = super::super::clock::wall(); pool.gc(now, &kio::Waiter::noop()); - let track = Track::new(pool.clone(), kio::Weak::new()); + let track = Track::new(pool.clone(), Default::default(), kio::Weak::new()); let (_read, reading) = flag(); track.watch_wall(now + Duration::from_secs(2), &reading); track.watch_wall(now + Duration::from_secs(1), &reading); @@ -1444,7 +1455,7 @@ mod test { #[test] fn charge_counts_gross_writes() { - let track = Track::new(bounded(1000), kio::Weak::new()); + let track = Track::new(bounded(1000), Default::default(), kio::Weak::new()); let mut c = track.charge(); c.add(100); assert_eq!(track.take_written(), ENTRY_OVERHEAD + 100); @@ -1526,7 +1537,7 @@ mod test { #[test] fn expiry_gate_reuses_a_supplied_tick() { let pool = Pool::new(Config::default().with_expiry(Duration::from_secs(1))); - let track = Track::new(pool, kio::Weak::new()); + let track = Track::new(pool, Default::default(), kio::Weak::new()); // A supplied tick drives the gate on its own: claimed immediately, closed // until the interval elapses, claimable again on the tick it reopens. assert!(track.expiry_due(Some(0))); @@ -1549,7 +1560,7 @@ mod test { let pool = bounded(1000); assert!(pool.inner.tracks.lock().is_empty()); - let track = Track::new(pool.clone(), kio::Weak::new()); + let track = Track::new(pool.clone(), Default::default(), kio::Weak::new()); assert_eq!(pool.inner.tracks.lock().len(), 1); // A registered account whose track is already gone is swept harmlessly. @@ -1563,7 +1574,7 @@ mod test { fn an_inert_pool_registers_nothing() { // No window means no sweep, so a bare pool pays no registry cost. let pool = Pool::unbounded(); - let track = Track::new(pool.clone(), kio::Weak::new()); + let track = Track::new(pool.clone(), Default::default(), kio::Weak::new()); assert!(pool.inner.tracks.lock().is_empty()); pool.sweep(); drop(track); @@ -1572,7 +1583,7 @@ mod test { #[test] fn expiry_gate_stays_closed_without_a_window() { // No window means no time gate, and no clock read to reach it. - let track = Track::new(Pool::unbounded(), kio::Weak::new()); + let track = Track::new(Pool::unbounded(), Default::default(), kio::Weak::new()); assert!(!track.expiry_due(None)); assert!(!track.expiry_due(Some(u64::MAX))); } diff --git a/rs/moq-net/src/model/frame.rs b/rs/moq-net/src/model/frame.rs index 429b19f8065..6bdfdfd9dff 100644 --- a/rs/moq-net/src/model/frame.rs +++ b/rs/moq-net/src/model/frame.rs @@ -195,34 +195,52 @@ impl Buffer { } } -/// Bytes one session may allocate up front for the frames it is still receiving. +/// Bytes the frames still being written through one origin handle may allocate up front. /// -/// A peer declares each frame's size before sending it, and allocating that size up -/// front saves a reallocation and copy per doubling as the payload arrives. The -/// declaration costs the peer nothing, though, so without a bound it could commit up to +/// A writer declares each frame's size before sending it, and allocating that size up +/// front saves a reallocation and copy per doubling as the payload arrives. A peer's +/// declaration costs it nothing, though, so without a bound it could commit up to /// [`group::MAX_CACHE_BYTES`] per stream without sending a byte. A frame whose declared /// size fits what remains is allocated up front; past that, its buffer grows with the /// bytes received. Each frame returns its share once it completes or aborts. -#[derive(Clone)] -#[cfg_attr(not(feature = "async"), allow(dead_code))] -// pending: /quest/m1/public-model/ingest.md -pub(crate) struct Budget(Arc); +/// +/// Every broadcast, track, and group minted from an [`crate::origin::Producer`] handle shares +/// its budget. The built-in sessions each ingest through a handle with its own. +#[derive(Clone, Default)] +// private: tuning +pub(crate) struct Budget(Arc); + +struct Remaining(AtomicUsize); + +impl Default for Remaining { + fn default() -> Self { + Self(AtomicUsize::new(Budget::DEFAULT)) + } +} + +impl std::fmt::Debug for Budget { + fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { + f.debug_tuple("Budget") + .field(&self.0.0.load(Ordering::Relaxed)) + .finish() + } +} impl Budget { /// Enough for a handful of large keyframes in flight at once. - #[cfg_attr(not(feature = "async"), allow(dead_code))] const DEFAULT: usize = 16 * 1024 * 1024; - #[cfg_attr(not(feature = "async"), allow(dead_code))] - // pending: /quest/m1/public-model/ingest.md + /// A budget of `bytes`, for a benchmark sweeping it. + #[cfg(any(test, feature = "fuzz"))] + // private: tuning pub(crate) fn new(bytes: usize) -> Self { - Self(Arc::new(AtomicUsize::new(bytes))) + Self(Arc::new(Remaining(AtomicUsize::new(bytes)))) } /// Take `size` bytes of the budget, or `None` if that is more than remains. - #[cfg_attr(not(feature = "async"), allow(dead_code))] pub(super) fn reserve(&self, size: usize) -> Option { self.0 + .0 .fetch_update(Ordering::Relaxed, Ordering::Relaxed, |left| left.checked_sub(size)) .ok()?; Some(Reservation { @@ -232,14 +250,7 @@ impl Budget { } } -impl Default for Budget { - fn default() -> Self { - Self::new(Self::DEFAULT) - } -} - /// A frame's share of a [`Budget`], returned on drop. -#[cfg_attr(not(feature = "async"), allow(dead_code))] pub(super) struct Reservation { budget: Budget, size: usize, @@ -247,7 +258,7 @@ pub(super) struct Reservation { impl Drop for Reservation { fn drop(&mut self) { - self.budget.0.fetch_add(self.size, Ordering::Relaxed); + self.budget.0.0.fetch_add(self.size, Ordering::Relaxed); } } @@ -257,7 +268,7 @@ impl Drop for Reservation { /// A whole-frame [`Bytes`] write is stored directly. Chunked writes are copied into a /// heap [`Segment`], either sized to the declared frame up front or grown as bytes /// arrive (see [`Budget`]). The producer writes through the raw pointer (sole writer, -/// guaranteed by the exclusive borrow of the parent group); `written` provides +/// guaranteed by the frame owning the group's only writer); `written` provides /// happens-before for cross-thread reads. #[derive(Clone)] pub(super) struct FrameBuf(Arc); @@ -343,7 +354,6 @@ impl FrameBuf { } /// A buffer for a frame of `size` bytes that allocates only as bytes arrive. - #[cfg_attr(not(feature = "async"), allow(dead_code))] pub(super) fn growing(size: usize) -> Self { Self::with_growth(size, true) } @@ -388,8 +398,8 @@ impl FrameBuf { /// Append `src` at the current write offset and publish it. /// /// Safety relies on the single-producer invariant: only one [`Producer`] exists for - /// a frame (it holds the exclusive borrow of the parent group), so this is the sole - /// writer even though it takes `&self`. + /// a frame (it owns the group's only writer), so this is the sole writer even though + /// it takes `&self`. fn append(&self, src: &[u8]) { if src.is_empty() { return; @@ -463,229 +473,88 @@ impl FrameBuf { } } -/// The writer behind [`Producer`] and [`ProducerOwned`], generic over how it -/// reaches the parent group (an exclusive borrow, or an owned clone). -struct Raw> { - group: Option, +/// Writes the payload of a group's single in-flight frame in one or more chunks. +/// +/// Created by [`group::Producer::create_frame`], which hands it the group's writer: no +/// other frame can be opened, and the group cannot finish, until [`Self::finish`] returns +/// the writer. Owned rather than borrowed, so a driver can hold it across polls while +/// the payload streams in. [`Self::group`] still reads the group meanwhile. +/// +/// The total bytes written must exactly match [`Info::size`]; call [`Self::finish`] to +/// commit the frame (or [`Self::abort`] to fail it). Dropping it without either aborts +/// the group, since an unfinished frame leaves the group's stream broken. +/// +/// A single whole-frame [`write`](Self::write) keeps the caller's allocation +/// (zero-copy); chunked writes copy into one buffer sized to the declared frame, or +/// grown as bytes arrive once the declared sizes in flight pass the origin's budget. +pub struct Producer { + group: Option, buf: FrameBuf, info: Info, // Set once the frame is committed (finished) or aborted, so Drop is a no-op. done: bool, - // An owned receive frame carries its handler's cancellation cleanup across polls. + // A receive handler's cancellation cleanup, carried across polls. cancel_on_drop: bool, // Ingress payload meter, inherited from the parent group. Counts each written // chunk's bytes. Empty (no-op) for an untagged group. stats: stats::Meter, + // The frame's share of the origin's [`Budget`], if it got one, held until it ends. + _reserved: Option, } -impl> Raw { - fn remaining(&self) -> usize { - self.buf.size() - self.buf.written(Ordering::Acquire) - } - - fn write(&mut self, chunk: B) -> Result<()> { - let len = chunk.as_ref().len(); - if len > self.remaining() { - return Err(Error::WrongSize); - } - // Ingress payload: count the chunk's bytes as they're written. - self.stats.bytes(len as u64); - // Fast path: a single whole-frame write keeps the caller's allocation. - if len == self.buf.size() && self.buf.written(Ordering::Acquire) == 0 { - match self.buf.try_set_bytes(chunk.into_bytes()) { - Ok(()) => { - let size = self.buf.size(); - // Safety: `try_set_bytes` checked the buffer exactly matches the declared - // size, so publishing all bytes is in bounds. - unsafe { self.buf.store_written(size) }; - } - Err(chunk) => self.buf.append(&chunk), - } - } else { - self.buf.append(chunk.as_ref()); - } - Ok(()) - } - - fn finish(&mut self) -> Result<()> { - if self.buf.written(Ordering::Acquire) != self.buf.size() { - return Err(Error::WrongSize); - } - let payload = self.buf.freeze(); - self.group - .as_mut() - .expect("frame owns its group") - .borrow_mut() - .frame_commit(Frame::new(self.info.timestamp, payload))?; - self.done = true; - Ok(()) - } - - fn abort(&mut self, err: Error) -> Result<()> { - self.group - .as_mut() - .expect("frame owns its group") - .borrow_mut() - .frame_abort(err); - self.done = true; - Ok(()) - } -} - -impl> Drop for Raw { - fn drop(&mut self) { - if !self.done { - // An unfinished frame leaves the group stream broken; fail the group so - // consumers surface an error instead of hanging on the partial forever. - // A group already aborted (superseded, evicted, cancelled) carries its own - // reason, so cutting its in-flight frame short is expected. - let Some(group) = self.group.as_mut() else { - return; - }; - let group = group.borrow_mut(); - if !group.is_aborted() && !self.cancel_on_drop { - tracing::warn!( - group = group.info().sequence, - "frame::Producer dropped before writing all bytes" - ); - } - group.frame_abort(if self.cancel_on_drop { - Error::Cancel - } else { - Error::Dropped - }); - } - } -} - -/// Writes the payload of the single in-flight frame in one or more chunks. -/// -/// Borrows the parent [`group::Producer`] exclusively, so no other frame can be -/// opened while this one is live. The total bytes written must exactly match -/// [`Info::size`]; call [`Self::finish`] to commit the frame (or [`Self::abort`] to -/// fail it). Dropping without either aborts the group, since an unfinished frame -/// leaves the group's stream broken. -/// -/// A single whole-frame [`write`](Self::write) keeps the caller's allocation -/// (zero-copy); chunked writes copy into one buffer sized to the declared frame. -pub struct Producer<'a>(Raw<&'a mut group::Producer>); - -impl std::ops::Deref for Producer<'_> { +impl std::ops::Deref for Producer { type Target = Info; fn deref(&self) -> &Self::Target { - &self.0.info + &self.info } } -impl<'a> Producer<'a> { - pub(super) fn new(group: &'a mut group::Producer, buf: FrameBuf, info: Info) -> Self { - Self(Raw { +impl Producer { + pub(super) fn new(group: group::Producer, buf: FrameBuf, info: Info, reserved: Option) -> Self { + Self { group: Some(group), buf, info, done: false, cancel_on_drop: false, stats: stats::Meter::default(), - }) + _reserved: reserved, + } } /// Attach the parent group's ingress meter, so written chunks bump `bytes`. pub(super) fn with_meter(mut self, meter: stats::Meter) -> Self { - self.0.stats = meter; + self.stats = meter; self } - /// The parent group this frame belongs to. - pub fn group(&self) -> group::Info { - self.0.group.as_ref().expect("frame owns its group").info() - } - - /// Bytes still needed to complete the frame. - pub fn remaining(&self) -> usize { - self.0.remaining() - } - - /// Write a chunk of data to the frame. - /// - /// Returns [`Error::WrongSize`] if the chunk would exceed the remaining bytes. - pub fn write(&mut self, chunk: B) -> Result<()> { - self.0.write(chunk)?; - self.0.group.as_mut().expect("frame owns its group").frame_notify(); - Ok(()) - } - - /// Commit the frame, verifying that all bytes were written. - /// - /// Returns [`Error::WrongSize`] if the bytes written don't match [`Info::size`]. - pub fn finish(mut self) -> Result<()> { - self.0.finish() - } - - /// Abort the frame (and its group) with the given error. - pub fn abort(mut self, err: Error) -> Result<()> { - self.0.abort(err) - } -} - -/// The owned counterpart of [`Producer`], for the wire drivers that stream a -/// frame across polls and cannot hold the group borrowed inside their state. -/// -/// Owns the only group writer until the frame finishes and returns it, so another -/// frame or a group finish cannot race this frame. -/// -/// Holds the frame's share of the session's [`Budget`], if it got one, until then. -#[cfg_attr(not(feature = "async"), allow(dead_code))] -// pending: /quest/m1/public-model/ingest.md -pub(crate) struct ProducerOwned { - raw: Raw, - _reserved: Option, -} - -impl std::ops::Deref for ProducerOwned { - type Target = Info; - - fn deref(&self) -> &Self::Target { - &self.raw.info - } -} - -impl ProducerOwned { /// Transfer a receive handler's cancellation cleanup into its in-flight frame. #[cfg_attr(not(feature = "async"), allow(dead_code))] // private: capability gap - // Public drivers still borrow frames; the owned public writer belongs to ingest. + // A dropped receive handler cannot name its error; a public driver aborts explicitly. pub(crate) fn cancel_on_drop(mut self) -> Self { - self.raw.cancel_on_drop = true; + self.cancel_on_drop = true; self } - #[cfg_attr(not(feature = "async"), allow(dead_code))] - pub(super) fn new(group: group::Producer, buf: FrameBuf, info: Info, reserved: Option) -> Self { - Self { - raw: Raw { - group: Some(group), - buf, - info, - done: false, - cancel_on_drop: false, - stats: stats::Meter::default(), - }, - _reserved: reserved, - } - } - - /// Attach the parent group's ingress meter, so written chunks bump `bytes`. - #[cfg_attr(not(feature = "async"), allow(dead_code))] - pub(super) fn with_meter(mut self, meter: stats::Meter) -> Self { - self.raw.stats = meter; - self + /// The group this frame belongs to, readable while the frame holds its writer. + pub fn group(&self) -> &group::Producer { + self.group.as_ref().expect("frame owns its group") } /// Bytes still needed to complete the frame. - #[cfg_attr(not(feature = "async"), allow(dead_code))] pub fn remaining(&self) -> usize { - self.raw.remaining() + self.buf.size() - self.buf.written(Ordering::Acquire) + } + + /// Write a chunk of data to the frame, waking its readers. + /// + /// Returns [`Error::WrongSize`] if the chunk would exceed the remaining bytes. + pub fn write(&mut self, chunk: B) -> Result<()> { + self.write_deferred(chunk)?; + self.notify(); + Ok(()) } /// Write a chunk of payload *without* waking consumers; pair it with [`Self::notify`]. @@ -698,34 +567,90 @@ impl ProducerOwned { /// `coding::Reader::poll_read_frame` owns the pairing and is the only caller. #[cfg_attr(not(feature = "async"), allow(dead_code))] // private: tuning - pub(crate) fn write(&mut self, chunk: B) -> Result<()> { - self.raw.write(chunk) + pub(crate) fn write_deferred(&mut self, chunk: B) -> Result<()> { + let len = chunk.as_ref().len(); + if len > self.remaining() { + return Err(Error::WrongSize); + } + // Ingress payload: count the chunk's bytes as they're written. + self.stats.bytes(len as u64); + // Fast path: a single whole-frame write keeps the caller's allocation. + if len == self.buf.size() && self.buf.written(Ordering::Acquire) == 0 { + match self.buf.try_set_bytes(chunk.into_bytes()) { + Ok(()) => { + let size = self.buf.size(); + // Safety: `try_set_bytes` checked the buffer exactly matches the declared + // size, so publishing all bytes is in bounds. + unsafe { self.buf.store_written(size) }; + } + Err(chunk) => self.buf.append(&chunk), + } + } else { + self.buf.append(chunk.as_ref()); + } + Ok(()) } /// Publish what has been written so far, waking consumers parked on the group. #[cfg_attr(not(feature = "async"), allow(dead_code))] // private: tuning pub(crate) fn notify(&self) { - self.raw.group.as_ref().expect("frame owns its group").frame_notify(); + self.group().frame_notify(); } - /// Commit the frame, verifying that all bytes were written. - #[cfg_attr(not(feature = "async"), allow(dead_code))] + /// Commit the frame, verifying that all bytes were written, and return the group's + /// writer for its next frame or its finish. + /// + /// Returns [`Error::WrongSize`] if the bytes written don't match [`Info::size`]. pub fn finish(mut self) -> Result { - self.raw.finish()?; - Ok(self.raw.group.take().expect("frame owns its group")) + if self.buf.written(Ordering::Acquire) != self.buf.size() { + return Err(Error::WrongSize); + } + let payload = self.buf.freeze(); + let mut group = self.group.take().expect("frame owns its group"); + let committed = group.frame_commit(Frame::new(self.info.timestamp, payload)); + self.done = true; + committed?; + Ok(group) } /// Abort the frame (and its group) with the given error. - #[cfg_attr(not(feature = "async"), allow(dead_code))] pub fn abort(mut self, err: Error) -> Result<()> { - self.raw.abort(err) + self.group.as_mut().expect("frame owns its group").frame_abort(err); + self.done = true; + Ok(()) } /// Heap bytes the frame's buffer currently holds for the payload. #[cfg(test)] pub(super) fn allocated(&self) -> usize { - self.raw.buf.allocated() + self.buf.allocated() + } +} + +impl Drop for Producer { + fn drop(&mut self) { + if self.done { + return; + } + // An unfinished frame leaves the group stream broken; fail the group so + // consumers surface an error instead of hanging on the partial forever. + // A group already aborted (superseded, evicted, cancelled) carries its own + // reason, so cutting its in-flight frame short is expected. + let Some(group) = self.group.as_mut() else { + return; + }; + if !group.is_aborted() && !self.cancel_on_drop { + tracing::warn!( + group = group.info().sequence, + "frame::Producer dropped before writing all bytes" + ); + } + group.frame_abort(if self.cancel_on_drop { + Error::Cancel + } else { + Error::Dropped + }); } } diff --git a/rs/moq-net/src/model/group.rs b/rs/moq-net/src/model/group.rs index 89311b0ea5a..6111a1febad 100644 --- a/rs/moq-net/src/model/group.rs +++ b/rs/moq-net/src/model/group.rs @@ -985,6 +985,10 @@ struct Alive { // policy (`Old`, `Timeout`, `Evicted`). Set before `aborted`, under the same rules, so // a track scan learns why without taking the group lock. cut: OnceLock, + // Monotone mirror of `GroupState::started` for the first frame or the finish, set after + // the group lock is released and before the track is told: a track scan reading a stale + // false judges the group frameless until that wake re-judges it. + started: AtomicBool, // The cache stamp `GroupState::charge` maintains, held here as well so the // eviction and expiry walks can weigh a candidate without taking the group lock // they already hold the track lock over. @@ -1114,6 +1118,7 @@ impl Producer { aborted: AtomicBool::new(false), checked: AtomicBool::new(false), cut: OnceLock::new(), + started: AtomicBool::new(false), access, }); Self { @@ -1136,9 +1141,8 @@ impl Producer { self } - /// The group header. - // pending: /quest/m1/public-model/ingest.md - pub(crate) fn info(&self) -> Info { + /// The group's header, as it was created. + pub fn info(&self) -> Info { self.handle.info } @@ -1150,7 +1154,7 @@ impl Producer { /// Whether the parent track compresses, so a received frame arrives as a stored slice /// with its inflated size ([`frame::Header::inflated`]). #[cfg_attr(not(feature = "async"), allow(dead_code))] - // pending: /quest/m1/public-model/ingest.md + // private: passthrough pub(crate) fn compressed(&self) -> bool { self.handle.track.compress } @@ -1261,6 +1265,7 @@ impl Producer { track.first_frame(self.handle.info.sequence, bound); } drop(track); + self.handle.start(); // With the group lock released (lock order is track then group), settle // eviction debt if enough has been written since the track last paid. @@ -1365,6 +1370,9 @@ impl Producer { track.first_frame(self.handle.info.sequence, bound); } drop(track); + if count > 0 { + self.handle.start(); + } self.handle.cache.settle(now); if let Some(latest) = latest { @@ -1376,38 +1384,31 @@ impl Producer { } /// Create a frame with an upfront size and presentation timestamp, streamed in - /// chunks. Borrows the group exclusively until the returned [`frame::Producer`] - /// is finished or dropped, so only one frame is open at a time. + /// chunks. The returned [`frame::Producer`] takes this writer, so only one frame is + /// open at a time; its [`finish`](frame::Producer::finish) hands the writer back. + /// Use [`Self::write_frame`] for a frame already in one buffer. /// /// The `timestamp` is converted into the parent track's timescale, so the scale you - /// build it with doesn't have to match the track. Returns [`Error::FrameTooLarge`] - /// if the declared size exceeds the group's byte budget (refused before allocating) - /// or [`Error::TimestampMismatch`] if the timestamp can't be converted (overflow). - pub fn create_frame(&mut self, frame: frame::Info) -> Result> { - // The buffer allocates on its first write, so refusing the frame costs nothing. - let buf = FrameBuf::new(frame.size as usize); - let info = self.open_frame(frame.into(), &buf)?; - let meter = self.chunk_meter(None); - Ok(frame::Producer::new(self, buf, info).with_meter(meter)) - } - - /// The owned counterpart of [`Self::create_frame`], for the wire drivers that - /// stream a frame across polls and cannot hold the group borrowed inside their - /// state. The frame owns the only writer until its finish returns it. + /// build it with doesn't have to match the track. A frame the group cannot take + /// aborts the group with the error: [`Error::FrameTooLarge`] if the declared size + /// exceeds the group's byte budget (refused before allocating), + /// [`Error::TimestampMismatch`] if the timestamp can't be converted, or + /// [`Error::Closed`] once the group finished. /// - /// The declared size is the peer's claim, so the buffer is allocated up front only - /// while it fits the session's `budget`; otherwise it grows with the bytes received. + /// The declared size is allocated up front while the frames in flight through the + /// origin handle fit its budget, and grows with the bytes written past that, so a + /// peer's declaration cannot commit memory it never sends. + pub fn create_frame(self, frame: frame::Info) -> Result { + self.create_object(frame.into()) + } + + /// [`Self::create_frame`] with the moq-transport object fields a relay forwards. #[cfg_attr(not(feature = "async"), allow(dead_code))] - // pending: /quest/m1/public-model/ingest.md - pub(crate) fn create_frame_owned( - mut self, - frame: impl Into, - budget: &frame::Budget, - ) -> Result { - let frame = frame.into(); + // private: passthrough + pub(crate) fn create_object(mut self, frame: frame::Header) -> Result { let meter = self.chunk_meter(frame.inflated); let size = frame.info.size as usize; - let reserved = budget.reserve(size); + let reserved = self.handle.cache.frames().reserve(size); let buf = match reserved { Some(_) => FrameBuf::new(size), None => FrameBuf::growing(size), @@ -1419,7 +1420,7 @@ impl Producer { return Err(err); } }; - Ok(frame::ProducerOwned::new(self, buf, info, reserved).with_meter(meter)) + Ok(frame::Producer::new(self, buf, info, reserved).with_meter(meter)) } /// The meter a streamed frame's chunks bump: none for a plain frame a compressed group @@ -1509,6 +1510,7 @@ impl Producer { track.first_frame(self.handle.info.sequence, bound); } drop(track); + self.handle.start(); // With the group lock released (lock order is track then group), settle // eviction debt if enough has been written since the track last paid. @@ -1622,6 +1624,9 @@ impl Producer { if let Some(flate) = &mut state.flate { flate.finish(fin); } + drop(state); + // An empty group counts as content once it ends. + self.handle.start(); // A finished group can no longer raise the track's largest, which may end its stream. self.handle.cache.finish_largest(self.sequence); Ok(()) @@ -1805,6 +1810,7 @@ impl Handle { } let now = state.charge.add(payload + metadata + growth); drop(state); + self.start(); self.cache.settle(now); } @@ -1951,11 +1957,29 @@ impl Handle { self.state.same_channel(&other.state) } - /// Whether the group opened its first frame, or ended without one. - #[cfg_attr(not(feature = "async"), allow(dead_code))] - // pending: /quest/m1/public-model/ingest.md - pub(crate) fn is_started(&self) -> bool { - self.state.read().started() + /// Whether the group opened its first frame or finished, so the track counts it as + /// content. An aborted group is not content either way. + /// + /// Reads the mirror rather than the group's state, so a track scan holding the track + /// lock never takes the group's. + pub(super) fn is_started(&self) -> bool { + self.alive.started.load(Ordering::Relaxed) + } + + /// The first frame opened or the group finished: tell the track once, so it re-judges + /// the reads that skipped this group while it was frameless. Called with the group + /// lock released, since the track's is taken first. + fn start(&self) { + if self.alive.started.swap(true, Ordering::Relaxed) { + return; + } + let Some(track) = self.cache.track() else { + return; + }; + let answers = track.read().reveal(self); + if answers && let Ok(mut state) = track.write() { + state.shown(self.sequence); + } } /// Whether this copy may yet present the group's frame 0: it holds it, and nothing @@ -3291,7 +3315,7 @@ mod test { #[cfg(feature = "async")] fn object_fields_follow_their_frames_through_every_read() { let pool = cache::Pool::unbounded(); - let cache = cache::Track::new(pool.clone(), kio::Weak::new()); + let cache = cache::Track::new(pool.clone(), Default::default(), kio::Weak::new()); let mut group = Producer::new(Info::from(0u64), track::Info::default(), cache); group.write_frame(None, Bytes::from_static(b"p")).unwrap(); let plain = pool.used(); @@ -3308,7 +3332,7 @@ mod test { })), inflated: None, }; - let mut frame = group.create_frame_owned(header, &frame::Budget::default()).unwrap(); + let mut frame = group.create_object(header).unwrap(); frame.write(Bytes::from_static(b"f")).unwrap(); group = frame.finish().unwrap(); } @@ -3360,7 +3384,7 @@ mod test { #[cfg(feature = "async")] fn terminal_metadata_stays_charged_after_frames_are_released() { let pool = cache::Pool::unbounded(); - let cache = cache::Track::new(pool.clone(), kio::Weak::new()); + let cache = cache::Track::new(pool.clone(), Default::default(), kio::Weak::new()); let mut group = Producer::new(Info::from(0u64), track::Info::default(), cache); group.write_frame(None, Bytes::from_static(b"payload")).unwrap(); let fields = super::super::object::Fields { @@ -3424,7 +3448,7 @@ mod test { fn frame_capacity_growth_is_charged_and_released() { for mode in 0..3 { let pool = cache::Pool::unbounded(); - let cache = cache::Track::new(pool.clone(), kio::Weak::new()); + let cache = cache::Track::new(pool.clone(), Default::default(), kio::Weak::new()); let mut group = Producer::new(Info::from(0u64), track::Info::timed(), cache); for _ in 0..FRAME_SLOTS { group.write_frame(Timestamp::ZERO, bytes::Bytes::new()).unwrap(); @@ -3444,7 +3468,7 @@ mod test { timestamp: Some(Timestamp::ZERO), }) .unwrap(); - frame.finish().unwrap(); + group = frame.finish().unwrap(); } } let capacity = group.handle.state.read().frames.capacity(); @@ -3558,18 +3582,16 @@ mod test { #[test] #[cfg(feature = "async")] fn chunked_frame_reads_whole() { - let mut producer = Info { sequence: 0 }.produce(); - { - let mut frame = producer - .create_frame(frame::Info { - size: 10, - timestamp: Some(Timestamp::ZERO), - }) - .unwrap(); - frame.write(Bytes::from_static(b"hello")).unwrap(); - frame.write(Bytes::from_static(b"world")).unwrap(); - frame.finish().unwrap(); - } + let producer = Info { sequence: 0 }.produce(); + let mut frame = producer + .create_frame(frame::Info { + size: 10, + timestamp: Some(Timestamp::ZERO), + }) + .unwrap(); + frame.write(Bytes::from_static(b"hello")).unwrap(); + frame.write(Bytes::from_static(b"world")).unwrap(); + let mut producer = frame.finish().unwrap(); producer.finish().unwrap(); // Frame data is held in a single per-frame buffer; a whole-frame read returns @@ -3582,7 +3604,7 @@ mod test { #[test] #[cfg(feature = "async")] fn chunked_frame_streams_partial() { - let mut producer = Info { sequence: 0 }.produce(); + let producer = Info { sequence: 0 }.produce(); let mut consumer = producer.consume(); let mut frame = producer @@ -3600,7 +3622,7 @@ mod test { assert!(f.read_chunk().now_or_never().is_none()); frame.write(Bytes::from_static(b"bar")).unwrap(); - frame.finish().unwrap(); + let _producer = frame.finish().unwrap(); let c2 = f.read_chunk().now_or_never().unwrap().unwrap(); assert_eq!(c2, Some(Bytes::from_static(b"bar"))); @@ -3704,7 +3726,7 @@ mod test { (Error::GroupTooLarge, false), ] { let pool = cache::Pool::unbounded(); - let cache = cache::Track::new(pool.clone(), kio::Weak::new()); + let cache = cache::Track::new(pool.clone(), Default::default(), kio::Weak::new()); let mut producer = Producer::new(Info::from(0u64), track::Info::default(), cache); producer.write_frame(None, Bytes::from_static(b"a")).unwrap(); producer.write_frame(None, Bytes::from_static(b"b")).unwrap(); @@ -3731,7 +3753,7 @@ mod test { #[test] fn a_held_head_expires_with_the_pool_window() { let pool = cache::Pool::new(cache::Config::default().with_expiry(std::time::Duration::from_secs(1))); - let cache = cache::Track::new(pool.clone(), kio::Weak::new()); + let cache = cache::Track::new(pool.clone(), Default::default(), kio::Weak::new()); let mut producer = Producer::new(Info::from(0u64), track::Info::default(), cache); producer.write_frame(None, Bytes::from_static(b"a")).unwrap(); let handoff = producer.consume().handoff(); @@ -3751,7 +3773,7 @@ mod test { fn the_held_registry_follows_the_heads_held() { const BURST: usize = 64; let pool = cache::Pool::new(cache::Config::default().with_expiry(std::time::Duration::from_secs(1))); - let cache = cache::Track::new(pool.clone(), kio::Weak::new()); + let cache = cache::Track::new(pool.clone(), Default::default(), kio::Weak::new()); let fail = |sequence: u64| { let mut producer = Producer::new(Info::from(sequence), track::Info::default(), cache.clone()); producer.write_frame(None, Bytes::from_static(b"a")).unwrap(); @@ -3779,7 +3801,7 @@ mod test { #[test] fn a_full_pool_holds_no_head() { let pool = cache::Pool::new(cache::Config::default().with_capacity(1)); - let cache = cache::Track::new(pool.clone(), kio::Weak::new()); + let cache = cache::Track::new(pool.clone(), Default::default(), kio::Weak::new()); let mut producer = Producer::new(Info::from(0u64), track::Info::default(), cache); producer.write_frame(None, Bytes::from_static(b"a")).unwrap(); let handoff = producer.consume().handoff(); @@ -3793,7 +3815,7 @@ mod test { #[test] fn an_open_frame_reserves_its_remainder_from_adoption() { let pool = cache::Pool::unbounded(); - let cache = cache::Track::new(pool, kio::Weak::new()); + let cache = cache::Track::new(pool, Default::default(), kio::Weak::new()); let mut tail = Producer::new(Info::from(0u64), track::Info::default(), cache); tail.start_at(1).unwrap(); let adopter = tail.handle(); @@ -3850,7 +3872,7 @@ mod test { }; for wired_first in [true, false] { let pool = cache::Pool::unbounded(); - let cache = cache::Track::new(pool.clone(), kio::Weak::new()); + let cache = cache::Track::new(pool.clone(), Default::default(), kio::Weak::new()); let mut tail = Producer::new(Info::from(0u64), track::Info::default(), cache); tail.start_at(2).unwrap(); if wired_first { @@ -4065,7 +4087,7 @@ mod test { #[cfg(feature = "async")] fn prefetched_consumer(pool: &cache::Pool, max_age: std::time::Duration) -> (Producer, Consumer) { - let cache = cache::Track::new(pool.clone(), kio::Weak::new()); + let cache = cache::Track::new(pool.clone(), Default::default(), kio::Weak::new()); let track = track::Info::timed().with_max_age(max_age); let mut producer = Producer::new(Info { sequence: 0 }, track, cache); producer.write_frame(Timestamp::ZERO, Bytes::from_static(b"a")).unwrap(); @@ -4312,7 +4334,7 @@ mod test { #[moq_clock::test] #[cfg(feature = "async")] async fn chunk_write_wakes_parked_reader() { - let mut producer = Info { sequence: 0 }.produce(); + let producer = Info { sequence: 0 }.produce(); let mut consumer = producer.consume(); let mut frame = producer .create_frame(frame::Info { @@ -4354,7 +4376,7 @@ mod test { chunked.write(Bytes::from_static(b"b")).unwrap(); moq_clock::sleep(Duration::from_millis(10)).await; chunked.write(Bytes::from_static(b"c")).unwrap(); - chunked.finish().unwrap(); + producer = chunked.finish().unwrap(); moq_clock::sleep(Duration::from_millis(10)).await; let mut batch = frame::Buffer::<2>::new(); @@ -4383,7 +4405,7 @@ mod test { fn create_frame_converts_mismatched_scale() { use crate::{Timescale, Timestamp}; - let mut producer = Producer::new( + let producer = Producer::new( Info { sequence: 0 }, track::Info::default().with_timescale(Timescale::MICRO), Default::default(), @@ -4402,7 +4424,7 @@ mod test { fn create_frame_converts_current_timestamp() { use crate::Timescale; - let mut producer = Producer::new( + let producer = Producer::new( Info { sequence: 0 }, track::Info::default().with_timescale(Timescale::MICRO), Default::default(), @@ -4579,7 +4601,7 @@ mod test { /// The per-frame size cap (the group byte budget) is enforced before allocating. #[test] fn create_frame_rejects_oversized() { - let mut producer = Info { sequence: 0 }.produce(); + let producer = Info { sequence: 0 }.produce(); let result = producer.create_frame(frame::Info { size: MAX_CACHE_BYTES + 1, timestamp: Some(Timestamp::ZERO), @@ -4600,17 +4622,15 @@ mod test { #[test] fn frame_is_charged_as_written() { let pool = cache::Pool::unbounded(); - let cache = cache::Track::new(pool.clone(), kio::Weak::new()); + let cache = cache::Track::new(pool.clone(), Default::default(), kio::Weak::new()); let producer = Producer::new(Info { sequence: 0 }, track::Info::timed(), cache); let before = pool.used(); let observing = producer.handle(); - let mut frame = producer - .create_frame_owned(sized(MAX_CACHE_BYTES), &frame::Budget::default()) - .unwrap(); + let mut frame = producer.create_frame(sized(MAX_CACHE_BYTES)).unwrap(); assert_eq!(pool.used(), before, "the declared size was charged"); - frame.write(Bytes::from(vec![0u8; 100])).unwrap(); + frame.write_deferred(Bytes::from(vec![0u8; 100])).unwrap(); assert_eq!(pool.used(), before, "charged before the write was published"); frame.notify(); assert_eq!(pool.used(), before + 100); @@ -4624,12 +4644,44 @@ mod test { assert!(pool.used() <= before); } + /// A writer names the group it fills. #[test] - fn refused_owned_frame_aborts_with_its_error() { + fn info_names_the_group() { + let producer = Info { sequence: 7 }.produce(); + assert_eq!(producer.info(), Info { sequence: 7 }); + } + + /// An open frame still reads its group: which one it is, how many frames it holds, + /// and whether anyone reads it. Finishing the frame hands the same writer back. + #[test] + #[cfg(feature = "async")] + fn an_open_frame_reads_its_group() { + let mut producer = Info { sequence: 3 }.produce(); + producer.write_frame(Timestamp::ZERO, Bytes::from_static(b"a")).unwrap(); + let mut consumer = producer.consume(); + + let mut frame = producer.create_frame(sized(1)).unwrap(); + let group = frame.group(); + assert_eq!(group.info().sequence, 3); + assert_eq!(group.frame_count(), 2, "the open frame counts"); + assert!(group.demand().is_used()); + assert!(group.poll_closed(&kio::Waiter::noop()).is_pending()); + + frame.write(Bytes::from_static(b"b")).unwrap(); + let mut producer = frame.finish().unwrap(); + producer.finish().unwrap(); + let mut read = || consumer.read_frame().now_or_never().unwrap().unwrap(); + assert_eq!(read().unwrap().payload, Bytes::from_static(b"a")); + assert_eq!(read().unwrap().payload, Bytes::from_static(b"b")); + assert!(read().is_none()); + } + + #[test] + fn refused_frame_aborts_with_its_error() { let producer = Info { sequence: 0 }.produce(); let handle = producer.handle(); assert!(matches!( - producer.create_frame_owned(sized(MAX_CACHE_BYTES + 1), &frame::Budget::default()), + producer.create_frame(sized(MAX_CACHE_BYTES + 1)), Err(Error::FrameTooLarge) )); assert!(matches!( @@ -4642,36 +4694,38 @@ mod test { #[test] fn frame_commit_charges_the_tail() { let pool = cache::Pool::unbounded(); - let cache = cache::Track::new(pool.clone(), kio::Weak::new()); + let cache = cache::Track::new(pool.clone(), Default::default(), kio::Weak::new()); let producer = Producer::new(Info { sequence: 0 }, track::Info::timed(), cache); let before = pool.used(); let observing = producer.handle(); - let mut frame = producer - .create_frame_owned(sized(300), &frame::Budget::default()) - .unwrap(); + let mut frame = producer.create_frame(sized(300)).unwrap(); frame.write(Bytes::from(vec![0u8; 100])).unwrap(); - frame.notify(); - frame.write(Bytes::from(vec![0u8; 200])).unwrap(); + frame.write_deferred(Bytes::from(vec![0u8; 200])).unwrap(); let _producer = frame.finish().unwrap(); assert_eq!(pool.used(), before + 300); assert_eq!(observing.state.read().cache, 300); } - /// Frames within the session's budget allocate their declared size up front; past + /// Frames within their origin's budget allocate their declared size up front; past /// it, a frame's buffer holds only what has arrived. A frame hands its share back /// once it ends. #[test] fn frame_budget_bounds_upfront_allocation() { let budget = frame::Budget::new(1024); - let a = Info { sequence: 0 }.produce(); - let b = Info { sequence: 1 }.produce(); + let pool = cache::Pool::unbounded(); + let group = |sequence| { + let cache = cache::Track::new(pool.clone(), budget.clone(), kio::Weak::new()); + Producer::new(Info { sequence }, track::Info::timed(), cache) + }; + let a = group(0); + let b = group(1); - let mut first = a.create_frame_owned(sized(1024), &budget).unwrap(); + let mut first = a.create_frame(sized(1024)).unwrap(); first.write(Bytes::from_static(b"x")).unwrap(); assert_eq!(first.allocated(), 1024, "a frame within budget is allocated up front"); - let mut second = b.create_frame_owned(sized(MAX_CACHE_BYTES), &budget).unwrap(); + let mut second = b.create_frame(sized(MAX_CACHE_BYTES)).unwrap(); second.write(Bytes::from(vec![0u8; 100])).unwrap(); assert_eq!( second.allocated(), @@ -4684,8 +4738,8 @@ mod test { let mut a = first.finish().unwrap(); a.finish().unwrap(); - let a = Info { sequence: 2 }.produce(); - let mut third = a.create_frame_owned(sized(1024), &budget).unwrap(); + let a = group(2); + let mut third = a.create_frame(sized(1024)).unwrap(); third.write(Bytes::from_static(b"x")).unwrap(); assert_eq!(third.allocated(), 1024, "the finished frame did not return its share"); } @@ -4703,7 +4757,7 @@ mod test { } fn compressed_group(pool: &cache::Pool) -> Producer { - let cache = cache::Track::new(pool.clone(), kio::Weak::new()); + let cache = cache::Track::new(pool.clone(), Default::default(), kio::Weak::new()); Producer::new(Info::from(0u64), track::Info::default().with_compress(true), cache) } @@ -4727,7 +4781,7 @@ mod test { for chunk in verbose(1).chunks(100) { frame.write(Bytes::copy_from_slice(chunk)).unwrap(); } - frame.finish().unwrap(); + group = frame.finish().unwrap(); group.write_frame(None, verbose(2)).unwrap(); group.finish().unwrap(); @@ -4737,7 +4791,7 @@ mod test { let mut reference = Producer::new( Info::from(0u64), track::Info::default(), - cache::Track::new(uncompressed.clone(), kio::Weak::new()), + cache::Track::new(uncompressed.clone(), Default::default(), kio::Weak::new()), ); for index in 0..3 { reference.write_frame(None, verbose(index)).unwrap(); @@ -4810,7 +4864,7 @@ mod test { let plain = fail(&mut Producer::new( Info::from(0u64), track::Info::default(), - cache::Track::new(pool.clone(), kio::Weak::new()), + cache::Track::new(pool.clone(), Default::default(), kio::Weak::new()), )); let refused = successor(); refused.handle.adopt_head(&plain); @@ -4923,7 +4977,7 @@ mod test { for chunk in verbose(3).chunks(100) { frame.write(Bytes::copy_from_slice(chunk)).unwrap(); } - frame.finish().unwrap(); + group = frame.finish().unwrap(); group.finish().unwrap(); let stored: u64 = (group.handle.state.read().frames.iter()) @@ -5007,7 +5061,7 @@ mod test { fields: None, inflated: Some(verbose(0).len() as u64 + 1), }; - let mut frame = group.create_frame_owned(header, &frame::Budget::default()).unwrap(); + let mut frame = group.create_object(header).unwrap(); frame.write(slice).unwrap(); let mut group = frame.finish().unwrap(); group.finish().unwrap(); @@ -5025,12 +5079,10 @@ mod test { inflated: Some(inflated), }; let pool = cache::Pool::unbounded(); - let res = compressed_group(&pool).create_frame_owned(header(MAX_CACHE_BYTES + 1), &frame::Budget::default()); + let res = compressed_group(&pool).create_object(header(MAX_CACHE_BYTES + 1)); assert!(matches!(res, Err(Error::FrameTooLarge))); - let res = Info::from(1u64) - .produce_untimed() - .create_frame_owned(header(1), &frame::Budget::default()); + let res = Info::from(1u64).produce_untimed().create_object(header(1)); assert!(matches!(res, Err(Error::ProtocolViolation))); } diff --git a/rs/moq-net/src/model/listing.rs b/rs/moq-net/src/model/listing.rs index 50d755a1df9..35ff4c7384a 100644 --- a/rs/moq-net/src/model/listing.rs +++ b/rs/moq-net/src/model/listing.rs @@ -734,6 +734,18 @@ mod tests { assert_eq!(drain(&mut tracks), ["-a"]); } + #[test] + fn a_staged_track_is_listed_until_dropped_uncommitted() { + let broadcast = Info::new().produce(); + let request = broadcast.reserve_track("a").unwrap(); + let mut tracks = broadcast.consume().tracks().unwrap(); + assert_eq!(drain(&mut tracks), ["synced"]); + let staged = request.stage(None); + assert_eq!(drain(&mut tracks), ["+a"]); + drop(staged); + assert_eq!(drain(&mut tracks), ["-a"]); + } + #[test] fn a_track_served_on_request_is_never_listed() { let broadcast = Info::new().produce(); diff --git a/rs/moq-net/src/model/mod.rs b/rs/moq-net/src/model/mod.rs index 10a7da6f77d..3c443bc5c77 100644 --- a/rs/moq-net/src/model/mod.rs +++ b/rs/moq-net/src/model/mod.rs @@ -25,8 +25,6 @@ mod delivered; mod expiry; // The DEFLATE codec behind compressed tracks. mod flate; -// pending: /quest/m1/public-model/ingest.md -pub(crate) mod ledger; // private: passthrough pub(crate) mod object; mod requests; diff --git a/rs/moq-net/src/model/origin.rs b/rs/moq-net/src/model/origin.rs index 4229dc2d341..7b4c0408a56 100644 --- a/rs/moq-net/src/model/origin.rs +++ b/rs/moq-net/src/model/origin.rs @@ -1776,6 +1776,10 @@ pub struct Producer { // The clock advanced by the origin driver. timers: Deadlines, + + // What the frames written through this handle may allocate up front, shared by every + // broadcast it creates. + frames: super::frame::Budget, } impl Producer { @@ -1803,6 +1807,7 @@ impl Producer { preference: Preference::default(), tasks, timers: timers.clone(), + frames: Default::default(), }; let driver = Driver { state: DriverState { @@ -1816,6 +1821,15 @@ impl Producer { (producer, driver) } + /// Give this handle a frame budget of its own, so what one session allocates up front + /// never crowds out another's. + #[cfg_attr(not(feature = "async"), allow(dead_code))] + // private: tuning + pub(crate) fn with_own_frames(mut self) -> Self { + self.frames = Default::default(); + self + } + /// The ingress stats context this handle was tagged with. #[cfg_attr(not(feature = "async"), allow(dead_code))] // pending: /quest/m1/public-model/answer.md @@ -1912,6 +1926,7 @@ impl Producer { preference: Preference::default(), tasks, timers: Deadlines::new(Instant::ZERO), + frames: Default::default(), } } @@ -1990,6 +2005,7 @@ impl Producer { cache_duration: self.cache_duration, path: full, epoch: None, + frames: self.frames.clone(), }; let source = info.produce().with_stats(ingress.clone()); let entry = announcing.announce( @@ -2031,6 +2047,7 @@ impl Producer { cache_duration: self.cache_duration, path: full, epoch: None, + frames: self.frames.clone(), } .produce() .with_stats(ingress) @@ -2191,6 +2208,7 @@ impl Producer { preference: self.preference, tasks: self.tasks.clone(), timers: self.timers.clone(), + frames: self.frames.clone(), }) } @@ -6370,6 +6388,8 @@ impl Consumer { cache_duration: self.cache_duration, path: absolute.clone(), epoch: None, + // A front reads its routes' copies, so it writes no frames of its own. + frames: Default::default(), }); let request = kio::Producer::::default(); let consumer = request.consume(); @@ -8824,7 +8844,7 @@ mod tests { .await .expect("the front asked the source") .expect("request"); - let source = request.resolving_start().accept(crate::track::Info::timed()); + let source = request.request_start(None).accept(crate::track::Info::timed()); let mut group = source.create_group(0u64.into()).unwrap(); group.write_frame(crate::Timestamp::ZERO, b"snapshot".as_ref()).unwrap(); group.finish().unwrap(); @@ -9256,7 +9276,7 @@ mod tests { serving.lock().unwrap().push(group); } }); - let mut next = request.resolving_start().accept(crate::track::Info::timed()); + let mut next = request.request_start(None).accept(crate::track::Info::timed()); next.start_at(0).unwrap(); let mut next_group = next.create_group(0u64.into()).unwrap(); next_group.start_at(2).unwrap(); diff --git a/rs/moq-net/src/model/resume.rs b/rs/moq-net/src/model/resume.rs index 317bd3ce9e7..04b5086e3f4 100644 --- a/rs/moq-net/src/model/resume.rs +++ b/rs/moq-net/src/model/resume.rs @@ -36,8 +36,8 @@ use crate::time::Instant; use crate::{Error, Result, StreamError, group, stats, track}; use super::delivered::Delivered; -use super::ledger; use super::subscription::{Anchor, Cap, 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. #[derive(Default)] @@ -1857,7 +1857,7 @@ mod test { let b = copy(); let dynamic = b.dynamic(); - let mut newer = b.receive_group(group::Info { sequence: 1 }).unwrap(); + let mut newer = b.create_group(group::Info { sequence: 1 }).unwrap(); newer.write_frame(ts(1), b"newer".as_ref()).unwrap(); newer.finish().unwrap(); routes.serve(b.consume()); @@ -1874,7 +1874,7 @@ mod test { ); if arrives { - let mut late = b.receive_group(group::Info { sequence: 0 }).unwrap(); + let mut late = b.create_group(group::Info { sequence: 0 }).unwrap(); late.write_frame(ts(0), b"first".as_ref()).unwrap(); late.write_frame(ts(1), b"continued".as_ref()).unwrap(); late.finish().unwrap(); @@ -2047,9 +2047,7 @@ mod test { fields: None, inflated: Some(frame().len() as u64 + 1), }; - let mut corrupt = group - .create_frame_owned(header, &crate::model::frame::Budget::default()) - .unwrap(); + let mut corrupt = group.create_object(header).unwrap(); corrupt.write(slice).unwrap(); let mut group = corrupt.finish().unwrap(); group.finish().unwrap(); @@ -2119,7 +2117,7 @@ mod test { routes.serve(a.consume()); let mut sub = subscribe(&logical, Duration::from_secs(10)); - let mut open = a.create_group(group::Info { sequence: 0 }).unwrap(); + let open = a.create_group(group::Info { sequence: 0 }).unwrap(); let mut frame = open .create_frame(crate::frame::Info { size: 4, @@ -3729,7 +3727,15 @@ mod test { let mut group = recv(&mut sub); assert_eq!(read(&mut group), Some(b"held".to_vec())); - let b = copy(); + // A moq-transport route's copy, whose timestamps are never checked for a rewind. + let b = track::Producer::new( + Arc::new(broadcast::Info::default()), + "video", + crate::track::Info { + unchecked: true, + ..crate::track::Info::timed() + }, + ); routes.serve(b.consume()); let groups = groups .iter() @@ -3800,7 +3806,8 @@ mod test { #[test] #[cfg(feature = "async")] fn a_group_no_route_continues_wakes_when_its_successor_aborts() { - let mut held = Held::new(&[(3, None), (4, Some(4000)), (5, Some(5000))]); + // A frameless successor bounds nothing, so it takes one that started near the edge. + let mut held = Held::new(&[(3, Some(4950)), (4, Some(4000)), (5, Some(5000))]); // Group 4 succeeds it instead, a full second behind the edge. held.groups.remove(&3).unwrap().abort(Error::Dropped).unwrap(); assert!(held.woken(), "the successor's abort wakes the held group"); @@ -3861,7 +3868,7 @@ mod test { let a = copy(); routes.serve(a.consume()); let mut sub = subscribe(&logical, Duration::from_secs(10)); - let mut open = a.create_group(group::Info { sequence: 0 }).unwrap(); + let open = a.create_group(group::Info { sequence: 0 }).unwrap(); let mut frame = open .create_frame(crate::frame::Info { size: 4, @@ -3911,7 +3918,7 @@ mod test { let a = copy(); routes.serve(a.consume()); let mut sub = subscribe(&logical, Duration::from_secs(2)); - let mut open = a.create_group(group::Info { sequence: 0 }).unwrap(); + let open = a.create_group(group::Info { sequence: 0 }).unwrap(); let mut frame = open .create_frame(crate::frame::Info { size: 4, @@ -3924,7 +3931,7 @@ mod test { assert!(chunks.read_chunk().now_or_never().unwrap().is_ok()); let b = copy(); - let mut replacement = b.create_group(group::Info { sequence: 0 }).unwrap(); + let replacement = b.create_group(group::Info { sequence: 0 }).unwrap(); let mut replacement_frame = replacement .create_frame(crate::frame::Info { size: 4, @@ -4015,20 +4022,17 @@ mod test { }) .unwrap(); let mut frame = group - .create_frame_owned( - crate::frame::Header { - info: crate::frame::Info { - size: 1, - timestamp: Some(ts(0)), - }, - fields: Some(Arc::new(super::super::object::Fields { - id: 6, - properties: Default::default(), - })), - inflated: None, + .create_object(crate::frame::Header { + info: crate::frame::Info { + size: 1, + timestamp: Some(ts(0)), }, - &crate::frame::Budget::default(), - ) + fields: Some(Arc::new(super::super::object::Fields { + id: 6, + properties: Default::default(), + })), + inflated: None, + }) .unwrap(); frame.write(bytes::Bytes::from_static(b"a")).unwrap(); let group = frame.finish().unwrap(); @@ -4038,20 +4042,17 @@ mod test { assert_eq!(read(&mut reading), Some(b"a".to_vec())); assert_eq!(a.consume().resume_position(), Some(Position::group(1))); let mut partial = group - .create_frame_owned( - crate::frame::Header { - info: crate::frame::Info { - size: 2, - timestamp: Some(ts(1)), - }, - fields: Some(Arc::new(super::super::object::Fields { - id: 8, - properties: Default::default(), - })), - inflated: None, + .create_object(crate::frame::Header { + info: crate::frame::Info { + size: 2, + timestamp: Some(ts(1)), }, - &crate::frame::Budget::default(), - ) + fields: Some(Arc::new(super::super::object::Fields { + id: 8, + properties: Default::default(), + })), + inflated: None, + }) .unwrap(); partial.write(bytes::Bytes::from_static(b"b")).unwrap(); let mut chunks = reading.next_frame().now_or_never().unwrap().unwrap().unwrap(); @@ -4086,20 +4087,17 @@ mod test { .unwrap(); for &(id, payload) in objects { let mut frame = group - .create_frame_owned( - crate::frame::Header { - info: crate::frame::Info { - size: payload.len() as u64, - timestamp: Some(ts(id)), - }, - fields: Some(Arc::new(super::super::object::Fields { - id, - properties: Default::default(), - })), - inflated: None, + .create_object(crate::frame::Header { + info: crate::frame::Info { + size: payload.len() as u64, + timestamp: Some(ts(id)), }, - &crate::frame::Budget::default(), - ) + fields: Some(Arc::new(super::super::object::Fields { + id, + properties: Default::default(), + })), + inflated: None, + }) .unwrap(); frame.write(bytes::Bytes::from_static(payload)).unwrap(); group = frame.finish().unwrap(); @@ -4117,7 +4115,7 @@ mod test { let a = copy(); routes.serve(a.consume()); let mut sub = subscribe(&front, Duration::from_secs(10)); - let mut open = a.create_group(group::Info { sequence: 0 }).unwrap(); + let open = a.create_group(group::Info { sequence: 0 }).unwrap(); let mut frame = open .create_frame(crate::frame::Info { size: 4, @@ -4786,21 +4784,25 @@ mod test { let mut sub = subscribe(&logical, Duration::from_secs(if widen { 2 } else { 10 })); let b = copy(); // Both routes carry the same content, including the unfinished payload. - let mut writers = [&a, &b].map(|source| source.create_group(group::Info { sequence: 0 }).unwrap()); - let _frames: Vec<_> = writers - .iter_mut() - .map(|group| { + let writers = [&a, &b].map(|source| source.create_group(group::Info { sequence: 0 }).unwrap()); + // Each group's writer, held open by its unfinished frame when chunked. + let _writers: Vec<_> = writers + .into_iter() + .map(|mut group| { group.write_frame(ts(0), b"first".as_ref()).unwrap(); - chunked.then(|| { - let mut frame = group - .create_frame(crate::frame::Info { - size: 4, - timestamp: Some(ts(1)), - }) - .unwrap(); - frame.write(b"ab".as_ref()).unwrap(); - frame - }) + match chunked { + false => (Some(group), None), + true => { + let mut frame = group + .create_frame(crate::frame::Info { + size: 4, + timestamp: Some(ts(1)), + }) + .unwrap(); + frame.write(b"ab".as_ref()).unwrap(); + (None, Some(frame)) + } + } }) .collect(); let mut group = recv(&mut sub); diff --git a/rs/moq-net/src/model/track.rs b/rs/moq-net/src/model/track.rs index a8c593de4f0..5a0f04c654d 100644 --- a/rs/moq-net/src/model/track.rs +++ b/rs/moq-net/src/model/track.rs @@ -17,8 +17,8 @@ use crate::{Error, Result, StreamError, Timescale, Timestamp, coding}; use crate::{broadcast, cache, group, stats}; use super::delivered::Delivered; -use super::ledger::{self, Ledger}; use super::{Datagram, Requests}; +use crate::ledger::{self, Ledger}; use super::Cap; pub use super::subscription::{Anchor, Order, Position, Range, Subscription}; @@ -175,7 +175,7 @@ pub struct Info { /// They stay on moq-transport: a moq-lite hop serves the track untimed, since its /// receivers check every timestamp. Never set on an untimed track. #[cfg_attr(not(feature = "async"), allow(dead_code))] - // pending: /quest/m1/public-model/ingest.md + // private: passthrough pub(crate) unchecked: bool, } @@ -320,6 +320,9 @@ pub(crate) struct TrackState { // Whether a live Producer was minted. A reverse fetch may install `info` // before acceptance, so the two states are deliberately separate. published: bool, + // Minted by `Request::stage` and not committed yet: the producer writes, but waiting + // subscribers resolve only at `Staged::commit`, with everything written by then. + staged: bool, // Whether a dynamic handler took the request. Its answer is the handler's call, // so ending the broadcast leaves it pending rather than rejecting it. claimed: bool, @@ -422,10 +425,11 @@ pub(crate) struct TrackState { // or the receiving session closed locally without declaring an end. sealed: bool, - // A wire subscription declared the end ahead of the group streams below it, which - // QUIC may deliver in any order: readers wait for its tail to settle, or for the - // last producer to go, rather than end at the boundary with groups still to arrive. - tail_pending: bool, + // Set once a received copy's end is declared, ahead of group streams below it that QUIC + // may deliver in any order: when the end or a start was declared, or a group last arrived since. + // Readers wait out the grace for that tail (see [`Self::tail_deadline`]), rather than + // end at the boundary with groups still to arrive. + tail: Option, // The sequences the live feed delivered, as a group or a datagram: what a pending tail // is judged by. Fetched copies never count, and eviction never touches it. A gap folds @@ -433,10 +437,6 @@ pub(crate) struct TrackState { // does, so this holds only the gaps still worth waiting for. arrivals: Ledger, - // Cached groups a route is still withholding (see `Slot::pending`), so an end check - // need not scan the cache for one. - withheld: usize, - // No producer remains (aborted, sealed, or dropped), so nothing protects the live // edge any longer: the pool's idle expiry reclaims it like every other group, and a // stale consumer cannot pin the cache. @@ -453,6 +453,9 @@ pub(crate) struct TrackState { // [`Subscriber::poll_start`]) wait on it; everything else treats the floor as usual. start_pending: bool, + // A copy received from a remote publisher, whose declared end waits for groups still + // in flight below it (see `tail`). + received: bool, // Sequences the upstream publisher gave up, with the error each was given up with: an // incoming SUBSCRIBE_DROP or a producer cut. Kept apart from the cache so reclaiming a // slot cannot erase a disposition a relay must forward, and as ranges so a wide DROP @@ -545,12 +548,8 @@ struct Slot { // subscription content. Fetch-only backfill stays cached but never anchors drift. visible: bool, - // A live group received from a route, withheld from readers until its first frame - // lands or its stream ends; see [`Producer::receive_group`]. - pending: bool, - - // When the group arrived here, withheld or not: the start of the wall clock for the - // group before it (see [`TrackState::arrival`]). Read on the pool's clock. + // When the group arrived here, before its first frame: the start of the wall clock for + // the group before it (see [`TrackState::arrival`]). Read on the pool's clock. arrived: crate::time::Instant, // A fetched copy of a live `group` that the feed started past the frames a fetch @@ -571,21 +570,23 @@ impl Slot { self.visible && !self.group.is_aborted() } - /// Whether readers see this slot as live content: [`Self::is_live`], and not withheld. + /// Whether this slot counts as live content: [`Self::is_live`], and its first frame + /// opened or it finished. A frameless group is handed to readers, but no judgment + /// counts it until then: not the live edge, a successor, nor the rejoin wait. fn is_shown(&self) -> bool { - self.is_live() && !self.pending + self.is_live() && self.group.is_started() } - /// Whether the arrival walk hands this slot out: the live feed's, not withheld, and - /// still serving, a fetched head counting for an aborted live group. + /// Whether the arrival walk hands this slot out: the live feed's, and still serving, a + /// fetched head counting for an aborted live group. fn is_walked(&self) -> bool { - self.visible && !self.pending && !self.is_aborted() + self.visible && !self.is_aborted() } /// Why the publisher gave up this live-feed group readers were shown, once nothing /// serves it: a reader is handed the group to see that error, never a missing group. fn cut(&self) -> Option<&Error> { - match self.visible && !self.pending && self.is_aborted() && !self.retired.load(Ordering::Relaxed) { + match self.visible && self.is_aborted() && !self.retired.load(Ordering::Relaxed) { true => self.group.cut_error(), false => None, } @@ -960,7 +961,7 @@ impl TrackState { } fn poll_info(&self) -> Poll> { - if let Some(info) = &self.info { + if let Some(info) = self.info.as_ref().filter(|_| !self.staged) { Poll::Ready(Ok(info.clone())) } else if let Some(err) = &self.abort { // Aborted before anyone served it, so the info can never arrive: fail the @@ -971,17 +972,17 @@ impl TrackState { } } - /// Find the next live group at or after `index` in arrival order. - /// - /// Returns the group and its absolute index so the consumer can advance past it. - /// The cached producer rather than a consumer: `consume` reads the clock and can - /// take the group's own lock, which the caller does once the track guard is gone. /// Whether readers may take from the cache: it reflects the live feed, or the track /// ended, which makes the cache the whole of it. fn readable(&self) -> bool { self.feed == Feed::Live || self.sealed || self.end.is_some() || self.abort.is_some() } + /// Find the next live group at or after `index` in arrival order. + /// + /// Returns the group and its absolute index so the consumer can advance past it. + /// The cached producer rather than a consumer: `consume` reads the clock and can + /// take the group's own lock, which the caller does once the track guard is gone. fn poll_recv_group(&self, index: usize, min_sequence: u64) -> Poll>> { let start = index.saturating_sub(self.offset); let readable = self.readable(); @@ -1249,8 +1250,8 @@ impl TrackState { self.successor(sequence, servable)?.group.timestamp() } - /// The group after `sequence` that bounds it: the first servable one in `servable`, - /// stamped or not, empty or not. + /// The group after `sequence` that bounds it: the first servable one in `servable` whose + /// first frame opened or that finished, stamped or not, empty or not. fn successor(&self, sequence: u64, servable: &Servable) -> Option<&Slot> { self.find_servable(servable, sequence.checked_add(1)?, false, |slot| { slot.is_shown().then_some(slot) @@ -1258,8 +1259,8 @@ impl TrackState { } /// The group after `sequence` that starts its wall clock: like [`Self::successor`], but - /// counting a group a route is still withholding. Its header arrived, so a relay ages the - /// group before it as the origin does, even if its first frame never comes. + /// counting a group before its first frame. Its header arrived, so a relay ages the group + /// before it as the origin does, even if its first frame never comes. fn arrival(&self, sequence: u64, servable: &Servable) -> Option<&Slot> { self.find_servable(servable, sequence.checked_add(1)?, false, |slot| { slot.is_live().then_some(slot) @@ -1635,10 +1636,23 @@ impl TrackState { } } - /// Drop the open groups nobody will finish now that the track ended abruptly, and - /// keep the finished ones for readers still draining. A consumer that already - /// pulled an open group keeps its own handle and ends with it. - fn drop_open_groups(&mut self, err: StreamError) { + /// End the track abruptly with `err`: drop the open groups nobody will finish, keep the + /// finished ones for readers still draining, and stop protecting the live edge. + /// + /// Returns every unfinished copy, to abort once the track lock is released, so a reader + /// that already pulled one ends with `err` too and its writer fails. + fn tear_down(&mut self, err: Error) -> OpenGroups { + // Snapshot the frame boundary before the open group it may sit in goes away: an + // abrupt end is exactly when a replacement route asks where to resume. + self.resume = self.resume_position(); + let groups = self + .lookup + .values() + .flat_map(Slot::copies) + .filter(|group| !group.is_finished()) + .cloned() + .collect(); + let dropped = StreamError::from(&err); let open: Vec<_> = self .lookup .iter() @@ -1646,11 +1660,10 @@ impl TrackState { .filter_map(|(&sequence, _)| Some(sequence..sequence.checked_add(1)?)) .collect(); for groups in open { - self.drop_groups(groups, err.clone()); + self.drop_groups(groups, dropped.clone()); } self.lookup .retain(|_, slot| slot.copies().any(group::Handle::is_finished)); - self.withheld = self.lookup.values().filter(|slot| slot.pending).count(); let lookup = &self.lookup; self.bounds .get_mut() @@ -1660,12 +1673,13 @@ impl TrackState { .get_mut() .unwrap_or_else(PoisonError::into_inner) .retain(|sequence, _| lookup.contains_key(sequence)); + self.close_cache(); + OpenGroups { groups, err } } - /// Take `sequence` out of the cache, keeping the withheld count in step. + /// Take `sequence` out of the cache, along with its checked start. fn remove_slot(&mut self, sequence: u64) -> Option { let slot = self.lookup.remove(&sequence)?; - self.withheld -= usize::from(slot.pending); self.bounds .get_mut() .unwrap_or_else(PoisonError::into_inner) @@ -1680,6 +1694,10 @@ impl TrackState { /// Record that the live feed delivered `sequence`, then fold the gaps that aged out. fn record_arrival(&mut self, sequence: u64, now: crate::time::Instant) { self.arrivals.account(sequence..sequence.saturating_add(1), now); + // A feed still delivering keeps the gap above its last arrival open. + if self.tail.is_some() { + self.tail = Some(now); + } self.fold_arrivals(now); } @@ -1690,10 +1708,16 @@ impl TrackState { if !self.arrivals.has_gaps() { return; } + self.arrivals.set_grace(self.arrival_grace()); + self.arrivals.expire(now); + } + + /// How long a missing live group is waited for, from the max delay the track's + /// subscribers ask for. + fn arrival_grace(&self) -> Duration { let max_delay = snapshot_subscription(&self.subscriptions, self.max_age_bound()) .map_or(Duration::ZERO, |subscription| subscription.max_delay); - self.arrivals.set_grace(ledger::grace(max_delay)); - self.arrivals.expire(now); + ledger::grace(max_delay) } /// Attach the publisher's immutable metadata without replacing it with local cache policy. @@ -1715,7 +1739,7 @@ impl TrackState { broadcast: broadcast.clone(), ..Default::default() }); - let cache = cache::Track::new(broadcast.pool.clone(), state.downgrade()); + let cache = cache::Track::new(broadcast.pool.clone(), broadcast.frames.clone(), state.downgrade()); state.write().ok().expect("a new track is open").cache = cache; state } @@ -1772,9 +1796,9 @@ impl TrackState { /// Updates the live edge, demoting the previous latest into the eviction order; /// the current latest is never enqueued, which is what protects it from /// eviction. `visible` controls arrival-order delivery: publisher-produced - /// groups reach subscribers, fetched backfill is served by sequence only. A - /// `pending` group joins arrival order only once [`Self::reveal`] shows it. - fn insert_group(&mut self, group: &group::Handle, visible: bool, pending: bool) { + /// groups reach subscribers, fetched backfill is served by sequence only. A group + /// counts as content only once [`Self::reveal`] reports its first frame or finish. + fn insert_group(&mut self, group: &group::Handle, visible: bool) { let sequence = group.sequence; self.next_stamp = self.next_stamp.wrapping_add(1); let stamp = self.next_stamp; @@ -1816,21 +1840,18 @@ impl TrackState { if visible { self.record_arrival(sequence, now); } - self.withheld += usize::from(pending); let replaced = self.lookup.insert( sequence, Slot { group: group.clone(), stamp, visible, - pending, arrived: now, head: None, retired: AtomicBool::new(false), }, ); - if let Some(replaced) = replaced { - self.withheld -= usize::from(replaced.pending); + if replaced.is_some() { self.bounds .get_mut() .unwrap_or_else(PoisonError::into_inner) @@ -1839,46 +1860,28 @@ impl TrackState { // A group inserted with its first frame already written started before it was here. self.index_start(sequence); self.cache.wakes().arrived(sequence..=sequence); - if visible && !pending { + if visible { + // Readers and group demand reach it at once. Its arrival starts the wall clock of + // the reads it succeeds, but it counts as content only once it starts. self.arrival.push_back((sequence, stamp)); - self.landed(sequence); - } else if visible { - // Withheld, but its arrival starts the wall clock of the reads it succeeds. self.wake_landed(sequence); } } - /// Show a [`Producer::receive_group`] group to readers, if `group` still holds its slot. - #[cfg_attr(not(feature = "async"), allow(dead_code))] - fn reveal(&mut self, group: &group::Handle) { + /// Count `group` as content now that its first frame opened or it finished, if it + /// still holds its slot: wake the reads it succeeds. Returns whether an answer waits on + /// it, which the caller shows with [`Self::shown`] under the write lock. + /// + /// Takes the read lock so a group starting wakes only the reads it can move, not every + /// reader parked on the track. + pub(super) fn reveal(&self, group: &group::Handle) -> bool { let sequence = group.sequence; - let Some(slot) = self.lookup.get_mut(&sequence) else { - return; - }; - if !slot.pending || !slot.group.is_clone(group) { - return; + match self.lookup.get(&sequence) { + Some(slot) if slot.visible && slot.group.is_clone(group) && !slot.group.is_aborted() => {} + _ => return false, } - slot.pending = false; - self.withheld -= 1; - self.arrival.push_back((sequence, slot.stamp)); - // A group reset before its first frame shows nothing of the route's feed. - if slot.group.is_aborted() { - return; - } - let latest = slot.group.latest(); - self.landed(sequence); - // Its frames presented while hidden, so a read woken by them may have judged the - // older edge and parked again: present them once more now that they count. - if let Some(latest) = latest { - self.cache.wakes().presented(latest); - } - } - - /// Content at `sequence` became servable: wake the reads it succeeds, and show an answer - /// waiting on it. - fn landed(&mut self, sequence: u64) { self.wake_landed(sequence); - self.shown(sequence); + matches!(self.feed, Feed::Answered { from } if sequence >= from) } /// Wake the reads a group landing at `sequence` succeeds. @@ -1894,7 +1897,7 @@ impl TrackState { } /// Content at `sequence` became readable: an answer waiting on it now shows. - fn shown(&mut self, sequence: u64) { + pub(super) fn shown(&mut self, sequence: u64) { if let Feed::Answered { from } = self.feed && sequence >= from { @@ -1905,9 +1908,9 @@ impl TrackState { /// Admit a freshly-created group: settle eviction debt first (so the newcomer /// can never be a victim of the very write that created it), insert it, then /// expire idle groups. - fn commit_group(&mut self, group: &group::Handle, pending: bool) { + fn commit_group(&mut self, group: &group::Handle) { self.charge_debt(); - self.insert_group(group, true, pending); + self.insert_group(group, true); self.evict_expired(); } @@ -2100,11 +2103,20 @@ impl TrackState { /// declaration: the signal is scoped to the current subscription's demand, /// which may legitimately move in either direction. `None` clears it (the /// demand dropped to the live edge, whose floor is unknown until declared). + /// + /// A declared start asks the feed for every group from it, so a gap in the arrivals at + /// or above it, and a pending tail above the last arrival, is waited for a fresh grace: + /// the feed may only now be sending it. fn set_start(&mut self, start_sequence: Option, pending: bool) { self.start_sequence = start_sequence; self.start_pending = pending; if let Some(start) = start_sequence { self.cache.wakes().arrived(..start); + let now = self.cache.pool().now_wall(); + self.arrivals.demand(start..u64::MAX, now); + if self.tail.is_some() { + self.tail = Some(now); + } } } @@ -2155,8 +2167,8 @@ impl TrackState { /// Whether the track has reached its end: the final boundary is set and the live /// edge has caught up to it, so no further group can arrive. A future boundary /// (declared via [`Producer::finish_at`] ahead of the live edge) stays incomplete - /// until the remaining groups are produced, or until the last producer drops without - /// them. Drives the end-of-stream signal from + /// until the remaining groups are produced, the last producer drops without them, or, + /// on a received copy, the grace for them passes. Drives the end-of-stream signal from /// the read methods (`recv_group` / `next_group` / `read_frame` return `None`). /// /// An abort before the end settled wins over it: a group below the boundary was @@ -2167,10 +2179,16 @@ impl TrackState { let reached = self.sealed || self .final_sequence() - .is_some_and(|fin| self.edge() >= fin && !self.withholds() && !self.awaits_tail(fin)); + .is_some_and(|fin| self.reaches(fin) && !self.awaits_tail(fin)); reached && (self.abort.is_none() || self.settled) } + /// Whether the live edge reached `fin`, or a received copy's tail decides it instead: + /// what it still misses up to `fin` is waited for only as long as the grace. + fn reaches(&self, fin: u64) -> bool { + self.edge() >= fin || self.tail.is_some() + } + /// Whether the largest can no longer advance while a producer is still held: the track /// reached its declared end, and the largest group's content is final. Every sequence below /// the end raised it already, and a group name fixes its content, so no legal write moves @@ -2184,14 +2202,6 @@ impl TrackState { self.max_sequence.map_or(0, |max| max.saturating_add(1)) } - /// Whether a cached group is still withheld from readers until its first frame lands - /// (see [`Producer::receive_group`]): the end is not reached before it shows, or - /// readers would end without it. Every cached group sits below a declared end. - fn withholds(&self) -> bool { - debug_assert_eq!(self.withheld, self.lookup.values().filter(|slot| slot.pending).count()); - self.withheld > 0 - } - /// Whether a group below `fin` the wire subscription still owes has yet to arrive. /// Only such a hole holds readers, so a tail with nothing missing ends them at once. fn awaits_tail(&self, fin: u64) -> bool { @@ -2199,26 +2209,60 @@ impl TrackState { self.abort.is_none() && self.owes(fin) } - /// Whether the pending tail misses a sequence from where the feed starts up to `fin`: - /// one no live group or datagram delivered, in a gap younger than the grace. - /// - /// Judged by the arrivals, not the cache, so an evicted group or a datagram counts - /// as delivered, and the check costs the same however much is cached. + /// Whether the tail misses a sequence from where the feed starts up to `fin` that is + /// still worth waiting for; see [`Self::tail_deadline`]. fn owes(&self, fin: u64) -> bool { - if !self.tail_pending { - return false; - } + self.tail_deadline(fin) + .is_some_and(|at| self.cache.pool().now_wall() < at) + } + + /// When a received copy's declared end stops waiting for its tail: the latest instant a + /// sequence below `fin` it still misses is given up. `None` when nothing is missing. + /// + /// A missing sequence is one no live group or datagram delivered and the publisher did + /// not drop. A gap below an arrival is given up a grace after that arrival opened it, as + /// the session's tail does. The gap above the last arrival is given up a grace after + /// the end or a start was declared, or a group last arrived, so a feed still delivering toward an + /// end declared ahead of it is not cut off. Judged by the arrivals, not the cache, so an evicted group or a + /// datagram counts as delivered, and the check costs the same however much is cached. + fn tail_deadline(&self, fin: u64) -> Option { + let active = self.tail?; + let grace = self.arrival_grace(); // Fetched backfill never reaches a reader in arrival order, so only the live feed's // arrivals count. Without a declared start, the first one stands in for it. let floor = match self.start_sequence { Some(start) => start, - None if self.start_pending => return true, - None => match self.arrivals.first() { - Some(first) => first, - None => return fin > 0, - }, + // Where the feed starts is still unknown, so everything below the end not yet + // delivered or dropped is owed. + None if self.start_pending => { + let missing = self + .arrivals + .gaps(0..fin) + .any(|(gap, _)| self.drops.gaps(&gap).next().is_some()); + return missing.then(|| active.checked_add(grace)).flatten(); + } + None => self.arrivals.first().unwrap_or(0), }; - !self.arrivals.covers(floor.min(fin)..fin) + let owed = floor.min(fin)..fin; + let top = self.arrivals.end().unwrap_or(0)..fin; + self.arrivals + .folds(grace) + .chain(active.checked_add(grace).map(|at| (top, at))) + .filter(|(gap, _)| { + let gap = gap.start.max(owed.start)..gap.end.min(owed.end); + !gap.is_empty() && self.drops.gaps(&gap).next().is_some() + }) + .map(|(_, at)| at) + .max() + } + + /// Wake `waiter` when a received copy's declared end stops waiting for its tail. + fn watch_tail(&self, waiter: &kio::Waiter) { + if let Some(at) = self.final_sequence().and_then(|fin| self.tail_deadline(fin)) + && self.cache.pool().now_wall() < at + { + self.cache.watch_wall(at, waiter); + } } /// Whether the declared end is reached, the pending tail owes nothing below it, and @@ -2230,7 +2274,7 @@ impl TrackState { let Some(fin) = self.final_sequence() else { return false; }; - let reached = self.sealed || self.edge() >= fin; + let reached = self.sealed || self.reaches(fin); reached && (self.abort.is_none() || self.settled) && !self.owes(fin) @@ -2344,7 +2388,7 @@ impl TrackState { .lookup .iter() .rev() - .find(|(_, slot)| slot.visible && !slot.pending)?; + .find(|(_, slot)| slot.visible && slot.group.is_started())?; Some((*sequence, slot.group.frame_count() as u64)) } @@ -2384,9 +2428,10 @@ impl TrackState { } /// Abort shared track state without extending its publisher lifetime. + #[cfg_attr(not(feature = "async"), allow(dead_code))] // pending: /quest/m1/public-model/deferred.md pub(crate) fn abort(producer: &kio::Producer, err: Error) -> Result<()> { - commit_abort(Self::modify(producer)?, err); + commit_abort(Self::modify(producer)?, err).abort(); Ok(()) } @@ -2453,32 +2498,45 @@ impl TrackState { } // Invisible to arrival-order subscribers: fetched on demand, not produced // live by the publisher. - None => self.insert_group(&group.handle(), false, false), + None => self.insert_group(&group.handle(), false), } self.evict_expired(); Ok(group) } } -/// Record `err` and close the track: the shared tail of [`Producer::abort`] and -/// [`Producer::abort_unused`]. -fn commit_abort(mut state: kio::Mut<'_, TrackState>, err: Error) { - // Snapshot the frame boundary before the open group it may sit in goes away: an - // abort is exactly when a replacement route asks where to resume. - state.resume = state.resume_position(); +/// Record `err` and close the track, the shared tail of every abort, returning the open +/// groups to abort once the guard is gone. +fn commit_abort(mut state: kio::Mut<'_, TrackState>, err: Error) -> OpenGroups { // Decided before the open groups go: the groups below the end are the evidence. A gap // past the grace was lost before the abort rather than cut off by it. let now = state.cache.pool().now_wall(); state.fold_arrivals(now); state.settled = state.is_settled(); - let dropped = StreamError::from(&err); - state.abort = Some(err); + state.abort = Some(err.clone()); // Keep what finished for consumers still draining: they get it, then the abort (or // the clean end, when the end settled). Clearing here would abort finished groups a // slower reader has not pulled yet. The pool's idle expiry bounds how long they stay. - state.drop_open_groups(dropped); - state.close_cache(); + let open = state.tear_down(err); state.close(); + open +} + +/// The unfinished groups a teardown took out of the track, aborted once the track lock +/// is released. +#[must_use = "abort the open groups after releasing the track lock"] +struct OpenGroups { + groups: Vec, + err: Error, +} + +impl OpenGroups { + /// End each group with the teardown's error: its readers end and its writer fails. + fn abort(self) { + for group in self.groups { + let _ = group.abort(self.err.clone()); + } + } } /// A reader's local group bounds: the floor, and the exclusive cap (`None` for none). @@ -2522,18 +2580,24 @@ fn poll_largest( /// Ready once the track's feed is live, or nothing more can move its largest. A declared /// end that is not reached yet does not count: an idle copy's largest is still only what /// its ended feed left. -fn largest_live(state: &TrackState) -> Poll<()> { +fn largest_live(state: &TrackState, waiter: &kio::Waiter) -> Poll<()> { match state.feed == Feed::Live || state.sealed || state.abort.is_some() || state.largest_settled() { true => Poll::Ready(()), - false => Poll::Pending, + false => { + state.watch_tail(waiter); + Poll::Pending + } } } /// Ready once the track's largest can no longer advance; see [`TrackState::largest_settled`]. -fn largest_ended(state: &TrackState) -> Poll<()> { +fn largest_ended(state: &TrackState, waiter: &kio::Waiter) -> Poll<()> { match state.largest_settled() { true => Poll::Ready(()), - false => Poll::Pending, + false => { + state.watch_tail(waiter); + Poll::Pending + } } } @@ -2635,34 +2699,11 @@ impl Producer { } /// Create a new group with the given sequence number. - pub fn create_group(&self, group: group::Info) -> Result { - self.insert(group, false) - } - - /// Create a group a session is receiving from a route, withheld from readers until - /// [`Self::reveal_group`]. /// - /// A publisher writes a group's first frame as it creates it, but a route's group - /// header lands before its first frame. Shown in between, it would leave the group - /// before it with no stamped successor, so a joiner at the live edge would be handed - /// that older group first. - #[cfg_attr(not(feature = "async"), allow(dead_code))] - // pending: /quest/m1/public-model/ingest.md - pub(crate) fn receive_group(&self, group: group::Info) -> Result { - self.insert(group, true) - } - - /// Show a [`Self::receive_group`] group to readers: its first frame landed, or its - /// stream ended. A no-op once another incarnation took its sequence. - #[cfg_attr(not(feature = "async"), allow(dead_code))] - // pending: /quest/m1/public-model/ingest.md - pub(crate) fn reveal_group(&self, group: &group::Handle) { - if let Ok(mut state) = self.modify() { - state.reveal(group); - } - } - - fn insert(&self, group: group::Info, pending: bool) -> Result { + /// Readers and group demand reach it at once, but the track counts it as content (its + /// live edge, or the successor that ages the group before it) only once its first frame + /// opens or it finishes. + pub fn create_group(&self, group: group::Info) -> Result { let mut state = self.modify()?; // A sealed track takes no group, not even one below its end. if state.sealed || state.final_sequence().is_some_and(|fin| group.sequence >= fin) { @@ -2675,7 +2716,7 @@ impl Producer { let group = group::Producer::new(group, track, state.cache.clone()).with_meter(self.stats.meter()); state.cap(&group.handle())?; - state.commit_group(&group.handle(), pending); + state.commit_group(&group.handle()); Ok(group) } @@ -2698,7 +2739,7 @@ impl Producer { let group = group::Producer::new(group::Info { sequence }, track, state.cache.clone()).with_meter(self.stats.meter()); state.cap(&group.handle())?; - state.commit_group(&group.handle(), false); + state.commit_group(&group.handle()); Ok(group) } @@ -2865,36 +2906,19 @@ impl Producer { Ok(()) } - /// End a locally closed session's receive track without declaring a wire boundary. - #[cfg_attr(not(feature = "async"), allow(dead_code))] - // pending: /quest/m1/public-model/ingest.md - pub(crate) fn close(self) -> Result<()> { + /// End the track without declaring where it ends, as a closed session does. + /// + /// Consumers drain the groups that finished and then end cleanly. The open groups are + /// aborted with [`Error::SessionClosed`], so a consumer that already pulled one ends + /// with it and their writers fail. A reader following the track's routes resumes from + /// another one where this copy stopped. Use [`Self::finish`] or [`Self::finish_at`] + /// when the end is known. + pub fn close(self) -> Result<()> { let mut state = self.modify()?; state.sealed = true; - // See `commit_abort`: a takeover resumes mid-group once the open group goes away. - state.resume = state.resume_position(); - state.drop_open_groups(StreamError::from(&Error::SessionClosed)); - state.close_cache(); + let open = state.tear_down(Error::SessionClosed); state.close(); - Ok(()) - } - - /// Abort the groups still receiving from a failed session before ending its track. - #[cfg_attr(not(feature = "async"), allow(dead_code))] - // pending: /quest/m1/public-model/ingest.md - pub(crate) fn abort_session(self, err: Error) -> Result<()> { - let state = self.modify()?; - let open: Vec<_> = state - .lookup - .values() - .filter(|slot| !slot.group.is_finished()) - .map(|slot| slot.group.clone()) - .collect(); - // Snapshot the resume boundary before aborting groups releases their frames. - commit_abort(state, err.clone()); - for group in open { - let _ = group.abort(err.clone()); - } + open.abort(); Ok(()) } @@ -2926,20 +2950,15 @@ impl Producer { /// already exists is [`Error::ProtocolViolation`]. Consumers only see end-of-stream /// once the live edge reaches the end's group. Use [`Self::finish`] to finish exactly /// at the live edge. - pub fn finish_at(&mut self, end: Position) -> Result<()> { - self.modify()?.set_end(end) - } - - /// [`Self::finish_at`] for a wire subscription that may still owe groups below the end. /// - /// The end and the pending tail land in one write: a reader that saw the end without - /// the tail would end at a hole the wire is still filling. Repeating the declared end - /// is a no-op, and a mid-group end may refine a group boundary it falls just before - /// (a FETCH_OK names only the boundary). Any other second end is - /// [`Error::ProtocolViolation`]. - #[cfg_attr(not(feature = "async"), allow(dead_code))] - // pending: /quest/m1/public-model/ingest.md - pub(crate) fn finish_at_pending(&mut self, end: Position) -> Result<()> { + /// Repeating the declared end is a no-op, and a mid-group end may refine the group + /// boundary it falls just before (a peer may name only the boundary first). Any other + /// second end is [`Error::ProtocolViolation`]. + /// + /// On a [received](Self::received) copy, groups below the end may still be in flight: + /// readers wait for a missing one until a grace passes, the subscription's max delay + /// or one second without one, before ending at the boundary. + pub fn finish_at(&mut self, end: Position) -> Result<()> { let mut state = self.modify()?; match state.end { Some(declared) if declared == end => return Ok(()), @@ -2953,24 +2972,10 @@ impl Producer { Some(_) => return Err(Error::ProtocolViolation), None => state.set_end(end)?, } - state.tail_pending = true; - Ok(()) - } - - /// Whether a wire subscription still owes group streams below the declared end. - /// - /// While pending, readers do not end at the boundary: a lower group's stream may - /// arrive after a higher one. The session clears it once its tail settles; the last - /// producer going ends readers regardless. - #[cfg_attr(not(feature = "async"), allow(dead_code))] - // pending: /quest/m1/public-model/ingest.md - pub(crate) fn set_tail_pending(&self, pending: bool) { - if self.state.read().tail_pending == pending { - return; - } - if let Ok(mut state) = self.modify() { - state.tail_pending = pending; + if state.received && state.tail.is_none() { + state.tail = Some(state.cache.pool().now_wall()); } + Ok(()) } /// Declare the first group the live feed serves (the wire's SUBSCRIBE_START, @@ -2983,16 +2988,26 @@ impl Producer { /// earlier, and a narrowed subscription skips groups an earlier declaration /// still promised. Pass `None` to clear it, for demand at the live edge: /// its floor is unknown until the feed declares one. + /// + /// Resolves a start left pending by [`Request::request_start`]. pub fn start_at(&mut self, sequence: impl Into>) -> Result<()> { self.modify()?.set_start(sequence.into(), false); Ok(()) } - /// Record sequences the upstream publisher explicitly gave up with `err`, ending the - /// groups still arriving in them with it. - #[cfg_attr(not(feature = "async"), allow(dead_code))] - // pending: /quest/m1/public-model/ingest.md - pub(crate) fn drop_groups(&self, groups: ops::Range, err: StreamError) { + /// Mark this track as a copy received from a remote publisher, before writing to it. + /// + /// Its declared end waits for groups still in flight below it; see [`Self::finish_at`]. + pub fn received(&self) { + if let Ok(mut state) = self.modify() { + state.received = true; + } + } + + /// Record that the publisher gave up `groups` with `err`: none will arrive, so a reader + /// waiting on one moves past it, a group still arriving in them ends with `err`, the + /// declared end does not wait for them, and a relay serving this track forwards the drop. + pub fn drop_groups(&self, groups: ops::Range, err: StreamError) { if groups.is_empty() { return; } @@ -3019,17 +3034,6 @@ impl Producer { } } - /// Restart the age of every arrival gap reaching into `groups`, which the live feed's - /// subscription newly asks for. - #[cfg_attr(not(feature = "async"), allow(dead_code))] - // pending: /quest/m1/public-model/ingest.md - pub(crate) fn demand_arrivals(&self, groups: ops::Range) { - if let Ok(mut state) = self.modify() { - let now = state.cache.pool().now_wall(); - state.arrivals.demand(groups, now); - } - } - /// Readers get nothing from the cache until [`Self::set_live`]: the upstream /// subscription ended with this copy still held, so what it cached may go stale. #[cfg_attr(not(feature = "async"), allow(dead_code))] @@ -3075,12 +3079,10 @@ impl Producer { state.idle_newest.filter(|_| state.feed == Feed::Idle) } - /// Declare the floor a subscription asked for while the serving session has yet to - /// resolve its start: nothing below `sequence` arrives, exactly as [`Self::start_at`], - /// but [`Subscriber::poll_start`] keeps waiting until a later [`Self::start_at`] - /// resolves it. + /// [`Request::request_start`] for a copy already accepted, which a held copy's next + /// subscription asks for again. #[cfg_attr(not(feature = "async"), allow(dead_code))] - // pending: /quest/m1/public-model/ingest.md + // private: capability gap pub(crate) fn request_start(&mut self, sequence: Option) -> Result<()> { self.modify()?.set_start(sequence, true); Ok(()) @@ -3106,10 +3108,11 @@ impl Producer { /// Abort the track with the given error. /// /// Consumes the handle, since nothing can be written to an aborted track. Consumers - /// still draining get the finished groups, then the abort error. Open groups leave the - /// cache; a consumer that already pulled one keeps its own handle and ends with it. - /// The pool's idle expiry (see [`cache::Config::with_expiry`]) reclaims the rest, the - /// latest group included, so a stale [`Consumer`] can't pin them in memory forever. + /// still draining get the finished groups, then the abort error. Open groups, fetched + /// copies included, are aborted with the same error and leave the cache, so a consumer + /// that already pulled one ends with it too, and their writers fail. The pool's idle expiry (see + /// [`cache::Config::with_expiry`]) reclaims the rest, the latest group included, so a + /// stale [`Consumer`] can't pin them in memory forever. /// /// If the declared end had settled (the final sequence from /// [`finish_at`](Self::finish_at) was reached and every group below it finished), @@ -3120,7 +3123,8 @@ impl Producer { pub fn abort(self, err: Error) -> Result<()> { // Unlisted first, so the track leaves the listing before its name is free again. self.alive.unlist(); - TrackState::abort(&self.state, err) + commit_abort(self.modify()?, err).abort(); + Ok(()) } /// Abort an unused track, returning the producer unchanged if consumers remain. @@ -3130,6 +3134,9 @@ impl Producer { /// the track is closed, including when it was already closed; existing handles /// may still observe its final state. `Err(producer)` leaves the track unchanged /// so the caller can continue serving and wait for the next unused wake. + /// + /// The abort is the same as [`Self::abort`]: a group consumer that outlived the track's + /// consumers ends with `err`, and the group's writer fails. #[expect( clippy::result_large_err, reason = "return the owned producer without allocating on an idle check" @@ -3137,7 +3144,7 @@ impl Producer { pub fn abort_unused(self, err: Error) -> std::result::Result<(), Self> { let used = match self.state.write_unused() { kio::Unused::Idle(guard) => { - commit_abort(guard, err); + commit_abort(guard, err).abort(); false } kio::Unused::Closed => false, @@ -3183,8 +3190,8 @@ impl Producer { &mut self.largest, Bounds::default(), waiter, - |waiter| state.poll(waiter, |state| largest_live(state)).map(|_| ()), - |waiter| state.poll(waiter, |state| largest_ended(state)).map(|_| ()), + |waiter| state.poll(waiter, |state| largest_live(state, waiter)).map(|_| ()), + |waiter| state.poll(waiter, |state| largest_ended(state, waiter)).map(|_| ()), ) } @@ -3194,13 +3201,30 @@ impl Producer { kio::wait(|waiter| self.poll_largest(waiter)).await } - /// Ready once the track holds a group past `sequence`, or is closed. + /// Ready once the track holds content past `sequence`, or is closed: a later group whose + /// first frame opened or that finished, or a later datagram. A frameless group header + /// does not count, since nothing says the copy reached it yet. #[cfg_attr(not(feature = "async"), allow(dead_code))] // private: capability gap pub(crate) fn poll_past(&self, sequence: u64, waiter: &kio::Waiter) -> Poll<()> { - let past = self.state.poll_ref(waiter, |state| match state.max_sequence { - Some(latest) if latest > sequence => Poll::Ready(()), - _ => Poll::Pending, + let Some(next) = sequence.checked_add(1) else { + return Poll::Pending; + }; + let past = self.state.poll_ref(waiter, |state| { + if state.shows(next) { + return Poll::Ready(()); + } + // A group starting wakes no reader parked on the track, so wait on each one past + // it that has yet to start. + let started = state + .lookup + .range(next..) + .filter(|(_, slot)| slot.is_live()) + .any(|(_, slot)| slot.group.poll_started(waiter).is_ready() && !slot.group.is_aborted()); + match started { + true => Poll::Ready(()), + false => Poll::Pending, + } }); past.map(|_| ()) } @@ -3573,10 +3597,9 @@ impl Drop for Alive { track = %self.name, "track::Producer dropped without finish() or abort()" ); - // See `abort`: keep the frame boundary once its open group goes away. - state.resume = state.resume_position(); - state.drop_open_groups(StreamError::from(&Error::Dropped)); - state.close_cache(); + let open = state.tear_down(Error::Dropped); + drop(state); + open.abort(); } Err(state) => { if state.sealed || state.end.is_some() || state.abort.is_some() { @@ -3752,7 +3775,7 @@ impl TrackWeak { }; match producer.write_unused() { kio::Unused::Idle(guard) => { - commit_abort(guard, err); + commit_abort(guard, err).abort(); true } kio::Unused::Closed => true, @@ -4529,8 +4552,8 @@ impl Consumer { seen, bounds, waiter, - |waiter| state.poll(waiter, |state| largest_live(state)).map(|_| ()), - |waiter| state.poll(waiter, |state| largest_ended(state)).map(|_| ()), + |waiter| state.poll(waiter, |state| largest_live(state, waiter)).map(|_| ()), + |waiter| state.poll(waiter, |state| largest_ended(state, waiter)).map(|_| ()), ), } }) @@ -4590,6 +4613,7 @@ impl Consumer { if state.end.is_some() && state.is_complete() { Poll::Ready(()) } else { + state.watch_tail(waiter); Poll::Pending } })) { @@ -5806,7 +5830,15 @@ impl Cursor { where F: Fn(&kio::Ref<'_, TrackState>) -> Poll>, { - Poll::Ready(match ready!(self.state.poll(waiter, f)) { + let polled = self.state.poll(waiter, |state| { + let res = f(state); + if res.is_pending() { + // The end can settle with no write: when the grace for a missing group passes. + state.watch_tail(waiter); + } + res + }); + Poll::Ready(match ready!(polled) { Ok(res) => res, // We try to clone abort just in case the function forgot to check for terminal state. Err(state) => Err(state.abort.clone().unwrap_or(Error::Dropped)), @@ -6880,8 +6912,8 @@ impl Subscriber { seen, bounds, waiter, - |waiter| state.poll(waiter, |state| largest_live(state)).map(|_| ()), - |waiter| state.poll(waiter, |state| largest_ended(state)).map(|_| ()), + |waiter| state.poll(waiter, |state| largest_live(state, waiter)).map(|_| ()), + |waiter| state.poll(waiter, |state| largest_ended(state, waiter)).map(|_| ()), ) } Inner::Resume(resume, _) => resume.poll_largest(seen, bounds, waiter), @@ -7082,12 +7114,62 @@ impl Ordered { } } +/// A requested track being written before any subscriber sees it; see [`Request::stage`]. +/// +/// Write through it as through the [`Producer`] it derefs to. Subscribers waiting on the +/// request resolve only at [`Self::commit`], with everything written by then. Dropping it +/// uncommitted rejects the request with [`Error::Dropped`]. +#[must_use = "a staged track is rejected unless committed"] +pub struct Staged { + // Taken only by `commit`. + producer: Option, + // The request's fetch claim, held until the track is published like an unanswered + // request's: a cache miss meanwhile waits rather than racing its own handler. + _dynamic: Dynamic, +} + +impl Staged { + /// Publish the track: every waiting subscriber resolves now, with what was written. + pub fn commit(mut self) -> Producer { + let producer = self.producer.take().expect("taken only by commit"); + if let Ok(mut state) = producer.state.write() { + state.staged = false; + } + producer + } +} + +impl ops::Deref for Staged { + type Target = Producer; + + fn deref(&self) -> &Producer { + self.producer.as_ref().expect("taken only by commit") + } +} + +impl ops::DerefMut for Staged { + fn deref_mut(&mut self) -> &mut Producer { + self.producer.as_mut().expect("taken only by commit") + } +} + +impl Drop for Staged { + fn drop(&mut self) { + let Some(producer) = self.producer.take() else { + return; + }; + // Aborted like the producer it derefs to, so a group written through it ends too. + let _ = producer.abort(Error::Dropped); + } +} + /// A subscriber asked for a track this broadcast doesn't have yet. /// /// Yielded by [`poll_requested_track`](crate::broadcast::Dynamic::poll_requested_track), /// or created up front with [`broadcast::Producer::reserve_track`](crate::broadcast::Producer::reserve_track). /// Subscribers block until the request is -/// resolved: call [`accept`](Self::accept) to serve it with a [`Producer`], or +/// resolved: call [`accept`](Self::accept) to serve it with a [`Producer`] (or +/// [`stage`](Self::stage) to write content before they see it), or /// [`reject`](Self::reject) to fail them. Dropping it without either rejects with /// [`Error::Dropped`]. /// @@ -7116,9 +7198,12 @@ pub struct Request { // unless this request was reserved on a tagged broadcast. stats: stats::Scope, - // The serving session resolves the start of each subscription itself, so the - // accepted track's start is unknown until it says (see [`Self::resolving_start`]). - resolving_start: bool, + // The floor the accepted track's start is pending at, until the source resolves it + // (see [`Self::request_start`]). + requested_start: Option>, + + // Whether the accepted track starts idle; see [`Self::idle`]. + idle: bool, // Served from a front's routes; see [`Self::routes`]. routes: Option, @@ -7141,7 +7226,8 @@ impl Request { alive, _dynamic: dynamic, stats: stats::Scope::default(), - resolving_start: false, + requested_start: None, + idle: false, routes: None, list: None, } @@ -7161,14 +7247,25 @@ impl Request { self } - /// Mark the track as served by a session that resolves each subscription's start - /// (lite-06+), so [`Subscriber::poll_start`] waits for its declaration instead of - /// reading the requested floor as the start. Applied atomically with - /// [`Self::accept`], before any reader can see the track. + /// Accept the track with its start pending at `floor`, the first group its source was + /// asked for (`None` for the live edge), until the source says where its feed starts + /// with [`Producer::start_at`]. + /// + /// Nothing below `floor` arrives, as with [`Producer::start_at`], and groups are read + /// as they arrive, but a relay serving the track waits for the resolved start before + /// declaring its own. Applied atomically with [`Self::accept`], before any reader can + /// see the track. + pub fn request_start(mut self, floor: impl Into>) -> Self { + self.requested_start = Some(floor.into()); + self + } + + /// Accept the track idle, as a copy that no live feed fills yet: readers get nothing + /// from it until the feed goes live. Applied atomically with [`Self::accept`]. #[cfg_attr(not(feature = "async"), allow(dead_code))] - // pending: /quest/m1/public-model/ingest.md - pub(crate) fn resolving_start(mut self) -> Self { - self.resolving_start = true; + // private: capability gap + pub(crate) fn idle(mut self) -> Self { + self.idle = true; self } @@ -7235,7 +7332,7 @@ impl Request { pub(crate) fn reject_unused(&self, err: Error) -> bool { match self.state.write_unused() { kio::Unused::Idle(guard) => { - commit_abort(guard, err); + commit_abort(guard, err).abort(); true } kio::Unused::Closed => true, @@ -7249,14 +7346,32 @@ impl Request { /// (`None` for the defaults). If the track was already aborted, the returned /// [`Producer`] is inert: writes fail with the abort error, as if it had been /// aborted immediately after accepting. + /// + /// The same as [`Self::stage`] followed by [`Staged::commit`]. pub fn accept(self, info: impl Into>) -> Producer { + self.stage(info).commit() + } + + /// Mint the track's [`Producer`] without resolving any subscriber yet, so content + /// written through the returned [`Staged`] is there when the first reader looks. + /// + /// For a relay that already holds groups of the track: write them, then + /// [`Staged::commit`]. Dropping the [`Staged`] uncommitted rejects the request with + /// [`Error::Dropped`]. + pub fn stage(self, info: impl Into>) -> Staged { let info = info.into().unwrap_or_default(); // A closed state means the track was aborted under us. Mirror `reject` and // tolerate it: the Producer we hand back simply can't write. let open = match self.state.write() { Ok(mut state) => { state.accept(info.clone()); - state.start_pending = self.resolving_start; + state.staged = true; + if let Some(floor) = self.requested_start { + state.set_start(floor, true); + } + if self.idle { + state.set_idle(); + } state.routes = self.routes; true } @@ -7269,15 +7384,18 @@ impl Request { if let Some(list) = self.list.filter(|_| open) { self.alive.list(list.list(&info)); } - Producer { - name: self.name, - info, - broadcast: self.broadcast, - state: self.state, - prev_subscription: None, - alive: self.alive, - stats: self.stats, - largest: None, + Staged { + producer: Some(Producer { + name: self.name, + info, + broadcast: self.broadcast, + state: self.state, + prev_subscription: None, + alive: self.alive, + stats: self.stats, + largest: None, + }), + _dynamic: self._dynamic, } } @@ -8229,13 +8347,10 @@ mod test { .unwrap(); let handle = group.handle(); let _partial = group - .create_frame_owned( - frame::Info { - size: 2, - timestamp: Some(Timestamp::ZERO), - }, - &frame::Budget::default(), - ) + .create_frame(frame::Info { + size: 2, + timestamp: Some(Timestamp::ZERO), + }) .unwrap(); assert_eq!(handle.frame_count(), 2); drop(_partial); @@ -8769,7 +8884,7 @@ mod test { #[test] fn streaming_frame_writes_keep_the_group_alive() { let producer = track_producer("test", Info::timed()); - let mut straggler = producer.create_group(0u64.into()).unwrap(); + let straggler = producer.create_group(0u64.into()).unwrap(); // The live edge moves on, so the straggler is demoted and expirable. producer.create_group(1u64.into()).unwrap().finish().unwrap(); @@ -8786,7 +8901,7 @@ mod test { frame.write(bytes::Bytes::from_static(b"x")).unwrap(); producer.create_group(seq.into()).unwrap().finish().unwrap(); } - frame.finish().unwrap(); + let mut straggler = frame.finish().unwrap(); straggler.finish().unwrap(); let state = producer.state.read(); @@ -8808,20 +8923,17 @@ mod test { producer.create_group(1u64.into()).unwrap().finish().unwrap(); let mut frame = straggler - .create_frame_owned( - frame::Info { - size: 3, - timestamp: Some(Timestamp::ZERO), - }, - &Default::default(), - ) + .create_frame(frame::Info { + size: 3, + timestamp: Some(Timestamp::ZERO), + }) .unwrap(); // The sender stalls past the retention window, then the whole payload lands in // one poll turn: the loop never returns `Pending`, so `notify` is never reached // and `finish` is the only write the charge sees. elapse(&producer, cache::DEFAULT_EXPIRY + Duration::from_secs(1)); - frame.write(bytes::Bytes::from_static(b"abc")).unwrap(); + frame.write_deferred(bytes::Bytes::from_static(b"abc")).unwrap(); let mut straggler = frame.finish().unwrap(); straggler.finish().unwrap(); @@ -9089,7 +9201,7 @@ mod test { fn streaming_frame_write_expires_idle_siblings() { let producer = track_producer_expiring("test", Duration::from_secs(1)); producer.append_group().unwrap().finish().unwrap(); // seq 0 - let mut live = producer.append_group().unwrap(); // seq 1 + let live = producer.append_group().unwrap(); // seq 1 let mut frame = live .create_frame(frame::Info { size: 1, @@ -9245,11 +9357,11 @@ mod test { } } - /// A route's successor whose header landed but whose first frame never does still - /// starts the wall clock, so a relay ages the group before it as the origin does. + /// A successor whose header landed but whose first frame never does still starts the + /// wall clock, so a relay ages the group before it as the origin does. #[moq_clock::test] #[cfg(feature = "async")] - async fn a_withheld_successor_ages_its_predecessor() { + async fn a_frameless_successor_ages_its_predecessor() { for info in [Info::default(), Info::timed()] { let producer = track_producer("test", info.clone()); let at = info.timescale.map(|_| Timestamp::ZERO); @@ -9263,7 +9375,7 @@ mod test { let woken = Arc::new(std::sync::atomic::AtomicBool::new(false)); let waiter = kio::Waiter::new(futures::task::waker(Arc::new(FlagWake(woken.clone())))); assert!(reading.poll_read_frame(&waiter).is_pending()); - let _successor = producer.receive_group(group::Info { sequence: 1 }).unwrap(); + let _successor = producer.create_group(group::Info { sequence: 1 }).unwrap(); assert!( woken.swap(false, Ordering::SeqCst), "{info:?}: the header never woke the read" @@ -9513,12 +9625,11 @@ mod test { producer.set_idle(); open.abort(Error::Cancel).unwrap(); - let mut answer = producer.receive_group(group::Info { sequence: 2 }).unwrap(); + let mut answer = producer.create_group(group::Info { sequence: 2 }).unwrap(); producer.set_live(Some(Position::group(2)), None); answer .write_frame(Timestamp::from_millis(533).unwrap(), bytes::Bytes::from_static(b"")) .unwrap(); - producer.reveal_group(&answer.handle()); let mut subscriber = producer.subscribe(Subscription::default().with_max_delay(Duration::from_millis(400))); assert_eq!(drain(&mut subscriber), vec![2]); @@ -9542,12 +9653,11 @@ mod test { let waiter = kio::Waiter::noop(); assert!(subscriber.poll_drop(&waiter).is_pending(), "nothing was given up"); - let mut again = producer.receive_group(group::Info { sequence: 1 }).unwrap(); + let mut again = producer.create_group(group::Info { sequence: 1 }).unwrap(); producer.set_live(Some(Position::group(1)), None); again .write_frame(Timestamp::from_millis(1000).unwrap(), bytes::Bytes::from_static(b"x")) .unwrap(); - producer.reveal_group(&again.handle()); assert_eq!(drain(&mut subscriber), vec![0, 1]); assert!(subscriber.poll_drop(&waiter).is_pending(), "nothing was given up"); } @@ -10147,9 +10257,9 @@ mod test { ); } - /// A received group's frames present while it is hidden, so a parked read they wake - /// still sees the older edge and parks again. Revealing the group has to wake it once - /// more, though the read sits below the group's nearest shown predecessor. + /// A group's header lands before its first frame, which moves no edge. The first frame + /// has to wake a parked read it expires, though the read sits below the group's nearest + /// started predecessor. #[test] #[cfg(feature = "async")] fn revealing_a_presented_group_wakes_a_read_it_expires() { @@ -10175,18 +10285,17 @@ mod test { let mut next = std::pin::pin!(held.read_frame()); assert!(next.as_mut().poll(&mut cx).is_pending()); - let mut received = producer.receive_group(group::Info { sequence: 2 }).unwrap(); - received - .write_frame(Timestamp::from_millis(2000).unwrap(), bytes::Bytes::from_static(b"x")) - .unwrap(); + let mut received = producer.create_group(group::Info { sequence: 2 }).unwrap(); woken.store(false, Ordering::SeqCst); assert!( next.as_mut().poll(&mut cx).is_pending(), - "the hidden group moves no edge" + "the frameless group moves no edge" ); - producer.reveal_group(&received.handle()); - assert!(woken.load(Ordering::SeqCst), "the reveal wakes the expired read"); + received + .write_frame(Timestamp::from_millis(2000).unwrap(), bytes::Bytes::from_static(b"x")) + .unwrap(); + assert!(woken.load(Ordering::SeqCst), "the first frame wakes the expired read"); let result = next.as_mut().poll(&mut cx); assert!( matches!(result, Poll::Ready(Err(Error::Old))), @@ -10195,70 +10304,92 @@ mod test { } /// A route can declare the end, then land every group's header before its first frame. - /// Those groups are withheld until their frames land, so the end is not reached before - /// they show: a reader ending at the boundary would never see them. + /// Readers reach those groups at once, and the end with them, but nothing counts a + /// frameless group as content: the track shows nothing past the first until it starts. #[test] #[cfg(feature = "async")] - fn a_withheld_group_holds_the_end() { + fn a_frameless_group_does_not_count_as_content() { let mut producer = track_producer("test", crate::track::Info::timed()); let mut subscriber = producer.subscribe(Subscription::default().with_max_delay(Duration::from_secs(60))); producer.finish_at(Position::group(2)).unwrap(); let mut received: Vec<_> = (0..2) - .map(|sequence| producer.receive_group(group::Info { sequence }).unwrap()) + .map(|sequence| producer.create_group(group::Info { sequence }).unwrap()) .collect(); + let mut first = subscriber.assert_group(); + let mut second = subscriber.assert_group(); + assert_eq!((first.sequence, second.sequence), (0, 1)); + assert!(subscriber.recv_group().now_or_never().unwrap().unwrap().is_none()); + + let waiter = kio::Waiter::noop(); assert!( - subscriber.recv_group().now_or_never().is_none(), - "the end waits for the withheld groups" + producer.poll_past(0, &waiter).is_pending(), + "a frameless group is not content" ); - for group in &mut received { group .write_frame(Timestamp::ZERO, bytes::Bytes::from_static(b"x")) .unwrap(); - producer.reveal_group(&group.handle()); } - assert_eq!(subscriber.assert_group().sequence, 0); - assert_eq!(subscriber.assert_group().sequence, 1); - assert!(subscriber.recv_group().now_or_never().unwrap().unwrap().is_none()); + assert!( + producer.poll_past(0, &waiter).is_ready(), + "its first frame makes it content" + ); + assert!(first.read_frame().now_or_never().unwrap().unwrap().is_some()); + assert!(second.read_frame().now_or_never().unwrap().unwrap().is_some()); } - /// A withheld group whose stream ends with no frame, cleanly or reset, shows when it - /// ends, which wakes a reader parked on the end. + /// A parked `poll_past` wakes when a later group starts, not when its header lands. + #[test] + fn poll_past_wakes_when_a_later_group_starts() { + use std::sync::atomic::{AtomicBool, Ordering}; + + let producer = track_producer("test", Info::timed()); + let woken = Arc::new(AtomicBool::new(false)); + let waiter = kio::Waiter::new(futures::task::waker(Arc::new(FlagWake(woken.clone())))); + assert!(producer.poll_past(0, &waiter).is_pending()); + + let mut group = producer.create_group(group::Info { sequence: 1 }).unwrap(); + woken.store(false, Ordering::SeqCst); + assert!( + producer.poll_past(0, &waiter).is_pending(), + "a frameless header is not content" + ); + group + .write_frame(Timestamp::ZERO, bytes::Bytes::from_static(b"x")) + .unwrap(); + assert!(woken.load(Ordering::SeqCst), "its first frame wakes the parked poll"); + assert!(producer.poll_past(0, &waiter).is_ready()); + } + + /// A frameless group whose stream ends with no frame, cleanly or reset, ends its readers + /// with it, and the track's end follows. #[moq_clock::test] #[cfg(feature = "async")] - async fn a_withheld_group_that_ends_empty_releases_the_end() { + async fn a_frameless_group_that_ends_empty_ends_its_readers() { for abort in [false, true] { let mut producer = track_producer("test", None); let mut subscriber = producer.subscribe(Subscription::default().with_max_delay(Duration::from_secs(60))); producer.finish_at(Position::group(1)).unwrap(); - let mut group = producer.receive_group(group::Info { sequence: 0 }).unwrap(); - let handle = group.handle(); + let mut group = producer.create_group(group::Info { sequence: 0 }).unwrap(); + let mut reading = subscriber.assert_group(); + assert_eq!(reading.sequence, 0); - let first = { - let mut next = std::pin::pin!(subscriber.recv_group()); - assert!( - futures::poll!(next.as_mut()).is_pending(), - "the end waits for the group" - ); + let ended = { + let mut next = std::pin::pin!(reading.read_frame()); + assert!(futures::poll!(next.as_mut()).is_pending(), "the group is still open"); match abort { true => group.abort(Error::Cancel).unwrap(), false => group.finish().unwrap(), } - producer.reveal_group(&handle); moq_clock::timeout(Duration::from_secs(1), next) .await - .expect("the reveal wakes the reader") - .unwrap() + .expect("the end wakes the reader") }; - match abort { - // A cancelled group shows nothing, so the reader ends. - true => assert!(first.is_none()), - false => { - assert_eq!(first.expect("the empty group").sequence, 0); - assert!(subscriber.recv_group().now_or_never().unwrap().unwrap().is_none()); - } + true => assert!(matches!(ended, Err(Error::Cancel)), "{ended:?}"), + false => assert!(matches!(ended, Ok(None)), "{ended:?}"), } + assert!(subscriber.recv_group().now_or_never().unwrap().unwrap().is_none()); } } @@ -10440,7 +10571,7 @@ mod test { async fn a_handed_out_partial_frame_expires_while_its_payload_is_stalled() { let mut producer = track_producer("test", Info::timed()); let mut subscriber = producer.subscribe(None); - let mut source = producer.append_group().unwrap(); + let source = producer.append_group().unwrap(); let mut writing = source .create_frame(frame::Info { size: 6, @@ -10557,12 +10688,12 @@ mod test { assert_eq!(drain(&mut sub), vec![1, 2]); } - /// An unstamped immediate successor leaves a group's reach unbounded: a later - /// stamped group proves nothing about where the successor will begin, and - /// shrinking the bound is the unsafe direction. + /// A frameless successor is not content, so the next started group bounds the group + /// before it. That bound is sound: the frameless group's first frame is checked to start + /// at or below the next group's, so the true reach can only be earlier. #[test] #[cfg(feature = "async")] - fn an_unstamped_immediate_successor_leaves_reach_unbounded() { + fn a_frameless_successor_leaves_the_next_started_group_as_the_bound() { let mut producer = track_producer("test", Info::timed()); // Any budget, so only media time judges: the wall clock stands still here. let mut subscriber = producer.subscribe(Subscription::default().with_max_delay(Duration::from_millis(500))); @@ -10572,10 +10703,8 @@ mod test { append_at(&mut producer, 10_000); // seq 2 append_at(&mut producer, 11_000); // seq 3 - // Group 1's reach is group 2's start, a second behind the edge: stale. - // Group 0's reach is unknown until group 1 presents its first frame, so it is - // kept rather than convicted on a bound that could shrink the wrong way. - assert_eq!(drain(&mut subscriber), vec![0, 2, 3]); + // Groups 0 and 1 both reach at most group 2's start, a second behind the edge: stale. + assert_eq!(drain(&mut subscriber), vec![2, 3]); } fn untimed_producer() -> Producer { @@ -10818,23 +10947,21 @@ mod test { assert_eq!(drain_ordered(&mut replay), vec![0, 1, 2, 3]); } - /// A group whose immediate successor has not presented a frame has no proven reach, - /// so nothing says its frames are too old and the ordered cursor keeps it. + /// The ordered cursor judges a group past a frameless successor by the next started one. #[test] #[cfg(feature = "async")] - fn next_group_keeps_a_group_with_no_proven_reach() { + fn next_group_judges_past_a_frameless_successor() { let mut producer = track_producer("test", Info::timed()); append_at(&mut producer, 0); // seq 0 let _writer_1 = producer.append_group().unwrap(); // seq 1 stalls before its first frame append_at(&mut producer, 10_000); // seq 2 append_at(&mut producer, 11_000); // seq 3 - // Group 1 reaches 10s, a second behind the edge: convicted. Group 0 is bounded - // only by group 1, which has yet to say where it begins, and arrived just now. + // Groups 0 and 1 reach at most 10s, a second behind the edge: convicted. let mut subscriber = producer .subscribe(Subscription::default().with_max_delay(Duration::from_millis(500))) .ordered(); - assert_eq!(drain_ordered(&mut subscriber), vec![0, 2, 3]); + assert_eq!(drain_ordered(&mut subscriber), vec![2, 3]); } #[test] @@ -10936,6 +11063,46 @@ mod test { ); } + /// A start requested before the accept holds a reader of the start from the moment the + /// track is visible, while its groups are read as they arrive, until the source + /// resolves it. + #[test] + #[cfg(feature = "async")] + fn a_requested_start_waits_for_the_source() { + let waiter = kio::Waiter::noop(); + let request = Request::new(Arc::new(broadcast::Info::default()), "test"); + let consumer = request.consume(); + let mut producer = request.request_start(2).accept(None); + let mut subscriber = consumer.subscribe(None).now_or_never().unwrap().unwrap(); + assert!( + subscriber.poll_start(&waiter).is_pending(), + "the floor is not the start" + ); + + // Nothing below the floor is waited for, and a group above it reads at once. + producer + .create_group(group::Info { sequence: 3 }) + .unwrap() + .finish() + .unwrap(); + assert_eq!(subscriber.assert_group().sequence, 3); + assert!(subscriber.poll_start(&waiter).is_pending()); + + producer.start_at(3).unwrap(); + assert_eq!(subscriber.poll_start(&waiter), Poll::Ready(Some(3))); + } + + /// A copy accepted idle is never readable as live in between. + #[test] + fn an_idle_accept_is_not_live() { + let request = Request::new(Arc::new(broadcast::Info::default()), "test"); + let consumer = request.consume(); + let mut producer = request.idle().accept(None); + assert!(!consumer.is_live(), "idle from the accept"); + producer.set_live(None, None); + assert!(consumer.is_live()); + } + /// A fetched group installs metadata but never accepts the track's live feed. #[test] fn a_fetch_only_cache_is_not_live() { @@ -11559,6 +11726,119 @@ mod test { assert!(matches!(result, Err(Error::Dropped))); } + /// Aborting a track aborts its open groups: a reader that already pulled one ends with + /// the error, and the group's writer fails. + #[test] + #[cfg(feature = "async")] + fn abort_ends_a_pulled_open_group() { + let producer = track_producer("test", Info::timed()); + let mut consumer = producer.subscribe(None); + let mut writer = producer.append_group().unwrap(); + writer + .write_frame(Timestamp::ZERO, bytes::Bytes::from_static(b"x")) + .unwrap(); + let mut group = consumer.assert_group(); + assert!(group.read_frame().now_or_never().unwrap().unwrap().is_some()); + + producer.clone().abort(Error::Cancel).unwrap(); + let read = group.read_frame().now_or_never().expect("should not block"); + assert!(matches!(read, Err(Error::Cancel)), "{read:?}"); + let write = writer.write_frame(Timestamp::ZERO, bytes::Bytes::from_static(b"y")); + assert!(matches!(write, Err(Error::Cancel)), "{write:?}"); + } + + /// Closing a track aborts its open groups like [`Producer::abort`], with + /// [`Error::SessionClosed`]. + #[test] + #[cfg(feature = "async")] + fn close_ends_a_pulled_open_group() { + let producer = track_producer("test", Info::timed()); + let mut consumer = producer.subscribe(None); + let mut writer = producer.append_group().unwrap(); + writer + .write_frame(Timestamp::ZERO, bytes::Bytes::from_static(b"x")) + .unwrap(); + let mut group = consumer.assert_group(); + assert!(group.read_frame().now_or_never().unwrap().unwrap().is_some()); + + producer.close().unwrap(); + let read = group.read_frame().now_or_never().expect("should not block"); + assert!(matches!(read, Err(Error::SessionClosed)), "{read:?}"); + let write = writer.write_frame(Timestamp::ZERO, bytes::Bytes::from_static(b"y")); + assert!(matches!(write, Err(Error::SessionClosed)), "{write:?}"); + } + + /// Aborting an unused track aborts an open group whose reader outlived the track's + /// consumers. + #[test] + #[cfg(feature = "async")] + fn abort_unused_ends_a_pulled_open_group() { + let producer = track_producer("test", Info::timed()); + let mut consumer = producer.subscribe(None); + let mut writer = producer.append_group().unwrap(); + writer + .write_frame(Timestamp::ZERO, bytes::Bytes::from_static(b"x")) + .unwrap(); + let mut group = consumer.assert_group(); + assert!(group.read_frame().now_or_never().unwrap().unwrap().is_some()); + drop(consumer); + + assert!(producer.abort_unused(Error::Cancel).is_ok()); + let read = group.read_frame().now_or_never().expect("should not block"); + assert!(matches!(read, Err(Error::Cancel)), "{read:?}"); + let write = writer.write_frame(Timestamp::ZERO, bytes::Bytes::from_static(b"y")); + assert!(matches!(write, Err(Error::Cancel)), "{write:?}"); + } + + /// Dropping the last producer without a finish aborts its open groups with + /// [`Error::Dropped`]. + #[test] + #[cfg(feature = "async")] + fn drop_unfinished_ends_a_pulled_open_group() { + let producer = track_producer("test", Info::timed()); + let mut consumer = producer.subscribe(None); + let mut writer = producer.append_group().unwrap(); + writer + .write_frame(Timestamp::ZERO, bytes::Bytes::from_static(b"x")) + .unwrap(); + let mut group = consumer.assert_group(); + assert!(group.read_frame().now_or_never().unwrap().unwrap().is_some()); + + drop(producer); + let read = group.read_frame().now_or_never().expect("should not block"); + assert!(matches!(read, Err(Error::Dropped)), "{read:?}"); + let write = writer.write_frame(Timestamp::ZERO, bytes::Bytes::from_static(b"y")); + assert!(matches!(write, Err(Error::Dropped)), "{write:?}"); + } + + /// Aborting a track also aborts a fetched head still being written, so its reader ends + /// with the track's error rather than waiting on a fetch that can no longer land. + #[moq_clock::test] + #[cfg(feature = "async")] + async fn abort_ends_an_open_fetched_head() { + let producer = track_producer("test", Info::timed()); + let dynamic = producer.dynamic(); + let consumer = producer.consume(); + let mut live = producer.create_group(group::Info { sequence: 0 }).unwrap(); + live.start_at(1).unwrap(); + live.write_frame(Timestamp::ZERO, bytes::Bytes::from_static(b"delta")) + .unwrap(); + + let _fetch = consumer.fetch_group(0, None); + let request = dynamic.requested_group().await.unwrap(); + let mut head = request.accept(Info::timed()).unwrap(); + head.write_frame(Timestamp::ZERO, bytes::Bytes::from_static(b"snapshot")) + .unwrap(); + let mut reading = consumer.peek_group(0).expect("the head serves group 0"); + assert!(reading.read_frame().now_or_never().unwrap().unwrap().is_some()); + + producer.abort(Error::App(7)).unwrap(); + let read = reading.read_frame().now_or_never().expect("the abort settles the head"); + assert!(matches!(read, Err(Error::App(7))), "{read:?}"); + let write = head.write_frame(Timestamp::ZERO, bytes::Bytes::from_static(b"delta")); + assert!(matches!(write, Err(Error::App(7))), "{write:?}"); + } + #[test] fn drop_after_abort_does_not_warn() { // abort() closes the channel after recording `abort`. Drop must treat the @@ -11692,8 +11972,10 @@ mod test { assert_eq!(producer.end(), Some(Position::group(6))); - // Re-finishing is rejected, and no group at or above the boundary can be created. - assert!(producer.finish_at(Position::group(6)).is_err()); + // Repeating the end is a no-op, moving it is rejected, and no group at or above the + // boundary can be created. + assert!(producer.finish_at(Position::group(6)).is_ok()); + assert!(producer.finish_at(Position::group(7)).is_err()); assert!(producer.create_group(group::Info { sequence: 4 }).is_ok()); assert!(producer.create_group(group::Info { sequence: 6 }).is_err()); } @@ -11703,14 +11985,13 @@ mod test { let pool = cache::Pool::new(cache::Config::default().with_expiry(Duration::from_secs(1))); let mut producer = track_producer_pooled("test", pool.clone()); let end = Position { group: 5, frame: 5 }; - producer.finish_at_pending(end).unwrap(); + producer.finish_at(end).unwrap(); let mut group = producer.create_group(group::Info { sequence: 5 }).unwrap(); for _ in 0..5 { group.write_frame(Timestamp::ZERO, b"x".as_slice()).unwrap(); } group.finish().unwrap(); let consumer = producer.consume(); - producer.set_tail_pending(false); drop(producer); // Date the last activity before advancing the cache clock past expiry. pool.sweep(); @@ -11729,15 +12010,12 @@ mod test { fn a_wire_end_repeats_or_refines_but_never_moves() { let mut producer = track_producer("test", Info::timed()); // A FETCH_OK names only the boundary; END_OF_TRACK may then name the frame before it. - producer.finish_at_pending(Position::group(6)).unwrap(); - producer.finish_at_pending(Position { group: 5, frame: 5 }).unwrap(); - producer.finish_at_pending(Position { group: 5, frame: 5 }).unwrap(); + producer.finish_at(Position::group(6)).unwrap(); + producer.finish_at(Position { group: 5, frame: 5 }).unwrap(); + producer.finish_at(Position { group: 5, frame: 5 }).unwrap(); assert_eq!(producer.end(), Some(Position { group: 5, frame: 5 })); for moved in [Position { group: 5, frame: 4 }, Position::group(6), Position::group(5)] { - assert!(matches!( - producer.finish_at_pending(moved), - Err(Error::ProtocolViolation) - )); + assert!(matches!(producer.finish_at(moved), Err(Error::ProtocolViolation))); } } @@ -11784,6 +12062,8 @@ mod test { .is_ok() ); assert!(matches!(group.write_frames(&mut frames), Err(Error::Closed))); + assert_eq!(group.frame_count(), 2); + // A refused frame aborts its group, since a write past the end is a bug. assert!(matches!( group.create_frame(frame::Info { size: 1, @@ -11791,7 +12071,6 @@ mod test { }), Err(Error::Closed) )); - assert_eq!(group.frame_count(), 2); assert!(producer.create_group(group::Info { sequence: 6 }).is_err()); } } @@ -11891,17 +12170,18 @@ mod test { )); } - /// A wire subscription's pending tail holds readers at a hole below the end, since a - /// lower group's stream may arrive after a higher one, until the hole fills or the tail - /// settles. The last producer going ends them regardless. + /// A received copy's end holds readers at a hole below it, since a lower group's stream + /// may arrive after a higher one, until the hole fills or its grace passes. The last + /// producer going ends them regardless. #[moq_clock::test] #[cfg(feature = "async")] async fn a_pending_tail_holds_readers_at_a_hole() { let mut producer = track_producer("test", None); + producer.received(); let mut arrival = producer.subscribe(replay()); // The wire declares where the feed starts. producer.start_at(0).unwrap(); - producer.finish_at_pending(Position::group(3)).unwrap(); + producer.finish_at(Position::group(3)).unwrap(); let _high = producer.create_group(group::Info { sequence: 2 }).unwrap(); assert_eq!(arrival.assert_group().sequence, 2); assert!(arrival.recv_group().now_or_never().is_none(), "held at the hole"); @@ -11914,39 +12194,214 @@ mod test { assert_eq!(arrival.assert_group().sequence, 1); assert!(arrival.recv_group().now_or_never().unwrap().unwrap().is_none()); - // A settled tail ends readers at the boundary, hole and all. + // The grace passing ends readers at the boundary, hole and all. let mut producer = track_producer("test", None); + producer.received(); let mut arrival = producer.subscribe(replay()); producer.start_at(0).unwrap(); - producer.finish_at_pending(Position::group(2)).unwrap(); + producer.finish_at(Position::group(2)).unwrap(); let _high = producer.create_group(group::Info { sequence: 1 }).unwrap(); assert_eq!(arrival.assert_group().sequence, 1); assert!(arrival.recv_group().now_or_never().is_none()); - producer.set_tail_pending(false); + // The subscription's max delay is the grace. + elapse(&producer, replay().max_delay); assert!(arrival.recv_group().now_or_never().unwrap().unwrap().is_none()); // So does the last producer going. let mut producer = track_producer("test", None); + producer.received(); let mut arrival = producer.subscribe(replay()); producer.start_at(0).unwrap(); - producer.finish_at_pending(Position::group(2)).unwrap(); + producer.finish_at(Position::group(2)).unwrap(); let _high = producer.create_group(group::Info { sequence: 1 }).unwrap(); assert_eq!(arrival.assert_group().sequence, 1); drop(producer); assert!(arrival.recv_group().now_or_never().unwrap().unwrap().is_none()); } + /// The grace alone ends a reader parked at a hole, with no write to wake it: below an + /// arrival it runs from that arrival, and above the last one from the declared end. + #[moq_clock::test] + #[cfg(feature = "async")] + async fn a_parked_reader_wakes_when_the_tail_grace_passes() { + // The subscription's max delay is the grace. + let grace = replay().max_delay; + // Hole 0 sits below arrival 1; holes 2..4 sit above the last arrival. + for (end, arrived_late) in [(2, false), (4, true)] { + let mut producer = track_producer("test", None); + producer.received(); + elapse(&producer, Duration::ZERO); + let mut arrival = producer.subscribe(replay()); + producer.start_at(0).unwrap(); + producer + .create_group(group::Info { sequence: 1 }) + .unwrap() + .finish() + .unwrap(); + assert_eq!(arrival.assert_group().sequence, 1); + if arrived_late { + // The end comes later than the arrival, so its gap runs from the end. + elapse(&producer, grace / 2); + } + producer.finish_at(Position::group(end)).unwrap(); + + let woken = Arc::new(std::sync::atomic::AtomicBool::new(false)); + let waiter = kio::Waiter::new(futures::task::waker(Arc::new(FlagWake(woken.clone())))); + assert!( + arrival.poll_recv_group(&waiter).is_pending(), + "end {end}: held at the hole" + ); + elapse(&producer, grace - Duration::from_millis(1)); + assert!(!woken.load(Ordering::SeqCst), "end {end}: woken before the grace"); + assert!(arrival.poll_recv_group(&waiter).is_pending()); + elapse(&producer, Duration::from_millis(1)); + assert!( + woken.load(Ordering::SeqCst), + "end {end}: the grace never woke the reader" + ); + assert!(matches!(arrival.poll_recv_group(&waiter), Poll::Ready(Ok(None)))); + } + } + + /// An end declared ahead of a feed still delivering does not cut it off: each arrival + /// restarts the grace for the groups above it. A feed that stalls past it ends readers. + #[test] + #[cfg(feature = "async")] + fn a_delivering_feed_holds_an_end_declared_ahead() { + let mut producer = track_producer("test", None); + producer.received(); + let grace = replay().max_delay; + let mut arrival = producer.subscribe(replay()); + producer.start_at(0).unwrap(); + producer.finish_at(Position::group(5)).unwrap(); + for sequence in 0..3 { + elapse(&producer, grace / 2); + producer + .create_group(group::Info { sequence }) + .unwrap() + .finish() + .unwrap(); + assert_eq!(arrival.assert_group().sequence, sequence); + } + elapse(&producer, grace - Duration::from_millis(1)); + assert!(arrival.recv_group().now_or_never().is_none(), "still within the grace"); + elapse(&producer, Duration::from_millis(1)); + assert!(arrival.recv_group().now_or_never().unwrap().unwrap().is_none()); + } + + /// A start declared after the end asks the feed for groups it may only now send, so the + /// tail above the last arrival waits a fresh grace from it, not what is left of the end's. + #[test] + #[cfg(feature = "async")] + fn a_late_start_restarts_the_tail_grace() { + let mut producer = track_producer("test", None); + producer.received(); + let grace = replay().max_delay; + let mut arrival = producer.subscribe(replay()); + producer.finish_at(Position::group(2)).unwrap(); + elapse(&producer, grace - Duration::from_millis(1)); + producer.start_at(0).unwrap(); + elapse(&producer, Duration::from_millis(1)); + assert!(arrival.recv_group().now_or_never().is_none(), "a fresh grace"); + elapse(&producer, grace - Duration::from_millis(1)); + assert!(arrival.recv_group().now_or_never().unwrap().unwrap().is_none()); + } + + /// Only a received copy waits for its tail: a local publisher's end below a hole ends + /// readers once the edge reaches it, as the publisher skipped the group. + #[test] + #[cfg(feature = "async")] + fn a_local_end_does_not_wait_for_a_tail() { + let mut producer = track_producer("test", None); + let mut arrival = producer.subscribe(replay()); + producer.start_at(0).unwrap(); + producer.finish_at(Position::group(2)).unwrap(); + producer + .create_group(group::Info { sequence: 1 }) + .unwrap() + .finish() + .unwrap(); + assert_eq!(arrival.assert_group().sequence, 1); + assert!(arrival.recv_group().now_or_never().unwrap().unwrap().is_none()); + } + + /// A group the publisher dropped is not in flight, so it holds no reader at the end. + #[test] + #[cfg(feature = "async")] + fn a_dropped_group_fills_the_tail() { + let mut producer = track_producer("test", None); + producer.received(); + let mut arrival = producer.subscribe(replay()); + producer.start_at(0).unwrap(); + producer.finish_at(Position::group(3)).unwrap(); + producer + .create_group(group::Info { sequence: 2 }) + .unwrap() + .finish() + .unwrap(); + assert_eq!(arrival.assert_group().sequence, 2); + assert!(arrival.recv_group().now_or_never().is_none(), "held at the hole"); + producer.drop_groups(0..2, StreamError::NotFound); + assert!(arrival.recv_group().now_or_never().unwrap().unwrap().is_none()); + } + + /// While the start is pending, everything below the end is owed, but only what has + /// not arrived or been dropped: an end with nothing missing below it ends readers at once. + #[test] + #[cfg(feature = "async")] + fn a_pending_start_owes_nothing_already_accounted_for() { + // An end before the first group owes nothing. + let mut producer = track_producer("test", None); + producer.received(); + producer.request_start(None).unwrap(); + let mut arrival = producer.subscribe(replay()); + producer.finish_at(Position::group(0)).unwrap(); + assert!(arrival.recv_group().now_or_never().unwrap().unwrap().is_none()); + + // Nor does one whose groups below it all arrived or were dropped. + let mut producer = track_producer("test", None); + producer.received(); + producer.request_start(None).unwrap(); + let mut arrival = producer.subscribe(replay()); + producer + .create_group(group::Info { sequence: 0 }) + .unwrap() + .finish() + .unwrap(); + assert_eq!(arrival.assert_group().sequence, 0); + producer.drop_groups(1..2, StreamError::NotFound); + producer.finish_at(Position::group(2)).unwrap(); + assert!(arrival.recv_group().now_or_never().unwrap().unwrap().is_none()); + + // A hole is still owed until the grace passes. + let mut producer = track_producer("test", None); + producer.received(); + producer.request_start(None).unwrap(); + let mut arrival = producer.subscribe(replay()); + producer + .create_group(group::Info { sequence: 1 }) + .unwrap() + .finish() + .unwrap(); + assert_eq!(arrival.assert_group().sequence, 1); + producer.finish_at(Position::group(2)).unwrap(); + assert!(arrival.recv_group().now_or_never().is_none(), "group 0 is owed"); + elapse(&producer, replay().max_delay); + assert!(arrival.recv_group().now_or_never().unwrap().unwrap().is_none()); + } + /// A fetched copy of a group the live feed still owes never reaches an arrival-order /// reader, so it does not fill the hole: the reader waits for the live group. #[moq_clock::test] #[cfg(feature = "async")] async fn a_fetched_group_does_not_fill_a_pending_tail() { let mut producer = track_producer("test", None); + producer.received(); let dynamic = producer.dynamic(); let consumer = producer.consume(); let mut arrival = producer.subscribe(None); producer.start_at(0).unwrap(); - producer.finish_at_pending(Position::group(2)).unwrap(); + producer.finish_at(Position::group(2)).unwrap(); let _high = producer.create_group(group::Info { sequence: 1 }).unwrap(); assert_eq!(arrival.assert_group().sequence, 1); @@ -11965,9 +12420,10 @@ mod test { #[cfg(feature = "async")] async fn an_abort_errors_a_pending_tail_short_of_a_group() { let mut producer = track_producer("test", None); + producer.received(); let mut arrival = producer.subscribe(None); producer.start_at(0).unwrap(); - producer.finish_at_pending(Position::group(2)).unwrap(); + producer.finish_at(Position::group(2)).unwrap(); let mut high = producer.create_group(group::Info { sequence: 1 }).unwrap(); high.finish().unwrap(); assert_eq!(arrival.assert_group().sequence, 1); @@ -11986,9 +12442,10 @@ mod test { #[cfg(feature = "async")] async fn an_abort_after_a_full_tail_ends_cleanly() { let mut producer = track_producer("test", None); + producer.received(); let mut arrival = producer.subscribe(replay()); producer.start_at(0).unwrap(); - producer.finish_at_pending(Position::group(2)).unwrap(); + producer.finish_at(Position::group(2)).unwrap(); for sequence in [1, 0] { producer .create_group(group::Info { sequence }) @@ -12009,9 +12466,10 @@ mod test { async fn an_abort_past_the_grace_ends_a_pending_tail_cleanly() { for (waited, ended) in [(ledger::GRACE / 2, false), (ledger::GRACE, true)] { let mut producer = track_producer("test", None); + producer.received(); let mut arrival = producer.subscribe(None); producer.start_at(0).unwrap(); - producer.finish_at_pending(Position::group(3)).unwrap(); + producer.finish_at(Position::group(3)).unwrap(); for sequence in [0, 2] { producer .create_group(group::Info { sequence }) @@ -12035,9 +12493,10 @@ mod test { #[cfg(feature = "async")] fn an_evicted_group_still_fills_a_pending_tail() { let mut producer = track_producer("test", None); + producer.received(); let mut arrival = producer.subscribe(replay()); producer.start_at(0).unwrap(); - producer.finish_at_pending(Position::group(3)).unwrap(); + producer.finish_at(Position::group(3)).unwrap(); for sequence in [0, 1] { producer .create_group(group::Info { sequence }) @@ -12062,9 +12521,10 @@ mod test { #[cfg(feature = "async")] fn a_datagram_fills_a_pending_tail() { let mut producer = track_producer("test", None); + producer.received(); let mut arrival = producer.subscribe(replay()); producer.start_at(0).unwrap(); - producer.finish_at_pending(Position::group(2)).unwrap(); + producer.finish_at(Position::group(2)).unwrap(); producer.insert_datagram(0, None, b"x".as_slice()).unwrap(); producer .create_group(group::Info { sequence: 1 }) @@ -12082,19 +12542,17 @@ mod test { #[cfg(feature = "async")] async fn an_end_after_the_highest_group_holds_the_reader() { let mut producer = track_producer("test", None); + producer.received(); let mut arrival = producer.subscribe(replay()); producer.start_at(0).unwrap(); let _high = producer.create_group(group::Info { sequence: 2 }).unwrap(); assert_eq!(arrival.assert_group().sequence, 2); assert!(arrival.recv_group().now_or_never().is_none()); - producer.finish_at_pending(Position::group(3)).unwrap(); + producer.finish_at(Position::group(3)).unwrap(); assert!(arrival.recv_group().now_or_never().is_none(), "held at the hole"); assert!( - matches!( - producer.finish_at_pending(Position::group(2)), - Err(Error::ProtocolViolation) - ), + matches!(producer.finish_at(Position::group(2)), Err(Error::ProtocolViolation)), "a second end is refused" ); assert_eq!(producer.end(), Some(Position::group(3)), "the first end stands"); @@ -12151,6 +12609,26 @@ mod test { assert!(matches!(consumer.recv_group().await, Err(Error::Timeout))); } + /// A close drops a group still open that no reader pulled: readers drain the finished + /// groups, then end without a declared end. + #[moq_clock::test] + #[cfg(feature = "async")] + async fn local_close_drops_an_unpulled_open_group() { + let producer = track_producer("local", Info::timed()); + let mut consumer = producer.consume().subscribe(None).await.unwrap(); + producer.append_group().unwrap().finish().unwrap(); + let mut open = producer.append_group().unwrap(); + open.write_frame(Timestamp::ZERO, bytes::Bytes::from_static(b"x")) + .unwrap(); + producer.clone().close().unwrap(); + assert_eq!( + consumer.recv_group().await.unwrap().map(|group| group.sequence), + Some(0) + ); + assert!(consumer.recv_group().await.unwrap().is_none()); + assert!(matches!(consumer.finished().await, Err(Error::Closed))); + } + /// A local close is a dead route to the origin, not finished content, so a /// replacement route can take over where it left off. #[test] @@ -14930,10 +15408,10 @@ mod test { } /// Lowering the floor re-offers only what the arrival walk could have read: a fetched - /// group stays out of arrival order, and a withheld one waits until it is revealed. + /// group stays out of arrival order, while a live one is offered before its first frame. #[moq_clock::test] #[cfg(feature = "async")] - async fn a_lowered_floor_reoffers_neither_fetched_nor_withheld_groups() { + async fn a_lowered_floor_reoffers_live_groups_but_not_fetched_ones() { let (producer, _pool) = pooled_producer(1 << 40); let dynamic = producer.dynamic(); let consumer = producer.consume(); @@ -14953,19 +15431,13 @@ mod test { .unwrap(); fetched.finish().unwrap(); pending.await.unwrap(); - let mut withheld = producer.receive_group(group::Info { sequence: 3 }).unwrap(); + let _frameless = producer.create_group(group::Info { sequence: 3 }).unwrap(); subscriber.update(replay().with_groups(0..)).unwrap(); + assert_eq!(subscriber.assert_group().sequence, 3, "offered before its first frame"); subscriber.assert_no_group(); - withheld - .write_frame(Timestamp::from_millis(3).unwrap(), bytes::Bytes::from_static(b"x")) - .unwrap(); - producer.reveal_group(&withheld.handle()); - assert_eq!(subscriber.assert_group().sequence, 3, "shown once revealed"); - subscriber.assert_no_group(); - - // A cursor floor lowered before the next read counts only shown groups as unread. + // A cursor floor lowered before the next read counts only walked groups as unread. let mut lowered = producer.subscribe(replay()); lowered.start_at(5); assert_eq!(lowered.assert_group().sequence, 5); @@ -15831,7 +16303,8 @@ mod test { assert_eq!(frames.len(), 1, "the batch is left to retry"); assert_eq!(batched.frame_count(), 0); - let mut streamed = producer.append_group().unwrap(); + let streamed = producer.append_group().unwrap(); + let handle = streamed.handle(); let refused = streamed .create_frame(frame::Info { size: 1, @@ -15839,7 +16312,8 @@ mod test { }) .err(); assert!(matches!(refused, Some(Error::TimestampMismatch)), "{refused:?}"); - assert_eq!(streamed.frame_count(), 0); + assert_eq!(handle.frame_count(), 0); + assert!(handle.is_aborted(), "a refused frame aborts its group"); } /// Eviction is not a sequence prefix: a group stamped after its predecessor was evicted diff --git a/rs/moq-net/src/recv.rs b/rs/moq-net/src/recv.rs index 28331f4cb9b..d005fd209c9 100644 --- a/rs/moq-net/src/recv.rs +++ b/rs/moq-net/src/recv.rs @@ -1,6 +1,6 @@ //! Receive-side ownership: a cancelled handler explicitly aborts its unfinished group. //! -//! Frames need no guard here: `frame::Raw`'s own `Drop` already aborts the group when a +//! Frames need no guard here: `frame::Producer`'s own `Drop` already aborts the group when a //! frame dies before its declared size is written, so a partial frame is never silent. use std::ops::{Deref, DerefMut}; @@ -22,16 +22,12 @@ impl Group { } /// Move the writer and cancellation cleanup into its next frame. - pub fn create_frame_owned( - &mut self, - frame: impl Into, - budget: &frame::Budget, - ) -> Result { + pub fn create_object(&mut self, frame: frame::Header) -> Result { self.writer .take() .expect("group writer is available between frames") - .create_frame_owned(frame, budget) - .map(frame::ProducerOwned::cancel_on_drop) + .create_object(frame) + .map(frame::Producer::cancel_on_drop) } /// Restore the writer returned by a completed frame. @@ -103,12 +99,12 @@ mod tests { let mut consumer = producer.consume(); let mut receiving = Group::new(producer); let frame = receiving - .create_frame_owned( + .create_object( crate::frame::Info { size: 2, timestamp: Some(crate::Timestamp::ZERO), - }, - &crate::frame::Budget::default(), + } + .into(), ) .unwrap(); drop(frame); @@ -124,12 +120,12 @@ mod tests { let mut consumer = producer.consume(); let mut receiving = Group::new(producer); let frame = receiving - .create_frame_owned( + .create_object( crate::frame::Info { size: 2, timestamp: Some(crate::Timestamp::ZERO), - }, - &crate::frame::Budget::default(), + } + .into(), ) .unwrap(); receiving.abort(Error::App(42)).unwrap(); diff --git a/rs/moq-net/src/tail.rs b/rs/moq-net/src/tail.rs index f7ca6c2f63b..8e8a8b41f26 100644 --- a/rs/moq-net/src/tail.rs +++ b/rs/moq-net/src/tail.rs @@ -12,9 +12,9 @@ use std::{ops::Range, task::Poll, time::Duration}; -pub(crate) use crate::model::ledger::{GRACE, grace}; +pub(crate) use crate::ledger::{GRACE, grace}; use crate::{ - model::ledger::Ledger, + ledger::Ledger, time::{Deadline, Instant}, }; diff --git a/rs/moq-net/tests/integration/compress.rs b/rs/moq-net/tests/integration/compress.rs index 52166fd4c5d..e562a73f998 100644 --- a/rs/moq-net/tests/integration/compress.rs +++ b/rs/moq-net/tests/integration/compress.rs @@ -120,7 +120,7 @@ async fn relay_serves_every_version() { for chunk in chunked.chunks(100) { frame.write(bytes::Bytes::copy_from_slice(chunk)).unwrap(); } - frame.finish().unwrap(); + let mut group = frame.finish().unwrap(); group .write_frame(Timestamp::from_millis(3).unwrap(), bytes::Bytes::new()) .unwrap(); diff --git a/rs/moq-tokio/tests/integration/broadcast.rs b/rs/moq-tokio/tests/integration/broadcast.rs index 0411a770512..4480e2330e1 100644 --- a/rs/moq-tokio/tests/integration/broadcast.rs +++ b/rs/moq-tokio/tests/integration/broadcast.rs @@ -161,15 +161,9 @@ async fn lite05_timestamp_roundtrip(scheme: &str) { let mut group = track.append_group().expect("failed to append group"); for &us in &frames { let payload = format!("frame@{us}").into_bytes(); - let frame = moq_tokio::moq_net::frame::Info { - size: payload.len() as u64, - timestamp: Some(Timestamp::new(us, Timescale::MICRO).unwrap()), - }; - let mut writer = group.create_frame(frame).expect("failed to create frame"); - writer - .write(bytes::Bytes::from(payload)) + group + .write_frame(Timestamp::new(us, Timescale::MICRO).unwrap(), payload) .expect("failed to write frame"); - writer.finish().expect("failed to finish frame"); } group.finish().expect("failed to finish group"); @@ -281,15 +275,9 @@ async fn lite05_fetch_roundtrip(scheme: &str) { let mut group = track.append_group().expect("failed to append group"); // seq 0 for &us in &frames { let payload = format!("frame@{us}").into_bytes(); - let frame = moq_tokio::moq_net::frame::Info { - size: payload.len() as u64, - timestamp: Some(Timestamp::new(us, Timescale::MICRO).unwrap()), - }; - let mut writer = group.create_frame(frame).expect("failed to create frame"); - writer - .write(bytes::Bytes::from(payload)) + group + .write_frame(Timestamp::new(us, Timescale::MICRO).unwrap(), payload) .expect("failed to write frame"); - writer.finish().expect("failed to finish frame"); } group.finish().expect("failed to finish group"); @@ -514,13 +502,6 @@ async fn fetch_moq_transport_20() { async fn lite05_fetch_during_subscribe(scheme: &str) { use moq_tokio::moq_net::{Timescale, Timestamp}; - fn timestamped_frame(us: u64, payload: &str) -> moq_net::frame::Info { - moq_net::frame::Info { - size: payload.len() as u64, - timestamp: Some(Timestamp::new(us, Timescale::MICRO).unwrap()), - } - } - let pub_origin = moq_tokio::origin::spawn(); let broadcast = pub_origin.create_broadcast("test").expect("failed to create broadcast"); broadcast @@ -536,15 +517,15 @@ async fn lite05_fetch_during_subscribe(scheme: &str) { // Group 0 is the "past" group only reachable via FETCH; group 1 is the latest, // delivered live over the subscription. let mut group0 = track.append_group().expect("append group 0"); // seq 0 - let mut w = group0.create_frame(timestamped_frame(10_000, "old")).expect("frame 0"); - w.write(bytes::Bytes::from_static(b"old")).expect("write 0"); - w.finish().expect("finish frame 0"); + group0 + .write_frame(Timestamp::new(10_000, Timescale::MICRO).unwrap(), b"old".as_slice()) + .expect("frame 0"); group0.finish().expect("finish group 0"); let mut group1 = track.append_group().expect("append group 1"); // seq 1 - let mut w = group1.create_frame(timestamped_frame(20_000, "new")).expect("frame 1"); - w.write(bytes::Bytes::from_static(b"new")).expect("write 1"); - w.finish().expect("finish frame 1"); + group1 + .write_frame(Timestamp::new(20_000, Timescale::MICRO).unwrap(), b"new".as_slice()) + .expect("frame 1"); group1.finish().expect("finish group 1"); let mut server_config = moq_tokio::listen::Config::default(); diff --git a/sh/rs/model-markers.py b/sh/rs/model-markers.py index 9d7cb2c8fa0..b061ad7fa10 100644 --- a/sh/rs/model-markers.py +++ b/sh/rs/model-markers.py @@ -5,7 +5,7 @@ past the public API to a marked set. Each item they reach is either pending, naming the quest that makes it public, or deliberately private with its reason: - // pending: /quest/m1/public-model/ingest.md + // pending: /quest/m1/public-model/serve.md // private: passthrough | tuning | capability gap | test | plumbing (JS only) The marker sits in the comment and attribute lines directly above the item. A marker