diff --git a/js/net/src/ietf/fetch.test.ts b/js/net/src/ietf/fetch.test.ts index 1ec207ea1d4..f0f34abb553 100644 --- a/js/net/src/ietf/fetch.test.ts +++ b/js/net/src/ietf/fetch.test.ts @@ -33,7 +33,7 @@ const INVALID_RANGE = 0x11; const INVALID_JOINING_REQUEST_ID = 0x32; /** A publisher serving the `room` broadcast, with its `video` track and the client's uni streams. */ -function serve(version: IetfVersion, grant?: Signal) { +function serve(version: IetfVersion, grant?: Signal, priority?: number) { const pair = createMockTransportPair(ALPNS[version]); const origin = new OriginProducer(); const pub = new Publisher({ @@ -45,7 +45,7 @@ function serve(version: IetfVersion, grant?: Signal) { }); const publication = origin.createBroadcast(Path.from("room")); publication.announce(); - const track = publication.broadcast.createTrack("video", { timescale: Timescale.MILLI }); + const track = publication.broadcast.createTrack("video", { timescale: Timescale.MILLI, priority }); const uni = pair.client.incomingUnidirectionalStreams.getReader() as ReadableStreamDefaultReader< ReadableStream >; @@ -296,6 +296,37 @@ test("a FETCH serves several groups in order", async () => { } }); +/** The Publisher Priority each object on a fetch stream states, absent where it inherits. */ +async function priorities(raw: Uint8Array, version: IetfVersion): Promise<(number | undefined)[]> { + const reader = new Reader(undefined, raw, version); + expect(await reader.u53()).toBe(FetchHeader.type); + await FetchHeader.decode(reader, version); + const out: (number | undefined)[] = []; + while (!(await reader.done())) { + const flags = await reader.u53(); + if (flags & 0x08) await reader.u53(); + if (flags & 0x04) await reader.u53(); + out.push(flags & 0x10 ? await reader.u8() : undefined); + if (flags & 0x20) await reader.read(await reader.u53()); + await reader.read(await reader.u53()); + } + return out; +} + +// A fetch stream's first object states the track's Publisher Priority, as a subgroup header +// does, and the rest inherit it. Model priority 72 is wire 55, lower first. +test("a FETCH states the track's priority on its first object", async () => { + for (const version of VERSIONS) { + using fx = serve(version, undefined, 72); + publishPairs(fx.track, 2); + const type = range(version, at(0, 0), at(1, 2)); + const answer = served(await fetch(fx, new Fetch({ requestId: FETCH_ID, type }))); + expect(answer.objects).toEqual(pairs([0, 1])); + expect(answer.ok.properties.priority).toBe(55); + expect(await priorities(answer.raw, version)).toEqual([55, undefined, undefined, undefined]); + } +}); + // Only a finished track's final object ends it, wherever the range starts or ends. test("a FETCH through the final object reports the end of track", async () => { for (const version of VERSIONS) { @@ -514,7 +545,8 @@ test("draft-18: a joining FETCH serves the head its subscription starts after", await reader.u53(); await FetchHeader.decode(reader, D18); expect(await reader.u53()).toBe(0x3c); - expect([await reader.u53(), await reader.u53(), await reader.u8()]).toEqual([5, 0, 0]); + // The priority is the track's, as FETCH_OK and every subgroup header state it. + expect([await reader.u53(), await reader.u53(), await reader.u8()]).toEqual([5, 0, 127]); await reader.read(await reader.u53()); await reader.read(await reader.u53()); expect(await reader.u53()).toBe(0x20); diff --git a/js/net/src/ietf/ietf.test.ts b/js/net/src/ietf/ietf.test.ts index cb4e1b8b693..78180fd1507 100644 --- a/js/net/src/ietf/ietf.test.ts +++ b/js/net/src/ietf/ietf.test.ts @@ -805,17 +805,18 @@ test("Frame reads only the current LOC Timestamp ID on every draft", async () => // A fetch stream's first object is the only one carrying absolute ids, so a wrong flag byte // there silently renumbers every object after it. This codec is the sole serialization path -// for a served fill. +// for a served fill. Its priority is the track's, as a subgroup header's is: model priority +// 72 is wire 55, lower first. test("FetchFrame: the first object carries its absolute ids and the rest inherit them", async () => { const timestamp = new Timestamp(96_000, Timescale.MILLI); - const frame = new FetchFrame({ payload: new Uint8Array([0xaa, 0xbb]), timestamp }); + const frame = new FetchFrame({ payload: new Uint8Array([0xaa, 0xbb]), timestamp, priority: 55 }); const first = await encodeFetchFrameVersioned(frame, { group: 7, object: 3, first: true }, Version.DRAFT_22); expect(Array.from(first)).toEqual([ 0x3c, // GROUP_ID | OBJECT_ID | PRIORITY | PROPERTIES 7, // group id 3, // object id - 0, // publisher priority + 55, // publisher priority 0x04, // properties length 0x10, // TIMESTAMP 0xc1, @@ -845,7 +846,11 @@ test("FetchFrame: the first object carries its absolute ids and the rest inherit // A fetch object has no status field, unlike a subgroup object: a zero payload length is // simply an empty object, and writing a status after it would desync the stream. test("FetchFrame: an empty payload is a zero length, with no status byte", async () => { - const frame = new FetchFrame({ payload: new Uint8Array(), timestamp: new Timestamp(0, Timescale.MILLI) }); + const frame = new FetchFrame({ + payload: new Uint8Array(), + timestamp: new Timestamp(0, Timescale.MILLI), + priority: 0, + }); const encoded = await encodeFetchFrameVersioned(frame, { group: 1, object: 0, first: true }, Version.DRAFT_22); expect(Array.from(encoded)).toEqual([ @@ -864,7 +869,7 @@ test("FetchFrame: an empty payload is a zero length, with no status byte", async // omitted rather than carrying a value in units the peer was never told. This is what a // subscriber that sent INCLUDE_PROPERTIES=0 gets. test("FetchFrame: an unstamped object omits the properties field", async () => { - const frame = new FetchFrame({ payload: new Uint8Array([0x01]) }); + const frame = new FetchFrame({ payload: new Uint8Array([0x01]), priority: 0 }); const encoded = await encodeFetchFrameVersioned(frame, { group: 0, object: 0, first: false }, Version.DRAFT_22); // Flags 0 (subgroup zero, no fields present), then the payload. @@ -873,7 +878,7 @@ test("FetchFrame: an unstamped object omits the properties field", async () => { // The first object still carries its absolute ids and priority; only the properties go. test("FetchFrame: an unstamped first object keeps its ids", async () => { - const frame = new FetchFrame({ payload: new Uint8Array([0x01]) }); + const frame = new FetchFrame({ payload: new Uint8Array([0x01]), priority: 0 }); const encoded = await encodeFetchFrameVersioned(frame, { group: 4, object: 2, first: true }, Version.DRAFT_22); expect(Array.from(encoded)).toEqual([ diff --git a/js/net/src/ietf/object.ts b/js/net/src/ietf/object.ts index 371d2f9f14d..2a8e762ed29 100644 --- a/js/net/src/ietf/object.ts +++ b/js/net/src/ietf/object.ts @@ -394,10 +394,16 @@ export class FetchFrame { payload: Uint8Array; /** The presentation timestamp carried in object properties, when present. */ timestamp?: Timestamp; + /** + * The track's Publisher Priority on the wire, which the stream's first object states for + * every object after it, as a subgroup header does. + */ + priority: number; - constructor({ payload, timestamp }: { payload: Uint8Array; timestamp?: Timestamp }) { + constructor({ payload, timestamp, priority }: { payload: Uint8Array; timestamp?: Timestamp; priority: number }) { this.payload = payload; this.timestamp = timestamp; + this.priority = priority; } /** @@ -419,7 +425,7 @@ export class FetchFrame { position.first ? position.group : Math.abs(position.group - (position.previousGroup as number)) - 1, ); await w.u53(position.object); - if (position.first) await w.u8(0); + if (position.first) await w.u8(this.priority); } else { // Same group and priority; the Object ID is the prior one plus one. await w.u53(stamped ? FETCH_PROPERTIES : 0); diff --git a/js/net/src/ietf/publisher.test.ts b/js/net/src/ietf/publisher.test.ts index a9fe499c6c9..b53e9a29946 100644 --- a/js/net/src/ietf/publisher.test.ts +++ b/js/net/src/ietf/publisher.test.ts @@ -4342,6 +4342,88 @@ test("draft-22: cancellation releases a fill parked on flow control", async () = } }); +// A fill reads the cache through forks of its own, ranked at the converted subscriber +// priority. Copied unconverted, wire 100 would raise the track's aggregate from 27 to 100, +// and wire 191 is outside the model's -128..=127, so the fork throws and the fill never runs. +test("draft-22: a SUBSCRIBE's fill reads the cache at the converted subscriber priority", async () => { + const fx = fixture(); + const track = fx.broadcast.createTrack("video", { timescale: Timescale.MILLI }); + writeGroup(track, 2); + const { client } = await runSubscribe( + fx, + new Subscribe({ + requestId: 0n, + trackNamespace: Path.from("test"), + trackName: "video", + subscriberPriority: 191, + filter: { kind: "absolute", startGroup: 10n, startObject: 0n }, + fill: { filter: { kind: "unfiltered" }, rangeFilters: false }, + }), + ); + try { + expect(track.subscription.peek()?.priority).toBe(-64); + const stream = await nextUni(fx.uni); + if (!stream) throw new Error("missing fill stream"); + const served = await readFill(new Reader(stream, undefined, V22), "ascending"); + expect(served.reset).toBeUndefined(); + expect(served.objects).toEqual([0, 1].map((id) => ({ group: 0, id, payload: `0.${id}` }))); + } finally { + client.close(); + track.finish(); + track.close(); + fx.close(); + } +}); + +test("draft-22: an update's fill reads the cache at the converted subscriber priority", async () => { + for (const [wire, model] of [ + [100, 27], + [191, -64], + ]) { + const fx = fixture(); + const parked = Promise.withResolvers(); + const stalled = new WritableStream({ + write() { + parked.resolve(); + return new Promise(() => {}); + }, + }); + const track = fx.broadcast.createTrack("video", { timescale: Timescale.MILLI }); + writeGroup(track, 1); + const { client } = await runSubscribe( + fx, + new Subscribe({ + requestId: 0n, + trackNamespace: Path.from("test"), + trackName: "video", + subscriberPriority: wire, + filter: { kind: "absolute", startGroup: 10n, startObject: 0n }, + }), + ); + try { + expect(track.subscription.peek()?.priority).toBe(model); + spyOn(fx.pair.server, "createUnidirectionalStream").mockImplementationOnce(async () => stalled); + const parameters = new Parameters(); + parameters.fillParameters = Filter.encodeFill( + { filter: { kind: "unfiltered" }, groupOrder: "ascending", rangeFilters: false }, + fx.version, + ); + await client.writer.u53(SubscribeUpdate.id); + await new SubscribeUpdate({ requestId: 2n, parameters }).encode(client.writer, fx.version); + expect(await client.reader.u53()).toBe(RequestOk.id); + await RequestOk.decode(client.reader, fx.version); + // The fill is parked writing its header, so the fork it reads through is still live. + await parked.promise; + expect(track.subscription.peek()?.priority, `wire ${wire}`).toBe(model); + } finally { + client.close(); + track.finish(); + track.close(); + fx.close(); + } + } +}); + test("draft-22: narrowing gives up an excluded group's open stream", async () => { const fx = fixture(); const track = fx.broadcast.createTrack("video", { timescale: Timescale.MILLI }); diff --git a/js/net/src/ietf/publisher.ts b/js/net/src/ietf/publisher.ts index 7cdc2a3bf8a..20e3559ac71 100644 --- a/js/net/src/ietf/publisher.ts +++ b/js/net/src/ietf/publisher.ts @@ -304,6 +304,9 @@ interface RunFill { /** The subscriber's delivery priority, applied to the cache subscription the fill reads. */ priority: number; + /** The track's Publisher Priority on the wire, which the fill's first object states. */ + publisherPriority: number; + /** * 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. @@ -809,6 +812,7 @@ export class Publisher { namespace: name, properties, timescale, + publisherPriority, ranking: ranked, } : { kind: "unsupported" }, @@ -863,6 +867,7 @@ export class Publisher { filling = this.#runFill({ requestId, priority: fromWire(msg.subscriberPriority), + publisherPriority, ranking: ranked, fill: selected, cache: source, @@ -1410,7 +1415,8 @@ export class Publisher { * fill-failure signal. Nothing here touches the subscription either way. */ async #runFill(options: RunFill) { - const { requestId, ranking, fill, cache, timescale, unsubscribed, cancelled, streams } = options; + const { requestId, ranking, fill, cache, timescale, publisherPriority, unsubscribed, cancelled, streams } = + options; const version = this.#session.version; // Everything is inside the try so the cache fork is released on every path out, @@ -1451,7 +1457,15 @@ export class Publisher { if (!group) continue; const slice = groupSlice(fill, sequence); try { - previous = await this.#writeFillGroup({ stream, group, slice, timescale, cancelled, previous }); + previous = await this.#writeFillGroup({ + stream, + group, + slice, + timescale, + publisherPriority, + cancelled, + previous, + }); } finally { group.close(); } @@ -1485,6 +1499,7 @@ export class Publisher { group, slice, timescale, + publisherPriority, cancelled, previous, }: { @@ -1492,6 +1507,8 @@ export class Publisher { group: group.Consumer; slice: GroupSlice; timescale: Timescale | undefined; + /** The track's Publisher Priority on the wire, which the stream's first object states. */ + publisherPriority: number; cancelled: AbortSignal; previous?: number; }): Promise { @@ -1524,6 +1541,7 @@ export class Publisher { first, previous, timescale, + publisherPriority, stop: cancelled, }); first = false; @@ -1542,6 +1560,7 @@ export class Publisher { first, previous, timescale, + publisherPriority, stop, }: { stream: Writer; @@ -1551,9 +1570,11 @@ export class Publisher { first: boolean; previous: number | undefined; timescale: Timescale | undefined; + /** The track's Publisher Priority on the wire, which the stream's first object states. */ + publisherPriority: number; stop: AbortSignal; }): Promise { - const obj = new FetchFrame({ payload: frame.payload, timestamp: frame.timestamp }); + const obj = new FetchFrame({ payload: frame.payload, timestamp: frame.timestamp, priority: publisherPriority }); const position = { group: sequence, object: frame.sequence, @@ -3186,6 +3207,7 @@ export class Publisher { ok: new FetchOk({ endOfTrack, endLocation, properties: trackProperties(info, msg.propertiesWanted) }), // A Timestamp goes out only when FETCH_OK actually carries TIMESCALE. timescale: msg.propertiesWanted ? (info.timescale ?? undefined) : undefined, + publisherPriority: toWire(info.priority), // Its own rank, so it competes with group streams by its priority alone. sendOrder: sendOrder({ priority }), order: msg.groupOrder ?? "ascending", @@ -3279,6 +3301,7 @@ export class Publisher { // Where the subscription starts, never the end of the track. ok: new FetchOk({ endOfTrack: false, endLocation: end, properties: join.properties }), timescale: join.timescale, + publisherPriority: join.publisherPriority, // Ranked as the group it heads, ahead of that group's live rest. sendOrder: join.ranking.rank(sequence, 0), ranking: join.ranking, @@ -3293,7 +3316,7 @@ export class Publisher { */ async #answerFetch(msg: Fetch, request: RequestStream, answer: FetchAnswer, stop: AbortSignal) { const version = this.#session.version; - const { cache, range, last, timescale, ranking } = answer; + const { cache, range, last, timescale, publisherPriority, ranking } = answer; const order = [...answer.groups, last.sequence]; if (answer.order === "descending") order.reverse(); @@ -3323,6 +3346,7 @@ export class Publisher { first, previous, timescale, + publisherPriority, stop, }); first = false; @@ -3339,6 +3363,7 @@ export class Publisher { group, slice, timescale, + publisherPriority, cancelled: stop, previous, }); @@ -3462,6 +3487,8 @@ type Joinable = properties: Properties.Properties; /** The units the subscription stamps objects in, if any; see {@link RunGroup.timescale}. */ timescale?: Timescale; + /** The track's Publisher Priority on the wire, which the fetch's first object states. */ + publisherPriority: number; /** The subscription's ranking, which the fetch stream joins as the group it heads. */ ranking: Priority; }; @@ -3488,6 +3515,8 @@ interface FetchAnswer { ok: FetchOk; /** The units objects are stamped in, if any; see {@link RunGroup.timescale}. */ timescale?: Timescale; + /** The track's Publisher Priority on the wire, which the stream's first object states. */ + publisherPriority: number; /** The fetch stream's send order. */ sendOrder: number; /** The subscription ranking the fetch stream joins, if any. */ diff --git a/rs/moq-net/src/ietf/publisher.rs b/rs/moq-net/src/ietf/publisher.rs index f5d8396da80..c881890e360 100644 --- a/rs/moq-net/src/ietf/publisher.rs +++ b/rs/moq-net/src/ietf/publisher.rs @@ -318,6 +318,8 @@ struct FetchObjectInfo<'a> { sequence: u64, object: u64, prior: FetchPrior, + /// The track's Publisher Priority on the wire, which the first object states for all. + priority: u8, timestamp: Option, inflated: Option, timescale: Option, @@ -2335,6 +2337,8 @@ impl Publisher { let res = async { stream.varint(FetchHeader::TYPE).await?; stream.encode(&FetchHeader { request_id }).await?; + // Resolved already: the subscription this fills described the track. + let publisher_priority = super::priority::to_wire(track.info().await?.priority); let (range, groups, _filled) = match fill { FillServe::Group { sequence, skip, until } => ( @@ -2419,6 +2423,7 @@ impl Publisher { }, timescale, self.version, + publisher_priority, &mut prior_group, ) .await?; @@ -2448,6 +2453,10 @@ impl Publisher { /// every later one inherits them and increments the Object ID, so only the /// properties (the timestamp) and the payload go on the wire. A fetch object has no /// status field. + #[expect( + clippy::too_many_arguments, + reason = "private plumbing; a single-use argument struct would only rename the parameters" + )] async fn write_fetch_group( stream: &mut Writer, Version>, mut group: group::Consumer, @@ -2455,6 +2464,7 @@ impl Publisher { slice: GroupSlice, timescale: Option, version: Version, + priority: u8, prior_group: &mut Option, ) -> Result<(), Error> { let GroupSlice { skip, until } = slice; @@ -2514,6 +2524,7 @@ impl Publisher { sequence, object: index, prior: fetch_position(*prior_group, sequence, prior, index)?, + priority, timestamp: frame.timestamp, inflated: frame.inflated, timescale, @@ -2562,6 +2573,7 @@ impl Publisher { sequence, object: index, prior: fetch_position(*prior_group, sequence, prior, index)?, + priority, timestamp: frame.timestamp, inflated: frame.inflated, timescale, @@ -2616,6 +2628,7 @@ impl Publisher { sequence, object, prior, + priority, timestamp, inflated, timescale, @@ -2646,12 +2659,13 @@ impl Publisher { let header = match prior { // The first object must carry its absolute Group and Object IDs. Include the - // priority too: "same as the prior object" has no prior to refer to. + // priority too: "same as the prior object" has no prior to refer to. It is the + // track's, as a subgroup header's Publisher Priority is. FetchPrior::None => ietf::FetchObject::Object { subgroup: ietf::FetchSubgroup::Zero, group: Some(sequence), object: Some(object), - priority: Some(0), + priority: Some(priority), properties, }, // Same group and priority; the Object ID is the prior one plus one. @@ -2687,6 +2701,7 @@ impl Publisher { timescale: Option, ) -> Result<(), Error> { let source = group.info.ietf(); + let priority = super::priority::to_wire(group.info.priority); let mut prior = None; let mut budget = kio::coop::Budget::new(32); for (ordinal, frame) in (group.first..).zip(group.frames) { @@ -2700,6 +2715,7 @@ impl Publisher { sequence: group.sequence, object, prior: position, + priority, timestamp: frame.timestamp, inflated: frame.inflated, timescale, @@ -10203,7 +10219,8 @@ mod serve_tests { if index == 0 { assert_eq!(crate::coding::decode_varint(&mut buf, version).unwrap(), LATEST); assert_eq!(crate::coding::decode_varint(&mut buf, version).unwrap(), 0); - assert_eq!(bytes::Buf::try_get_u8(&mut buf).unwrap(), 0); + // The track's Publisher Priority, as FETCH_OK states it: unset is wire 127. + assert_eq!(bytes::Buf::try_get_u8(&mut buf).unwrap(), 127); } let properties = crate::coding::decode_buf(&mut buf, version, |r, _| Ok(r.bytes()?.to_vec())).unwrap(); assert!(!properties.is_empty(), "{version}: missing Timestamp"); @@ -10800,6 +10817,92 @@ mod serve_tests { } } + /// The Publisher Priority each object on a fetch stream states, after its FETCH_HEADER. + fn fetch_object_priorities(buf: &mut Decoder<'_>, version: Version) -> Vec> { + assert_eq!(buf.varint().unwrap(), FetchHeader::TYPE, "{version}"); + FetchHeader::decode(buf, version).unwrap(); + let mut priorities = Vec::new(); + while !buf.is_empty() { + let ietf::FetchObject::Object { priority, .. } = ietf::FetchObject::decode(buf, version).unwrap() else { + panic!("{version}: unexpected End of Range"); + }; + let size = buf.varint().unwrap() as usize; + buf.slice(size).unwrap(); + priorities.push(priority); + } + priorities + } + + /// A fetch stream's first object states the track's Publisher Priority, as a subgroup + /// header does, and every later one inherits it. Model 72 is wire 55 (lower first). + #[moq_clock::test] + async fn a_standalone_fetch_states_the_track_priority() { + for version in FETCH_DRAFTS { + let mut h = serve_track( + version, + track::Info { + priority: 72, + ..track::Info::timed() + }, + ); + publish_pairs(&mut h, 3, None); + settle().await; + + let wire = standalone_fetch( + &h, + Location { group: 0, object: 0 }, + Location { group: 2, object: 0 }, + GroupOrder::Ascending, + ) + .await; + let mut buf = Decoder::new(&wire, version.into()); + assert_eq!(buf.varint().unwrap(), ietf::FetchOk::ID, "{version}"); + ietf::FetchOk::decode(&mut buf, version).unwrap(); + assert_eq!( + fetch_object_priorities(&mut buf, version), + [Some(55), None, None, None, None, None], + "{version}" + ); + } + } + + /// A fill's fetch stream states the track's Publisher Priority the same way. + #[moq_clock::test] + async fn a_fill_states_the_track_priority() { + let version = Version::Draft22; + let h = serve_track( + version, + track::Info { + priority: 72, + ..track::Info::timed() + }, + ); + let mut group = h.track.create_group(group::Info { sequence: 4 }).unwrap(); + group.write_frame(timestamp(), b"fill".as_slice()).unwrap(); + group.finish().unwrap(); + + let ranking = Ranking { + queue: h.publisher.priority.clone(), + group: None, + request_id: RequestId(REQUEST_ID), + priority: kio::Producer::new(PRIORITY).consume(), + publisher: 0, + order: Order::Descending, + }; + let opened = AtomicU64::new(0); + let fill = FillServe::Group { + sequence: 4, + skip: 0, + until: None, + }; + h.publisher + .run_fill(fill, &ranking, h.track.consume(), None, &opened, ranking.request_id) + .await; + let wire = bytes::Bytes::from(h.log.writes.lock().unwrap().to_vec()); + let mut buf = Decoder::new(&wire, version.into()); + assert_eq!(fetch_object_priorities(&mut buf, version), [Some(55)]); + } + /// The Track Properties block a publisher upstream of a relay sent on `version`: an even /// property the draft defines but moq-net does not implement (OBJECT_DELIVERY_TIMEOUT), /// and an odd one from the application range.