diff --git a/doc/concept/standard.md b/doc/concept/standard.md index f92bc1782fb..2e9c0f6bfb2 100644 --- a/doc/concept/standard.md +++ b/doc/concept/standard.md @@ -32,7 +32,7 @@ subset drops. What a peer actually observes against this implementation: - **One `SETUP` credential**, forwarded to the [auth server](/bin/relay/auth#the-contract) unverified. A second `SETUP` token closes the session. We advertise no token cache, so an alias reference in `SETUP` closes it with `PROTOCOL_VIOLATION`, one on a request with `UNKNOWN_AUTH_TOKEN_ALIAS`, and a registration on a request with `AUTH_TOKEN_CACHE_OVERFLOW`. Where the Rust side authorizes the peer or verifies tokens, a token on a `SUBSCRIBE` or `PUBLISH_NAMESPACE` is verified like an in-band session token and authorizes that one request alone, even where that authorization already covers it; it never widens the session. It is refused with `NOT_SUPPORTED` when nothing verifies it, when it is empty, or when its Token Type is anything but 0 (out of band). A side that does neither, JavaScript included, ignores the token. Rust refuses a request carrying more than one distinct token with `NOT_SUPPORTED`, since it verifies one; JavaScript, which verifies none, ignores them all. A token-authorized `SUBSCRIBE` still stays within the grant the peer gave us. A token-authorized `PUBLISH_NAMESPACE` needs a grant covering everything beneath the namespace, and the tracks we subscribe under it rely on that announce instead of our limit, ending with it. An update renews the token, except on a drafts 14 and 15 `PUBLISH_NAMESPACE`, which has no update, and a refused renewal ends only that request. Rust and JavaScript send the token a route names (`Route::auth`) on its `PUBLISH_NAMESPACE`, including the one drafts 14 and 15 answer a solicited `SUBSCRIBE_NAMESPACE` with, and swapping it renews the request with `REQUEST_UPDATE` from draft 16, or ends and re-sends it before; the inline `NAMESPACE` that answers a solicited `SUBSCRIBE_NAMESPACE` from draft 16 carries no token. The token belongs to the session that added it, so a reconnect means adding it again and re-announcing. A token on any other request is decoded and grants nothing, and a request repeating one is refused with `MALFORMED_AUTH_TOKEN`. `SUBSCRIBE_TRACKS` reads its namespace before refusal; its token is not decoded. On draft 17 and later, the negotiated [MoQ Auth extension](/concept/moq-lite#authorization) accepts additional session tokens in band. - **Refused, not fatal.** A legal request this stack does not serve is rejected on its own and the session stays up: `FORWARD=0`, `SUBSCRIBE_TRACKS`, and the fetch forms above get `NOT_SUPPORTED`. Range Filters get `INVALID_FILTER` on draft 19 and later because the advertised filter limit is zero. On draft 21 and later, namespaces whose first tuple field is exactly `.` or `.session` get `DOES_NOT_EXIST` before application lookup; other dot prefixes still reach the application. Subscription updates accept priority, negotiated subscriber max age, and delivery timeouts; Rust also renews request tokens and judges `NEW_GROUP_REQUEST` as a join (see dynamic groups below). Other supported-but-unimplemented preferences end that subscription; a `TRACK_PROPERTY_FILTER` there closes the session with `PROTOCOL_VIOLATION`, since it belongs only to `SUBSCRIBE_TRACKS`. On draft 18 and later a namespace update may change its prefix; suffixes after the acknowledgement are relative to that new prefix. - **Objects and datagrams.** Only subgroup 0 is accepted: a stream for any other subgroup, whether its header gives the ID or takes it from the first Object ID, is stopped and the session stays up. Rust relays preserve Object IDs, gaps, object properties, FIRST\_OBJECT, and END\_OF\_GROUP status objects between moq-transport peers for subgroup 0. Datagrams retain their IDs, properties, priority, and status. Plain Rust readers and moq-lite peers see consecutive frames and normal datagram payloads; JavaScript supports only normal datagrams at Object ID 0. A malformed datagram closes the session; a relayed one the downstream draft cannot carry is dropped. A relayed Timestamp leaves in the units the downstream response declares, and is dropped where it declares none (drafts 14 through 16), as for a plain frame; an immutable one that would change or vanish is refused. Only property 0x10 is read as a Timestamp. Property 0x06 stays opaque and keeps its value regardless of timestamp units; it is dropped across the draft-19 boundary, or refused when immutable, because draft 19 assigns it to SUBGROUP\_DELIVERY\_TIMEOUT. From draft 15, a status object carrying properties is refused, and one relayed from draft 14 leaves without them. Draft 14 allows them, but an END\_OF\_TRACK carrying properties ends the subscription as unsupported, since a track end has nowhere to keep them. A `FETCH` carries the END\_OF\_GROUP object on drafts 14 and 15; later drafts have no FETCH status, so their response ends at the last frame. A group cannot resume across route changes by frame ordinal once Object IDs skip ahead of the ordinals on either route; recovery refuses it instead of splicing different objects. -- **Dynamic groups.** A track advertises `DYNAMIC_GROUPS` when its publisher sets a refresh ratio, and a track received with `DYNAMIC_GROUPS` gets a ratio of 0. A `NEW_GROUP_REQUEST` (draft 15 and later) counts as one more subscriber joining, which a `SUBSCRIBE` already is: it asks for a new group only when the newest group's bytes after its first frame exceed the ratio times the first frame. Joins coalesce until the asked-for group arrives. A Rust relay sends `NEW_GROUP_REQUEST` upstream, on the `SUBSCRIBE` or in a `REQUEST_UPDATE`, once a join wants a group past the newest it holds; a relay holding nothing yet asks for none. On a track without a ratio, an update carrying one ends the subscription with `UPDATE_FAILED`. On drafts 15 and 16, whose `TRACK_STATUS` answer has no room for it, a relay copy first learned from `TRACK_STATUS` (a fetch-only reader) does not advertise it to later subscribers. moq-lite hops do not carry requests yet. +- **Dynamic groups.** A track advertises `DYNAMIC_GROUPS` when its publisher sets a refresh ratio, and a track received with `DYNAMIC_GROUPS` gets a ratio of 0. A `NEW_GROUP_REQUEST` (draft 15 and later) counts as one more subscriber joining, which a `SUBSCRIBE` already is: it asks for a new group only when the newest group's bytes after its first frame exceed the ratio times the first frame. Joins coalesce until the asked-for group arrives. A Rust relay sends `NEW_GROUP_REQUEST` upstream, on the `SUBSCRIBE` or in a `REQUEST_UPDATE`, once a join wants a group past the newest it holds; a relay holding nothing yet asks for none. On a track without a ratio, an update carrying one ends the subscription with `UPDATE_FAILED`. On drafts 15 and 16, whose `TRACK_STATUS` answer has no room for it, a relay copy first learned from `TRACK_STATUS` (a fetch-only reader) does not advertise it to later subscribers. A moq-lite-07 hop (`moq-lite-07-wip`, opt-in) carries the same demand natively: the ratio in `TRACK_INFO` and the asked-for group in `SUBSCRIBE_UPDATE`. Earlier moq-lite versions carry neither, so a track received over one never refreshes. - **Priority.** Higher is served first. The IETF default of 128 is this stack's 127, and a track that never sets one is 127. A relay's upstream subscription carries the highest priority its subscribers ask for and updates it as they come and go; its group order stays as the `SUBSCRIBE` asked, since no draft lets an update change it. - **Size.** An object extension block larger than 64 KiB ends that subgroup stream. The session stays up. This cap is ours, not the draft's. diff --git a/drafts/draft-lcurley-moq-lite.md b/drafts/draft-lcurley-moq-lite.md index c3382646bb5..583757c3888 100644 --- a/drafts/draft-lcurley-moq-lite.md +++ b/drafts/draft-lcurley-moq-lite.md @@ -1219,6 +1219,7 @@ SUBSCRIBE_UPDATE Message { Group End (i) Frame Start (i) Frame End (i) + Wanted Group (i) } ~~~ @@ -1226,6 +1227,14 @@ See [SUBSCRIBE](#subscribe) for information about each field. Moving `Frame Start` forward within a group that is already being delivered does not retract frames the publisher has already sent; like `Group Start`, it only bounds what the publisher sends from here on. +**Wanted Group**: +The newest group the subscriber's live-edge joins want, encoded as the sequence plus one; `0` means none. +Like the other fields, it is subscription state: every SUBSCRIBE_UPDATE restates it, and the latest one applies. +A relay sends a SUBSCRIBE_UPDATE when local demand wants a group beyond its largest that differs from the value it last sent, and keeps restating that value in later updates, including after the group arrives. +A publisher MUST ignore a value at or below its largest group, and otherwise evaluate it as a new SUBSCRIBE under the Track's Refresh ratio. +Restating a value is harmless: a join while a request is pending asks for the same group. +A new SUBSCRIBE itself counts as a join and needs no Wanted Group field. + ## TRACK TRACK is sent by a subscriber to request a Track's immutable publisher properties. It is the first message on a Track Stream (0x6). @@ -1260,6 +1269,7 @@ TRACK_INFO Message { Publisher Priority (8) Publisher Max Age (i) Timescale (i) + Refresh (i) } ~~~ @@ -1292,6 +1302,13 @@ The number of timestamp units per second for frame timestamps on this Track, or lite-05 and lite-06 have no untimed encoding: there it MUST be non-zero, and a subscriber that receives 0 MUST reset the stream with a protocol violation. Common values include `1000` (milliseconds), `1000000` (microseconds), `48000` (audio sample rate), and `90000` (RTP video clock). +**Refresh**: +An optional unsigned 32-bit byte ratio, encoded as the ratio plus one; `0` disables refresh. +On a live-edge join, a publisher asks for a group beyond every sequence already produced when the newest group's bytes after its first frame exceed the ratio times that first frame's bytes. +Joins coalesce until the requested group arrives. +A relay preserves the ratio and evaluates joins against its own cache, forwarding demand in SUBSCRIBE_UPDATE. +Versions before lite-07 omit Refresh and Wanted Group; a Track received on those versions never refreshes. + ## SUBSCRIBE_OK {#subscribe-ok} A SUBSCRIBE_OK message confirms a subscription and resolves its absolute start position. It is the first message the publisher sends on the Subscribe Stream, once the start position is known. @@ -1622,6 +1639,8 @@ The `Message Length` describes the payload size on the wire. ## moq-lite-07 +- Added TRACK_INFO `Refresh` and SUBSCRIBE_UPDATE `Wanted Group`, carrying ratio-based refresh demand through relays. + - Replaced ANNOUNCE_OK Active Count with an ordered, empty SYNCED event (0x4), marking the initial set without retaining routes that end before delivery. - A publisher must not start a timed Group's frame 0 earlier than a lower-sequence Group's. Receivers do not check it, since a received timestamp may be a send time. diff --git a/js/net/bench/refresh.ts b/js/net/bench/refresh.ts new file mode 100644 index 00000000000..1cfccd18b8c --- /dev/null +++ b/js/net/bench/refresh.ts @@ -0,0 +1,86 @@ +/** Sweep retained groups, unrelated tracks, and joined readers for a refresh crossing one lite hop. */ +import { Manual, Nano } from "@moq/clock"; +import { accept } from "../src/connection/accept.ts"; +import { connect } from "../src/connection/connect.ts"; +import { ALPN_07_WIP } from "../src/lite/version.ts"; +import { createMockTransportPair } from "../src/mock.ts"; +import { Producer } from "../src/origin.ts"; +import * as Path from "../src/path.ts"; + +console.debug = () => {}; +console.log("retained,tracks,joined,refresh_us"); +for (const retained of [1, 64, 1024]) + for (const tracks of [1, 8, 32]) + for (const joined of [1, 8, 32]) { + const clock = new Manual(); + const restore = clock.install(); + const source = new Producer(); + const destination = new Producer(); + const broadcast = source.createBroadcast(Path.from("room")); + broadcast.announce(); + const producers = Array.from({ length: tracks }, (_, i) => + broadcast.createTrack(`data${i}`, { refresh: 1 }), + ); + const pair = createMockTransportPair(ALPN_07_WIP); + const url = new URL("https://localhost/refresh"); + const peers = await Promise.all([ + connect({ url, transport: pair.client, consume: destination }), + accept({ url, transport: pair.server, publish: source.consume() }), + ]); + try { + const announcements = destination.announced(); + while ((await announcements.next())?.kind !== "start") {} + const request = destination.request(Path.from("room")); + while (!request.active.peek()) await request.active.changed(); + const remote = request.active.peek()!; + const consumers = producers.map((_, i) => remote.track(`data${i}`)); + const baseline = consumers.map((track) => track.subscribe()); + for (let i = 0; i < tracks; i++) { + const group = producers[i].appendGroup(); + group.writeFrame({ payload: new Uint8Array(3) }); + group.close(); + const received = (await baseline[i].recvGroup())!; + await received.readFrame(); + received.close(); + } + // Keep this track's historical groups in its cache. Only the touched + // track grows, so scanning that cache appears independently of fanout. + for (let old = 1; old < retained; old++) { + const group = producers[0].appendGroup(); + group.writeFrame({ payload: new Uint8Array(3) }); + group.close(); + const received = await baseline[0].recvGroup(); + if (!received) throw new Error("historical group missing"); + await received.readFrame(); + received.close(); + } + + const samples: number[] = []; + for (let round = 0; round < 9; round++) { + const group = producers[0].appendGroup(); + group.writeFrame({ payload: new Uint8Array(3) }); + group.writeFrame({ payload: new Uint8Array(4) }); + group.close(); + const received = (await baseline[0].recvGroup())!; + await received.readFrame(); + await received.readFrame(); + received.close(); + const start = performance.now(); + const joins = Array.from({ length: joined }, () => consumers[0].subscribe()); + const wanted = producers[0].demand().wanted; + while (wanted.peek() !== group.sequence + 1) await wanted.changed(); + if (round > 0) samples.push((performance.now() - start) * 1000); + for (const join of joins) join.close(); + } + samples.sort((a, b) => a - b); + console.log(`${retained},${tracks},${joined},${samples[4].toFixed(2)}`); + for (const sub of baseline) sub.close(); + request.close(); + } finally { + destination.close(); + source.close(); + for (const peer of peers) peer.abort(); + await clock.advanceAsync(Nano(0)); + restore(); + } + } diff --git a/js/net/src/internal.ts b/js/net/src/internal.ts index bf7ae262fe7..c342ed8218a 100644 --- a/js/net/src/internal.ts +++ b/js/net/src/internal.ts @@ -283,6 +283,8 @@ export type RecvDatagram = * buffer of its own. Implemented by `resume.ts`, the counterpart of the Rust `Inner::Resume`. */ export interface ResumeSource { + /** Re-evaluate a live-edge join at the serving copy. */ + join(): void; /** The next group not in `delivered`, in arrival or sequence order, without waiting. */ tryGroup(ordered: boolean, delivered: Delivered): Recv; /** @@ -345,6 +347,16 @@ export const hooks: { * a higher one. Mirrors the Rust `finish_at_pending`; assigned by `track.ts`. */ endTrack: (producer: Producer, end: Location) => void; + // private: capability gap + /** The producer's largest reported location and its subsequent changes. */ + producerLargest: (producer: Producer) => Getter; + + // private: passthrough + /** Re-evaluate a live-edge join at this subscriber's copy. */ + joinSubscriber: (subscriber: Subscriber) => void; + /** Re-evaluate a live-edge join at a producer. */ + joinProducer: (producer: Producer) => void; + // pending: /quest/m1/public-model/deferred.md /** * Declare the first group a wire subscription's live feed serves (lite SUBSCRIBE_START, or @@ -491,6 +503,15 @@ export const hooks: { endTrack: () => { throw new Error("track.ts not loaded"); }, + producerLargest: () => { + throw new Error("track.ts not loaded"); + }, + joinProducer: () => { + throw new Error("track.ts not loaded"); + }, + joinSubscriber: () => { + throw new Error("track.ts not loaded"); + }, startTrack: () => { throw new Error("track.ts not loaded"); }, diff --git a/js/net/src/lite/publisher.ts b/js/net/src/lite/publisher.ts index 3c5f9a9f990..c9e64cc4336 100644 --- a/js/net/src/lite/publisher.ts +++ b/js/net/src/lite/publisher.ts @@ -893,6 +893,11 @@ export class Publisher { writer: stream.writer, version: this.version, apply: (update) => { + // Every update restates the wanted group. Past our largest it is a join, which + // repeats the pending ask; at or below it the group already exists. + const largest = hooks.peekLargest(track).largest?.group; + if (update.wantedGroup !== undefined && (largest === undefined || update.wantedGroup > largest)) + hooks.joinSubscriber(track); const end = exclusiveGroupEnd(update.endGroup); track.update({ priority: update.priority, @@ -1431,6 +1436,7 @@ export class Publisher { const info = await wireOf(front).resolveTrackInfo(track, release.signal); return new TrackInfoMessage({ priority: info.priority, + refresh: info.refresh, // Publisher Max Age: the publisher's retention bound, advertised so // relays re-serve with the same window. maxAge: info.maxAge, diff --git a/js/net/src/lite/refresh.test.ts b/js/net/src/lite/refresh.test.ts new file mode 100644 index 00000000000..45ac727154f --- /dev/null +++ b/js/net/src/lite/refresh.test.ts @@ -0,0 +1,81 @@ +import { expect, spyOn, test } from "bun:test"; +import { Manual, Nano } from "@moq/clock"; +import { accept } from "../connection/accept.ts"; +import { connect } from "../connection/connect.ts"; +import { createMockTransportPair } from "../mock.ts"; +import { Producer } from "../origin.ts"; +import * as Path from "../path.ts"; +import { SubscribeUpdate } from "./subscribe.ts"; +import { ALPN_06, ALPN_07_WIP } from "./version.ts"; + +test.each([ALPN_06, ALPN_07_WIP])("refresh joins reach a browser publisher on %s", async (alpn) => { + const clock = new Manual(); + const restore = clock.install(); + const source = new Producer(); + const b = new Producer(); + const broadcast = source.createBroadcast(Path.from("room")); + broadcast.announce(); + const producer = broadcast.createTrack("data", { refresh: 1 }); + const pair = createMockTransportPair(alpn); + const url = new URL("https://localhost/refresh"); + const updates: number[] = []; + const encode = SubscribeUpdate.prototype.encode; + const spy = spyOn(SubscribeUpdate.prototype, "encode").mockImplementation(function ( + this: SubscribeUpdate, + writer, + version, + ) { + if (this.wantedGroup !== undefined) updates.push(this.wantedGroup); + return encode.call(this, writer, version); + }); + const peers: { abort(): void }[] = []; + try { + peers.push( + ...(await Promise.all([ + connect({ url, transport: pair.client, consume: b }), + accept({ url, transport: pair.server, publish: source.consume() }), + ])), + ); + const announcements = b.announced(); + while ((await announcements.next())?.kind !== "start") {} + const request = b.request(Path.from("room")); + while (request.active.peek() === undefined) await request.active.changed(); + const remote = request.active.peek()!.track("data"); + expect((await remote.info()).refresh).toBe(alpn === ALPN_07_WIP ? 1 : undefined); + const baseline = remote.subscribe(); + const group = producer.appendGroup(); + group.writeFrame({ payload: new Uint8Array(3) }); + group.writeFrame({ payload: new Uint8Array(3) }); + const received = await baseline.recvGroup(); + expect((await received!.readFrame())!.payload.length).toBe(3); + expect((await received!.readFrame())!.payload.length).toBe(3); + const joins = [remote.subscribe()]; + await clock.advanceAsync(Nano(0)); + expect(producer.demand().wanted.peek()).toBe(0); + updates.length = 0; + group.writeFrame({ payload: new Uint8Array(1) }); + expect((await received!.readFrame())!.payload.length).toBe(1); + for (let i = 0; i < 8; i++) joins.push(remote.subscribe()); + await clock.advanceAsync(Nano(0)); + if (alpn === ALPN_07_WIP) { + while (producer.demand().wanted.peek() !== 1) await producer.demand().wanted.changed(); + } + expect(producer.demand().wanted.peek()).toBe(alpn === ALPN_07_WIP ? 1 : 0); + // Concurrent local joins coalesce into one upstream update. + expect(updates).toEqual(alpn === ALPN_07_WIP ? [1] : []); + // A parameter change restates the wanted group rather than clearing it. + joins.push(remote.subscribe({ priority: 9 })); + await clock.advanceAsync(Nano(0)); + expect(updates).toEqual(alpn === ALPN_07_WIP ? [1, 1] : []); + for (const join of joins) join.close(); + received!.close(); + baseline.close(); + group.close(); + } finally { + spy.mockRestore(); + for (const origin of [b, source]) origin.close(); + for (const peer of peers) peer.abort(); + await clock.advanceAsync(Nano(0)); + restore(); + } +}); diff --git a/js/net/src/lite/subscribe.test.ts b/js/net/src/lite/subscribe.test.ts index 9c3c5a56385..5f029bcc6c9 100644 --- a/js/net/src/lite/subscribe.test.ts +++ b/js/net/src/lite/subscribe.test.ts @@ -307,3 +307,23 @@ test.each([Version.DRAFT_03, Version.DRAFT_05, Version.DRAFT_06])( expect(decoded.order).toBe("descending"); }, ); + +test("wanted group survives lite-07 and disappears on legacy wires", async () => { + for (const version of [Version.DRAFT_05, Version.DRAFT_06, Version.DRAFT_07]) { + for (const wantedGroup of [undefined, 0, 3, Number.MAX_SAFE_INTEGER]) { + const update = new SubscribeUpdate({ priority: 7, wantedGroup }); + const encoded = await encodeMessage(version, update); + const decoded = await SubscribeUpdate.decode(new Reader(undefined, encoded, version), version); + expect(decoded.wantedGroup).toBe(version === Version.DRAFT_07 ? wantedGroup : undefined); + } + } +}); + +test("wanted groups refuse malformed input before writing bytes", async () => { + for (const wantedGroup of [-1, 0.5, Number.MAX_SAFE_INTEGER + 1, Number.NaN]) { + expect(() => new SubscribeUpdate({ priority: 0, wantedGroup })).toThrow(RangeError); + const update = new SubscribeUpdate({ priority: 0 }); + update.wantedGroup = wantedGroup; + await expect(encodeMessage(Version.DRAFT_07, update)).rejects.toThrow(RangeError); + } +}); diff --git a/js/net/src/lite/subscribe.ts b/js/net/src/lite/subscribe.ts index d04671f960a..b2a6903997d 100644 --- a/js/net/src/lite/subscribe.ts +++ b/js/net/src/lite/subscribe.ts @@ -5,7 +5,7 @@ import type { Reader, Writer } from "../stream.ts"; import type { Location, Order } from "../track.ts"; import { decodeEpoch, encodeEpoch } from "./epoch.ts"; import * as Message from "./message.ts"; -import { hasFrameBounds, hasGroupOrder, hasLargest, hasOrder, resolvesStart, Version } from "./version.ts"; +import { hasFrameBounds, hasGroupOrder, hasLargest, hasOrder, hasRefresh, resolvesStart, Version } from "./version.ts"; /** * Encode the `Group Start` field shared by SUBSCRIBE and SUBSCRIBE_UPDATE. @@ -181,6 +181,8 @@ export function emptyRange({ startGroup, endGroup }: { startGroup?: number; endG } export class SubscribeUpdate { + /** A join requesting this group or later, judged against the local refresh ratio. */ + wantedGroup?: number; priority: number; /** See {@link Subscribe.order}. */ order: Order; @@ -195,6 +197,7 @@ export class SubscribeUpdate { constructor(props: { priority: number; + wantedGroup?: number; order?: Order; maxDelay?: number; startGroup?: number; @@ -202,6 +205,9 @@ export class SubscribeUpdate { startFrame?: number; endFrame?: number; }) { + if (props.wantedGroup !== undefined && (!Number.isSafeInteger(props.wantedGroup) || props.wantedGroup < 0)) + throw new RangeError("wanted group must be a safe non-negative integer"); + this.wantedGroup = props.wantedGroup; this.priority = props.priority; this.order = props.order ?? "descending"; this.maxDelay = props.maxDelay ?? 0; @@ -224,6 +230,8 @@ export class SubscribeUpdate { await encodeStartGroup(w, version, this.startGroup); await w.u53(this.endGroup !== undefined ? this.endGroup + 1 : 0); await encodeFrameBounds(w, version, this); + if (hasRefresh(version)) + await w.u62(this.wantedGroup === undefined ? 0n : BigInt(this.wantedGroup) + 1n); break; } } @@ -241,7 +249,11 @@ export class SubscribeUpdate { const endGroup = (await r.u53()) || undefined; const end = endGroup !== undefined ? endGroup - 1 : undefined; const frames = await decodeFrameBounds(r, version, startGroup, end); + const wanted = hasRefresh(version) ? await r.u62() : 0n; + if (wanted > BigInt(Number.MAX_SAFE_INTEGER) + 1n) + throw new RangeError("wanted group exceeds safe integer"); return new SubscribeUpdate({ + wantedGroup: wanted === 0n ? undefined : Number(wanted - 1n), priority, order, maxDelay, @@ -254,6 +266,8 @@ export class SubscribeUpdate { } async encode(w: Writer, version: Version): Promise { + if (this.wantedGroup !== undefined && (!Number.isSafeInteger(this.wantedGroup) || this.wantedGroup < 0)) + throw new RangeError("wanted group must be a safe non-negative integer"); return Message.encode(w, (w) => this.#encode(w, version)); } diff --git a/js/net/src/lite/subscriber.ts b/js/net/src/lite/subscriber.ts index a28793953b2..4a1cacc8009 100644 --- a/js/net/src/lite/subscriber.ts +++ b/js/net/src/lite/subscriber.ts @@ -57,6 +57,7 @@ import { hasFetchMaxDelay, hasOrder, hasProbeRtt, + hasRefresh, hasSynced, hasTrackStream, resolvesStart, @@ -964,6 +965,7 @@ export class Subscriber { // matches what the upstream advertises (relays re-serve with the same bound). maxAge: info.maxAge === undefined ? undefined : Milli(info.maxAge), priority: info.priority, + refresh: info.refresh, }; } @@ -1312,11 +1314,32 @@ export class Subscriber { }, }; + // The wanted group is subscription state: an update announces each new one past our + // largest, and every later update restates it. Joins asking for the same group + // coalesce into that one update. + let sentWanted: number | undefined; + const demand = track.demand(); + const edge = hooks.producerLargest(track); for (;;) { + const largest = edge.peek()?.group; + const wanted = demand.wanted.peek(); + const refresh = + hasRefresh(this.version) && + largest !== undefined && + wanted !== undefined && + wanted > largest && + wanted !== sentWanted + ? wanted + : undefined; const current = track.subscription.peek(); - if (current === undefined || this.#sameSubscription(current, lastSent)) { + if (current === undefined || (refresh === undefined && this.#sameSubscription(current, lastSent))) { // Nothing new to send; wait for a change or termination. - const next = await race([track.subscription.changed(), stopped]); + const next = await race([ + track.subscription.changed(), + demand.wanted.changed(), + edge.changed(), + stopped, + ]); if (next === null) return; continue; } @@ -1335,6 +1358,7 @@ export class Subscriber { // Round-trip the other Subscribe parameters so the publisher doesn't // interpret SUBSCRIBE_UPDATE as a reset of ordered/maxDelay/etc. const update = new SubscribeUpdate({ + wantedGroup: refresh ?? sentWanted, priority: current.priority ?? 0, order: current.order, maxDelay: current.maxDelay, @@ -1352,6 +1376,7 @@ export class Subscriber { } catch { return; } + if (refresh !== undefined) sentWanted = refresh; lastSent = { ...current }; console.debug(`subscribe update: id=${id} broadcast=${broadcast} track=${track.name}`); } diff --git a/js/net/src/lite/track.test.ts b/js/net/src/lite/track.test.ts index 096ad5dad9b..e0c776bf829 100644 --- a/js/net/src/lite/track.test.ts +++ b/js/net/src/lite/track.test.ts @@ -201,3 +201,14 @@ for (const version of [Version.DRAFT_05, Version.DRAFT_06]) { } }); } + +test("refresh ratio survives lite-07 and disappears on legacy wires", async () => { + for (const version of [Version.DRAFT_05, Version.DRAFT_06, Version.DRAFT_07]) { + for (const refresh of [undefined, 0, 3, 0xffff_ffff]) { + const info = new TrackInfo({ priority: 7, refresh }); + const encoded = await bytes((w) => info.encode(w, version), version); + const decoded = await TrackInfo.decode(new Reader(undefined, encoded, version), version); + expect(decoded.refresh).toBe(version === Version.DRAFT_07 ? refresh : undefined); + } + } +}); diff --git a/js/net/src/lite/track.ts b/js/net/src/lite/track.ts index 109ee2933ba..e68210b4565 100644 --- a/js/net/src/lite/track.ts +++ b/js/net/src/lite/track.ts @@ -4,7 +4,7 @@ import type { Reader, Writer } from "../stream.ts"; import { Timescale } from "../time.ts"; import { decodeEpoch, encodeEpoch } from "./epoch.ts"; import * as Message from "./message.ts"; -import { hasGroupOrder, hasTrackStream, Version, wireTimescale } from "./version.ts"; +import { hasGroupOrder, hasRefresh, hasTrackStream, Version, wireTimescale } from "./version.ts"; function guardTrack(version: Version) { if (!hasTrackStream(version)) throw new Error("track stream not supported for this version"); @@ -56,6 +56,8 @@ export class Track { * FETCH for the track. */ export class TrackInfo { + /** Refresh byte ratio on lite-07. */ + refresh?: number; /** The publisher's tie-break priority for this track. */ priority: number; /** @@ -74,10 +76,12 @@ export class TrackInfo { priority = 0, maxAge, timescale, + refresh, }: { priority?: number; maxAge?: number; timescale?: number; + refresh?: number; }) { if (!Number.isInteger(priority) || priority < 0 || priority > 255) { throw new RangeError(`priority must be an integer in 0..=255: ${priority}`); @@ -85,6 +89,9 @@ export class TrackInfo { if (maxAge !== undefined && (!Number.isSafeInteger(maxAge) || maxAge < 0)) { throw new RangeError(`maxAge must be a safe non-negative integer: ${maxAge}`); } + if (refresh !== undefined && (!Number.isInteger(refresh) || refresh < 0 || refresh > 0xffff_ffff)) + throw new RangeError("refresh exceeds u32"); + this.refresh = refresh; this.priority = priority; this.maxAge = maxAge; this.timescale = timescale === undefined ? undefined : Timescale(timescale); @@ -98,6 +105,7 @@ export class TrackInfo { const age = this.maxAge === undefined ? undefined : BigInt(this.maxAge); await w.u62(legacy ? (age ?? BigInt(Number.MAX_SAFE_INTEGER)) : age === undefined ? 0n : age + 1n); await w.u53(wireTimescale(version, this.timescale) ?? 0); + if (hasRefresh(version)) await w.u53(this.refresh === undefined ? 0 : this.refresh + 1); } static async #decode(r: Reader, version: Version): Promise { @@ -118,7 +126,8 @@ export class TrackInfo { // Lite-05/06 have no untimed encoding, so zero is malformed there. const scale = await r.u53(); const timescale = scale === 0 && !legacy ? undefined : Timescale(scale); - return new TrackInfo({ priority, maxAge, timescale }); + const refresh = hasRefresh(version) ? (await r.u53()) - 1 : undefined; + return new TrackInfo({ priority, maxAge, timescale, refresh: refresh === -1 ? undefined : refresh }); } async encode(w: Writer, version: Version): Promise { @@ -131,6 +140,11 @@ export class TrackInfo { if (this.maxAge !== undefined && (!Number.isSafeInteger(this.maxAge) || this.maxAge < 0)) { throw new RangeError(`maxAge must be a safe non-negative integer: ${this.maxAge}`); } + if ( + this.refresh !== undefined && + (!Number.isInteger(this.refresh) || this.refresh < 0 || this.refresh > 0xffff_ffff) + ) + throw new RangeError("refresh exceeds u32"); if (this.timescale !== undefined) Timescale(this.timescale); return Message.encode(w, (w) => this.#encode(w, version)); } diff --git a/js/net/src/lite/version.ts b/js/net/src/lite/version.ts index 287bcd49327..7ad0208cba6 100644 --- a/js/net/src/lite/version.ts +++ b/js/net/src/lite/version.ts @@ -387,6 +387,23 @@ export function hasAnnounceCompression(version: Version): boolean { } } +/** Whether TRACK_INFO carries the refresh ratio and SUBSCRIBE_UPDATE a wanted group. Added in lite-07. + * Older peers see a track that never refreshes. */ +export function hasRefresh(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; + } +} + /// The WebTransport subprotocol identifier for moq-lite. /// Version negotiation still happens via SETUP when this is used. export const ALPN = "moql"; diff --git a/js/net/src/resume.ts b/js/net/src/resume.ts index f108886ba1b..afc76f21b2b 100644 --- a/js/net/src/resume.ts +++ b/js/net/src/resume.ts @@ -694,6 +694,12 @@ class Reader implements ResumeSource { } } + join(): void { + this.sync(); + const serving = this.#serving(); + if (serving) hooks.joinSubscriber(serving.sub); + } + fork(options?: track.Subscription): track.Subscriber { this.sync(); const newest = this.#copies.at(-1); diff --git a/js/net/src/track.ts b/js/net/src/track.ts index 47b3eef98bc..d6f11592e30 100644 --- a/js/net/src/track.ts +++ b/js/net/src/track.ts @@ -723,6 +723,8 @@ export class Producer { } static { + hooks.producerLargest = (producer) => producer.#state.largest; + hooks.joinProducer = (producer) => producer.#join(); hooks.endTrack = (producer, end) => producer.#endPending(end); hooks.startTrack = (producer, served) => { producer.#served = served; @@ -1784,6 +1786,10 @@ export class Subscriber { static { makeSubscriber = (name, state) => new Subscriber(name, state); + hooks.joinSubscriber = (subscriber) => { + if (subscriber.#resume) subscriber.#resume.join(); + else if (subscriber.#state.producer) hooks.joinProducer(subscriber.#state.producer); + }; hooks.tryRecvGroup = (subscriber, started) => subscriber.#tryRecvGroup(started); hooks.tryNextGroup = (subscriber) => subscriber.#tryNextGroup(); hooks.peekGroup = (subscriber, ordered) => subscriber.#peekGroup(ordered); diff --git a/quest/m1/ietf-extension/lite.md b/quest/m1/ietf-extension/lite.md index 7abbe62a543..fbfb48b122e 100644 --- a/quest/m1/ietf-extension/lite.md +++ b/quest/m1/ietf-extension/lite.md @@ -36,7 +36,8 @@ Decided 2026-10-13 (see the [epic](/quest/m1/ietf-extension/README.md)). unchanged inner bytes, so downstream IETF egress can refuse incompatible encodings. - Dynamic-group requests are not this extension's job. Native lite-07 - carries them as [refresh](/quest/m1/refresh/lite.md), decided 2026-10-16. + carries them as refresh (TRACK_INFO `Refresh` and SUBSCRIBE_UPDATE + `Wanted Group`), decided 2026-10-16. - Write `drafts/draft-lcurley-moq-ietf.md` for the extension and pass `just drafts check`. List it with the other project drafts in `doc/concept/standard.md`, and note in `doc/bin/relay/` that relays enable @@ -56,6 +57,4 @@ and the framing above, only when negotiated. ## Related -- [Refresh on the lite wire](/quest/m1/refresh/lite.md) - carries dynamic-group requests between relays instead of this extension - - [Finalize moq-lite-07](/quest/m1/lite07-finalize.md) - the extension targets the wip version and does not gate the cut diff --git a/quest/m1/lite07-finalize.md b/quest/m1/lite07-finalize.md index 0b304f49302..22d9f51b48b 100644 --- a/quest/m1/lite07-finalize.md +++ b/quest/m1/lite07-finalize.md @@ -87,7 +87,6 @@ is published; older versions are unchanged. - [Readers see SUBSCRIBE_DROP](/quest/m1/subscribe-drop-errors.md) - settles what lite-07's DROP Error Code means - [Subscribe ranges](/quest/m1/subscribe-ranges/README.md) - SUBSCRIBE carries ranges and an order and lite FETCH is gone, in Rust and JS - [Announcement takeover](/quest/m1/announce-takeover.md) - ANNOUNCE_TAKEOVER preserves a proven instance under a new independent route -- [Refresh on the lite wire](/quest/m1/refresh/lite.md) - TRACK_INFO carries the refresh ratio and SUBSCRIBE_UPDATE the wanted group - [Compressed tracks in Rust](/quest/m1/compress/core.md) - TRACK_INFO carries the compress flag and the frame header each compressed frame's inflated size - [Compressed tracks in js/net](/quest/m1/compress/js.md) - JS reads and writes compressed lite-07 tracks instead of refusing them - [TRACKS](/quest/m1/archive/tracks.md) - lite-07 carries the request listing a broadcast's tracks as they appear diff --git a/quest/m1/refresh/README.md b/quest/m1/refresh/README.md index 708e994f19d..af813a7d571 100644 --- a/quest/m1/refresh/README.md +++ b/quest/m1/refresh/README.md @@ -62,7 +62,6 @@ Work owned by this README, after the children land: ## Required -- [Lite wire](/quest/m1/refresh/lite.md) - lite-07 TRACK_INFO advertises the ratio and SUBSCRIBE_UPDATE carries the wanted group, so a join at any relay reaches the origin - [moq-json](/quest/m1/refresh/json.md) - snapshot and window groups roll on a qualifying join, reading the ratio from the track; `delta_ratio` and `op_ratio` become `deltas` and `ops` switches in every binding - [Video](/quest/m1/refresh/video.md) - video publishers advertise refresh and force a keyframe on demand, keeping the encoder's max GOP diff --git a/quest/m1/refresh/lite.md b/quest/m1/refresh/lite.md deleted file mode 100644 index 8ed29cc630e..00000000000 --- a/quest/m1/refresh/lite.md +++ /dev/null @@ -1,46 +0,0 @@ -# [M] Refresh on the moq-lite wire - -## Goal - -On lite-07, a track's refresh ratio reaches every subscriber in -TRACK_INFO. A join at any relay that crosses the ratio reaches the origin -publisher's `Demand::wanted`, through a relay cluster, in Rust and JS. A -peer on an older lite version sees a track that never refreshes. - -## Plan - -Decided 2026-10-16 (see the [epic](/quest/m1/refresh/README.md)). - -- **TRACK_INFO** gains a `Refresh` varint: 0 for none, otherwise ratio + 1, - matching how lite-07 encodes Publisher Max Age. lite-07 only, while it is - the wip version. This quest gates the - [lite-07 cut](/quest/m1/lite07-finalize.md), because missing it would push - core-message fields to lite-08. -- **SUBSCRIBE needs no field.** A new SUBSCRIBE is itself a join at the - upstream hop, which evaluates the ratio against its own cache. -- **SUBSCRIBE_UPDATE** gains a `Wanted Group` varint: 0 for none, otherwise - sequence + 1. A relay's upstream driver sends it when its track's - `Demand::wanted` passes the largest group. It sends nothing more until the - largest group reaches it, so redundant downstream joins coalesce at every - hop. Clear it with the subscription, so a reconnect inherits nothing. -- **Receiving it** counts as a join under the ratio at that hop, like a - downstream IETF NEW_GROUP_REQUEST. A stale value at or below the largest - group is ignored. -- **js/net** encodes and decodes both fields and feeds its `Demand::wanted`, - so a browser publisher refreshes. A browser subscriber's SUBSCRIBE is its - join. -- **Drafts.** Update `drafts/draft-lcurley-moq-lite.md` (TRACK_INFO, - SUBSCRIBE_UPDATE, the lite-07 changelog) and pass `just drafts check`. -- **The ietf extension.** Cluster hops no longer need it to carry - dynamic-group requests; native lite does. This quest removes that duty - from the [relay extension](/quest/m1/ietf-extension/lite.md) if that quest - has not landed yet, or deletes its request path if it has. - -Tests: codec round trips on lite-07 and an older version without the -fields. A two-relay cluster test checks that a join over the ratio at the far -relay reaches the origin's `wanted`, a join under it does not, and -concurrent joins send one SUBSCRIBE_UPDATE. Use simulated time. Run -`just test interop --all`. - -Public API: none beyond `Demand::wanted` and `track::Info::refresh`. Wire: two -new lite-07 fields. diff --git a/rs/moq-net/src/fuzz.rs b/rs/moq-net/src/fuzz.rs index 442fead6fed..822c77ef887 100644 --- a/rs/moq-net/src/fuzz.rs +++ b/rs/moq-net/src/fuzz.rs @@ -611,6 +611,7 @@ impl Default for Messages { end_frame: None, }, lite_update: lite::SubscribeUpdate { + wanted_group: None, order: crate::track::Order::Descending, priority: 4, max_delay: Duration::from_millis(500), @@ -624,6 +625,7 @@ impl Default for Messages { largest: None, }), lite_info: lite::TrackInfo { + refresh: None, priority: 1, max_age: Some(Duration::from_secs(10)), timescale: Some(crate::Timescale::MICRO), diff --git a/rs/moq-net/src/lite/publisher.rs b/rs/moq-net/src/lite/publisher.rs index ce8a6b85f0c..133acc236b0 100644 --- a/rs/moq-net/src/lite/publisher.rs +++ b/rs/moq-net/src/lite/publisher.rs @@ -1941,6 +1941,7 @@ impl Request for TrackInfoServe { // TRACK_INFO only flows on Lite05+ (the encode errors otherwise). writer.buffer(&lite::TrackInfo { + refresh: info.refresh, priority: info.priority, max_age: info.max_age, timescale: info.timescale, @@ -3639,6 +3640,14 @@ 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) { + // Every update restates the wanted group. Past our largest it is a join, which + // repeats the pending ask; at or below it the group already exists. + if upd + .wanted_group + .is_some_and(|wanted| self.track.peek_largest().is_none_or(|largest| wanted > largest.group)) + { + self.track.join(); + } if let Ok(mut value) = self.steer_tx.write() { *value = Steer { priority: upd.priority, @@ -4935,6 +4944,42 @@ mod serve_group_test { (TrackRun::new(ctx, track, bounds, steer), writer, log) } + #[moq_clock::test] + async fn wanted_updates_ignore_stale_groups_and_recheck_the_ratio() { + let track = track::Producer::new( + Arc::new(broadcast::Info::default()), + "refresh", + track::Info::default().with_refresh(1), + ); + let subscriber = track.subscribe(None); + let (mut run, _, _) = lite_run(Version::Lite07, SinkSession::new(Log::default()), subscriber); + let mut group = track.append_group().unwrap(); + group.write_frame(None, &b"key"[..]).unwrap(); + group.write_frame(None, &b"more"[..]).unwrap(); + group.finish().unwrap(); + let update = |wanted_group| lite::SubscribeUpdate { + wanted_group, + priority: 0, + max_delay: Duration::ZERO, + start_group: None, + end_group: None, + start_frame: 0, + end_frame: None, + order: Order::Descending, + }; + run.update(update(Some(0))); + assert_eq!(track.demand().wanted(), Some(0), "stale request is not a join"); + run.update(update(Some(1))); + assert_eq!(track.demand().wanted(), Some(1)); + let mut group = track.append_group().unwrap(); + group.write_frame(None, &b"key"[..]).unwrap(); + group.finish().unwrap(); + run.update(update(Some(1))); + assert_eq!(track.demand().wanted(), Some(1), "answered request stays answered"); + run.update(update(Some(2))); + assert_eq!(track.demand().wanted(), Some(1), "new hop judges its own ratio"); + } + fn write_group(track: &mut track::Producer, sequence: u64, millis: u64) { let mut group = track.create_group(group::Info { sequence }).unwrap(); group @@ -4977,6 +5022,7 @@ mod serve_group_test { assert!(log.priorities().is_empty(), "the session queue ranks no stream"); run.update(lite::SubscribeUpdate { + wanted_group: None, order: Order::Ascending, priority: 7, max_delay: Duration::ZERO, @@ -5051,6 +5097,7 @@ mod serve_group_test { } run.update(lite::SubscribeUpdate { + wanted_group: None, order: Order::Ascending, priority: 3, max_delay: Duration::from_secs(3600), @@ -5343,6 +5390,7 @@ mod serve_group_test { assert_eq!(drops(&mut writer, &log, version).await, []); run.update(lite::SubscribeUpdate { + wanted_group: None, order: crate::track::Order::Descending, priority: 0, max_delay: Duration::from_secs(60), @@ -5505,6 +5553,7 @@ mod serve_group_test { assert_eq!(run.start, Some(5)); run.update(lite::SubscribeUpdate { + wanted_group: None, order: crate::track::Order::Descending, priority: 0, max_delay: Duration::from_secs(60), @@ -5547,6 +5596,7 @@ mod serve_group_test { moq_clock::sim::advance(Duration::from_secs(2)).await; run.update(lite::SubscribeUpdate { + wanted_group: None, order: crate::track::Order::Descending, priority: 0, max_delay: Duration::from_secs(1), @@ -5592,6 +5642,7 @@ mod serve_group_test { } let update = |start_group| lite::SubscribeUpdate { + wanted_group: None, order: crate::track::Order::Descending, priority: 0, max_delay: Duration::from_secs(1), @@ -5637,6 +5688,7 @@ mod serve_group_test { } let update = |start_group| lite::SubscribeUpdate { + wanted_group: None, order: crate::track::Order::Ascending, priority: 0, max_delay: Duration::from_secs(10), @@ -5684,6 +5736,7 @@ mod serve_group_test { assert_eq!(settle(&mut run), 1); run.update(lite::SubscribeUpdate { + wanted_group: None, order: crate::track::Order::Descending, priority: 0, max_delay: Duration::from_secs(60), @@ -5715,6 +5768,7 @@ mod serve_group_test { ); let (mut run, mut writer, _log) = lite_run(Version::Lite05, SinkSession::new(Log::default()), subscriber); run.update(lite::SubscribeUpdate { + wanted_group: None, order: crate::track::Order::Descending, priority: 0, max_delay: Duration::from_secs(60), @@ -5851,6 +5905,7 @@ mod serve_group_test { assert_eq!(relay.opened(), 0, "the resume is past the only group"); relay.run.update(lite::SubscribeUpdate { + wanted_group: None, order: crate::track::Order::Descending, priority: 0, max_delay: Duration::from_secs(30), @@ -5882,6 +5937,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 { + wanted_group: None, order: crate::track::Order::Descending, priority: 0, max_delay: Duration::from_secs(30), @@ -5910,6 +5966,7 @@ mod serve_group_test { // The subscriber moves its start past the held group before the source resolves. let update = lite::SubscribeUpdate { + wanted_group: None, order: crate::track::Order::Descending, priority: 0, max_delay: Duration::ZERO, @@ -6751,7 +6808,9 @@ mod tests { } /// SUBSCRIBE_UPDATE is not a close: an update arriving while the subscription - /// resolves keeps it waiting, and still applies once it starts. + /// resolves keeps it waiting, and the latest applies once it starts. Its wanted group + /// is state each update restates: past the largest it joins, and once that group + /// exists the same value asks for nothing more. #[moq_clock::test] async fn a_subscribe_update_is_not_a_close() { let origin = crate::origin::Config::new(crate::Hop::new(1).unwrap()).produce(); @@ -6788,7 +6847,8 @@ mod tests { track: "video".into(), priority: 1, max_delay: Duration::ZERO, - start_group: None, + // A relay asks from its cached group, so the SUBSCRIBE is not a live-edge join. + start_group: Some(1), end_group: None, start_frame: 0, end_frame: None, @@ -6808,30 +6868,54 @@ mod tests { let mut serve = RequestServe::<_, SubscribeServe>::new(publisher.shared.clone(), stream); assert!(!drive(&mut serve).await); - let update = lite::SubscribeUpdate { + let update = |wanted_group, priority| lite::SubscribeUpdate { + wanted_group, order: crate::track::Order::Descending, - priority: 7, + priority, max_delay: Duration::ZERO, - start_group: None, + start_group: Some(1), end_group: None, start_frame: 0, end_frame: None, }; - session.push(&update.encode_bytes(version).unwrap()); + session.push(&update(Some(2), 3).encode_bytes(version).unwrap()); + session.push(&update(Some(2), 7).encode_bytes(version).unwrap()); assert!(!drive(&mut serve).await, "an update ended the subscription"); - // Resolve the track: the run starts at the updated priority. + // Resolve the track with a group over the ratio: the run starts at the latest + // priority, and its restated wanted group joins. let request = dynamic .requested_track() .now_or_never() .expect("track requested") .unwrap(); - let _track = request.accept(crate::track::Info::timed()); + let track = request.accept(crate::track::Info::timed().with_refresh(1)); + let mut group = track.create_group(group::Info { sequence: 1 }).unwrap(); + for frame in [&b"key"[..], b"abc", b"d"] { + group.write_frame(crate::Timestamp::ZERO, frame).unwrap(); + } + group.finish().unwrap(); assert!(!drive(&mut serve).await, "the subscription ended"); let RequestState::Serve(SubscribeServe::Run(run)) = &serve.state else { panic!("the subscription is not running"); }; assert_eq!(run.steer_tx.read().priority, 7, "the update was lost"); + assert_eq!(track.demand().wanted(), Some(2), "the refresh request was lost"); + + // The asked-for group arrives, over the ratio too. A restated wanted group is now + // stale, so it is not another join. + let mut group = track.create_group(group::Info { sequence: 2 }).unwrap(); + for frame in [&b"key"[..], b"abc", b"d"] { + group.write_frame(crate::Timestamp::ZERO, frame).unwrap(); + } + group.finish().unwrap(); + session.push(&update(Some(2), 5).encode_bytes(version).unwrap()); + assert!(!drive(&mut serve).await, "the subscription ended"); + let RequestState::Serve(SubscribeServe::Run(run)) = &serve.state else { + panic!("the subscription is not running"); + }; + assert_eq!(run.steer_tx.read().priority, 5, "the update was lost"); + assert_eq!(track.demand().wanted(), Some(2), "a stale wanted group joined"); } /// A subscription that always has another group ready yields within its budget, so a diff --git a/rs/moq-net/src/lite/subscribe.rs b/rs/moq-net/src/lite/subscribe.rs index 79c7c44b8c8..570edad4f6f 100644 --- a/rs/moq-net/src/lite/subscribe.rs +++ b/rs/moq-net/src/lite/subscribe.rs @@ -401,6 +401,8 @@ impl Message for SubscribeEnd { /// Lite03+ only. #[derive(Clone, Debug)] pub struct SubscribeUpdate { + /// A join requesting this group or later, judged against the local refresh ratio. + pub wanted_group: Option, pub priority: u8, pub max_delay: std::time::Duration, pub start_group: Option, @@ -434,7 +436,13 @@ impl Message for SubscribeUpdate { let (start_frame, end_frame) = decode_frame_bounds(r, version, start_group, end_group)?; let start_group = canonical_start_group(version, start_group, start_frame); + let wanted_group = match version.has_refresh() { + true => r.varint()?.checked_sub(1), + false => None, + }; + Ok(Self { + wanted_group, priority, max_delay, start_group, @@ -470,6 +478,9 @@ impl Message for SubscribeUpdate { self.end_frame, )?; + if version.has_refresh() { + w.varint_opt(self.wanted_group)?; + } Ok(()) } } @@ -910,6 +921,28 @@ mod test { ); } + /// Lite-07 carries `Wanted Group` on SUBSCRIBE_UPDATE; older versions drop it. + #[test] + fn wanted_group_roundtrips_only_on_lite07() { + for version in [Version::Lite05, Version::Lite06, Version::Lite07] { + for wanted in [None, Some(0), Some(1), Some(u64::MAX - 1)] { + let update = SubscribeUpdate { + wanted_group: wanted, + priority: 0, + max_delay: std::time::Duration::ZERO, + start_group: None, + end_group: None, + start_frame: 0, + end_frame: None, + order: crate::track::Order::Descending, + }; + let buf = update.encode_bytes(version).unwrap(); + let got = crate::coding::decode_buf(&mut buf.as_ref(), version, SubscribeUpdate::decode).unwrap(); + assert_eq!(got.wanted_group, if version.has_refresh() { wanted } else { None }); + } + } + } + /// Lite-07 carries `Group Order` right after the priority, on SUBSCRIBE and /// SUBSCRIBE_UPDATE alike, and refuses a value it does not define. #[test] @@ -927,6 +960,7 @@ mod test { assert_eq!(got.order, order); let update = SubscribeUpdate { + wanted_group: None, priority: 3, max_delay: std::time::Duration::from_millis(250), start_group: None, diff --git a/rs/moq-net/src/lite/subscriber.rs b/rs/moq-net/src/lite/subscriber.rs index 8758fe03f7a..3f029582145 100644 --- a/rs/moq-net/src/lite/subscriber.rs +++ b/rs/moq-net/src/lite/subscriber.rs @@ -1683,6 +1683,7 @@ mod tests { tail: tail.clone(), served: None, end: None, + wanted: None, }) } @@ -2095,6 +2096,7 @@ mod tests { tail: Default::default(), served: None, end: Some(lite::SubscribeEnd { group: 10 }), + wanted: None, }; assert_eq!( sub.owed(None), @@ -3480,6 +3482,57 @@ mod tests { assert_eq!((msg.end_group, msg.end_frame), (Some(5), None)); } + /// Concurrent joins over the refresh ratio send one SUBSCRIBE_UPDATE upstream, a new + /// group past the largest sends the next, and every update restates the latest. + #[moq_clock::test] + async fn refresh_joins_coalesce_upstream() { + let h = Harness::new(Version::Lite07); + let request = h._broadcast.reserve_track("refresh").unwrap(); + let mut serving = ServeLoop::new(&h.serve, request, track::Info::default().with_refresh(1), None); + let track = h._broadcast.consume().track("refresh").unwrap(); + let _baseline = track.subscribe(None).await.unwrap(); + assert!(serving.poll(&h.serve, &kio::Waiter::noop()).is_pending()); + assert!(matches!(serving.sub, Sub::Active(_)), "the reader opens the upstream"); + let established = h.wire().len(); + + let arrive = |serving: &ServeLoop, sequence| { + let mut group = serving.serving.receive_group(group::Info { sequence }).unwrap(); + for frame in [&b"key"[..], b"abc", b"d"] { + group.write_frame(None, frame).unwrap(); + } + group.finish().unwrap(); + }; + let wanted = |h: &Harness| { + let wire = h.wire(); + let mut wire = &wire[established..]; + let mut wanted = Vec::new(); + while !wire.is_empty() { + let msg = crate::coding::decode_buf(&mut wire, Version::Lite07, lite::SubscribeUpdate::decode).unwrap(); + wanted.extend(msg.wanted_group); + } + wanted + }; + + // The deltas outweigh the first frame, so every join asks for group 1. + arrive(&serving, 0); + let mut joins = Vec::new(); + for _ in 0..8 { + joins.push(track.subscribe(None).await.unwrap()); + assert!(serving.poll(&h.serve, &kio::Waiter::noop()).is_pending()); + } + assert_eq!(wanted(&h), [1], "joins coalesce into one request"); + + arrive(&serving, 1); + joins.push(track.subscribe(None).await.unwrap()); + assert!(serving.poll(&h.serve, &kio::Waiter::noop()).is_pending()); + assert_eq!(wanted(&h), [1, 2], "the requested group re-arms the next request"); + + // A parameter change restates the pending wanted group rather than clearing it. + let _urgent = track.subscribe(Subscription::default().with_priority(9)).await.unwrap(); + assert!(serving.poll(&h.serve, &kio::Waiter::noop()).is_pending()); + assert_eq!(wanted(&h), [1, 2, 2], "every update restates the wanted group"); + } + /// A buffered SUBSCRIBE_START describes the demand its SUBSCRIBE carried, so /// it applies exactly while the current start matches that demand: an update /// that moves the start makes it stale (applying it could reopen a range the @@ -4721,6 +4774,8 @@ struct SubStream { served: Option, /// The track's exclusive end (SUBSCRIBE_END), once declared. end: Option, + /// The refresh join's wanted group, restated in every SUBSCRIBE_UPDATE. + wanted: Option, } impl SubStream { @@ -4742,6 +4797,9 @@ impl SubStream { } } +// One per track copy, which holds a live stream while anyone reads it, so boxing it +// would add an allocation per upstream subscription without saving memory. +#[allow(clippy::large_enum_variant)] enum Sub { None, Active(SubStream), @@ -5352,14 +5410,14 @@ enum Begin { Establish(Establish), } -/// Buffer a SUBSCRIBE_UPDATE echoing the current params, varying only the end -/// bound. The caller flushes. +/// Buffer the current SUBSCRIBE parameters with an updated end. The caller flushes. fn buffer_update( active: &mut SubStream, end: Option, ) -> Result<(), Error> { let bounds = WireBounds::new(active.start, end); active.stream.writer.buffer(&lite::SubscribeUpdate { + wanted_group: active.wanted, priority: active.priority, max_delay: active.max_delay, start_group: bounds.start_group, @@ -5479,6 +5537,7 @@ impl Establish { tail: self.tail.clone(), served: None, end: None, + wanted: None, } } } @@ -5762,7 +5821,8 @@ impl TrackInfoFetch { let model = track::Info::default() .with_timescale(info.timescale) .with_max_age(info.max_age) - .with_priority(info.priority); + .with_priority(info.priority) + .with_refresh(info.refresh); return Poll::Ready(Ok((model, HeldTrack(stream)))); } } @@ -5792,6 +5852,7 @@ struct ServeLoop { /// through the producer's aggregate (including the resume floor after a source /// change). serving: track::Producer, + largest: Option, /// Watches `serving`'s subscribers, to release the copy once nobody reads it. demand: track::Demand, /// Serve on-demand fetches of uncached groups from this session. @@ -6000,6 +6061,7 @@ impl ServeLoop { let serving = request.accept(info); serving.received(); Self { + largest: None, demand: serving.demand(), serving, dynamic, @@ -6125,6 +6187,29 @@ impl ServeLoop { Poll::Pending => {} } + // The wanted group is subscription state: an update announces each new one + // past our largest, and every later update restates it. Joins asking for + // the same group coalesce into that one update. + if serve.subscriber.version.has_refresh() { + if let Poll::Ready(Some(largest)) = self.serving.poll_largest(waiter) { + self.largest = Some(largest.group); + } + let _ = self.demand.poll_wanted_changed(waiter); + if let Sub::Active(active) = &mut self.sub + && let Some(largest) = self.largest + && let Some(wanted) = self.demand.wanted().filter(|wanted| *wanted > largest) + && active.wanted != Some(wanted) + { + active.wanted = Some(wanted); + if let Err(err) = + buffer_update(active, self.serving.subscription().and_then(|sub| sub.end())) + { + return Poll::Ready(ServeEnd::GiveBack(err)); + } + continue; + } + } + // (2) In-flight fetches; completions just retire. The demand is settled, // so a held fetch with no feed open is a miss. let _ = self.fetches.poll(waiter); diff --git a/rs/moq-net/src/lite/track.rs b/rs/moq-net/src/lite/track.rs index bb8d5d4c706..a2a5f5ca5f1 100644 --- a/rs/moq-net/src/lite/track.rs +++ b/rs/moq-net/src/lite/track.rs @@ -59,6 +59,8 @@ impl Message for Track<'_> { /// Lite05+ only. #[derive(Clone, Debug)] pub struct TrackInfo { + /// Refresh byte ratio, advertised on lite-07 only. + pub refresh: Option, /// The publisher's tie-break priority for this track. pub priority: u8, /// Publisher Max Age: an upper bound on how long the publisher caches a @@ -89,8 +91,19 @@ impl Message for TrackInfo { scale => Some(Timescale::new(scale).map_err(|_| DecodeError::InvalidValue)?), }; + let refresh = match version.has_refresh() { + true => r + .varint()? + .checked_sub(1) + .map(u32::try_from) + .transpose() + .map_err(|_| DecodeError::InvalidValue)?, + false => None, + }; + Ok(Self { priority, + refresh, max_age, timescale, }) @@ -111,6 +124,9 @@ impl Message for TrackInfo { }; w.varint(encoded)?; w.varint(version.wire_timescale(self.timescale).map_or(0, u64::from))?; + if version.has_refresh() { + w.varint(self.refresh.map_or(0, |ratio| u64::from(ratio) + 1))?; + } Ok(()) } } @@ -121,6 +137,7 @@ mod test { fn info_sample() -> TrackInfo { TrackInfo { + refresh: None, priority: 7, max_age: Some(Duration::from_millis(2000)), timescale: Some(Timescale::MICRO), @@ -135,6 +152,20 @@ mod test { crate::coding::decode_buf(&mut slice, version, TrackInfo::decode_msg).unwrap() } + #[test] + fn refresh_is_lite07_only() { + for version in [Version::Lite05, Version::Lite06, Version::Lite07] { + for ratio in [None, Some(0), Some(1), Some(u32::MAX)] { + let info = TrackInfo { + refresh: ratio, + ..info_sample() + }; + let expected = if version.has_refresh() { ratio } else { None }; + assert_eq!(info_roundtrip(version, &info).refresh, expected); + } + } + } + #[test] fn optional_max_age_roundtrips() { for version in [Version::Lite05, Version::Lite06, Version::Lite07] { @@ -208,6 +239,7 @@ mod test { fn track_info_defaults_match_cross_language_wire_bytes() { let info = crate::track::Info::default(); let info = TrackInfo { + refresh: None, priority: info.priority, max_age: info.max_age, // The default track is untimed, which lite-05 declares as milliseconds. @@ -276,6 +308,7 @@ mod test { #[test] fn track_info_roundtrips_varint_and_priority_bounds() { let info = TrackInfo { + refresh: None, priority: 255, max_age: None, timescale: Some(Timescale::new((1u64 << 62) - 1).unwrap()), @@ -289,6 +322,7 @@ mod test { #[test] fn track_info_encodes_sub_millisecond_max_age_as_zero() { let info = TrackInfo { + refresh: None, priority: 0, max_age: Some(Duration::from_nanos(999_999)), timescale: Some(Timescale::MILLI), @@ -301,6 +335,7 @@ mod test { fn track_info_encode_rejects_max_age_past_varint() { // Lite-07 varints carry the whole u64, and the age goes on the wire plus one. let info = TrackInfo { + refresh: None, priority: 7, max_age: Some(Duration::from_millis(u64::MAX)), timescale: Some(Timescale::MILLI), diff --git a/rs/moq-net/src/lite/version.rs b/rs/moq-net/src/lite/version.rs index 59c749088a9..37ae7bb9637 100644 --- a/rs/moq-net/src/lite/version.rs +++ b/rs/moq-net/src/lite/version.rs @@ -285,6 +285,18 @@ impl Version { } } + /// Whether TRACK_INFO carries the refresh ratio and SUBSCRIBE_UPDATE a wanted group, + /// so a join at any hop reaches the publisher. Added in lite-07; older peers see a + /// track that never refreshes. + #[allow(clippy::match_like_matches_macro)] + pub(crate) fn has_refresh(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 discovery streams end their initial set with SYNCED rather than a count. #[allow(clippy::match_like_matches_macro)] pub fn has_synced(self) -> bool { diff --git a/rs/moq-net/src/test_interop.rs b/rs/moq-net/src/test_interop.rs index 0911b3be94a..fdc8c2116f9 100644 --- a/rs/moq-net/src/test_interop.rs +++ b/rs/moq-net/src/test_interop.rs @@ -168,6 +168,7 @@ fn lite_varint_interop() { // An untimed track: zero on lite-07, milliseconds before it. let track_info = lite::TrackInfo { + refresh: None, priority: 1, max_age: None, timescale: None, diff --git a/rs/moq-net/tests/integration/main.rs b/rs/moq-net/tests/integration/main.rs index bddf638a904..b9578657a54 100644 --- a/rs/moq-net/tests/integration/main.rs +++ b/rs/moq-net/tests/integration/main.rs @@ -37,6 +37,7 @@ mod multi_cdn; mod partial_group; mod quiet_catalog; mod received_rewind; +mod refresh; mod rejoin; mod replacement; mod request_caps; diff --git a/rs/moq-net/tests/integration/refresh.rs b/rs/moq-net/tests/integration/refresh.rs new file mode 100644 index 00000000000..2c11334e23f --- /dev/null +++ b/rs/moq-net/tests/integration/refresh.rs @@ -0,0 +1,70 @@ +#![cfg(feature = "async")] + +//! Refresh joins traverse two real protocol hops, judged independently from each cache. +use crate::support::harness::{MockConnectOptions, connect_mock, spawn}; +use moq_net::{Hop, Version, origin, track}; +use std::time::Duration; + +fn origin(hop: u64) -> origin::Producer { + let (origin, driver) = origin::Producer::new(origin::Config::new(Hop::new(hop).unwrap())); + spawn(driver); + origin +} + +#[moq_clock::test] +async fn ratio_joins_cross_two_relays() { + for name in ["moq-lite-06", "moq-lite-07-wip"] { + let version: Version = name.parse().unwrap(); + let source = origin(1); + let a = origin(2); + let b = origin(3); + let broadcast = source.create_broadcast("room").unwrap(); + let producer = broadcast + .create_track("data", track::Info::default().with_refresh(1)) + .unwrap(); + broadcast.announce(Default::default()).unwrap(); + let mut links = Vec::new(); + for (upstream, downstream) in [(&source, &a), (&a, &b)] { + let mut options = MockConnectOptions::new(version); + options.server_publish = Some(upstream.consume()); + options.client_subscribe = Some(downstream.clone()); + links.push(connect_mock(options).await); + } + b.consume().routed("room").await.unwrap(); + let remote = b.consume().request_broadcast("room", None).await.unwrap(); + let remote = remote.track("data").unwrap(); + let mut baseline = remote.subscribe(None).await.unwrap(); + assert_eq!(baseline.info().refresh, (name == "moq-lite-07-wip").then_some(1)); + crate::support::harness::subscribed(&producer).await; + let mut group = producer.append_group().unwrap(); + group.write_frame(None, &b"key"[..]).unwrap(); + group.write_frame(None, &b"abc"[..]).unwrap(); + let mut received = baseline.recv_group().await.unwrap().unwrap(); + assert_eq!(received.read_frame().await.unwrap().unwrap().payload.len(), 3); + assert_eq!(received.read_frame().await.unwrap().unwrap().payload.len(), 3); + let mut under = remote.subscribe(None).await.unwrap(); + let _under_group = under.recv_group().await.unwrap().unwrap(); + assert_eq!(producer.demand().wanted(), Some(0), "ratio equality does not refresh"); + group.write_frame(None, &b"d"[..]).unwrap(); + assert_eq!(received.read_frame().await.unwrap().unwrap().payload.len(), 1); + let mut joins = Vec::new(); + for _ in 0..8 { + let mut join = remote.subscribe(None).await.unwrap(); + let _group = join.recv_group().await.unwrap().unwrap(); + joins.push(join); + } + if name == "moq-lite-07-wip" { + let mut demand = producer.demand(); + moq_clock::timeout(Duration::from_secs(1), async { + while demand.wanted_changed().await.unwrap() != Some(1) {} + }) + .await + .unwrap(); + } else { + // Drain runnable protocol tasks on simulated time, without a wall-clock sleep. + moq_clock::sleep(Duration::from_millis(1)).await; + assert_eq!(producer.demand().wanted(), Some(0)); + } + drop((joins, under, received, baseline, group, links)); + } +} diff --git a/sh/gh/nightly.sh b/sh/gh/nightly.sh index 6e5db513b02..357ccece72f 100755 --- a/sh/gh/nightly.sh +++ b/sh/gh/nightly.sh @@ -102,7 +102,7 @@ case "$1" in done ;; js) - for benchmark in broadcasts request-ids requests forward reader frames varint lite-varint track resume interests priority subscribe-drop; do + for benchmark in broadcasts request-ids requests forward reader frames varint lite-varint track resume interests priority subscribe-drop refresh; do javascript "$benchmark" just js bench "$benchmark" done javascript catalog just js catalog-bench