diff --git a/doc/concept/moq-lite.md b/doc/concept/moq-lite.md index 5f11187bee1..a0758d866a6 100644 --- a/doc/concept/moq-lite.md +++ b/doc/concept/moq-lite.md @@ -191,9 +191,15 @@ Each subscription carries the knobs that decide behavior under congestion: | Knob | Effect | | --- | --- | | **Priority** (0..255) | Higher-priority tracks get bandwidth first. Audio above video, base layer above enhancement. | -| **Order** | Which group to send first when several are pending. Newest first for live, oldest first for catch-up. | +| **Order** | Which group to send first when several are pending. Newest first for live (the default), oldest first for catch-up. Needs moq-lite 07 or moq-transport; older moq-lite always sends newest first. | | **Max delay** | How far a non-latest group may fall behind the live edge before it is skipped. Zero means "live edge only", and raising it is also what asks for history. | +Order only decides what goes first, never what is skipped, so catching up oldest +first needs a max delay that covers the backlog. When a relay serves subscribers of +both orders from one upstream subscription, it asks upstream for newest first, and +still sends each subscriber its groups in that subscriber's own order. Over +moq-transport the upstream order is fixed by whichever subscriber arrived first. + Max delay is measured on the media timeline, not the wall clock, so a backlog delivered as a burst is still late while a congestion stall never expires anything on its own. Both ends apply it: the publisher skips a group rather diff --git a/drafts/draft-lcurley-moq-lite.md b/drafts/draft-lcurley-moq-lite.md index 9caf4125ea8..222a7173fad 100644 --- a/drafts/draft-lcurley-moq-lite.md +++ b/drafts/draft-lcurley-moq-lite.md @@ -145,6 +145,7 @@ Both bounds may be refined to a Frame within their Group, so a subscription can The subscriber and publisher both indicate their delivery preference: - `Priority` indicates if Track A should be transmitted instead of Track B. +- `Group Order` indicates if the newest or oldest pending Group of a Track should be transmitted first. - `Subscriber Max Age` indicates how far a non-latest Group may fall behind the latest Group before it is dropped from live delivery; `Publisher Max Age` indicates the maximum age before a non-latest Group is dropped from the publisher's cache. The combination of these preferences enables the most important content to arrive during network degradation while still respecting encoding dependencies. @@ -578,7 +579,7 @@ How these streams get transmitted over the network is very important, and yet ha ## Prioritization The Publisher and Subscriber both exchange a `Priority` value, which determines which Track should be transmitted next. -Group order within a Track is fixed: newest first. +The subscriber's `Group Order` determines which Group within the Track is transmitted next. A publisher SHOULD attempt to transmit streams based on these rules. This depends on the QUIC implementation and it may not be possible to get fine-grained control. @@ -616,12 +617,14 @@ ali/video: subscriber_priority=1 publisher_priority=1 The subscriber priority takes precedence, so the subscriber can likewise full-screen Ali's window by raising the subscriber priority of Ali's tracks above Bob's. ### Group Order -Within a Track, a publisher SHOULD transmit the newest Group first. -Under congestion this sheds the backlog rather than the live edge, which is what a Group boundary exists to make possible. +Within a subscription, a publisher SHOULD transmit pending Groups in the subscriber's `Group Order`: newest first when descending (the default), oldest first when ascending. +Descending sheds the backlog rather than the live edge under congestion, which is what a Group boundary exists to make possible; ascending drains a backlog in sequence order, for catch-up. -There is no field to invert it. -A subscriber that wants Groups in sequence order gets them by reading in sequence order: reordering is a local decision, it costs the network nothing, and encoding it on the wire only lets one subscriber's preference reach a Track that a relay is fanning out to many. -Such a subscriber SHOULD raise its `Subscriber Max Age` so the Groups it intends to read in order are still being delivered when it reaches them. +`Group Order` only orders transmission; it never decides whether a Group is delivered, which is [Expiration](#expiration)'s job. +An ascending subscriber SHOULD raise its `Subscriber Max Age` so the backlog it intends to drain is not expired first. + +A relay serving several subscriptions from one upstream subscription SHOULD request descending upstream unless every one of them is ascending, so a live subscriber is never held behind another's backlog. +Each downstream subscription is still transmitted in its own `Group Order`. A subscriber MUST support gaps and out-of-order delivery regardless. @@ -1088,6 +1091,7 @@ SUBSCRIBE Message { Epoch (b) Track Name (s) Subscriber Priority (8) + Group Order (8) Subscriber Max Age (i) Group Start (i) Group End (i) @@ -1105,6 +1109,11 @@ The priority of the subscription within the session, represented as a u8. The publisher SHOULD transmit *higher* values first during congestion. See the [Prioritization](#prioritization) section for more information. +**Group Order**: +Which pending Group the publisher SHOULD transmit first: descending (0x0), newest first, or ascending (0x1), oldest first. +Any other value is a PROTOCOL_VIOLATION. +See the [Group Order](#group-order) section for more information. + **Subscriber Max Age**: The subscriber's preference, in milliseconds, for how long a non-latest group may remain in flight before being considered stale and dropped from live delivery. The publisher SHOULD reset (at the QUIC level) Group Streams for groups whose age relative to the latest group exceeds this duration. @@ -1151,6 +1160,7 @@ The start and end group can be changed in either direction (growing or shrinking SUBSCRIBE_UPDATE Message { Message Length (i) Subscriber Priority (8) + Group Order (8) Subscriber Max Age (i) Group Start (i) Group End (i) @@ -1538,6 +1548,7 @@ The `Message Length` describes the payload size on the wire. ## moq-lite-07 +- Added `Group Order` to SUBSCRIBE and SUBSCRIBE_UPDATE: descending (0x0, the previous fixed order) or ascending (0x1). A relay requests descending upstream unless every subscription it serves is ascending. - Listed the shared INVALID_REQUEST_ID (0x4) session code used by moq-transport drafts 14 through 16. - SUBSCRIBE_OK `Group` names where delivery starts when the subscription resolves, which need not be the first group sent. It is not a new floor. A subscriber does not wait for a group between the requested floor and it, but a publisher still delivers one that arrives later within Subscriber Max Age. @@ -1720,7 +1731,6 @@ Some of these fields occur in multiple messages. - Request ID - Track Alias -- Group Order - Filter Type - StartObject - Expires diff --git a/js/net/src/broadcast.test.ts b/js/net/src/broadcast.test.ts index 7ce0177414b..e5fa2ab0a77 100644 --- a/js/net/src/broadcast.test.ts +++ b/js/net/src/broadcast.test.ts @@ -416,6 +416,7 @@ test("a request exposes the aggregate subscription options", async () => { expect(request?.subscription).toEqual({ priority: 7, maxDelay: Milli(250), + order: "descending", groups: { start: { included: 0 }, end: { excluded: 30 } }, }); expect(request?.priority).toBe(7); diff --git a/js/net/src/ietf/ietf.test.ts b/js/net/src/ietf/ietf.test.ts index f1ee0688de1..01fe7791066 100644 --- a/js/net/src/ietf/ietf.test.ts +++ b/js/net/src/ietf/ietf.test.ts @@ -2152,3 +2152,103 @@ for (const version of [Version.DRAFT_14, Version.DRAFT_15, Version.DRAFT_16]) { expect(params.groupOrder).toBe(0); }); } + +// Caller-selected SUBSCRIBE group order, on both wire shapes: draft-14's inline u8 and +// the draft-15+ message parameter. +test.each([ + ["v14", Version.DRAFT_14], + ["v20", Version.DRAFT_20], +] as const)("Subscribe %s: group order defaults to descending", async (_name, version) => { + const msg = new Subscribe.Subscribe({ + requestId: 1n, + trackNamespace: Path.from("test"), + trackName: "video", + subscriberPriority: 128, + }); + expect(msg.groupOrder).toBe("descending"); + + const encoded = await encodeVersioned(msg, version); + const decoded = await decodeVersioned(encoded, Subscribe.Subscribe.decode, version); + expect(decoded.groupOrder).toBe("descending"); +}); + +test.each([ + ["v14", Version.DRAFT_14], + ["v20", Version.DRAFT_20], +] as const)("Subscribe %s: a caller can request ascending group order", async (_name, version) => { + const msg = new Subscribe.Subscribe({ + requestId: 1n, + trackNamespace: Path.from("test"), + trackName: "video", + subscriberPriority: 128, + groupOrder: "ascending", + }); + + const encoded = await encodeVersioned(msg, version); + + // Differential, not a byte search: `toContain(1)` would pass on requestId 1n + // alone. Encode the same message as descending and require that exactly one + // byte moved, from 0x02 to 0x01. + const descending = await encodeVersioned( + new Subscribe.Subscribe({ + requestId: 1n, + trackNamespace: Path.from("test"), + trackName: "video", + subscriberPriority: 128, + groupOrder: "descending", + }), + version, + ); + expect(encoded.length).toBe(descending.length); + const differing = [...encoded].flatMap((byte, i) => (byte === descending[i] ? [] : [i])); + expect(differing).toHaveLength(1); + expect(encoded[differing[0]]).toBe(Subscribe.GroupOrder.Ascending); + expect(descending[differing[0]]).toBe(Subscribe.GroupOrder.Descending); + + const decoded = await decodeVersioned(encoded, Subscribe.Subscribe.decode, version); + expect(decoded.groupOrder).toBe("ascending"); +}); + +// Draft-14 carries GROUP_ORDER as an inline u8 rather than a message parameter, so 0 ("no +// preference") is reachable there from a peer. It decodes as descending rather than surfacing +// as a third value the model has to handle, and anything past 2 is refused. +test("Subscribe v14: an inline group order of 0 decodes as descending", async () => { + const msg = new Subscribe.Subscribe({ + requestId: 1n, + trackNamespace: Path.from("test"), + trackName: "video", + subscriberPriority: 128, + }); + const encoded = await encodeVersioned(msg, Version.DRAFT_14); + + // Rewrite the encoded inline order byte, which no encoder of ours emits as 0 or 3. + const orderAt = encoded.lastIndexOf(Subscribe.GroupOrder.Descending); + const zeroed = new Uint8Array(encoded); + zeroed[orderAt] = Subscribe.GroupOrder.Default; + const decoded = await decodeVersioned(zeroed, Subscribe.Subscribe.decode, Version.DRAFT_14); + expect(decoded.groupOrder).toBe("descending"); + + const invalid = new Uint8Array(encoded); + invalid[orderAt] = 3; + await expect(decodeVersioned(invalid, Subscribe.Subscribe.decode, Version.DRAFT_14)).rejects.toThrow(/group order/); +}); + +// Draft-15 still lets a GROUP_ORDER parameter of 0 through, and it means the same. +test("Subscribe v15: a group order parameter of 0 decodes as descending", async () => { + const msg = new Subscribe.Subscribe({ + requestId: 1n, + trackNamespace: Path.from("test"), + trackName: "video", + subscriberPriority: 128, + groupOrder: "ascending", + }); + const encoded = await encodeVersioned(msg, Version.DRAFT_15); + + // The parameter's value is the byte after its id, 0x22. + const orderAt = encoded.findIndex((byte, i) => byte === 0x22 && encoded[i + 1] === Subscribe.GroupOrder.Ascending); + expect(orderAt).toBeGreaterThan(-1); + const zeroed = new Uint8Array(encoded); + zeroed[orderAt + 1] = Subscribe.GroupOrder.Default; + const decoded = await decodeVersioned(zeroed, Subscribe.Subscribe.decode, Version.DRAFT_15); + expect(decoded.groupOrder).toBe("descending"); +}); diff --git a/js/net/src/ietf/publisher.test.ts b/js/net/src/ietf/publisher.test.ts index 4c1d9d25994..b2c9c9fb284 100644 --- a/js/net/src/ietf/publisher.test.ts +++ b/js/net/src/ietf/publisher.test.ts @@ -22,7 +22,7 @@ import { PublishDone } from "./publish.ts"; import { PublishNamespace, PublishNamespaceUpdate } from "./publish_namespace.ts"; import { Publisher } from "./publisher.ts"; import { RequestError, RequestOk } from "./request.ts"; -import { Subscribe, SubscribeOk, SubscribeUpdate, Unsubscribe } from "./subscribe.ts"; +import { GroupOrder, Subscribe, SubscribeOk, SubscribeUpdate, Unsubscribe } from "./subscribe.ts"; import { SubscribeNamespace, SubscribeNamespaceEntry, SubscribeNamespaceEntryDone } from "./subscribe_namespace.ts"; import { TrackStatusRequest } from "./track.ts"; import { ALPN, type IetfVersion, Version } from "./version.ts"; @@ -2173,6 +2173,34 @@ test("draft-20: an opt-out peer gets no track properties", async () => { } }); +/** + * Through draft-15 SUBSCRIBE_OK restates the order the subscription is served in; later + * drafts announce the publisher's default, newest first. + */ +test.each([ + [Version.DRAFT_14, GroupOrder.Ascending], + [Version.DRAFT_15, GroupOrder.Ascending], + [Version.DRAFT_17, GroupOrder.Descending], +] as const)("%s: SUBSCRIBE_OK announces the served order", async (version, announced) => { + const fx = fixture(version); + fx.broadcast.createTrack("video", { timescale: Timescale.MILLI }); + + const { client, ok } = await runSubscribe( + fx, + new Subscribe({ + requestId: 7n, + trackNamespace: Path.from("test"), + trackName: "video", + subscriberPriority: 0, + groupOrder: "ascending", + }), + ); + expect(ok.properties.groupOrder).toBe(announced); + + fx.close(); + client.close(); +}); + /** * Drafts 14-16 cannot send TIMESCALE, so a subscribed group carries no Timestamp even though * the track has units. Draft-17 declares the units and stamps the object. diff --git a/js/net/src/ietf/publisher.ts b/js/net/src/ietf/publisher.ts index 45146b11d1e..f625bd3cd92 100644 --- a/js/net/src/ietf/publisher.ts +++ b/js/net/src/ietf/publisher.ts @@ -10,6 +10,7 @@ import type { Hop, Route } from "../hop.ts"; import { hiddenBelow, hooks, presented } from "../internal.ts"; import type { Consumer as OriginConsumer } from "../origin.ts"; import * as Path from "../path.ts"; +import { Priority } from "../priority.ts"; import { type Stream, Writer } from "../stream.ts"; import { Milli, Timescale } from "../time.ts"; import type { Location as TrackLocation, Subscriber as TrackSubscriber } from "../track.ts"; @@ -38,7 +39,7 @@ import { } from "./publish_namespace.ts"; import { RequestError, RequestOk } from "./request.ts"; import { cancelled, finCancels } from "./request_stream.ts"; -import { type Subscribe, SubscribeError, SubscribeOk, SubscribeUpdate } from "./subscribe.ts"; +import { GroupOrder, type Subscribe, SubscribeError, SubscribeOk, SubscribeUpdate } from "./subscribe.ts"; import { type SubscribeNamespace, SubscribeNamespaceEntry, @@ -180,6 +181,9 @@ interface RunGroup { /** The publisher's tie-break priority, already converted to the IETF wire convention. */ publisherPriority: number; + /** The subscription's ranking, which orders its group streams by priority and GROUP_ORDER. */ + ranking: Priority; + /** The objects of this group the subscription's filter selects. */ slice: GroupSlice; @@ -198,14 +202,14 @@ interface RunFill { /** The subscription's request ID, which the fetch stream names. */ requestId: bigint; + /** The subscriber's delivery priority, applied to the cache subscription the fill reads. */ + priority: number; + /** - * The subscriber's delivery priority, applied to the cache subscription the fill reads. - * - * Deliberately not the fetch stream's send order: this publisher leaves its group - * streams at the transport's default, so ranking the fill alone would put backfill - * ahead of the live groups it is catching up to. + * The subscription's ranking. The fill joins it as the group it fills, so backfill goes out + * in the subscription's GROUP_ORDER rather than ahead of the live groups or behind them all. */ - priority: number; + ranking: Priority; /** The range the fill resolved to. */ fill: FillServe; @@ -429,8 +433,10 @@ export class Publisher { if (!broadcast) return; const priority = fromWire(msg.subscriberPriority); + const order = msg.groupOrder; const track = wireOf(broadcast).subscribe(msg.trackName, { priority, + order, // moq-transport has no subscriber latency parameter. Keep everything the // producer retained and let the receiving subscriber enforce its own budget. // Keep the sentinel encodable if this demand crosses a Lite hop before the @@ -439,6 +445,7 @@ export class Publisher { }); let cache: TrackSubscriber | undefined; + let ranking: Priority | undefined; try { const info = await untilAborted(track.info(), left.signal); @@ -466,6 +473,7 @@ export class Publisher { // group; the model's `endGroup` is exclusive. track.update({ priority, + order, maxDelay: Milli(Varint.MAX_U53), groups: { start: range.start ? { included: Number(range.start.group) } : undefined, @@ -482,7 +490,9 @@ export class Publisher { const fill = msg.fill && Filter.isDraft20(version) ? fillRange(msg.fill, msg.filter, edge.largest) : undefined; cache = - fill && fill.kind !== "empty" ? track.fork({ priority, maxDelay: Milli(Varint.MAX_U53) }) : undefined; + fill && fill.kind !== "empty" + ? track.fork({ priority, order, maxDelay: Milli(Varint.MAX_U53) }) + : undefined; // Send SUBSCRIBE_OK await stream.writer.u53(SubscribeOk.id); @@ -505,12 +515,17 @@ export class Publisher { : { groupId: edge.largest.group, objectId: 0n }), properties: msg.propertiesWanted ? // TIMESCALE is what opts the track into timestamps, on drafts that can - // send it. We serve the newest group first, matching moq-lite. + // send it. { // An untimed track declares none, so it stays untimed downstream. timescale: info.timescale ?? undefined, priority: publisherPriority, - groupOrder: Properties.DESCENDING, + // Through draft-15 this restates the order the subscription is served + // in. Later drafts carry the publisher's default instead, newest first. + groupOrder: + (version === Version.DRAFT_14 || version === Version.DRAFT_15) && order === "ascending" + ? GroupOrder.Ascending + : Properties.DESCENDING, maxCacheDuration: info.maxAge === undefined ? undefined : BigInt(info.maxAge), } : // INCLUDE_PROPERTIES=0. The block stays present but empty, which also means @@ -602,6 +617,9 @@ export class Publisher { // opened for PUBLISH_DONE to report. const groups = new Set>(); const streams: StreamCount = { opened: 0 }; + // One ranking for the whole subscription, shared by every group and the fill. + const ranked = new Priority(track); + ranking = ranked; // Serve groups until the track ends or the requester cancels. const serving = (async () => { @@ -625,6 +643,7 @@ export class Publisher { group, timescale, publisherPriority, + ranking: ranked, slice: groupSlice(range, group.sequence), unsubscribed, streams, @@ -645,6 +664,7 @@ export class Publisher { ? this.#runFill({ requestId: msg.requestId, priority, + ranking: ranked, fill, cache, timescale, @@ -748,6 +768,8 @@ export class Publisher { else console.warn(`publish error: broadcast=${name} track=${track.name} error=${reason(e)}`); stream.abort(e); } finally { + // Groups still draining keep being ranked until they finish. + ranking?.close(); track.close(); // Idempotent, and the backstop for a throw between the fork and the fill starting: // #runFill closes it itself on every path it reaches. @@ -759,15 +781,17 @@ export class Publisher { * Runs a group and sends its frames using ObjectStream (Subgroup delivery mode). */ async #runGroup(options: RunGroup) { - const { requestId, track, group, timescale, publisherPriority, slice, unsubscribed, streams } = options; + const { requestId, track, group, timescale, publisherPriority, ranking, slice, unsubscribed, streams } = + options; try { // One stream per group is faster than a peer at its limit can retire them, so this // is the one path that doesn't wait for a slot: the transport would serve the opens - // in the order we asked, which is oldest-first, exactly backwards for live media. - // Failing here drops the group and lets the next one compete for the next slot. + // in the order we asked, not the subscription's order. Failing here drops the group + // and lets the next one compete for the next slot. const stream = await Writer.tryOpen(this.#quic, { cancel: unsubscribed, version: this.#session.version, + sendOrder: ranking.rank(group.sequence), waitUntilAvailable: false, }); if (!stream) { @@ -775,6 +799,8 @@ export class Publisher { return; } streams.opened += 1; + // A REQUEST_UPDATE re-ranks the subscription, so a group already on the wire follows it. + ranking.add(stream, group.sequence); const header = new GroupMessage({ trackAlias: requestId, @@ -861,6 +887,10 @@ export class Publisher { } } catch (err: unknown) { stream.reset(error(err)); + } finally { + // A closed stream may still have data queued behind its FIN, so it keeps + // competing at its rank until the stream settles. + void stream.closed.catch(() => {}).then(() => ranking.remove(stream)); } } finally { group.close(); @@ -955,7 +985,7 @@ export class Publisher { * fill-failure signal. Nothing here touches the subscription either way. */ async #runFill(options: RunFill) { - const { requestId, fill, cache, timescale, unsubscribed, streams } = options; + const { requestId, ranking, fill, cache, timescale, unsubscribed, streams } = options; const version = this.#session.version; // Everything is inside the try so the cache fork is released on every path out, @@ -964,12 +994,19 @@ export class Publisher { try { if (fill.kind === "empty") return; - stream = await Writer.tryOpen(this.#quic, { cancel: unsubscribed, version }); + // A fill we cannot serve is reset right after its header, so it needs no rank. + const sequence = fill.kind === "group" ? Number(fill.sequence) : undefined; + stream = await Writer.tryOpen(this.#quic, { + cancel: unsubscribed, + version, + sendOrder: sequence === undefined ? undefined : ranking.rank(sequence), + }); if (!stream) { console.debug(`fill stream failed to open: fill=${requestId}`); return; } streams.opened += 1; + if (sequence !== undefined) ranking.add(stream, sequence); await stream.u53(FetchHeader.type); await new FetchHeader({ requestId }).encode(stream, version); @@ -993,6 +1030,11 @@ export class Publisher { console.debug(`fill failed, resetting its stream: fill=${requestId} error=${reason(e)}`); stream?.reset(e); } finally { + // Ranked until it settles, like a group stream. + if (stream) { + const opened = stream; + void opened.closed.catch(() => {}).then(() => ranking.remove(opened)); + } cache.close(); } } diff --git a/js/net/src/ietf/subscribe.ts b/js/net/src/ietf/subscribe.ts index 1eed75c3eac..4faf34903ee 100644 --- a/js/net/src/ietf/subscribe.ts +++ b/js/net/src/ietf/subscribe.ts @@ -1,5 +1,6 @@ import type * as Path from "../path.ts"; import type { Reader, Writer } from "../stream.ts"; +import type { Order } from "../track.ts"; import * as Filter from "./filter.ts"; import * as Message from "./message.ts"; import * as Namespace from "./namespace.ts"; @@ -7,8 +8,41 @@ import { type MessageLocation, Parameters } from "./parameters.ts"; import * as Properties from "./properties.ts"; import { type IetfVersion, Version } from "./version.ts"; -// we only support Group Order descending -const GROUP_ORDER = 0x02; +/** + * The GROUP_ORDER wire values. + * + * `Default` (0x0) is the wire's "no preference": the publisher picks, which in practice + * means its own DEFAULT_PUBLISHER_GROUP_ORDER track property. It decodes as descending, the + * order this publisher prefers, so the model never sees it and this client never sends it. + * Only drafts 14 to 16 can carry it; {@link Parameters} rejects it as a protocol violation + * on later drafts. + */ +export const GroupOrder = { + Default: 0x00, + Ascending: 0x01, + Descending: 0x02, +} as const; + +/** A GROUP_ORDER wire value. */ +export type GroupOrder = (typeof GroupOrder)[keyof typeof GroupOrder]; + +/** The GROUP_ORDER byte for a model {@link Order}. */ +function encodeGroupOrder(order: Order): GroupOrder { + return order === "ascending" ? GroupOrder.Ascending : GroupOrder.Descending; +} + +/** The model {@link Order} for a GROUP_ORDER byte, refusing a value the draft does not define. */ +function decodeGroupOrder(value: number): Order { + switch (value) { + case GroupOrder.Ascending: + return "ascending"; + case GroupOrder.Default: + case GroupOrder.Descending: + return "descending"; + default: + throw new Error(`unknown group order: ${value}`); + } +} /** * The filter this implementation joins a live track with. @@ -29,6 +63,9 @@ export class Subscribe { trackName: string; subscriberPriority: number; + /** The order the publisher is asked to deliver groups in (GROUP_ORDER). Defaults to descending. */ + groupOrder: Order; + /** Which Objects the subscription delivers, resolved by the publisher against the live edge. */ filter: Filter.Filter; @@ -49,6 +86,7 @@ export class Subscribe { trackNamespace, trackName, subscriberPriority, + groupOrder, filter, fill, propertiesWanted, @@ -59,6 +97,7 @@ export class Subscribe { trackNamespace: Path.Valid; trackName: string; subscriberPriority: number; + groupOrder?: Order; filter?: Filter.Filter; fill?: Filter.Fill; propertiesWanted?: boolean; @@ -69,6 +108,7 @@ export class Subscribe { this.trackNamespace = trackNamespace; this.trackName = trackName; this.subscriberPriority = subscriberPriority; + this.groupOrder = groupOrder ?? "descending"; this.filter = filter ?? { kind: "unfiltered" }; this.fill = fill; this.propertiesWanted = propertiesWanted ?? true; @@ -86,7 +126,7 @@ export class Subscribe { if (version === Version.DRAFT_14) { await w.u8(this.subscriberPriority); - await w.u8(GROUP_ORDER); + await w.u8(encodeGroupOrder(this.groupOrder)); await w.bool(this.forward); await w.write(Filter.encode(this.filter, version)); await w.u53(0); // no parameters @@ -94,7 +134,7 @@ export class Subscribe { // v15+: fields moved into parameters const params = new Parameters(); params.subscriberPriority = this.subscriberPriority; - params.groupOrder = GROUP_ORDER; + params.groupOrder = encodeGroupOrder(this.groupOrder); params.forward = this.forward; params.subscriptionFilter = this.filter; @@ -134,31 +174,27 @@ export class Subscribe { if (version === Version.DRAFT_14) { const subscriberPriority = await r.u8(); - let groupOrder = await r.u8(); - if (groupOrder > 2) { - throw new Error(`unknown group order: ${groupOrder}`); - } - if (groupOrder === 0) { - groupOrder = GROUP_ORDER; // default to descending - } + const groupOrder = decodeGroupOrder(await r.u8()); const forward = await r.bool(); const filter = await Filter.decodeInline(r); await Parameters.decode(r, version); // ignore parameters - return new Subscribe({ requestId, trackNamespace, trackName, subscriberPriority, filter, forward }); + return new Subscribe({ + requestId, + trackNamespace, + trackName, + subscriberPriority, + groupOrder, + filter, + forward, + }); } // v15+: fields are in parameters const params = await Parameters.decode(r, version, "subscribe"); const subscriberPriority = params.subscriberPriority ?? 128; - let groupOrder = params.groupOrder ?? GROUP_ORDER; - if (groupOrder > 2) { - throw new Error(`unknown group order: ${groupOrder}`); - } - if (groupOrder === 0) { - groupOrder = GROUP_ORDER; // default to descending - } + const groupOrder = decodeGroupOrder(params.groupOrder ?? GroupOrder.Descending); // FILL_PARAMETERS and INCLUDE_PROPERTIES are draft-20 additions, and the Range // Filters draft-19 ones. An unknown message parameter is a protocol violation, so @@ -185,6 +221,7 @@ export class Subscribe { trackNamespace, trackName, subscriberPriority, + groupOrder, filter, fill, // Defaults to 1, so an absent parameter means the subscriber wants them. @@ -242,7 +279,7 @@ export class SubscribeOk { if (version === Version.DRAFT_14) { await w.u62(0n); // expires = 0 - await w.u8(this.properties.groupOrder ?? GROUP_ORDER); + await w.u8(this.properties.groupOrder ?? GroupOrder.Descending); await w.bool(this.largest !== undefined); if (this.largest !== undefined) { await w.u62(this.largest.groupId); @@ -291,7 +328,7 @@ export class SubscribeOk { // arrives as PUBLISH_DONE regardless, so there is nothing to act on. await r.u62(); - await r.u8(); // Don't care about group order + properties.groupOrder = await r.u8(); const contentExists = await r.bool(); if (contentExists) { @@ -308,7 +345,10 @@ export class SubscribeOk { const params = await Parameters.decode(r, version, "subscribe-ok"); largest = params.largest; properties = await Properties.decode(r, version); - if (version === Version.DRAFT_15) properties.maxCacheDuration = params.maxCacheDuration; + if (version === Version.DRAFT_15) { + properties.maxCacheDuration = params.maxCacheDuration; + properties.groupOrder = params.groupOrder; + } } return new SubscribeOk({ requestId, trackAlias, largest, properties }); diff --git a/js/net/src/ietf/subscriber.ts b/js/net/src/ietf/subscriber.ts index 45d61952028..05dda0d959c 100644 --- a/js/net/src/ietf/subscriber.ts +++ b/js/net/src/ietf/subscriber.ts @@ -886,6 +886,8 @@ export class Subscriber { trackNamespace: broadcast, trackName: request.name, subscriberPriority: toWire(request.priority), + // Fixed for the subscription's life: no REQUEST_UPDATE parameter carries it. + groupOrder: request.subscription.order, // No fill is requested: the fill's fetch stream and the live subscription split // the group across two streams, and this subscriber does not reassemble them into // one group yet. A lenient publisher (like ours) replays the whole in-range group diff --git a/js/net/src/integration.test.ts b/js/net/src/integration.test.ts index 39ce93419b5..64190049bc8 100644 --- a/js/net/src/integration.test.ts +++ b/js/net/src/integration.test.ts @@ -181,6 +181,7 @@ test("integration: lite subscription options and updates reach the publisher", a expect(producer.subscription.peek()).toEqual({ priority: 3, maxDelay: Milli(250), + order: "descending", groups: { start: { included: 1 }, end: { excluded: 9 } }, }); @@ -193,6 +194,7 @@ test("integration: lite subscription options and updates reach the publisher", a expect(await updated).toEqual({ priority: 8, maxDelay: Milli(500), + order: "descending", groups: { start: { included: 2 }, end: { excluded: 12 } }, }); diff --git a/js/net/src/lite/publisher.test.ts b/js/net/src/lite/publisher.test.ts index c8caf2814c9..e1c422314cb 100644 --- a/js/net/src/lite/publisher.test.ts +++ b/js/net/src/lite/publisher.test.ts @@ -9,12 +9,12 @@ import { hooks } from "../internal.ts"; import { createMockTransportPair, textFrame } from "../mock.ts"; import { Producer as OriginProducer } from "../origin.ts"; import * as Path from "../path.ts"; +import { sendOrder } from "../priority.ts"; import { Reader, Stream, Writer } from "../stream.ts"; import { Milli, Timescale, Timestamp } from "../time.ts"; import { type AnnounceBroadcast, AnnounceRequest, decodeAnnounceBroadcast } from "./announce.ts"; import { Fetch } from "./fetch.ts"; import { Group as GroupMessage } from "./group.ts"; -import { sendOrder } from "./priority.ts"; import { Probe as ProbeMessage } from "./probe.ts"; import { Publisher } from "./publisher.ts"; import { decodeSubscribeResponse, Subscribe, type SubscribeEnd, SubscribeUpdate } from "./subscribe.ts"; @@ -1049,6 +1049,7 @@ test("lite draft-06: scheduling updates apply while SUBSCRIBE_START is blocked", expect(sub.track.subscription.peek()).toEqual({ priority: 9, maxDelay: TEST_MAX_DELAY_MS, + order: "descending", groups: { start: undefined, end: { excluded: 6 } }, }); expect(ranges).not.toHaveBeenCalled(); diff --git a/js/net/src/lite/publisher.ts b/js/net/src/lite/publisher.ts index d4f4f6644a5..40341d5d582 100644 --- a/js/net/src/lite/publisher.ts +++ b/js/net/src/lite/publisher.ts @@ -10,6 +10,7 @@ import { Cost, type Hop, type Route, routesEqual } from "../hop.ts"; import { finalSequence, hiddenBelow, hooks, presented } from "../internal.ts"; import type { Consumer as OriginConsumer } from "../origin.ts"; import * as Path from "../path.ts"; +import { Priority, sendOrder } from "../priority.ts"; import { type Reader, type Stream, Writer } from "../stream.ts"; import { Milli, Timescale, Timestamp } from "../time.ts"; import type * as track from "../track.ts"; @@ -20,7 +21,6 @@ import { AnnounceInit, AnnounceOk, type AnnounceRequest, encodeAnnounceBroadcast import { Datagram as DatagramMessage } from "./datagram.ts"; import type { Fetch } from "./fetch.ts"; import { Group as GroupMessage } from "./group.ts"; -import { Priority, sendOrder } from "./priority.ts"; import { Probe } from "./probe.ts"; import { encodeSubscribeResponse, @@ -750,6 +750,7 @@ export class Publisher { const endGroup = exclusiveGroupEnd(msg.endGroup); const track = wireOf(front).subscribe(msg.track, { priority: msg.priority, + order: msg.order, maxDelay: Milli(servingMaxDelay(this.version, msg.maxDelay)), groups: { start: msg.startGroup === undefined ? undefined : { included: msg.startGroup }, @@ -808,6 +809,7 @@ export class Publisher { const end = exclusiveGroupEnd(update.endGroup); track.update({ priority: update.priority, + order: update.order, maxDelay: Milli(servingMaxDelay(this.version, update.maxDelay)), groups: { start: update.startGroup === undefined ? undefined : { included: update.startGroup }, diff --git a/js/net/src/lite/subscribe.test.ts b/js/net/src/lite/subscribe.test.ts index 7310913f277..16f77f46796 100644 --- a/js/net/src/lite/subscribe.test.ts +++ b/js/net/src/lite/subscribe.test.ts @@ -1,4 +1,5 @@ import { expect, test } from "bun:test"; +import { ProtocolViolation } from "../error.ts"; import * as Path from "../path.ts"; import { Reader, Writer } from "../stream.ts"; import { @@ -267,3 +268,47 @@ test("a requested range is empty when its bounds meet anywhere", () => { expect(emptyRange({ startGroup: 5, endGroup: 6 })).toBe(false); expect(emptyRange({ startGroup: 5 })).toBe(false); }); + +// Lite-07 carries `Group Order` right after the priority, on SUBSCRIBE and SUBSCRIBE_UPDATE +// alike, and refuses a value it does not define. +test.each(["ascending", "descending"] as const)("lite-07 round-trips a %s group order", async (order) => { + const version = Version.DRAFT_07; + const subscribe = new Subscribe({ id: 1n, broadcast: Path.from("room"), track: "video", priority: 3, order }); + const got = await Subscribe.decode( + new Reader(undefined, await encodeMessage(version, subscribe), version), + version, + ); + expect(got.order).toBe(order); + + const update = await encodeMessage(version, new SubscribeUpdate({ priority: 3, order, maxDelay: 250 })); + // The length prefix, the priority, then the order. + expect(update[1]).toBe(3); + expect(update[2]).toBe(order === "ascending" ? 1 : 0); + const decoded = await SubscribeUpdate.decode(new Reader(undefined, update, version), version); + expect(decoded.order).toBe(order); + + const invalid = new Uint8Array(update); + invalid[2] = 2; + await expect(SubscribeUpdate.decode(new Reader(undefined, invalid, version), version)).rejects.toThrow( + ProtocolViolation, + ); +}); + +// No earlier wire has `Group Order`, so an ascending subscription falls back to descending, +// byte-identical to one that never asked. +test.each([Version.DRAFT_03, Version.DRAFT_05, Version.DRAFT_06])( + "version %d falls back to a descending group order", + async (version) => { + const props = { id: 1n, broadcast: Path.from("room"), track: "video", priority: 3, maxDelay: 250 }; + const descending = await encodeMessage(version, new Subscribe(props)); + const ascending = await encodeMessage(version, new Subscribe({ ...props, order: "ascending" })); + expect(ascending).toEqual(descending); + const got = await Subscribe.decode(new Reader(undefined, ascending, version), version); + expect(got.order).toBe("descending"); + + const update = await encodeMessage(version, new SubscribeUpdate({ priority: 3, order: "ascending" })); + expect(update).toEqual(await encodeMessage(version, new SubscribeUpdate({ priority: 3 }))); + const decoded = await SubscribeUpdate.decode(new Reader(undefined, update, version), version); + expect(decoded.order).toBe("descending"); + }, +); diff --git a/js/net/src/lite/subscribe.ts b/js/net/src/lite/subscribe.ts index 76ee8666987..3b3fdd30fc1 100644 --- a/js/net/src/lite/subscribe.ts +++ b/js/net/src/lite/subscribe.ts @@ -1,10 +1,19 @@ import type * as Epoch from "../epoch.ts"; +import { ProtocolViolation } from "../error.ts"; import * as Path from "../path.ts"; import type { Reader, Writer } from "../stream.ts"; -import type { Location } from "../track.ts"; +import type { Location, Order } from "../track.ts"; import { decodeEpoch, encodeEpoch } from "./epoch.ts"; import * as Message from "./message.ts"; -import { hasFrameBounds, hasGroupOrder, hasLargest, hasStreamCount, resolvesStart, Version } from "./version.ts"; +import { + hasFrameBounds, + hasGroupOrder, + hasLargest, + hasOrder, + hasStreamCount, + resolvesStart, + Version, +} from "./version.ts"; /** * Encode the `Group Start` field shared by SUBSCRIBE and SUBSCRIBE_UPDATE. @@ -110,6 +119,38 @@ async function padGroupOrder(w: Writer, version: Version) { if (hasGroupOrder(version)) await w.bool(false); } +/** + * Decode the byte after the subscriber priority shared by SUBSCRIBE and SUBSCRIBE_UPDATE: + * lite-07's `Group Order`, or the retired `Ordered` byte an older layout still carries. + */ +async function decodeOrder(r: Reader, version: Version): Promise { + if (!hasOrder(version)) { + await skipGroupOrder(r, version); + return "descending"; + } + const order = await r.u8(); + switch (order) { + case 0: + return "descending"; + case 1: + return "ascending"; + default: + throw new ProtocolViolation(`unknown group order: ${order}`); + } +} + +/** + * The inverse of {@link decodeOrder}. A wire without `Group Order` serves newest first, so an + * ascending subscription over it falls back to descending. + */ +async function encodeOrder(w: Writer, version: Version, order: Order) { + if (!hasOrder(version)) { + await padGroupOrder(w, version); + return; + } + await w.u8(order === "ascending" ? 1 : 0); +} + /** * Exclusive model/local cap from a decoded inclusive last group. * @@ -149,6 +190,8 @@ export function emptyRange({ startGroup, endGroup }: { startGroup?: number; endG export class SubscribeUpdate { priority: number; + /** See {@link Subscribe.order}. */ + order: Order; /** Subscriber max delay in milliseconds; zero skips once a newer group is available. */ maxDelay: number; startGroup?: number; @@ -160,6 +203,7 @@ export class SubscribeUpdate { constructor(props: { priority: number; + order?: Order; maxDelay?: number; startGroup?: number; endGroup?: number; @@ -167,6 +211,7 @@ export class SubscribeUpdate { endFrame?: number; }) { this.priority = props.priority; + this.order = props.order ?? "descending"; this.maxDelay = props.maxDelay ?? 0; this.startGroup = props.startGroup; this.endGroup = props.endGroup; @@ -182,7 +227,7 @@ export class SubscribeUpdate { break; default: await w.u8(this.priority); - await padGroupOrder(w, version); + await encodeOrder(w, version, this.order); await w.u53(this.maxDelay); await encodeStartGroup(w, version, this.startGroup); await w.u53(this.endGroup !== undefined ? this.endGroup + 1 : 0); @@ -198,7 +243,7 @@ export class SubscribeUpdate { return new SubscribeUpdate({ priority: await r.u8() }); default: { const priority = await r.u8(); - await skipGroupOrder(r, version); + const order = await decodeOrder(r, version); const maxDelay = await r.u53(); const startGroup = await decodeStartGroup(r, version); const endGroup = (await r.u53()) || undefined; @@ -206,6 +251,7 @@ export class SubscribeUpdate { const frames = await decodeFrameBounds(r, version, startGroup, end); return new SubscribeUpdate({ priority, + order, maxDelay, startGroup: canonicalStartGroup(version, startGroup, frames.startFrame), endGroup: end, @@ -235,6 +281,11 @@ export class Subscribe { epoch?: Epoch.Valid; track: string; priority: number; + /** + * Which pending group to send first. Lite-07+; earlier wires decode as descending and + * cannot ask for anything else. + */ + order: Order; /** Subscriber max delay in milliseconds; zero skips once a newer group is available. */ maxDelay: number; @@ -260,6 +311,7 @@ export class Subscribe { epoch?: Epoch.Valid; track: string; priority: number; + order?: Order; maxDelay?: number; startGroup?: number; endGroup?: number; @@ -271,6 +323,7 @@ export class Subscribe { this.epoch = props.epoch; this.track = props.track; this.priority = props.priority; + this.order = props.order ?? "descending"; this.maxDelay = props.maxDelay ?? 0; this.startGroup = props.startGroup; this.endGroup = props.endGroup; @@ -290,7 +343,7 @@ export class Subscribe { case Version.DRAFT_02: break; default: - await padGroupOrder(w, version); + await encodeOrder(w, version, this.order); await w.u53(this.maxDelay); await encodeStartGroup(w, version, this.startGroup); await w.u53(this.endGroup !== undefined ? this.endGroup + 1 : 0); @@ -311,7 +364,7 @@ export class Subscribe { case Version.DRAFT_02: return new Subscribe({ id, broadcast, track, priority }); default: { - await skipGroupOrder(r, version); + const order = await decodeOrder(r, version); const maxDelay = await r.u53(); const startGroup = await decodeStartGroup(r, version); const endGroup = (await r.u53()) || undefined; @@ -323,6 +376,7 @@ export class Subscribe { epoch, track, priority, + order, maxDelay, startGroup: canonicalStartGroup(version, startGroup, frames.startFrame), endGroup: end, diff --git a/js/net/src/lite/subscriber.ts b/js/net/src/lite/subscriber.ts index 43b31ec3f50..d8e73680300 100644 --- a/js/net/src/lite/subscriber.ts +++ b/js/net/src/lite/subscriber.ts @@ -22,6 +22,7 @@ import * as netGroup from "../group.ts"; import { Cost, type Hop, MAX_HOPS, type Route, routesEqual, UNKNOWN_HOP } from "../hop.ts"; import { groupBounds, hiddenBelow, scopeCaptures, scopeHead, scopeOverlaps } from "../internal.ts"; import * as Path from "../path.ts"; +import { sendOrder } from "../priority.ts"; import { type OpenOptions, type Reader, Stream } from "../stream.ts"; import { TAIL_GRACE_MS, Tail } from "../tail.ts"; import * as Time from "../time.ts"; @@ -40,7 +41,6 @@ import { import { Datagram as DatagramMessage } from "./datagram.ts"; import { Fetch as FetchMessage } from "./fetch.ts"; import { frameDecoder, type Group as GroupMessage, readFrames } from "./group.ts"; -import { sendOrder } from "./priority.ts"; import { Probe } from "./probe.ts"; import { ProbeLevel, type Setup } from "./setup.ts"; import { StreamId } from "./stream.ts"; @@ -59,6 +59,7 @@ import { hasAnnounceId, hasAnnounceOk, hasDatagrams, + hasOrder, hasProbeRtt, hasStreamCount, resolvesStart, @@ -676,6 +677,7 @@ export class Subscriber { epoch, track: request.name, priority: subscription.priority ?? 0, + order: subscription.order, maxDelay: subscription.maxDelay, startGroup: subscription.groups?.start === undefined ? undefined : bounds.start, endGroup: inclusiveGroupEnd(bounds.end), @@ -1224,6 +1226,7 @@ export class Subscriber { const stopped: Promise = race([track.closed, stream.reader.closed]).then(() => null); let lastSent: track.Subscription = { priority: msg.priority, + order: msg.order, maxDelay: Time.Milli(msg.maxDelay), groups: { start: msg.startGroup === undefined ? undefined : { included: msg.startGroup }, @@ -1255,6 +1258,7 @@ export class Subscriber { // interpret SUBSCRIBE_UPDATE as a reset of ordered/maxDelay/etc. const update = new SubscribeUpdate({ priority: current.priority ?? 0, + order: current.order, maxDelay: current.maxDelay, startGroup: current.groups?.start === undefined ? undefined : bounds.start, endGroup: inclusiveGroupEnd(bounds.end), @@ -1272,8 +1276,11 @@ export class Subscriber { // joins at the publisher's start, and 0 is group 0. Lite-06 encodes both as 0. const sameStart = resolvesStart(this.version) || (a.groups?.start === undefined) === (b.groups?.start === undefined); + // A wire without `Group Order` cannot carry a change to it. + const sameOrder = !hasOrder(this.version) || (a.order ?? "descending") === (b.order ?? "descending"); return ( (a.priority ?? 0) === (b.priority ?? 0) && + sameOrder && (a.maxDelay ?? 0) === (b.maxDelay ?? 0) && sameStart && ag.start === bg.start && diff --git a/js/net/src/lite/version.ts b/js/net/src/lite/version.ts index 2d492e38f11..91c3df2169d 100644 --- a/js/net/src/lite/version.ts +++ b/js/net/src/lite/version.ts @@ -189,12 +189,29 @@ export function hasFrameBounds(version: Version): boolean { } } +/** Whether SUBSCRIBE and SUBSCRIBE_UPDATE carry the subscriber's `Group Order`. Added in + * lite-07; an earlier subscription is served newest first. */ +export function hasOrder(version: Version): boolean { + // Explicitly list older versions so future versions keep the lite-07+ behavior. + switch (version) { + case Version.DRAFT_01: + case Version.DRAFT_02: + case Version.DRAFT_03: + case Version.DRAFT_04: + case Version.DRAFT_05: + case Version.DRAFT_06: + return false; + default: + return true; + } +} + /** Whether SUBSCRIBE, SUBSCRIBE_UPDATE, SUBSCRIBE_OK, and TRACK_INFO carry the retired * `Ordered` byte. * - * The field is gone from the model: a publisher transmits newest-first within a track, - * always. Deployed drafts still have the byte in their layout, so it is written as 0 and - * ignored on read rather than shifting every field behind it. */ + * These drafts are served newest first whatever the byte says, so it is written as 0 and + * ignored on read rather than shifting every field behind it. Lite-07's `Group Order` (see + * {@link hasOrder}) is a new field, not this one. */ export function hasGroupOrder(version: Version): boolean { // Explicitly list older versions so future versions keep the lite-06+ behavior. switch (version) { diff --git a/js/net/src/order.test.ts b/js/net/src/order.test.ts new file mode 100644 index 00000000000..bd13efdb266 --- /dev/null +++ b/js/net/src/order.test.ts @@ -0,0 +1,276 @@ +// Group order end to end: what a subscriber asks for reaches the publisher, and the publisher's +// group streams carry send orders that put the requested group first. +// +// The mock transport delivers streams in creation order and ignores send order, so the send +// order each stream was assigned is the observable. Every group is left open, so all of their +// streams stay in flight and ranked against each other. + +import { expect, test } from "bun:test"; +import { accept, connect, type Established } from "./connection/index.ts"; +import type { Producer as GroupProducer } from "./group.ts"; +import * as Ietf from "./ietf/index.ts"; +import * as Lite from "./lite/index.ts"; +import { createMockTransportPair, type MockTransport, textFrame } from "./mock.ts"; +import { Producer as OriginProducer } from "./origin.ts"; +import * as Path from "./path.ts"; +import { sendOrder } from "./priority.ts"; +import type { SendStream } from "./stream.ts"; +import { Milli, Timescale } from "./time.ts"; +import type { Order, Producer as TrackProducer, Subscriber as TrackSubscriber } from "./track.ts"; +import { wireOf } from "./wire.ts"; + +const url = new URL("https://localhost:4443/test"); + +// A budget covering every group these tests write, so expiry never decides what is sent. +const MAX_DELAY = Milli(30_000); + +// The send orders a subscription at priority 0 gives its streams, in the order they opened, +// when stream `i` carries group `i` of `count` all still in flight. +function expected(order: Order, count: number): number[] { + return Array.from({ length: count }, (_, sequence) => + sendOrder({ priority: 0, position: order === "ascending" ? sequence : count - 1 - sequence }), + ); +} + +// The send orders of a transport's group streams. Protocol streams, such as the setup stream, +// open without one. +function sendOrders(transport: MockTransport): number[] { + return transport.sendStreams.uni.flatMap((stream) => (stream.sendOrder === undefined ? [] : [stream.sendOrder])); +} + +// A group with one frame, left open. +function writeGroup(track: TrackProducer): GroupProducer { + const group = track.appendGroup(); + group.writeFrame(textFrame("x")); + return group; +} + +// Receiving a group means its stream header was written, which the publisher does only after +// ranking the stream. +async function receive(subscriber: TrackSubscriber, count: number): Promise { + const sequences: number[] = []; + for (let i = 0; i < count; i++) { + const group = await subscriber.recvGroup(); + if (!group) throw new Error("track ended early"); + sequences.push(group.sequence); + } + return sequences; +} + +// Resolve once the producer's aggregate subscription satisfies `predicate`. +async function aggregate(track: TrackProducer, predicate: (order: Order | undefined) => boolean): Promise { + while (!predicate(track.subscription.peek()?.order)) await track.subscription.changed(); +} + +interface Session { + client: Established; + server: Established; + transport: MockTransport; +} + +async function session(protocol: string, origin: OriginProducer): Promise { + const pair = createMockTransportPair(protocol); + const [client, server] = await Promise.all([ + connect({ url, transport: pair.client }), + accept({ transport: pair.server, url, publish: origin.consume() }), + ]); + return { client, server, transport: pair.server }; +} + +// A backlog already cached when the subscription arrives. The publisher's own reader hands a +// buffered backlog out lowest first, so stream `i` carries group `i`. With `update`, the +// subscriber switches to that order once every group is in flight. +async function backlog(protocol: string, order: Order, update?: Order) { + const origin = new OriginProducer(); + const { client, server, transport } = await session(protocol, origin); + + const broadcast = origin.createBroadcast(Path.from("test")); + broadcast.announce(); + const video = broadcast.createTrack("video", { timescale: Timescale.MILLI }); + const groups = [0, 1, 2].map(() => writeGroup(video)); + + const remote = wireOf(client).consume(Path.from("test")); + const subscriber = remote.track("video").subscribe({ + maxDelay: MAX_DELAY, + order, + groups: { start: { included: 0 } }, + }); + await receive(subscriber, groups.length); + + if (update !== undefined) { + subscriber.update({ maxDelay: MAX_DELAY, order: update, groups: { start: { included: 0 } } }); + await aggregate(video, (upstream) => upstream === update); + } + + const result = { upstream: video.subscription.peek()?.order, orders: sendOrders(transport) }; + + for (const group of groups) group.close(); + subscriber.close(); + remote.close(); + broadcast.close(); + client.abort(); + server.abort(); + return result; +} + +test.each(["ascending", "descending"] as const)("lite-07 serves a backlog %s", async (order) => { + const { upstream, orders } = await backlog(Lite.ALPN_07_WIP, order); + expect(upstream).toBe(order); + expect(orders).toEqual(expected(order, 3)); +}); + +// SUBSCRIBE_UPDATE re-ranks the groups already on the wire, not only the ones opened after. +test("lite-07 re-ranks a backlog in flight when the order changes", async () => { + const { orders } = await backlog(Lite.ALPN_07_WIP, "descending", "ascending"); + expect(orders).toEqual(expected("ascending", 3)); +}); + +// Lite-06 has no field for it, so the publisher never hears the request and serves newest first. +test("lite-06 serves an ascending subscription newest first", async () => { + const { upstream, orders } = await backlog(Lite.ALPN_06, "ascending"); + expect(upstream).toBe("descending"); + expect(orders).toEqual(expected("descending", 3)); +}); + +// moq-transport joins at the live edge, so the groups arrive live, one at a time. +test.each(["ascending", "descending"] as const)("ietf serves GROUP_ORDER %s", async (order) => { + const origin = new OriginProducer(); + const { client, server, transport } = await session(Ietf.ALPN.DRAFT_17, origin); + + const broadcast = origin.createBroadcast(Path.from("test")); + broadcast.announce(); + const video = broadcast.createTrack("video", { timescale: Timescale.MILLI }); + + const remote = wireOf(client).consume(Path.from("test")); + const subscriber = remote.track("video").subscribe({ maxDelay: MAX_DELAY, order }); + await aggregate(video, (upstream) => upstream === order); + + const groups: GroupProducer[] = []; + for (let i = 0; i < 3; i++) { + groups.push(writeGroup(video)); + await receive(subscriber, 1); + } + expect(sendOrders(transport)).toEqual(expected(order, 3)); + + for (const group of groups) group.close(); + subscriber.close(); + remote.close(); + broadcast.close(); + client.abort(); + server.abort(); +}); + +// Holds the FIN of every uni stream `transport` opens from here on, while their data still +// flows, until `release`. `closing` resolves once a stream has asked to close. +function holdFins(transport: MockTransport): { closing: Promise; release: () => void } { + let release!: () => void; + const released = new Promise((resolve) => { + release = resolve; + }); + let closed!: () => void; + const closing = new Promise((resolve) => { + closed = resolve; + }); + + const create = transport.createUnidirectionalStream.bind(transport); + transport.createUnidirectionalStream = async (options) => { + const inner = await create(options); + const writer = inner.getWriter(); + const outer: SendStream = new WritableStream({ + write: (chunk) => writer.write(chunk), + close: async () => { + closed(); + await released; + await writer.close(); + }, + abort: (reason) => writer.abort(reason), + }); + outer.sendOrder = options?.sendOrder; + // Record the stream the publisher re-ranks. + const log = transport.sendStreams.uni; + log[log.indexOf(inner)] = outer; + return outer; + }; + return { closing, release }; +} + +// A finished group whose FIN is still queued keeps its rank, rather than being frozen while +// the groups behind it are promoted to tie with it. +test("ietf keeps a closing group stream ranked until it settles", async () => { + const origin = new OriginProducer(); + const { client, server, transport } = await session(Ietf.ALPN.DRAFT_17, origin); + const fins = holdFins(transport); + + const broadcast = origin.createBroadcast(Path.from("test")); + broadcast.announce(); + const video = broadcast.createTrack("video", { timescale: Timescale.MILLI }); + + const remote = wireOf(client).consume(Path.from("test")); + const subscriber = remote.track("video").subscribe({ maxDelay: MAX_DELAY, order: "descending" }); + await aggregate(video, (upstream) => upstream === "descending"); + + const groups: GroupProducer[] = []; + for (let i = 0; i < 3; i++) { + groups.push(writeGroup(video)); + await receive(subscriber, 1); + } + + // The newest group, ranked first, finishes while its FIN is held. + groups[2]?.close(); + await fins.closing; + expect(sendOrders(transport)).toEqual(expected("descending", 3)); + + fins.release(); + for (const group of groups) group.close(); + subscriber.close(); + remote.close(); + broadcast.close(); + client.abort(); + server.abort(); +}); + +// One track fanned out to an ascending and a descending subscriber, the shape a relay serves +// from one upstream request (a JS app does not proxy, so the track is local here). The +// aggregate a wire would request upstream turns descending once the descending subscriber +// joins, so it is never held behind the other's backlog, and each session still serves its +// own subscriber in its own order. +test("a shared track aggregates descending and serves each subscriber in its own order", async () => { + const origin = new OriginProducer(); + const [ascending, descending] = await Promise.all([ + session(Lite.ALPN_07_WIP, origin), + session(Lite.ALPN_07_WIP, origin), + ]); + + const broadcast = origin.createBroadcast(Path.from("test")); + broadcast.announce(); + const video = broadcast.createTrack("video", { timescale: Timescale.MILLI }); + + const ascendingRemote = wireOf(ascending.client).consume(Path.from("test")); + const ascendingTrack = ascendingRemote.track("video").subscribe({ maxDelay: MAX_DELAY, order: "ascending" }); + await aggregate(video, (order) => order === "ascending"); + + const descendingRemote = wireOf(descending.client).consume(Path.from("test")); + const descendingTrack = descendingRemote.track("video").subscribe({ maxDelay: MAX_DELAY, order: "descending" }); + await aggregate(video, (order) => order === "descending"); + + // One at a time, so each session opens its streams in sequence order. + const groups: GroupProducer[] = []; + for (let i = 0; i < 3; i++) { + groups.push(writeGroup(video)); + await Promise.all([receive(ascendingTrack, 1), receive(descendingTrack, 1)]); + } + + expect(sendOrders(ascending.transport)).toEqual(expected("ascending", 3)); + expect(sendOrders(descending.transport)).toEqual(expected("descending", 3)); + + for (const group of groups) group.close(); + ascendingTrack.close(); + descendingTrack.close(); + ascendingRemote.close(); + descendingRemote.close(); + broadcast.close(); + for (const { client, server } of [ascending, descending]) { + client.abort(); + server.abort(); + } +}); diff --git a/js/net/src/lite/priority.test.ts b/js/net/src/priority.test.ts similarity index 75% rename from js/net/src/lite/priority.test.ts rename to js/net/src/priority.test.ts index db70ad2a906..43103b38063 100644 --- a/js/net/src/lite/priority.test.ts +++ b/js/net/src/priority.test.ts @@ -1,10 +1,10 @@ import { expect, test } from "bun:test"; -import { Producer as BroadcastProducer } from "../broadcast.ts"; -import { type SendStream, Writer } from "../stream.ts"; -import { Timescale } from "../time.ts"; - +import { Producer as BroadcastProducer } from "./broadcast.ts"; +import { Version } from "./lite/version.ts"; import { Priority, sendOrder } from "./priority.ts"; -import { Version } from "./version.ts"; +import { type SendStream, Writer } from "./stream.ts"; +import { Timescale } from "./time.ts"; +import type { Subscription } from "./track.ts"; // The last position that still fits below the track priority. const MAX_POSITION = 2 ** 44 - 1; @@ -56,7 +56,7 @@ test("out of range ranks stay inside their own bits", () => { // The ranking itself, driven directly: a subscription outlives its own serving loop, since a // group already on the wire keeps writing after the track stops handing out new ones. -function ranking(options: { priority?: number; ordered?: boolean } = {}) { +function ranking(options: Subscription = {}) { const broadcast = new BroadcastProducer(); const track = broadcast.createTrack("video", { timescale: Timescale.MILLI }); const subscriber = track.subscribe(options); @@ -69,7 +69,7 @@ function ranking(options: { priority?: number; ordered?: boolean } = {}) { return new Writer(stream, Version.DRAFT_06); }; - return { priority: new Priority(subscriber), open, streams, broadcast }; + return { priority: new Priority(subscriber), subscriber, open, streams, broadcast }; } // A track that finishes while several groups are still draining leaves them as the only data @@ -95,3 +95,28 @@ test("groups still draining are promoted after the subscription closes", () => { priority.remove(older); broadcast.close(); }); + +// An ascending subscription drains its backlog oldest first, and changing the order re-ranks +// the groups already on the wire rather than only the ones opened after. +test("the subscription's order picks which group goes first", async () => { + const { priority, subscriber, open, streams, broadcast } = ranking({ priority: 7, order: "ascending" }); + + const writers = [5, 1, 10].map((sequence) => { + const writer = open(); + priority.add(writer, sequence); + return writer; + }); + const at = (...positions: number[]) => positions.map((position) => sendOrder({ priority: 7, position })); + + // Groups 5, 1, 10: oldest first. + expect(streams.map((stream) => stream.sendOrder)).toEqual(at(1, 0, 2)); + + const changed = subscriber.subscription.changed(); + subscriber.update({ priority: 7, order: "descending" }); + await changed; + expect(streams.map((stream) => stream.sendOrder)).toEqual(at(1, 2, 0)); + + priority.close(); + for (const writer of writers) priority.remove(writer); + broadcast.close(); +}); diff --git a/js/net/src/lite/priority.ts b/js/net/src/priority.ts similarity index 83% rename from js/net/src/lite/priority.ts rename to js/net/src/priority.ts index 542143756d3..31172fbfc86 100644 --- a/js/net/src/lite/priority.ts +++ b/js/net/src/priority.ts @@ -1,12 +1,13 @@ /** - * Stream prioritization for moq-lite, mirroring the Rust `lite::priority` queue. + * Group stream prioritization shared by the moq-lite and moq-transport publishers, mirroring + * the Rust `lite::priority` queue. * * @module */ import type { Dispose } from "@moq/signals"; -import type { Writer } from "../stream.ts"; -import type * as track from "../track.ts"; +import type { Writer } from "./stream.ts"; +import type * as track from "./track.ts"; // The transport compares send orders as a single number, so the two ranks are packed into // disjoint ranges: the track priority takes the high bits so it always dominates, and the @@ -60,9 +61,9 @@ function clamp(value: number, max: number): number { * set changes or the subscription is updated. * * A group's rank is its position among the groups in flight, so which group goes first is - * decided here rather than by arithmetic on sequence numbers. Newest first, always: under - * congestion that sheds the backlog rather than the live edge, and a subscriber wanting - * sequence order reorders locally rather than asking the wire for it. + * decided here rather than by arithmetic on sequence numbers. The subscription's + * {@link track.Order} picks the direction: newest first sheds a congested backlog rather than + * the live edge, oldest first drains it. * * One listener covers the whole subscription. A listener per group would instead pile up on * it, and a track that stalls with many groups open would trip the signals leak guard. @@ -83,9 +84,10 @@ export class Priority { /** The send order for a group at `sequence`, whether or not it has a stream yet. */ rank(sequence: number): number { + const subscription = this.#track.subscription.peek(); return sendOrder({ - priority: this.#track.subscription.peek()?.priority ?? 0, - position: this.#position(sequence), + priority: subscription?.priority ?? 0, + position: this.#position(sequence, subscription?.order), }); } @@ -124,18 +126,19 @@ export class Priority { // How many of this subscription's groups in flight should be sent before `sequence`. // Sequences are unique within a subscription, so a group already registered never counts // itself. - #position(sequence: number): number { + #position(sequence: number, order: track.Order = "descending"): number { let ahead = 0; for (const other of this.#streams.values()) { - if (other > sequence) ahead++; + if (order === "ascending" ? other < sequence : other > sequence) ahead++; } return ahead; } #rerank() { - const priority = this.#track.subscription.peek()?.priority ?? 0; + const subscription = this.#track.subscription.peek(); + const priority = subscription?.priority ?? 0; for (const [stream, sequence] of this.#streams) { - stream.setPriority(sendOrder({ priority, position: this.#position(sequence) })); + stream.setPriority(sendOrder({ priority, position: this.#position(sequence, subscription?.order) })); } } } diff --git a/js/net/src/track.test.ts b/js/net/src/track.test.ts index d979da41091..5821d85e86e 100644 --- a/js/net/src/track.test.ts +++ b/js/net/src/track.test.ts @@ -300,15 +300,22 @@ test("subscriber options and updates are forwarded to the producer's aggregate", expect(producer.subscription.peek()).toEqual({ priority: 0, maxDelay: Milli(0), + order: "descending", groups: { start: { included: 0 } }, }); // The wire layer watches the producer's signal to emit SUBSCRIBE_UPDATE. const next = producer.subscription.changed(); - track.update({ priority: 7, maxDelay: Milli(250), groups: { start: { included: 2 }, end: { excluded: 9 } } }); + track.update({ + priority: 7, + maxDelay: Milli(250), + order: "ascending", + groups: { start: { included: 2 }, end: { excluded: 9 } }, + }); expect(await next).toEqual({ priority: 7, maxDelay: Milli(250), + order: "ascending", groups: { start: { included: 2 }, end: { excluded: 9 } }, }); }); @@ -332,6 +339,14 @@ test("subscriber maxAge is refused before defaults or updates take effect", () = producer.close(); }); +// A typo from plain JS would otherwise be served as the default without a word. +test("an unknown subscriber order is refused", () => { + const producer = new TrackProducer("test"); + expect(() => producer.subscribe({ order: "newest" } as unknown as Subscription)).toThrow(TypeError); + expect(producer.subscription.peek()).toBeUndefined(); + producer.close(); +}); + test("a fractional maxDelay is rounded up before the wire sees it", async () => { const producer = new TrackProducer("test"); @@ -387,13 +402,17 @@ test("multiple subscriber options aggregate like Rust", async () => { const bounded = producer.subscribe({ priority: 2, maxDelay: Milli(100), + order: "ascending", groups: { start: { included: 10 }, end: { excluded: 20 } }, }); const live = producer.subscribe({ priority: 7, maxDelay: Milli(250), groups: { start: { included: 5 } } }); + // One descending subscriber makes the aggregate descending, so a live reader is never held + // behind another's backlog. expect(producer.subscription.peek()).toEqual({ priority: 7, maxDelay: Milli(250), + order: "descending", groups: { start: { included: 5 } }, }); @@ -402,6 +421,7 @@ test("multiple subscriber options aggregate like Rust", async () => { expect(await narrowed).toEqual({ priority: 2, maxDelay: Milli(100), + order: "ascending", groups: { start: { included: 10 }, end: { excluded: 20 } }, }); diff --git a/js/net/src/track.ts b/js/net/src/track.ts index 57630978b2d..1a3040842a6 100644 --- a/js/net/src/track.ts +++ b/js/net/src/track.ts @@ -159,8 +159,30 @@ export interface Subscription { * subscription naming where it left off). */ groups?: Groups; + /** + * Which pending group the publisher sends first. Defaults to `"descending"`. + * + * Carried by moq-lite 07 and moq-transport (fixed at subscribe time there); older + * moq-lite versions are served newest first whatever this says. + * + * Aggregated across every live subscriber: any descending subscriber makes the aggregate + * descending, so a relay fanning one upstream request out keeps its live subscribers + * fresh. Each subscriber's own publisher still serves it in its own order. + */ + order?: Order; } +/** + * Which of a subscription's pending groups the publisher sends first: `"descending"` (newest + * first, so congestion sheds the backlog rather than the live edge) or `"ascending"` (oldest + * first, draining a backlog in sequence order). + * + * A transmission order only: it never decides whether a group is delivered, which is + * {@link Subscription.maxDelay}'s job, so an ascending subscriber that wants a backlog needs a + * budget that covers it. + */ +export type Order = "ascending" | "descending"; + // Materialize the defaults at the model boundary so every layer observes a complete // subscription rather than interpreting an omitted field differently. function subscriptionDefaults(subscription: Subscription = {}): Subscription { @@ -169,6 +191,7 @@ function subscriptionDefaults(subscription: Subscription = {}): Subscription { return { priority: priorityByte(subscription.priority ?? 0), maxDelay: wireMillis("maxDelay", subscription.maxDelay ?? Milli.zero), + order: orderOf(subscription.order), groups: { start: subscription.groups?.start === undefined ? undefined : { included: bounds.start }, end: bounds.end === undefined ? undefined : { excluded: bounds.end }, @@ -176,6 +199,13 @@ function subscriptionDefaults(subscription: Subscription = {}): Subscription { }; } +// A plain JS caller can pass anything, and silently serving a typo as descending would hide it. +function orderOf(order: Order | undefined): Order { + if (order === undefined) return "descending"; + if (order !== "ascending" && order !== "descending") throw new TypeError(`unknown order: ${String(order)}`); + return order; +} + // Aggregate the preferences of every live subscriber, matching Rust's Subscription::poll_combined. function combineSubscriptions(states: Iterable): Subscription | undefined { let combined: Subscription | undefined; @@ -189,6 +219,9 @@ function combineSubscriptions(states: Iterable): Subscription | unde combined.priority = Math.max(combined.priority ?? 0, subscription.priority ?? 0); combined.maxDelay = Milli(Math.max(combined.maxDelay ?? Milli.zero, subscription.maxDelay ?? Milli.zero)); + // One live subscriber held behind another's backlog is worse than a backlog sent late. + combined.order = + combined.order === "ascending" && subscription.order === "ascending" ? "ascending" : "descending"; // A floor only restricts, so a subscriber without one clears the aggregate: // its budget may reach below any floor the others set. diff --git a/quest/m1/subscribe-ranges/README.md b/quest/m1/subscribe-ranges/README.md index 99a584ccea9..9836d735bd6 100644 --- a/quest/m1/subscribe-ranges/README.md +++ b/quest/m1/subscribe-ranges/README.md @@ -30,8 +30,7 @@ relay bounds a sparse FETCH only if the model can request ranges: requested ranges the publisher won't deliver: never existed, expired, or refused upstream. Datagram groups are always dropped in a past range (#4982). The publisher delivers what it has and fills the rest as upstream answers. -- **Model.** `Subscription` gains `ranges` and `order`, mirroring the wire - (`order` lands first, split out 2026-10-13); +- **Model.** `Subscription` gains `ranges` beside its `order`, mirroring the wire; `request_groups` as a separate API was rejected. A publisher's `track::Dynamic` receives range requests for misses, replacing per-group `requested_group`, and `fetch_group` becomes a one-range subscription or is @@ -72,7 +71,6 @@ every sequence delivered or dropped. ## Required -- [Subscription order](/quest/m1/subscribe-ranges/order.md) - `Subscription` carries ascending or descending order in both languages, over moq-transport and lite-07 - [Model ranges](/quest/m1/subscribe-ranges/model.md) - `Subscription` carries ranges, and `Dynamic` fills misses by range - [SUBSCRIBE_DROP](/quest/m1/subscribe-drop.md) - publishers name every group they won't deliver - [Lite-07 ranges](/quest/m1/subscribe-ranges/lite.md) - the lite-07 wire, Rust publisher and subscriber, and the draft diff --git a/quest/m1/subscribe-ranges/js.md b/quest/m1/subscribe-ranges/js.md index adb072fc32f..97852e818a3 100644 --- a/quest/m1/subscribe-ranges/js.md +++ b/quest/m1/subscribe-ranges/js.md @@ -2,9 +2,8 @@ ## Goal -`@moq/net` matches Rust: `Subscription` carries ranges beside the order from -[Subscription order](/quest/m1/subscribe-ranges/order.md), the lite-07 -SUBSCRIBE carries them on the wire, FETCH is gone from lite-07, and +`@moq/net` matches Rust: `Subscription` carries ranges beside its existing +`order`, the lite-07 SUBSCRIBE carries them on the wire, FETCH is gone from lite-07, and `fetchGroup` becomes a one-range subscription or is removed. A JavaScript publisher serves requested ranges that are no longer in its live cache. diff --git a/quest/m1/subscribe-ranges/model.md b/quest/m1/subscribe-ranges/model.md index 2d2884d00c1..1f8684994ba 100644 --- a/quest/m1/subscribe-ranges/model.md +++ b/quest/m1/subscribe-ranges/model.md @@ -16,8 +16,8 @@ Guidance: - Ranges have `Absolute` or `Relative` ends (see the line). Aggregating subscribers onto one upstream request is the union of their ranges; a relative end resolves against the track's latest group when the publisher - serves it. [Subscription order](/quest/m1/subscribe-ranges/order.md) owns - `order` and its merge rule (descending wins). + serves it. Ranges are served in the existing `Subscription::order`, which + merges with descending winning. - This absorbs the deleted lite-07 Live flag quest, so the model mirrors the wire with no `live` field, and its tests move here, on mock time and both in-process and through a relay: a subscriber from `Absolute(4)` merged with @@ -48,5 +48,4 @@ Guidance: ## Related -- [Subscription order](/quest/m1/subscribe-ranges/order.md) - `Subscription` carries `order`, which ranges are served in - [FETCH max-delay](/quest/m1/fetch-max-delay.md) - historical request budgets and per-caller enforcement diff --git a/quest/m1/subscribe-ranges/order.md b/quest/m1/subscribe-ranges/order.md deleted file mode 100644 index a623b281a85..00000000000 --- a/quest/m1/subscribe-ranges/order.md +++ /dev/null @@ -1,36 +0,0 @@ -# [L] Subscription order - -## Goal - -A subscriber chooses whether a track serves pending groups oldest or newest -first. `Subscription` carries `order: Order` (`Ascending` or `Descending`, -default `Descending`, today's rule) in Rust and `@moq/net`, and the track's -cursor serves its own subscriber in that order: ascending drains a backlog -oldest first instead of skipping to the newest group. moq-transport SUBSCRIBE -GROUP_ORDER and the lite-07 SUBSCRIBE carry it. Ranges stay in -[Model ranges](/quest/m1/subscribe-ranges/model.md). - -## Plan - -Split out of the model quest (maintainer, 2026-10-13) so it can land on -moq-dev/moq#5370, which added a JS GROUP_ORDER codec field nothing set or -honored. Build on that contributor's commit and credit them with a -`Co-authored-by:` trailer. - -- **Name.** `Order` under the track module (`Order::Ascending`, - `Order::Descending`; JS `"ascending" | "descending"`), not `GroupOrder`. - The private IETF `GroupOrder` maps to it; draft-14's 0 (any) decodes as - `Descending`, so no default variant is representable in the model. -- **Aggregation.** Subscribers sharing one upstream request may want - different orders; `Descending` wins upstream, so live subscribers stay - fresh. Each local cursor still serves its own subscriber in its own order - from the cache. -- **Wire.** lite-07 SUBSCRIBE and SUBSCRIBE_UPDATE carry `order`, documented - in `drafts/draft-lcurley-moq-lite.md`; lite-07 is unpublished. moq-transport - maps GROUP_ORDER both ways, and its publisher honors `Ascending`. -- **Older wires.** lite-06 and older cannot carry the field: an `Ascending` - subscription over them falls back to `Descending` (maintainer, 2026-10-13). -- Cover on mock time, in-process and through a relay, in both languages: a - backlog served ascending and descending, an ascending and a descending - subscriber merged on one upstream request, and an `Ascending` request over - lite-06 served newest first. diff --git a/rs/moq-net/benches/priority.rs b/rs/moq-net/benches/priority.rs index 3d593a19782..0bb25f0914b 100644 --- a/rs/moq-net/benches/priority.rs +++ b/rs/moq-net/benches/priority.rs @@ -1,13 +1,18 @@ -//! Worst-case insertion benchmarks for the Lite publisher's stream priority queue. +//! Worst-case insertion benchmarks for the publishers' stream priority queue. use criterion::{BatchSize, BenchmarkId, Criterion, criterion_group, criterion_main}; -// Compiled straight from source so the queue stays private to `lite`; a `pub` re-export +// Compiled straight from source so the queue stays private to the crate; a `pub` re-export // just for the bench would widen the crate's surface. -#[path = "../src/lite/priority.rs"] +#[path = "../src/priority.rs"] #[allow(dead_code)] mod priority; +// The queue names `crate::track::Order`, which is public. +mod track { + pub use moq_net::track::Order; +} + use priority::{Priority, PriorityHandle, PriorityQueue}; const DEPTHS: [usize; 3] = [8, 64, 255]; diff --git a/rs/moq-net/src/fuzz.rs b/rs/moq-net/src/fuzz.rs index 7ca5a21be26..61708b02db9 100644 --- a/rs/moq-net/src/fuzz.rs +++ b/rs/moq-net/src/fuzz.rs @@ -339,6 +339,7 @@ impl LiteSample { .encode(w, version) .unwrap(), Self::Subscribe => lite::Subscribe { + order: crate::track::Order::Descending, epoch: None, id: 3, broadcast: Path::new("room/alice"), @@ -523,6 +524,7 @@ impl Default for Messages { Self { lite_subscribe: lite::Subscribe { + order: crate::track::Order::Descending, epoch: None, id: 7, broadcast: Path::new("room/alice"), @@ -535,6 +537,7 @@ impl Default for Messages { end_frame: None, }, lite_update: lite::SubscribeUpdate { + order: crate::track::Order::Descending, priority: 4, max_delay: Duration::from_millis(500), start_group: Some(1_000), diff --git a/rs/moq-net/src/ietf/group.rs b/rs/moq-net/src/ietf/group.rs index c49de86026e..7eb58215e19 100644 --- a/rs/moq-net/src/ietf/group.rs +++ b/rs/moq-net/src/ietf/group.rs @@ -132,6 +132,24 @@ impl GroupOrder { other => other, } } + + /// The model's order: `Any` leaves the choice to the publisher, which serves newest + /// first. + pub fn to_order(self) -> crate::track::Order { + match self { + Self::Ascending => crate::track::Order::Ascending, + Self::Any | Self::Descending => crate::track::Order::Descending, + } + } +} + +impl From for GroupOrder { + fn from(order: crate::track::Order) -> Self { + match order { + crate::track::Order::Ascending => Self::Ascending, + crate::track::Order::Descending => Self::Descending, + } + } } impl Encode for GroupOrder { diff --git a/rs/moq-net/src/ietf/publisher.rs b/rs/moq-net/src/ietf/publisher.rs index 674bd79a937..76b2da615c6 100644 --- a/rs/moq-net/src/ietf/publisher.rs +++ b/rs/moq-net/src/ietf/publisher.rs @@ -16,7 +16,8 @@ use crate::{ AsPath, DecodeError, Error, Timescale, Timestamp, coding::{Encode as _, Encoder, Stream, Writer}, ietf::{self, Control, EndLocation, FetchHeader, FetchType, Filter, GroupOrder, Location, RequestId}, - track::Subscription, + priority::{Priority, PriorityHandle, PriorityQueue}, + track::{Order, Subscription}, util::{MaybeBoxedExt, MaybeSendBox}, }; @@ -42,8 +43,8 @@ fn serving_subscription(subscriber_priority: u8) -> Subscription { /// INCLUDE_PROPERTIES=0, which keeps the block present but empty. /// /// Declaring the timescale is what opts the track into timestamps; every object Timestamp -/// is in these units. We serve the newest group first, matching moq-lite. A draft without -/// room for a property drops it on encode. +/// is in these units. We serve the newest group first by default, matching moq-lite. A draft +/// without room for a property drops it on encode. fn track_properties(info: &track::Info, wanted: bool) -> ietf::Properties { if !wanted { return ietf::Properties::default(); @@ -376,6 +377,8 @@ pub(super) struct Publisher { pub(super) owed: Arc, // Subscriptions the peer may hold at once (`session::Limits::subscriptions`). pub(super) subscriptions: crate::session::Slots, + // Ranks every subscription's group streams against each other for the transport. + priority: PriorityQueue, } struct Serve(Arc); @@ -444,6 +447,7 @@ where auth: crate::auth::Handle::new(false), owed: Default::default(), subscriptions: Default::default(), + priority: Default::default(), } } @@ -769,7 +773,8 @@ where } }; - let mut subscription = serving_subscription(msg.subscriber_priority); + let order = msg.group_order.to_order(); + let mut subscription = serving_subscription(msg.subscriber_priority).with_order(order); let priority = subscription.priority; // Subscribe before resolving the filter: on a routed broadcast the live edge only @@ -850,7 +855,15 @@ where track_alias: request_id.0, // The subscription floor and FETCH/FILL cap use this same snapshot. largest: edge.largest, - properties: track_properties(track.info(), msg.properties_wanted), + properties: { + let mut properties = track_properties(track.info(), msg.properties_wanted); + // Through draft-15 this restates the order the subscription is served in. + // Later drafts carry the publisher's default instead. + if matches!(self.version, Version::Draft14 | Version::Draft15) { + properties.group_order = Some(order.into()); + } + properties + }, }) .await?; @@ -860,7 +873,8 @@ where // The fill (when one was requested) runs alongside on its own fetch stream; // its failures reset that stream and never touch the subscription. let mut track_serve = - TrackServe::new(self.session.clone(), track, request_id, self.version, range, timescale); + TrackServe::new(self.session.clone(), track, request_id, self.version, range, timescale) + .ranked(self.priority.clone()); let opened = track_serve.opened.clone(); let fill = async { if let Some((fill, cache, timescale)) = fill { @@ -2896,6 +2910,8 @@ struct TrackServe { children: kio::Tasks>, /// The subscriber priority, which every group stream follows while it is open. priority: kio::Producer, + /// Where the group streams are ranked: the session's queue once [`Self::ranked`]. + queue: PriorityQueue, /// The track finished: the in-flight group machines drain, then FIN. draining: bool, /// Group streams opened, shared with the group machines. @@ -2945,6 +2961,7 @@ impl TrackServe { timescale, children: kio::Tasks::new(), priority, + queue: PriorityQueue::default(), draining: false, opened: Default::default(), end: None, @@ -2953,6 +2970,28 @@ impl TrackServe { } } + /// Rank this subscription's group streams in `queue`, shared with the session's other + /// subscriptions. Without it they are only ranked against each other. + fn ranked(mut self, queue: PriorityQueue) -> Self { + self.queue = queue; + self + } + + /// This group's place in the queue, in the subscription's order. + fn rank(&self, sequence: u64) -> Rank { + let priority = self.priority.consume(); + let current = *priority.read(); + let order = self.track.subscription().order; + Rank { + handle: self + .queue + .insert(Priority::new(current, self.request_id.0, sequence).with_order(order)), + priority, + applied: current, + order, + } + } + /// Move the subscriber priority, for the group streams already open as well as later ones. fn set_priority(&mut self, priority: u8) -> Result<(), Error> { let mut subscription = self.track.subscription(); @@ -3072,11 +3111,12 @@ impl TrackServe { }, }; + let rank = self.rank(sequence); self.children.push( GroupServe::new( self.session.clone(), msg, - self.priority.consume(), + rank, group, self.timescale, self.version, @@ -3159,6 +3199,49 @@ impl TrackServe { } } +/// A group stream's place in the session's send order: its subscription's priority, then +/// its sequence in the subscription's GROUP_ORDER. +struct Rank { + handle: PriorityHandle, + /// The subscription's priority, followed while the stream is open. + priority: kio::Consumer, + /// The priority last applied to [`Self::handle`]. + applied: u8, + /// The subscription's GROUP_ORDER, fixed for its life: no update carries it. + order: Order, +} + +impl Rank { + /// A group ranked only against itself, for driving one group machine alone. + #[cfg(test)] + fn solo(priority: kio::Consumer) -> Self { + let applied = *priority.read(); + Self { + handle: PriorityQueue::default().insert(Priority::new(applied, 0, 0)), + priority, + applied, + order: Order::Descending, + } + } + + /// A send order for the stream once the subscription priority or the queue moved it. + fn poll_moved(&mut self, waiter: &kio::Waiter) -> Option { + let applied = self.applied; + let mut moved = None; + if let Poll::Ready(Ok(priority)) = self.priority.poll(waiter, |priority| match **priority == applied { + true => Poll::Pending, + false => Poll::Ready(**priority), + }) { + self.applied = priority; + moved = Some(PriorityHandle::send_order_of(self.handle.steer(priority, self.order))); + } + while let Poll::Ready(rank) = self.handle.poll_next(waiter) { + moved = Some(PriorityHandle::send_order_of(rank)); + } + moved + } +} + /// Serves one group on its own unidirectional stream in the moq-transport /// subgroup format. struct GroupServe { @@ -3166,10 +3249,7 @@ struct GroupServe { /// The subscription's count of opened streams, bumped once this one opens. opened: Arc, msg: ietf::GroupHeader, - /// The subscription's priority, followed while the stream is open. - priority: kio::Consumer, - /// The priority last handed to the stream. - applied: u8, + rank: Rank, group: group::Consumer, timescale: Option, version: Version, @@ -3219,7 +3299,7 @@ impl GroupServe { fn new( session: S, msg: ietf::GroupHeader, - priority: kio::Consumer, + rank: Rank, mut group: group::Consumer, timescale: Option, version: Version, @@ -3228,13 +3308,11 @@ impl GroupServe { group.skip_to(slice.skip); group.end_at(slice.until.map_or(Bound::Unbounded, Bound::Excluded)); let object_delta = group.index(); - let applied = *priority.read(); Self { session, opened: Default::default(), msg, - applied, - priority, + rank, group, timescale, version, @@ -3259,20 +3337,11 @@ impl GroupServe { fn poll_serve(&mut self, waiter: &kio::Waiter) -> Poll> { let mut cx = waiter.context(); - // A REQUEST_UPDATE can move the subscriber priority while this stream is open. - // Serve and Closed, the only states holding a writer, apply the change; Open - // reads the current value once it gets its stream. - let applied = self.applied; - let mut moved = match self.priority.poll(waiter, |priority| match **priority == applied { - true => Poll::Pending, - false => Poll::Ready(**priority), - }) { - Poll::Ready(Ok(priority)) => { - self.applied = priority; - Some(priority) - } - _ => None, - }; + // A REQUEST_UPDATE can move the subscriber priority while this stream is open, and + // the session's other group streams can move its rank. Serve and Closed, the only + // states holding a writer, apply the change; Open reads the current rank once it + // gets its stream. + let mut moved = self.rank.poll_moved(waiter); loop { match &mut self.state { GroupState::Open => { @@ -3289,8 +3358,9 @@ impl GroupServe { }; self.opened.fetch_add(1, Ordering::Relaxed); let mut stream = stream; - self.applied = *self.priority.read(); - stream.set_priority(self.applied.into()); + // The current rank, which already includes anything `moved` saw. + stream.set_priority(self.rank.handle.send_order().into()); + moved = None; let mut writer = Writer::new(stream, self.version); if let Err(err) = writer.buffer(&self.msg) { @@ -3697,7 +3767,7 @@ mod group_priority_test { publisher_priority: 0, flags: Default::default(), }, - kio::Producer::new(0).consume(), + Rank::solo(kio::Producer::new(0).consume()), group, Some(Timescale::MILLI), Version::Draft19, @@ -3734,14 +3804,25 @@ mod group_priority_test { } } + /// A group of `subscribe` ranked in `queue` at `priority`'s current value. + fn rank_in(queue: &PriorityQueue, priority: &kio::Producer, subscribe: u64) -> Rank { + let applied = *priority.read(); + Rank { + handle: queue.insert(Priority::new(applied, subscribe, 0)), + priority: priority.consume(), + applied, + order: Order::Descending, + } + } + /// The model's `Subscription::priority` is higher-first ("higher values preempt - /// lower ones"), matching the transport trait's send order, so a group stream must - /// receive the model value unchanged. An inversion here would transmit the - /// LOWEST-priority track first under contention. + /// lower ones"), matching the transport trait's send order, so the higher-priority + /// subscription's group stream must get the higher send order. An inversion here + /// would transmit the LOWEST-priority track first under contention. #[moq_net_sim::test] async fn group_stream_preserves_model_priority() { let log = crate::lite::test_transport::Log::default(); - let session = SinkSession::new(log.clone()); + let queue = PriorityQueue::default(); let track = track::Producer::new( std::sync::Arc::new(crate::broadcast::Info::default()), @@ -3752,7 +3833,6 @@ mod group_priority_test { group .write_frame(crate::Timestamp::from_millis(0).unwrap(), b"hello".as_slice()) .unwrap(); - let consumer = group.consume(); group.finish().unwrap(); let msg = ietf::GroupHeader { @@ -3763,21 +3843,28 @@ mod group_priority_test { flags: Default::default(), }; - let mut serve = GroupServe::new( - session, - msg, - kio::Producer::new(200).consume(), - consumer, - Some(Timescale::MILLI), - Version::Draft14, - GroupSlice::default(), - ); - kio::wait(|waiter| serve.poll_serve(waiter)).await.unwrap(); + // Queue both before either opens, so each stream is handed its final rank. + let high = kio::Producer::new(200); + let low = kio::Producer::new(100); + let mut serves = [(&low, 1), (&high, 0)].map(|(priority, subscribe)| { + GroupServe::new( + SinkSession::new(log.clone()), + msg.clone(), + rank_in(&queue, priority, subscribe), + group.consume(), + Some(Timescale::MILLI), + Version::Draft14, + GroupSlice::default(), + ) + }); + for serve in &mut serves { + kio::wait(|waiter| serve.poll_serve(waiter)).await.unwrap(); + } assert_eq!( log.priorities(), - vec![200], - "model priority must pass through unchanged" + vec![254, 255], + "the higher model priority must transmit first" ); } @@ -4080,7 +4167,7 @@ mod group_priority_test { publisher_priority: 0, flags: Default::default(), }, - kio::Producer::new(0).consume(), + Rank::solo(kio::Producer::new(0).consume()), group, Some(Timescale::MILLI), Version::Draft19, @@ -4127,7 +4214,7 @@ mod group_priority_test { publisher_priority: 0, flags: Default::default(), }, - kio::Producer::new(0).consume(), + Rank::solo(kio::Producer::new(0).consume()), group, Some(Timescale::MILLI), Version::Draft19, @@ -4165,6 +4252,10 @@ mod group_priority_test { let consumer = group.consume(); group.finish().unwrap(); + // Another subscription's group at 150 sits in the same queue, so each update + // moves this stream across it. + let queue = PriorityQueue::default(); + let _other = queue.insert(Priority::new(150, 1, 0)); let priority = kio::Producer::new(200); let mut serve = GroupServe::new( session, @@ -4175,7 +4266,7 @@ mod group_priority_test { publisher_priority: 0, flags: Default::default(), }, - priority.consume(), + rank_in(&queue, &priority, 0), consumer, Some(Timescale::MILLI), Version::Draft19, @@ -4186,15 +4277,15 @@ mod group_priority_test { futures::poll!(serving.as_mut()).is_pending(), "the FIN is unacknowledged" ); - assert_eq!(log.priorities(), vec![200]); + assert_eq!(log.priorities(), vec![255]); *priority.write().ok().unwrap() = 100; assert!(futures::poll!(serving.as_mut()).is_pending()); - assert_eq!(log.priorities(), vec![200, 100]); + assert_eq!(log.priorities(), vec![255, 254]); - *priority.write().ok().unwrap() = 50; + *priority.write().ok().unwrap() = 175; assert!(futures::poll!(serving.as_mut()).is_pending()); - assert_eq!(log.priorities(), vec![200, 100, 50]); + assert_eq!(log.priorities(), vec![255, 254, 255]); } /// The final payload remains guarded after its frame has advanced the group cursor. @@ -4226,7 +4317,7 @@ mod group_priority_test { publisher_priority: 0, flags: Default::default(), }, - kio::Producer::new(0).consume(), + Rank::solo(kio::Producer::new(0).consume()), group, Some(Timescale::MILLI), Version::Draft19, @@ -4530,6 +4621,10 @@ mod serve_tests { let h = serve(version); let session = ScriptedSession::new(Vec::new()); let mut stream = Stream::open(&mut session.clone(), version).await.unwrap(); + // Another subscription's group at 100 shares the queue, so the update moves this + // subscription's stream past it. + let queue = PriorityQueue::default(); + let _other = queue.insert(Priority::new(100, 1, 0)); let mut serving = TrackServe::new( h.session.clone(), h.track.subscribe(None), @@ -4537,7 +4632,8 @@ mod serve_tests { version, ServeRange::default(), None, - ); + ) + .ranked(queue); let mut finished = false; let mut run = std::pin::pin!( h.publisher @@ -4549,7 +4645,7 @@ mod serve_tests { group.write_frame(timestamp(), b"open".as_slice()).unwrap(); assert!(futures::poll!(run.as_mut()).is_pending()); let before = h.log.priorities(); - assert_eq!(before.len(), 1, "{before:?}"); + assert_eq!(before, [254], "below the other subscription"); // REQUEST_UPDATE with SUBSCRIBER_PRIORITY 10. session.push(&[0x02, 0, 4, 2, 1, 0x20, 10]); @@ -4558,7 +4654,7 @@ mod serve_tests { } assert_eq!(h.track.subscription().unwrap().priority, 245); let after = h.log.priorities(); - assert_eq!(after.last(), Some(&245), "{after:?}"); + assert_eq!(after.last(), Some(&255), "above the other subscription: {after:?}"); } #[moq_net_sim::test] @@ -7417,6 +7513,45 @@ mod serve_tests { .largest } + /// Through draft-15 SUBSCRIBE_OK restates the order the subscription is served in; later + /// drafts announce the publisher's default, newest first. + #[moq_net_sim::test] + async fn subscribe_ok_announces_the_served_order() { + for version in [ + Version::Draft14, + Version::Draft15, + Version::Draft16, + Version::Draft17, + Version::Draft20, + ] { + for (requested, announced) in [ + (GroupOrder::Ascending, GroupOrder::Ascending), + (GroupOrder::Descending, GroupOrder::Descending), + (GroupOrder::Any, GroupOrder::Descending), + ] { + let mut h = serve(version); + let mut msg = subscribe(Filter::NextObject, None); + msg.group_order = requested; + run_live(&mut h, msg).await; + + let writes = h.log.writes.lock().unwrap().clone(); + let mut buf = writes.as_slice(); + assert_eq!( + crate::coding::decode_varint(&mut buf, version).unwrap(), + ietf::SubscribeOk::ID + ); + let ok = crate::coding::decode_buf(&mut buf, version, ietf::SubscribeOk::decode).unwrap(); + let expected = match version { + Version::Draft14 | Version::Draft15 => Some(announced), + // Draft-16 has no room for it. + Version::Draft16 => None, + _ => Some(GroupOrder::Descending), + }; + assert_eq!(ok.properties.group_order, expected, "{version:?} {requested:?}"); + } + } + } + #[moq_net_sim::test] async fn largest_object_is_the_live_edge_before_draft20() { for version in [ @@ -7480,7 +7615,7 @@ mod serve_tests { let mut serve = GroupServe::new( session, header(), - kio::Producer::new(0).consume(), + Rank::solo(kio::Producer::new(0).consume()), consumer, Some(Timescale::MILLI), Version::Draft20, diff --git a/rs/moq-net/src/ietf/subscriber.rs b/rs/moq-net/src/ietf/subscriber.rs index 4ef936d7b84..b8a7c53f10b 100644 --- a/rs/moq-net/src/ietf/subscriber.rs +++ b/rs/moq-net/src/ietf/subscriber.rs @@ -2099,8 +2099,11 @@ where } // Write Subscribe message. The aggregate is read now: a subscriber can join while - // the request ID and stream were awaited, and nothing updates the priority after. - let priority = target.subscription().map(|s| s.priority).unwrap_or(0); + // the request ID and stream were awaited, and nothing updates the priority or + // order after. + let aggregate = target.subscription(); + let priority = aggregate.as_ref().map(|s| s.priority).unwrap_or(0); + let order = aggregate.map(|s| s.order).unwrap_or_default(); let written = async { stream.writer.varint(ietf::Subscribe::ID).await?; stream @@ -2110,7 +2113,7 @@ where track_namespace: broadcast_path.to_owned(), track_name: track_name.into(), subscriber_priority: super::priority::to_wire(priority), - group_order: GroupOrder::Descending, + group_order: order.into(), filter: join.filter, fill: join.fill, // A resumed copy already knows the track, from the answer that accepted it. diff --git a/rs/moq-net/src/lib.rs b/rs/moq-net/src/lib.rs index 31e6cf337c5..c57d0cd9f52 100644 --- a/rs/moq-net/src/lib.rs +++ b/rs/moq-net/src/lib.rs @@ -89,6 +89,7 @@ mod ietf; mod lite; mod model; pub mod path; +mod priority; mod recv; pub mod setup; mod tail; diff --git a/rs/moq-net/src/lite/mod.rs b/rs/moq-net/src/lite/mod.rs index d577793743c..b4cad690160 100644 --- a/rs/moq-net/src/lite/mod.rs +++ b/rs/moq-net/src/lite/mod.rs @@ -16,7 +16,6 @@ mod group; mod info; pub mod message; mod parameters; -mod priority; mod probe; mod publisher; mod session; diff --git a/rs/moq-net/src/lite/publisher.rs b/rs/moq-net/src/lite/publisher.rs index 8e839df7aff..936f6bf5c23 100644 --- a/rs/moq-net/src/lite/publisher.rs +++ b/rs/moq-net/src/lite/publisher.rs @@ -19,10 +19,9 @@ use crate::transport::Stats; use crate::{ Error, Hop, Hops, coding::{Decode, DecodeError, Decoder, Encode, Stream, Writer}, - lite::{ - self, - priority::{Priority, PriorityHandle, PriorityQueue}, - }, + lite, + priority::{Priority, PriorityHandle, PriorityQueue}, + track::Order, }; use super::Version; @@ -1887,6 +1886,7 @@ impl Request for SubscribeServe { let subscription = crate::track::Subscription { priority: msg.priority, max_delay: serving_max_delay(shared.version, msg.max_delay), + order: msg.order, ..Bounds::from(&msg).positions() }; @@ -1961,19 +1961,23 @@ impl Request for SubscribeServe { writer.buffer(&lite::SubscribeResponse::Ok(info))?; } - // Track-level subscriber priority. SUBSCRIBE_UPDATE messages broadcast - // new values to the run loop (so future groups inherit the new priority) - // and the in-flight group machines (so they update via - // PriorityHandle::set_track). - let track_priority_tx = kio::Producer::new(msg.priority); + // Track-level subscriber priority and group order. SUBSCRIBE_UPDATE + // messages broadcast new values to the run loop (so future groups inherit + // them) and the in-flight group machines (so they update via + // PriorityHandle::steer). + let steer = Steer { + priority: msg.priority, + order: msg.order, + }; + let steer_tx = kio::Producer::new(steer); let sub = Subscription { session: shared.session.clone(), id: msg.id, track_name: Arc::from(track.name()), priority: shared.priority.clone(), - track_priority: track_priority_tx.consume(), - track_priority_seen: msg.priority, + steer: steer_tx.consume(), + steer_seen: steer, version: shared.version, timescale, runtime: shared.runtime.clone(), @@ -1982,7 +1986,7 @@ impl Request for SubscribeServe { let bounds = Bounds::from(msg.as_ref()); position_cursor(&mut track, shared.version, bounds.start_group, latest); - let mut run = TrackRun::new(sub, track, bounds, track_priority_tx); + let mut run = TrackRun::new(sub, track, bounds, steer_tx); if let Some(update) = update { run.update(update); } @@ -3065,9 +3069,16 @@ impl From<&lite::SubscribeUpdate> for Bounds { } } +/// The part of each group's rank a SUBSCRIBE_UPDATE can move. +#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)] +struct Steer { + priority: u8, + order: Order, +} + /// Shared per-subscription state for the publisher side. Cloned cheaply. Every /// field is either small or already Arc-backed for each in-flight serve_group task -/// so each in-flight group reads the latest SUBSCRIBE_UPDATE priority via its own +/// so each in-flight group reads the latest SUBSCRIBE_UPDATE steer via its own /// consumer cursor. #[derive(Clone)] struct Subscription { @@ -3075,9 +3086,9 @@ struct Subscription { id: u64, track_name: Arc, priority: PriorityQueue, - track_priority: kio::Consumer, - /// Last track priority observed by this clone, so a change only fires once. - track_priority_seen: u8, + steer: kio::Consumer, + /// Last steer observed by this clone, so a change only fires once. + steer_seen: Steer, version: Version, /// Negotiated timestamp scale for this track. `Some(_)` on lite-05+ after /// TRACK_INFO; used to validate per-frame timestamps before encoding. @@ -3144,10 +3155,10 @@ impl Subscription { true } - /// Read the latest SUBSCRIBE_UPDATE track priority, marking it seen. - fn track_priority_current(&mut self) -> u8 { - self.track_priority_seen = *self.track_priority.read(); - self.track_priority_seen + /// Read the latest SUBSCRIBE_UPDATE steer, marking it seen. + fn steer_current(&mut self) -> Steer { + self.steer_seen = *self.steer.read(); + self.steer_seen } /// Remember an encode failure the group stream could not carry. @@ -3186,7 +3197,7 @@ struct TrackRun { ctx: Subscription, track: track::Subscriber, /// Broadcasts SUBSCRIBE_UPDATE priorities to the in-flight group machines. - track_priority_tx: kio::Producer, + steer_tx: kio::Producer, // Frame bounds qualify the start and end group only; everything in between is // served whole. Each is `(group, frame)`, or `None` for no offset at all. start_frame: Option<(u64, u64)>, @@ -3220,12 +3231,7 @@ struct TrackRun { } impl TrackRun { - fn new( - ctx: Subscription, - mut track: track::Subscriber, - bounds: Bounds, - track_priority_tx: kio::Producer, - ) -> Self { + fn new(ctx: Subscription, mut track: track::Subscriber, bounds: Bounds, steer_tx: kio::Producer) -> Self { // Apply the initial cap from the original Subscribe. Subsequent updates // flow through the SUBSCRIBE_UPDATE arm below. track.end_at(bounds.end_group.map_or(Bound::Unbounded, Bound::Included)); @@ -3241,7 +3247,7 @@ impl TrackRun { end_frame: bounds.end_frame(), ctx, track, - track_priority_tx, + steer_tx, emit_range, start: None, first: None, @@ -3262,8 +3268,11 @@ impl TrackRun { /// subscription. This is what lets relays pause an upstream subscription across /// consumer churn without tearing it down. fn update(&mut self, upd: lite::SubscribeUpdate) { - if let Ok(mut value) = self.track_priority_tx.write() { - *value = upd.priority; + if let Ok(mut value) = self.steer_tx.write() { + *value = Steer { + priority: upd.priority, + order: upd.order, + }; } // Feed the full update into the model subscriber so the producer's // aggregate reflects it (and a relay re-forwards it upstream). @@ -3274,6 +3283,7 @@ impl TrackRun { let _ = self.track.update(crate::track::Subscription { priority: upd.priority, max_delay: serving_max_delay(self.ctx.version, upd.max_delay), + order: upd.order, ..bounds.positions() }); // An explicit start moves the read cursor. Lite-06+ encodes an absent @@ -3543,15 +3553,15 @@ impl TrackRun { self.mark_served(sequence); tracing::debug!(subscribe = self.ctx.id, track = %self.ctx.track_name, sequence, "serving group"); - // Use the latest priority for new groups so SUBSCRIBE_UPDATE applies to them too. - let current_priority = self.ctx.track_priority_current(); + // Use the latest steer for new groups so SUBSCRIBE_UPDATE applies to them too. + let steer = self.ctx.steer_current(); // The subscribe id scopes the group tie-break: one queue serves every // subscription on the session, and only groups of the same one may be - // ranked against each other by sequence. + // ranked against each other by sequence, in that subscription's order. let handle = self .ctx .priority - .insert(Priority::new(current_priority, self.ctx.id, sequence)); + .insert(Priority::new(steer.priority, self.ctx.id, sequence).with_order(steer.order)); self.children .push(GroupServe::new(self.ctx.clone(), sequence, frame_start, handle, group)); } @@ -3640,17 +3650,17 @@ impl GroupServe { while let Poll::Ready(rank) = self.priority.poll_next(waiter) { writer.set_priority(PriorityHandle::send_order_of(rank)); } - let seen = self.ctx.track_priority_seen; + let seen = self.ctx.steer_seen; // A dropped producer just disables this arm, like the queue arm above. - if let Poll::Ready(Ok(value)) = self.ctx.track_priority.poll(waiter, |value| { + if let Poll::Ready(Ok(value)) = self.ctx.steer.poll(waiter, |value| { if **value != seen { Poll::Ready(**value) } else { Poll::Pending } }) { - self.ctx.track_priority_seen = value; - let rank = self.priority.set_track(value); + self.ctx.steer_seen = value; + let rank = self.priority.steer(value.priority, value.order); writer.set_priority(PriorityHandle::send_order_of(rank)); } } @@ -3999,14 +4009,14 @@ mod serve_group_test { let log = Log::default(); let session = SinkSession::new(log.clone()); - let track_priority = kio::Producer::new(0u8); + let steer = kio::Producer::new(Steer::default()); let subscription = Subscription { session, id: 0, track_name: "test".into(), priority: PriorityQueue::default(), - track_priority: track_priority.consume(), - track_priority_seen: 0, + steer: steer.consume(), + steer_seen: Steer::default(), version: Version::Lite06, timescale: Some(crate::Timescale::MILLI), runtime: crate::time::Clock::sim(), @@ -4043,14 +4053,14 @@ mod serve_group_test { let gate = kio::Producer::new(false); let session = SinkSession::gated_uni(gate.consume()); let log = session.log.clone(); - let track_priority = kio::Producer::new(0u8); + let steer = kio::Producer::new(Steer::default()); let subscription = Subscription { session, id: 0, track_name: "test".into(), priority: PriorityQueue::default(), - track_priority: track_priority.consume(), - track_priority_seen: 0, + steer: steer.consume(), + steer_seen: Steer::default(), version: Version::Lite06, timescale: Some(crate::Timescale::MILLI), runtime: crate::time::Clock::sim(), @@ -4091,14 +4101,14 @@ mod serve_group_test { let gate = kio::Producer::new(true); let session = SinkSession::gated_uni(gate.consume()); let log = session.log.clone(); - let track_priority = kio::Producer::new(0u8); + let steer = kio::Producer::new(Steer::default()); let subscription = Subscription { session, id: 0, track_name: "test".into(), priority: PriorityQueue::default(), - track_priority: track_priority.consume(), - track_priority_seen: 0, + steer: steer.consume(), + steer_seen: Steer::default(), version: Version::Lite06, timescale: Some(crate::Timescale::MILLI), runtime: crate::time::Clock::sim(), @@ -4157,14 +4167,14 @@ mod serve_group_test { async fn blocked_transport_open_expires_with_the_group() { let gate = kio::Producer::new(false); let session = SinkSession::gated_open_uni(gate.consume()); - let track_priority = kio::Producer::new(0u8); + let steer = kio::Producer::new(Steer::default()); let subscription = Subscription { session, id: 0, track_name: "test".into(), priority: PriorityQueue::default(), - track_priority: track_priority.consume(), - track_priority_seen: 0, + steer: steer.consume(), + steer_seen: Steer::default(), version: Version::Lite06, timescale: Some(crate::Timescale::MILLI), runtime: crate::time::Clock::sim(), @@ -4232,14 +4242,14 @@ mod serve_group_test { let log = Log::default(); let session = SinkSession::new(log.clone()); - let track_priority = kio::Producer::new(0u8); + let steer = kio::Producer::new(Steer::default()); let subscription = Subscription { session, id: 0, track_name: "test".into(), priority: PriorityQueue::default(), - track_priority: track_priority.consume(), - track_priority_seen: 0, + steer: steer.consume(), + steer_seen: Steer::default(), version: Version::Lite06, timescale: Some(crate::Timescale::MILLI), runtime: crate::time::Clock::sim(), @@ -4279,14 +4289,14 @@ mod serve_group_test { async fn unacknowledged_fin_expires_with_the_group() { let session = SinkSession::new(Log::default()).with_unacked_fin(); let log = session.log.clone(); - let track_priority = kio::Producer::new(0u8); + let steer = kio::Producer::new(Steer::default()); let subscription = Subscription { session, id: 0, track_name: "test".into(), priority: PriorityQueue::default(), - track_priority: track_priority.consume(), - track_priority_seen: 0, + steer: steer.consume(), + steer_seen: Steer::default(), version: Version::Lite06, timescale: Some(crate::Timescale::MILLI), runtime: crate::time::Clock::sim(), @@ -4325,14 +4335,14 @@ mod serve_group_test { async fn unacknowledged_fin_follows_priority_changes() { let session = SinkSession::new(Log::default()).with_unacked_fin(); let log = session.log.clone(); - let track_priority = kio::Producer::new(0u8); + let steer = kio::Producer::new(Steer::default()); let subscription = Subscription { session, id: 0, track_name: "test".into(), priority: PriorityQueue::default(), - track_priority: track_priority.consume(), - track_priority_seen: 0, + steer: steer.consume(), + steer_seen: Steer::default(), version: Version::Lite06, timescale: Some(crate::Timescale::MILLI), runtime: crate::time::Clock::sim(), @@ -4361,7 +4371,7 @@ mod serve_group_test { assert_eq!(log.priorities().last(), Some(&254)); // A SUBSCRIBE_UPDATE raising this track reranks it above the newer group. - *track_priority.write().ok().expect("the group watches the priority") = 1; + steer.write().ok().expect("the group watches the priority").priority = 1; assert!(futures::poll!(serve.as_mut()).is_pending()); assert_eq!(log.priorities().last(), Some(&255)); assert!(log.resets().is_empty()); @@ -4383,14 +4393,14 @@ mod serve_group_test { ) -> (TrackRun, Writer, Log) { let log = Log::default(); let writer = Writer::new(SinkSend::new(log.clone()), version); - let track_priority = kio::Producer::new(0u8); + let steer = kio::Producer::new(Steer::default()); let ctx = Subscription { session, id: 0, track_name: "test".into(), priority: PriorityQueue::default(), - track_priority: track_priority.consume(), - track_priority_seen: 0, + steer: steer.consume(), + steer_seen: Steer::default(), version, timescale: Some(crate::Timescale::MILLI), runtime: crate::time::Clock::sim(), @@ -4402,7 +4412,7 @@ mod serve_group_test { end_group: None, end_frame: None, }; - (TrackRun::new(ctx, track, bounds, track_priority), writer, log) + (TrackRun::new(ctx, track, bounds, steer), writer, log) } fn write_group(track: &mut track::Producer, sequence: u64, millis: u64) { @@ -4563,6 +4573,7 @@ mod serve_group_test { assert_eq!(run.start, Some(5)); run.update(lite::SubscribeUpdate { + order: crate::track::Order::Descending, priority: 0, max_delay: Duration::from_secs(60), start_group: Some(0), @@ -4604,6 +4615,7 @@ mod serve_group_test { moq_net_sim::advance(Duration::from_secs(2)).await; run.update(lite::SubscribeUpdate { + order: crate::track::Order::Descending, priority: 0, max_delay: Duration::from_secs(1), start_group: Some(0), @@ -4644,6 +4656,7 @@ mod serve_group_test { } let update = |start_group| lite::SubscribeUpdate { + order: crate::track::Order::Descending, priority: 0, max_delay: Duration::from_secs(1), start_group: Some(start_group), @@ -4692,6 +4705,7 @@ mod serve_group_test { assert_eq!(settle(&mut run), 1); run.update(lite::SubscribeUpdate { + order: crate::track::Order::Descending, priority: 0, max_delay: Duration::from_secs(60), start_group: None, @@ -4722,6 +4736,7 @@ mod serve_group_test { ); let (mut run, mut writer, _log) = lite_run(Version::Lite05, SinkSession::new(Log::default()), subscriber); run.update(lite::SubscribeUpdate { + order: crate::track::Order::Descending, priority: 0, max_delay: Duration::from_secs(60), start_group: None, @@ -4789,15 +4804,15 @@ mod serve_group_test { let session = ScriptedSession::new(Vec::new()); let writer = Writer::new(SinkSend::new(session.log.clone()), Version::Lite07); - let track_priority = kio::Producer::new(0u8); + let steer = kio::Producer::new(Steer::default()); let opens = Arc::::default(); let ctx = Subscription { session: session.clone(), id: 0, track_name: "test".into(), priority: PriorityQueue::default(), - track_priority: track_priority.consume(), - track_priority_seen: 0, + steer: steer.consume(), + steer_seen: Steer::default(), version: Version::Lite07, timescale: Some(crate::Timescale::MILLI), runtime: crate::time::Clock::sim(), @@ -4810,7 +4825,7 @@ mod serve_group_test { end_frame: None, }; Self { - run: TrackRun::new(ctx, subscriber, bounds, track_priority), + run: TrackRun::new(ctx, subscriber, bounds, steer), writer, session, opens, @@ -4856,6 +4871,7 @@ mod serve_group_test { assert_eq!(relay.opened(), 0, "the resume is past the only group"); relay.run.update(lite::SubscribeUpdate { + order: crate::track::Order::Descending, priority: 0, max_delay: Duration::from_secs(30), start_group: None, @@ -4886,6 +4902,7 @@ mod serve_group_test { assert_eq!(relay.opened(), 2, "groups 1 and 2 are at or above the floor"); relay.run.update(lite::SubscribeUpdate { + order: crate::track::Order::Descending, priority: 0, max_delay: Duration::from_secs(30), start_group: None, @@ -4913,6 +4930,7 @@ mod serve_group_test { // The subscriber moves its start past the held group before the source resolves. let update = lite::SubscribeUpdate { + order: crate::track::Order::Descending, priority: 0, max_delay: Duration::ZERO, start_group: Some(7), @@ -5510,6 +5528,7 @@ mod tests { leave_request::(version, &track, wait, close).await; let subscribe = lite::Subscribe { + order: crate::track::Order::Descending, epoch: None, id: 0, broadcast: broadcast.clone(), @@ -5650,6 +5669,7 @@ mod tests { let mut script = Vec::new(); lite::Subscribe { + order: crate::track::Order::Descending, epoch: None, id: 0, broadcast: crate::Path::new("room"), @@ -5677,6 +5697,7 @@ mod tests { assert!(!drive(&mut serve).await); let update = lite::SubscribeUpdate { + order: crate::track::Order::Descending, priority: 7, max_delay: Duration::ZERO, start_group: None, @@ -5698,7 +5719,7 @@ mod tests { let RequestState::Serve(SubscribeServe::Run(run)) = &serve.state else { panic!("the subscription is not running"); }; - assert_eq!(*run.track_priority_tx.read(), 7, "the update was lost"); + assert_eq!(run.steer_tx.read().priority, 7, "the update was lost"); } /// A subscription that always has another group ready yields within its budget, so a @@ -5739,6 +5760,7 @@ mod tests { let mut script = Vec::new(); lite::Subscribe { + order: crate::track::Order::Descending, epoch: None, id: 0, broadcast: crate::Path::new("room"), @@ -5843,6 +5865,7 @@ mod tests { }; let subscribe = encode(lite::ControlType::Subscribe, &|script| { lite::Subscribe { + order: crate::track::Order::Descending, epoch: None, id: 0, broadcast: crate::Path::new("room"), diff --git a/rs/moq-net/src/lite/subscribe.rs b/rs/moq-net/src/lite/subscribe.rs index 41708df312e..f34b38d3d3a 100644 --- a/rs/moq-net/src/lite/subscribe.rs +++ b/rs/moq-net/src/lite/subscribe.rs @@ -6,6 +6,7 @@ use crate::{ }; use super::{Message, Version}; +use crate::track::Order; /// Sent by the subscriber to request all future objects for the given track. /// @@ -33,6 +34,9 @@ pub struct Subscribe<'a> { /// Last frame to deliver (inclusive) within `end_group`'s group, or `None` for the /// whole group. Lite06+ only, and meaningless without an explicit `end_group`. pub end_frame: Option, + /// Which pending group to send first. Lite07+ only; earlier wires decode as + /// [`Order::Descending`] and cannot ask for anything else. + pub order: Order, } impl Version { @@ -54,14 +58,14 @@ impl Message for Subscribe<'_> { let track = Cow::Owned(r.string()?); let priority = r.u8()?; - let (max_delay, start_group, end_group) = match version { - Version::Lite01 | Version::Lite02 => (std::time::Duration::ZERO, None, None), + let (order, max_delay, start_group, end_group) = match version { + Version::Lite01 | Version::Lite02 => (Order::Descending, std::time::Duration::ZERO, None, None), _ => { - skip_group_order(r, version)?; + let order = decode_order(r, version)?; let max_delay = std::time::Duration::from_millis(r.varint()?); let start_group = decode_start_group(r, version)?; let end_group = r.varint_opt()?; - (max_delay, start_group, end_group) + (order, max_delay, start_group, end_group) } }; @@ -79,6 +83,7 @@ impl Message for Subscribe<'_> { end_group, start_frame, end_frame, + order, }) } @@ -92,7 +97,7 @@ impl Message for Subscribe<'_> { match version { Version::Lite01 | Version::Lite02 => {} _ => { - pad_group_order(w, version)?; + encode_order(w, version, self.order)?; w.varint(u64::try_from(self.max_delay.as_millis()).map_err(|_| EncodeError::BoundsExceeded)?)?; encode_start_group(w, version, self.start_group)?; w.varint_opt(self.end_group)?; @@ -131,6 +136,33 @@ pub(super) fn pad_group_order(w: &mut Encoder<'_>, version: Version) -> Result<( Ok(()) } +/// Decode the byte after the subscriber priority shared by SUBSCRIBE and SUBSCRIBE_UPDATE: +/// lite-07's `Group Order`, or the retired `Ordered` byte an older layout still carries. +fn decode_order(r: &mut Decoder<'_>, version: Version) -> Result { + if !version.has_order() { + skip_group_order(r, version)?; + return Ok(Order::Descending); + } + match r.u8()? { + 0 => Ok(Order::Descending), + 1 => Ok(Order::Ascending), + _ => Err(DecodeError::InvalidValue), + } +} + +/// Encode the inverse of [`decode_order`]. A wire without `Group Order` serves newest +/// first, so an ascending subscription over it falls back to descending. +fn encode_order(w: &mut Encoder<'_>, version: Version, order: Order) -> Result<(), EncodeError> { + if !version.has_order() { + return pad_group_order(w, version); + } + w.u8(match order { + Order::Descending => 0, + Order::Ascending => 1, + }); + Ok(()) +} + /// Decode the `Group Start` field shared by SUBSCRIBE and SUBSCRIBE_UPDATE. /// /// Lite-06 carries the raw floor, so every value names a concrete group and 0 decodes as @@ -388,6 +420,8 @@ pub struct SubscribeUpdate { pub start_frame: u64, /// See [`Subscribe::end_frame`]. pub end_frame: Option, + /// See [`Subscribe::order`]. + pub order: Order, } impl Message for SubscribeUpdate { @@ -400,7 +434,7 @@ impl Message for SubscribeUpdate { } let priority = r.u8()?; - skip_group_order(r, version)?; + let order = decode_order(r, version)?; let max_delay = std::time::Duration::from_millis(r.varint()?); let start_group = decode_start_group(r, version)?; let end_group = match r.varint()? { @@ -418,6 +452,7 @@ impl Message for SubscribeUpdate { end_group, start_frame, end_frame, + order, }) } @@ -430,7 +465,7 @@ impl Message for SubscribeUpdate { } w.u8(self.priority); - pad_group_order(w, version)?; + encode_order(w, version, self.order)?; w.varint(u64::try_from(self.max_delay.as_millis()).map_err(|_| EncodeError::BoundsExceeded)?)?; encode_start_group(w, version, self.start_group)?; @@ -712,6 +747,7 @@ mod test { fn subscribe_sample() -> Subscribe<'static> { Subscribe { + order: crate::track::Order::Descending, epoch: None, id: 1, broadcast: Path::new("room").to_owned(), @@ -893,4 +929,70 @@ mod test { .is_err() ); } + + /// Lite-07 carries `Group Order` right after the priority, on SUBSCRIBE and + /// SUBSCRIBE_UPDATE alike, and refuses a value it does not define. + #[test] + fn group_order_roundtrips_on_lite07() { + use crate::track::Order; + + let version = Version::Lite07; + for order in [Order::Ascending, Order::Descending] { + let mut msg = subscribe_sample(); + msg.order = order; + let mut buf = Vec::new(); + msg.encode_msg(&mut Encoder::new(&mut buf, version.into()), version) + .unwrap(); + let got = crate::coding::decode_buf(&mut buf.as_slice(), version, Subscribe::decode_msg).unwrap(); + assert_eq!(got.order, order); + + let update = SubscribeUpdate { + priority: 3, + max_delay: std::time::Duration::from_millis(250), + start_group: None, + end_group: None, + start_frame: 0, + end_frame: None, + order, + }; + let mut buf = Vec::new(); + update + .encode_msg(&mut Encoder::new(&mut buf, version.into()), version) + .unwrap(); + // The priority, then the order. + assert_eq!(buf[1], u8::from(order == Order::Ascending)); + let got = crate::coding::decode_buf(&mut buf.as_slice(), version, SubscribeUpdate::decode_msg).unwrap(); + assert_eq!(got.order, order); + + buf[1] = 2; + assert!(matches!( + crate::coding::decode_buf(&mut buf.as_slice(), version, SubscribeUpdate::decode_msg), + Err(DecodeError::InvalidValue) + )); + } + } + + /// No earlier wire has `Group Order`, so an ascending subscription falls back to + /// descending, byte-identical to one that never asked. + #[test] + fn group_order_falls_back_before_lite07() { + use crate::track::Order; + + for version in [Version::Lite03, Version::Lite05, Version::Lite06] { + let mut msg = subscribe_sample(); + msg.start_frame = 0; + msg.end_frame = None; + let mut descending = Vec::new(); + msg.encode_msg(&mut Encoder::new(&mut descending, version.into()), version) + .unwrap(); + msg.order = Order::Ascending; + let mut ascending = Vec::new(); + msg.encode_msg(&mut Encoder::new(&mut ascending, version.into()), version) + .unwrap(); + assert_eq!(ascending, descending, "{version}"); + + let got = crate::coding::decode_buf(&mut ascending.as_slice(), version, Subscribe::decode_msg).unwrap(); + assert_eq!(got.order, Order::Descending, "{version}"); + } + } } diff --git a/rs/moq-net/src/lite/subscriber.rs b/rs/moq-net/src/lite/subscriber.rs index cfe14c40bae..d08b62df139 100644 --- a/rs/moq-net/src/lite/subscriber.rs +++ b/rs/moq-net/src/lite/subscriber.rs @@ -1615,6 +1615,7 @@ mod tests { async fn feed_sub(tail: &kio::Producer) -> Sub { let mut session = crate::lite::test_transport::ScriptedSession::new(Vec::new()); Sub::Active(SubStream { + order: crate::track::Order::Descending, stream: Stream::open(&mut session, Version::Lite04).await.unwrap(), id: 0, max_delay: Duration::ZERO, @@ -1712,6 +1713,7 @@ mod tests { let mut session = crate::lite::test_transport::ScriptedSession::new(Vec::new()); let stream = Stream::open(&mut session, VERSION).await.unwrap(); let mut sub = SubStream { + order: crate::track::Order::Descending, stream, id: 0, max_delay: Duration::ZERO, @@ -3808,6 +3810,7 @@ struct SubStream { max_delay: Duration, start: Option, priority: u8, + order: crate::track::Order, /// The start the SUBSCRIBE itself carried, fixed for the stream's life. A /// SUBSCRIBE_START describes this demand and no fresh one follows an update, /// so a buffered START only applies while `start` still equals it: while the @@ -4273,6 +4276,7 @@ impl TrackServe { // SUBSCRIBE_UPDATE (Lite03+ only; older peers can't carry one). let start_moved = active.start != subscription.start; active.priority = subscription.priority; + active.order = subscription.order; active.max_delay = subscription.max_delay; if let Ok(mut tail) = active.tail.write() { tail.set_grace(tail::grace(subscription.max_delay)); @@ -4457,6 +4461,7 @@ fn buffer_update( end_group: bounds.end_group, start_frame: bounds.start_frame, end_frame: bounds.end_frame, + order: active.order, }) } @@ -4513,6 +4518,7 @@ impl Establish { end_group: bounds.end_group, start_frame: bounds.start_frame, end_frame: bounds.end_frame, + order: self.subscription.order, }; stream.writer.buffer(&lite::ControlType::Subscribe)?; stream.writer.buffer(&msg)?; @@ -4563,6 +4569,7 @@ impl Establish { max_delay: self.subscription.max_delay, start: self.subscription.start, priority: self.subscription.priority, + order: self.subscription.order, requested: self.subscription.start, tail: self.tail.clone(), served: None, diff --git a/rs/moq-net/src/lite/version.rs b/rs/moq-net/src/lite/version.rs index bc41a7b11ed..c83d6a70158 100644 --- a/rs/moq-net/src/lite/version.rs +++ b/rs/moq-net/src/lite/version.rs @@ -178,12 +178,23 @@ impl Version { } } + /// Whether SUBSCRIBE and SUBSCRIBE_UPDATE carry the subscriber's `Group Order`. + /// Added in lite-07; an earlier subscription is served newest first. + #[allow(clippy::match_like_matches_macro)] + pub(crate) fn has_order(self) -> bool { + // Match form so future versions default forward (AGENTS.md convention). + match self { + Self::Lite01 | Self::Lite02 | Self::Lite03 | Self::Lite04 | Self::Lite05 | Self::Lite06 => false, + _ => true, + } + } + /// Whether this version's SUBSCRIBE, SUBSCRIBE_UPDATE, SUBSCRIBE_OK, and TRACK_INFO /// carry the retired `Ordered` byte. /// - /// The field is gone from the model: a publisher transmits newest-first within a - /// track, always. Deployed drafts still have the byte in their layout, so it is - /// written as 0 and ignored on read rather than shifting every field behind it. + /// These drafts are served newest first whatever the byte says, so it is written as 0 + /// and ignored on read rather than shifting every field behind it. Lite-07's + /// `Group Order` (see [`Self::has_order`]) is a new field, not this one. pub(crate) fn has_group_order(self) -> bool { match self { Self::Lite01 | Self::Lite02 | Self::Lite03 | Self::Lite04 | Self::Lite05 => true, diff --git a/rs/moq-net/src/model/subscription.rs b/rs/moq-net/src/model/subscription.rs index b8dfa090640..487a1fb7ddd 100644 --- a/rs/moq-net/src/model/subscription.rs +++ b/rs/moq-net/src/model/subscription.rs @@ -86,6 +86,27 @@ pub struct Subscription { /// cursor; [`Position::group_end`] translates this field into its bound. Setting one /// does not imply the other. pub end: Option, + /// Which pending group the publisher sends first; see [`Order`]. + /// + /// Aggregated across every live subscriber: any [`Order::Descending`] subscriber makes + /// the aggregate descending, so a relay fanning one upstream request out keeps its live + /// subscribers fresh. Each subscriber's own publisher (a relay's downstream session) + /// still serves it in its own order. + pub order: Order, +} + +/// Which of a subscription's pending groups the publisher sends first. +/// +/// A transmission order only: it never decides *whether* a group is delivered, which is +/// [`Subscription::max_delay`]'s job. An ascending subscriber that wants a backlog +/// therefore needs a budget that covers it. +#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Hash)] +pub enum Order { + /// Oldest first, draining a backlog in sequence order. + Ascending, + /// Newest first, so congestion sheds the backlog rather than the live edge. + #[default] + Descending, } impl Default for Subscription { @@ -95,6 +116,7 @@ impl Default for Subscription { max_delay: Duration::ZERO, start: None, end: None, + order: Order::Descending, } } } @@ -134,6 +156,12 @@ impl Subscription { self } + /// Set which pending group the publisher sends first, returning `self` for chaining. + pub fn with_order(mut self, order: Order) -> Self { + self.order = order; + self + } + /// Request the whole groups in `groups`, replacing both [`Self::start`] and /// [`Self::end`]. Returns `self` for chaining. /// @@ -165,6 +193,10 @@ impl Subscription { // would invent a bound neither asked for. start: min_floored(self.start, combined.start), end: max_unbounded(self.end, combined.end), + order: match (self.order, combined.order) { + (Order::Ascending, Order::Ascending) => Order::Ascending, + _ => Order::Descending, + }, }; if &merged != combined { @@ -475,6 +507,26 @@ mod tests { assert_eq!(combined.end, Some(Position { group: 6, frame: 2 })); } + #[test] + fn combined_order_prefers_descending() { + let ascending = Subscription::default().with_order(Order::Ascending); + let descending = Subscription::default(); + + assert_eq!( + combine(std::slice::from_ref(&ascending)).unwrap().order, + Order::Ascending + ); + assert_eq!( + combine(&[ascending.clone(), ascending.clone()]).unwrap().order, + Order::Ascending + ); + assert_eq!( + combine(&[ascending.clone(), descending.clone()]).unwrap().order, + Order::Descending + ); + assert_eq!(combine(&[descending, ascending]).unwrap().order, Order::Descending); + } + #[test] fn combined_group_end_uses_latest_bounded_end() { let early = Subscription::default().with_end(Position::after_group(10)); diff --git a/rs/moq-net/src/model/track.rs b/rs/moq-net/src/model/track.rs index 9b086da8656..2e8e834c28b 100644 --- a/rs/moq-net/src/model/track.rs +++ b/rs/moq-net/src/model/track.rs @@ -19,7 +19,7 @@ use crate::{broadcast, cache, group, stats}; use super::{Datagram, Requests}; use super::Cap; -pub use super::subscription::{Position, Subscription}; +pub use super::subscription::{Order, Position, Subscription}; use std::{ collections::{BTreeMap, VecDeque}, diff --git a/rs/moq-net/src/lite/priority.rs b/rs/moq-net/src/priority.rs similarity index 91% rename from rs/moq-net/src/lite/priority.rs rename to rs/moq-net/src/priority.rs index 711172da48b..8ddac9269c3 100644 --- a/rs/moq-net/src/lite/priority.rs +++ b/rs/moq-net/src/priority.rs @@ -6,6 +6,8 @@ use std::{ use slab::Slab; +use crate::track::Order; + // Hybrid priority queue that provides strict priority ordering for the top 255 items. // // Design: @@ -19,10 +21,11 @@ use slab::Slab; // group sequence in that subscription's own direction. /// A group stream's rank: its subscription's track priority, the subscription it -/// belongs to, and its group sequence. +/// belongs to, and its group sequence in that subscription's [`Order`]. /// -/// Higher `track` always wins. `group` breaks ties only *within* one `subscribe`, -/// newest first, so a congested track sheds its backlog rather than its live edge. +/// Higher `track` always wins. `group` breaks ties only *within* one `subscribe`: +/// newest first by default, so a congested track sheds its backlog rather than its live +/// edge, or oldest first for an ascending subscription draining one. /// /// Scoping the tie-break to a subscription is what keeps group sequence from deciding /// between tracks. The draft gives that job to `Priority` alone, so a session carrying @@ -31,6 +34,7 @@ use slab::Slab; pub struct Priority { track: u8, subscribe: u64, + order: Order, group: u64, } @@ -40,9 +44,16 @@ impl Priority { Self { track, subscribe, + order: Order::Descending, group, } } + + /// Rank groups of the same subscription in `order` instead. + pub fn with_order(mut self, order: Order) -> Self { + self.order = order; + self + } } impl Ord for Priority { @@ -55,9 +66,15 @@ impl Ord for Priority { // stable and independent of either one's direction. The older (lower id) // subscription goes first. .then(self.subscribe.cmp(&other.subscribe)) - // Newest group first, which is what makes a congested track shed its - // backlog rather than its live edge. - .then(other.group.cmp(&self.group)) + // Only an update in flight leaves one subscription's groups in two orders, and + // keeping the two apart keeps the comparison total meanwhile. + .then((self.order == Order::Ascending).cmp(&(other.order == Order::Ascending))) + // The subscription's own direction: newest first sheds a congested backlog + // rather than the live edge, oldest first drains it. + .then(match self.order { + Order::Descending => other.group.cmp(&self.group), + Order::Ascending => self.group.cmp(&other.group), + }) } } @@ -216,6 +233,7 @@ impl PriorityState { PriorityHandle { id, track: priority.track, + order: priority.order, seen: u8::MAX, queue: myself, } @@ -338,10 +356,11 @@ impl PriorityState { } } - /// Change one item's track priority, leaving the rest of its rank alone. - fn set_track(&mut self, id: usize, track: u8) { + /// Change one item's track priority and order, leaving the rest of its rank alone. + fn steer(&mut self, id: usize, track: u8, order: Order) { let mut item = self.extract(id); item.priority.track = track; + item.priority.order = order; self.place(item); } @@ -367,9 +386,10 @@ impl PriorityState { pub struct PriorityHandle { id: usize, - /// This item's track priority, the only part of its rank a handle owns; the - /// rest is fixed when the item is queued. + /// This item's track priority and order, the only parts of its rank a handle owns; + /// the rest is fixed when the item is queued. track: u8, + order: Order, /// Last value observed via [`current`](Self::current)/[`next`](Self::next), so /// `next` fires only on a real change. seen: u8, @@ -430,17 +450,18 @@ impl PriorityHandle { kio::wait(|waiter| self.poll_next(waiter)).await } - /// Change this item's track priority and re-sort the queue, returning its new rank. - /// No-op if the track value hasn't changed. - pub fn set_track(&mut self, new_track: u8) -> u8 { - if self.track == new_track { + /// Change this item's track priority and order and re-sort the queue, returning its + /// new rank. No-op if neither changed. + pub fn steer(&mut self, track: u8, order: Order) -> u8 { + if self.track == track && self.order == order { return self.current(); } - self.track = new_track; + self.track = track; + self.order = order; let rank = { let mut state = self.queue.lock(); - state.set_track(self.id, new_track); + state.steer(self.id, track, order); state.rank(self.id) }; @@ -612,6 +633,8 @@ mod tests { let mixed = [ Priority::new(100, 7, 1), Priority::new(100, 7, 2), + Priority::new(100, 7, 1).with_order(Order::Ascending), + Priority::new(100, 7, 2).with_order(Order::Ascending), Priority::new(100, 8, 1), Priority::new(200, 7, 1), ]; @@ -630,6 +653,27 @@ mod tests { } } + #[test] + fn test_ascending_ranks_oldest_first() { + let queue = PriorityQueue::default(); + let ascending = |group| Priority::new(100, 0, group).with_order(Order::Ascending); + let mut group5 = queue.insert(ascending(5)); + let mut group1 = queue.insert(ascending(1)); + let mut group10 = queue.insert(ascending(10)); + + assert_eq!(group1.current(), 0); + assert_eq!(group5.current(), 1); + assert_eq!(group10.current(), 2); + + // Steering the subscription back to descending flips it once every group moved. + for group in [&mut group1, &mut group5, &mut group10] { + group.steer(100, Order::Descending); + } + assert_eq!(group10.current(), 0); + assert_eq!(group5.current(), 1); + assert_eq!(group1.current(), 2); + } + #[test] fn test_track_priority_overrides_group() { let queue = PriorityQueue::default(); @@ -912,7 +956,7 @@ mod tests { } #[test] - fn test_set_track_reorders() { + fn test_steer_track_reorders() { let queue = PriorityQueue::default(); // Subscription 1 (track=255), Subscription 2 (track=55) @@ -927,10 +971,10 @@ mod tests { assert_eq!(s2_g1.current(), 3); // Swap track priorities for each handle individually. - s1_g1.set_track(55); - s1_g2.set_track(55); - s2_g1.set_track(255); - s2_g2.set_track(255); + s1_g1.steer(55, Order::Descending); + s1_g2.steer(55, Order::Descending); + s2_g1.steer(255, Order::Descending); + s2_g2.steer(255, Order::Descending); assert_eq!(s2_g2.current(), 0); // s2 now highest assert_eq!(s2_g1.current(), 1); @@ -939,7 +983,7 @@ mod tests { } #[moq_net_sim::test] - async fn test_set_track_notifies_other_handles() { + async fn test_steer_track_notifies_other_handles() { let queue = PriorityQueue::default(); // h_low at index 1, will be promoted to 0 when h_high is demoted. @@ -948,19 +992,19 @@ mod tests { assert_eq!(h_low.current(), 1); - // Wait for a change notification on h_low while another handle's set_track runs. + // Wait for a change notification on h_low while another handle's steer runs. let task = moq_net_sim::spawn(async move { h_low.next().await }); moq_net_sim::sleep(std::time::Duration::from_millis(10)).await; // Demote h_high below h_low. - h_high.set_track(10); + h_high.steer(10, Order::Descending); let new_priority = task.await.unwrap(); assert_eq!(new_priority, 0, "h_low should be promoted to the top"); } #[test] - fn test_set_track_self() { + fn test_steer_track_self() { let queue = PriorityQueue::default(); let mut h_high = queue.insert(live(255, 1)); @@ -972,7 +1016,7 @@ mod tests { assert_eq!(h_low.current(), 2); // Demote h_high below the others. - h_high.set_track(10); + h_high.steer(10, Order::Descending); assert_eq!(h_mid.current(), 0); assert_eq!(h_low.current(), 1); @@ -980,7 +1024,7 @@ mod tests { } #[test] - fn test_set_track_swaps_demoted_vec_item_with_overflow() { + fn test_steer_track_swaps_demoted_vec_item_with_overflow() { let queue = PriorityQueue::default(); // Fill vec with 255 items at track=100, groups 1..=255. @@ -995,14 +1039,14 @@ mod tests { // Lower top's track below every filler. Without the swap, top would land // in vec at the tail while f1 stays in overflow despite having higher // priority, breaking the "every overflow item < every vec item" invariant. - top.set_track(0); + top.steer(0, Order::Descending); assert!(fillers[0].current() < u8::MAX, "f1 should be promoted back into vec"); assert_eq!(top.current(), u8::MAX, "demoted top should land in overflow"); } #[test] - fn test_set_track_lowered_within_vec_no_overflow_disruption() { + fn test_steer_track_lowered_within_vec_no_overflow_disruption() { let queue = PriorityQueue::default(); // Three items, all in vec; no overflow involvement. @@ -1014,7 +1058,7 @@ mod tests { assert_eq!(c.current(), 2); // Lowering A's priority below B but above C should leave A at index 1. - a.set_track(75); + a.steer(75, Order::Descending); assert_eq!(b.current(), 0); assert_eq!(a.current(), 1); assert_eq!(c.current(), 2); @@ -1049,7 +1093,7 @@ mod tests { } #[moq_net_sim::test] - async fn test_set_track_notifies_swapped_overflow_item() { + async fn test_steer_track_notifies_swapped_overflow_item() { let queue = PriorityQueue::default(); // Fill vec, then insert top, kicking f1 (filler at group=1) into overflow. @@ -1065,7 +1109,7 @@ mod tests { moq_net_sim::yield_now().await; // Demoting top below every filler swaps it with f1 in overflow. - top.set_track(0); + top.steer(0, Order::Descending); let promoted = task.await.unwrap(); assert!(promoted < u8::MAX, "f1 should be notified of promotion"); diff --git a/rs/moq-net/tests/group_order.rs b/rs/moq-net/tests/group_order.rs new file mode 100644 index 00000000000..b4f7db31910 --- /dev/null +++ b/rs/moq-net/tests/group_order.rs @@ -0,0 +1,251 @@ +//! A subscription's `Order` decides which pending group a publisher sends first, directly +//! and through a relay, and one upstream request serves subscribers of both orders. +//! +//! The mock ignores stream priority on its own, so each test holds the group streams on +//! the hop into the subscriber and releases them by send order, the way a congested +//! sender would transmit them. + +mod support; + +use std::time::Duration; + +use moq_net::track::{Info, Order, Position, Subscription}; +use moq_net::{Hop, Timescale, Timestamp, Version}; +use support::harness::{MockConnectOptions, MockPair, connect_mock}; + +const TIMEOUT: Duration = Duration::from_secs(10); + +/// A budget no group outlives, so order alone decides what goes first. +const FOREVER: Duration = Duration::from_millis((1 << 53) - 1); + +/// The backlog every test writes while the subscriber's hop is held. +const BACKLOG: [u64; 4] = [0, 1, 2, 3]; + +fn produce_origin(hop: u64) -> moq_net::origin::Producer { + let (producer, driver) = moq_net::origin::Producer::new(moq_net::origin::Config::new(Hop::new(hop).unwrap())); + support::harness::spawn(driver); + producer +} + +/// Connect a session serving `publish` to a fresh subscribing origin. +async fn connect( + version: Version, + publish: moq_net::origin::Consumer, + hop: u64, +) -> (MockPair, moq_net::origin::Producer) { + let subscriber = produce_origin(hop); + let mut options = MockConnectOptions::new(version); + options.server_publish = Some(publish); + options.client_subscribe = Some(subscriber.clone()); + (connect_mock(options).await, subscriber) +} + +/// Subscribe to the test track through `origin` in `order`, then read every backlog group +/// in the order it arrives. +fn read_arrivals(origin: moq_net::origin::Producer, order: Order) -> moq_net_sim::JoinHandle> { + moq_net_sim::spawn(async move { + let consumer = origin.consume(); + moq_net_sim::timeout(TIMEOUT, consumer.routed("bcast")) + .await + .expect("announce timeout") + .expect("routed"); + let remote = consumer + .request_broadcast("bcast", None) + .await + .expect("broadcast resolves"); + let subscription = Subscription::default() + .with_max_delay(FOREVER) + .with_start(Position::group(0)) + .with_order(order); + let mut sub = remote + .track("ordered") + .unwrap() + .subscribe(subscription) + .await + .expect("subscribe"); + + let mut arrivals = Vec::new(); + while arrivals.len() < BACKLOG.len() { + let group = moq_net_sim::timeout(TIMEOUT, sub.recv_group()) + .await + .expect("group timeout") + .expect("recv_group") + .expect("track open"); + arrivals.push(group.sequence); + } + arrivals + }) +} + +/// Write the backlog oldest first, leaving each group open. +/// +/// A held stream's FIN is acknowledged at once, which ends its group machine, and a machine +/// that ended stops following its rank. Open groups keep every stream re-ranked as the +/// newer ones queue, as the unacknowledged streams of a congested link would be. +fn write_backlog(track: &moq_net::track::Producer) -> Vec { + BACKLOG + .iter() + .map(|&sequence| { + let mut group = track.create_group(moq_net::group::Info { sequence }).unwrap(); + group + .write_frame(Timestamp::from_millis(sequence * 10).unwrap(), &b"frame"[..]) + .unwrap(); + group + }) + .collect() +} + +fn expected(order: Order) -> Vec { + match order { + Order::Ascending => BACKLOG.to_vec(), + Order::Descending => BACKLOG.iter().rev().copied().collect(), + } +} + +/// Whether `version` can carry an ascending order at all. +fn carries_order(version: &str) -> bool { + version == "moq-lite-07-wip" || version.starts_with("moq-transport") +} + +/// Serve one subscriber in `order`, optionally through a relay, and return the order its +/// backlog arrived in. +async fn round(version: &str, relay: bool, order: Order) -> Vec { + let version: Version = version.parse().unwrap(); + let publisher = produce_origin(1); + let broadcast = publisher.create_broadcast("bcast").unwrap(); + let track = broadcast + .create_track( + "ordered", + Info::default().with_timescale(Timescale::MILLI).with_max_age(FOREVER), + ) + .unwrap(); + broadcast.announce(Default::default()).unwrap(); + + let upstream = match relay { + true => Some(connect(version, publisher.consume(), 2).await), + false => None, + }; + let serving = match &upstream { + Some((_, relay)) => relay.consume(), + None => publisher.consume(), + }; + let (pair, subscriber) = connect(version, serving, 3).await; + let reader = read_arrivals(subscriber.clone(), order); + + support::harness::subscribed(&track).await; + // Simulated time advances only once every task is idle, so this settles the + // subscription on every hop before the groups exist. + moq_net_sim::sleep(Duration::from_millis(10)).await; + + pair.server_transport.hold_unis(); + let backlog = write_backlog(&track); + // Every group stream is open and ranked before any reaches the subscriber. + moq_net_sim::sleep(Duration::from_millis(10)).await; + pair.server_transport.release_unis_by_priority(); + + let got = moq_net_sim::timeout(TIMEOUT * 3, reader) + .await + .expect("reader hung") + .expect("reader panicked"); + drop((backlog, track, pair, upstream, broadcast, publisher, subscriber)); + got +} + +#[moq_net_sim::test] +async fn a_backlog_is_served_in_the_subscription_order() { + let mut failures = Vec::new(); + for version in [ + "moq-lite-05", + "moq-lite-06", + "moq-lite-07-wip", + "moq-transport-14", + "moq-transport-17", + "moq-transport-22", + ] { + for relay in [false, true] { + for order in [Order::Ascending, Order::Descending] { + let got = round(version, relay, order).await; + // An older lite wire cannot ask for ascending, so it is served newest first. + let served = match carries_order(version) { + true => order, + false => Order::Descending, + }; + if got != expected(served) { + failures.push(format!("{version} relay={relay} {order:?}: {got:?}")); + } + } + } + } + assert!(failures.is_empty(), "{failures:#?}"); +} + +/// One relay request serves an ascending and a descending subscriber: upstream asks for +/// descending so the live subscriber stays fresh, and each downstream session still sends +/// its own subscriber's backlog in that subscriber's order. +#[moq_net_sim::test] +async fn merged_subscribers_keep_their_own_order() { + for version in ["moq-lite-07-wip", "moq-transport-17"] { + let version: Version = version.parse().unwrap(); + let publisher = produce_origin(1); + let broadcast = publisher.create_broadcast("bcast").unwrap(); + let track = broadcast + .create_track( + "ordered", + Info::default().with_timescale(Timescale::MILLI).with_max_age(FOREVER), + ) + .unwrap(); + broadcast.announce(Default::default()).unwrap(); + + let (upstream, relay) = connect(version, publisher.consume(), 2).await; + let (descending_pair, descending_origin) = connect(version, relay.consume(), 3).await; + let (ascending_pair, ascending_origin) = connect(version, relay.consume(), 4).await; + + let upstream_order = || track.subscription().map(|subscription| subscription.order); + + let ascending = read_arrivals(ascending_origin.clone(), Order::Ascending); + support::harness::subscribed(&track).await; + moq_net_sim::sleep(Duration::from_millis(10)).await; + assert_eq!( + upstream_order(), + Some(Order::Ascending), + "{version}: alone, its own order" + ); + + let descending = read_arrivals(descending_origin.clone(), Order::Descending); + moq_net_sim::sleep(Duration::from_millis(10)).await; + // lite-07 moves the upstream request with a SUBSCRIBE_UPDATE. This moq-transport + // subscriber never updates a request, priority included, so its first order stands. + let merged = match version.is_lite() { + true => Order::Descending, + false => Order::Ascending, + }; + assert_eq!(upstream_order(), Some(merged), "{version}: one upstream request"); + + descending_pair.server_transport.hold_unis(); + ascending_pair.server_transport.hold_unis(); + let backlog = write_backlog(&track); + moq_net_sim::sleep(Duration::from_millis(10)).await; + descending_pair.server_transport.release_unis_by_priority(); + ascending_pair.server_transport.release_unis_by_priority(); + + for (reader, order) in [(descending, Order::Descending), (ascending, Order::Ascending)] { + let got = moq_net_sim::timeout(TIMEOUT * 3, reader) + .await + .expect("reader hung") + .expect("reader panicked"); + assert_eq!(got, expected(order), "{version} {order:?}"); + } + drop(( + backlog, + track, + upstream, + descending_pair, + ascending_pair, + relay, + descending_origin, + ascending_origin, + broadcast, + publisher, + )); + } +} diff --git a/rs/moq-net/tests/support/mock.rs b/rs/moq-net/tests/support/mock.rs index 71a872f3b1c..f752f14ea83 100644 --- a/rs/moq-net/tests/support/mock.rs +++ b/rs/moq-net/tests/support/mock.rs @@ -15,7 +15,7 @@ use std::{ sync::{ Arc, Mutex, - atomic::{AtomicBool, AtomicUsize, Ordering}, + atomic::{AtomicBool, AtomicI32, AtomicUsize, Ordering}, }, task::{Context, Poll}, time::Duration, @@ -143,6 +143,9 @@ pub struct MockSendStream { /// Where to log the first byte written, the stream type (see /// [`MockSession::bidi_types`]), until it is written. first_byte: Option, + /// The send order last set, shared with the peer's end for + /// [`MockSession::release_unis_by_priority`]. + priority: Arc, conn: Arc, } @@ -175,7 +178,9 @@ impl poll::SendStream for MockSendStream { ) } - fn set_priority(&mut self, _order: i32) {} + fn set_priority(&mut self, order: i32) { + self.priority.store(order, Ordering::Relaxed); + } fn finish(&mut self) -> Result<(), Self::Error> { if self.withhold_fin.load(Ordering::Relaxed) { @@ -245,6 +250,8 @@ pub struct MockRecvStream { chunks: usize, /// Shared signal to notify the peer's send-side `poll_closed`. closed: Arc, + /// The sender's send order; see [`MockSendStream::priority`]. + priority: Arc, park: kio::Park, conn: Arc, } @@ -386,6 +393,7 @@ type StreamTypes = Arc>>; fn new_stream_pair(conn: &Arc, resets: &Resets) -> (MockSendStream, MockRecvStream) { let queue = kio::Queue::new(); let closed = Arc::new(ClosedSignal::default()); + let priority = Arc::new(AtomicI32::new(0)); let send = MockSendStream { tx: Some(queue.clone()), @@ -395,6 +403,7 @@ fn new_stream_pair(conn: &Arc, resets: &Resets) -> (MockSendStr ack_fin: false, withhold_fin: Arc::default(), first_byte: None, + priority: priority.clone(), conn: conn.clone(), }; let recv = MockRecvStream { @@ -406,6 +415,7 @@ fn new_stream_pair(conn: &Arc, resets: &Resets) -> (MockSendStr split: None, chunks: 0, closed, + priority, park: kio::Park::default(), conn: conn.clone(), }; @@ -692,6 +702,16 @@ impl MockSession { } } + /// Deliver the held uni streams highest send order first, as a congested sender + /// would transmit them, and stop holding. Equal send orders keep their open order. + pub fn release_unis_by_priority(&self) { + let mut held = self.side.held.lock().unwrap().take().unwrap_or_default(); + held.sort_by_key(|stream| std::cmp::Reverse(stream.priority.load(Ordering::Relaxed))); + for stream in held { + let _ = self.side.peer_uni.try_push(stream); + } + } + /// Lose the held uni streams, as if each were reset before its header arrived, and /// stop holding. pub fn drop_unis(&self) {