From 4c387527c8babab3db04b680c339770abef6ca8c Mon Sep 17 00:00:00 2001 From: HangPlayerEngineer Date: Thu, 8 Oct 2026 18:30:24 +0000 Subject: [PATCH] feat(moq-net): carry SUBSCRIBE_OK's Largest Location to the consumer SubscribeOk.largest is decoded off the wire and then dropped: outside its own codec and tests it has no readers, and `request.accept(...)` carries no location, so nothing downstream can observe it. It is the only thing that can answer "where is the publisher's live edge" before the first group arrives, which is what a NEXT_GROUP_START anchor needs. `Subscriber.largest()` cannot: its own doc says it reads the groups buffered for this subscriber, so it is undefined before anything arrives and again after eviction -- exactly the window the anchor asks about. Surface it as `Info.publisherLargest`. Three notes on the shape: - Not named `largest`. `Subscriber.largest()` already exists and means the weaker buffered-edge value; a caller reaching for the wrong one would anchor against undefined and silently fall back, which never raises. - A snapshot, not a live edge: fixed at accept time and never updated, which is what lets it sit beside the other accept-time properties. The "maps 1:1 onto TRACK_INFO" sentence on Info is amended to name it as the exception -- the moq-lite path has no equivalent wire field and leaves it unset, where every other Info field is defaulted. - Not a Location. `PublishedLocation` is {group, object} because the second component is an Object ID, not a frame index; a publisher may number its objects with gaps, so this does not count what precedes it. Both wire fields are u62 and the API carries numbers, so a value past 2^53 is dropped with a debug log rather than rounded: `undefined` already means "the publisher did not say", which every caller handles, and a silently wrong anchor does not. Two tests. The first asserts the value reaches the consumer before any group is handled AND that `largest()` is still undefined at that moment -- asserting both together is what pins the distinction. The second pins that an omitted field stays distinguishable from a stated one. Dropping the single line from accept() turns the first red and leaves the second green. --- js/net/src/ietf/subscriber.test.ts | 30 +++++++++++++++++- js/net/src/ietf/subscriber.ts | 27 ++++++++++++++++ js/net/src/track.ts | 50 +++++++++++++++++++++++++++++- 3 files changed, 105 insertions(+), 2 deletions(-) diff --git a/js/net/src/ietf/subscriber.test.ts b/js/net/src/ietf/subscriber.test.ts index e67b56d016a..eb0fa5a6509 100644 --- a/js/net/src/ietf/subscriber.test.ts +++ b/js/net/src/ietf/subscriber.test.ts @@ -946,9 +946,11 @@ function encodeObjects(deltas: number[]): Uint8Array { async function subscribeTrack({ version = VERSION, properties = {}, + largest, }: { version?: IetfVersion; properties?: Properties; + largest?: { groupId: bigint; objectId: bigint }; } = {}): Promise<{ subscriber: Subscriber; track: track.Subscriber }> { const pair = createMockTransportPair(version === Version.DRAFT_16 ? ALPN.DRAFT_16 : ALPN.DRAFT_19); const session = new NativeSession(pair.server, version, true); @@ -964,7 +966,10 @@ async function subscribeTrack({ expect(await peer.reader.u53()).toBe(Subscribe.id); const request = await Subscribe.decode(peer.reader, version); await peer.writer.u53(SubscribeOk.id); - await new SubscribeOk({ requestId: request.requestId, trackAlias: ALIAS, properties }).encode(peer.writer, version); + await new SubscribeOk({ requestId: request.requestId, trackAlias: ALIAS, largest, properties }).encode( + peer.writer, + version, + ); return { subscriber, track }; } @@ -1681,3 +1686,26 @@ test("an object datagram is a datagram group", async () => { ).toBeInstanceOf(ProtocolViolation); track.close(); }); + +/** + * SUBSCRIBE_OK's Largest Location is the only thing that can answer "where is the publisher's + * live edge" before the first group arrives. Asserting `largest()` is still undefined in the + * same test is the point: the two are different values, and this is exactly the window where + * the subscriber's own buffered edge cannot answer. + */ +test("the publisher's largest location reaches the consumer before the first group", async () => { + const { track } = await subscribeTrack({ largest: { groupId: 42n, objectId: 7n } }); + + expect((await track.info()).publisherLargest).toEqual({ group: 42, object: 7 }); + // Nothing has arrived, so the subscriber's own buffered edge still cannot answer this. + expect(track.largest()).toBeUndefined(); + + track.close(); +}); + +/** A publisher with no content omits the field, and "not stated" stays distinguishable. */ +test("a SUBSCRIBE_OK with no largest location leaves it unset", async () => { + const { track } = await subscribeTrack(); + expect((await track.info()).publisherLargest).toBeUndefined(); + track.close(); +}); diff --git a/js/net/src/ietf/subscriber.ts b/js/net/src/ietf/subscriber.ts index 76d775fb261..83ace05666a 100644 --- a/js/net/src/ietf/subscriber.ts +++ b/js/net/src/ietf/subscriber.ts @@ -30,6 +30,7 @@ import * as Cluster from "./cluster.ts"; import { ObjectDatagram } from "./datagram.ts"; import { requestReason, toRequestCode } from "./error.ts"; import { decodeObjectTime, Frame, type Group as GroupMessage, hasFirstObjectBit, ObjectIdGap } from "./object.ts"; +import type { MessageLocation } from "./parameters.ts"; import { fromWire, toWire } from "./priority.ts"; import { type Publish, PublishDone, PublishError, publishDoneClean } from "./publish.ts"; import { @@ -62,6 +63,31 @@ const SUBSCRIBE_OK_TIMEOUT_MS = 10_000; // candidate outranks it, while the route stays selectable as the last path. Matches Rust // Cost::DRAIN: cost is the whole mechanism, not a separate state. const DRAIN_COST: Cost = 2n ** 62n - 1n; +/** + * SUBSCRIBE_OK's Largest Location, as the track's `largest` Info. + * + * The draft requires it once the publisher has content, and it is the only thing that can + * answer "where is the live edge" before the first group arrives: the subscriber's own + * `Subscriber.largest()` is derived from what it has buffered, so it is `undefined` until then. + * + * Both fields are u62 on the wire and the API carries them as numbers. A publisher past + * 2^53 groups is reporting a position no sequence number here can hold, so drop the field + * rather than surface a rounded one: `undefined` says "not stated", which is a value the + * caller already handles, and a silently wrong anchor is not. + */ +function largestLocation(largest: MessageLocation | undefined): track.PublishedLocation | undefined { + if (largest === undefined) return undefined; + + const group = Number(largest.groupId); + const object = Number(largest.objectId); + if (!Number.isSafeInteger(group) || !Number.isSafeInteger(object)) { + console.debug( + `ignoring a largest location past the safe integer range: ${largest.groupId}/${largest.objectId}`, + ); + return undefined; + } + return { group, object }; +} // A live subscription, as the track alias its data streams name resolves to. type Subscription = { @@ -869,6 +895,7 @@ export class Subscriber { timescale: ok.properties.timescale, priority: fromWire(ok.properties.priority ?? 128), maxAge: maxCacheDuration === undefined ? undefined : Milli(Number(maxCacheDuration)), + publisherLargest: largestLocation(ok.largest), }); try { diff --git a/js/net/src/track.ts b/js/net/src/track.ts index fcb950141e4..22f290c95e7 100644 --- a/js/net/src/track.ts +++ b/js/net/src/track.ts @@ -49,12 +49,26 @@ export interface Location { frame: number; } +/** + * A position the publisher states it has published to, as a group and an Object ID. + * + * Deliberately not a {@link Location}: `object` is an Object ID, not a frame index. A + * publisher may number its objects with gaps, so this does not count what precedes it. + */ +export interface PublishedLocation { + /** The group's sequence number within the track. */ + group: number; + /** The Object ID within that group. */ + object: number; +} + /** * A track's immutable publisher properties, fixed for the lifetime of the track. * * A producer declares these once (via {@link Request.accept} or * {@link Producer.accept}); a consumer awaits them via {@link Subscriber.info} - * (resolved from the wire TRACK_INFO on lite-05+). They map 1:1 onto TRACK_INFO. + * (resolved from the wire TRACK_INFO on lite-05+). They map 1:1 onto TRACK_INFO, except + * {@link Info.publisherLargest}, which only the moq-transport path carries. */ export interface Info { /** @@ -80,6 +94,26 @@ export interface Info { maxAge?: Milli; /** Tie-break priority between subscriptions of equal subscriber priority (`0..=255`, higher first). Defaults to `127`. */ priority: number; + /** + * Where the publisher had published to **at the moment it accepted this subscription**, + * or `undefined` when it did not say. + * + * A snapshot, not a live edge: it is fixed at accept time and is never updated, which is + * what lets it sit beside the other accept-time properties here. Read it as "where the + * track was when I subscribed", and not as "where the track is now" — the publisher will + * have moved past it by the time anything reads this. + * + * **Not {@link Subscriber.largest}, and deliberately not named the same.** That one is the + * newest frame in *this subscriber's own buffer*: it reads `undefined` until something + * arrives and again once the newest group is evicted. A `NEXT_GROUP_START` anchor needs + * an answer in exactly the window where that returns `undefined`, so a caller who reached + * for the wrong one would anchor against nothing and silently fall back. + * + * Carried on the moq-transport path from SUBSCRIBE_OK's Largest Location (draft-20 + * 8.4.2). The moq-lite path has no equivalent wire field and leaves it unset — so unlike + * the fields above, this one is absent on a lite session rather than defaulted. + */ + publisherLargest?: PublishedLocation; } // Normalize a duration for the wire, which carries it as an unsigned varint. @@ -106,12 +140,26 @@ function priorityByte(value: number): number { return value; } +/** Validate a publisher-stated Location, which arrives off the wire as two varints. */ +function publishedLocation({ group, object }: PublishedLocation): PublishedLocation { + for (const [name, value] of [ + ["group", group], + ["object", object], + ] as const) { + if (!Number.isSafeInteger(value) || value < 0) { + throw new RangeError(`publisherLargest ${name} must be a non-negative safe integer: ${value}`); + } + } + return { group, object }; +} + /** Fill in any unset {@link Info} fields with their defaults. */ export function infoDefaults(info: Partial = {}): Info { return { timescale: info.timescale == null ? undefined : Timescale(info.timescale), maxAge: info.maxAge === undefined ? undefined : wireMillis("maxAge", info.maxAge), priority: priorityByte(info.priority ?? DEFAULT_PRIORITY), + publisherLargest: info.publisherLargest === undefined ? undefined : publishedLocation(info.publisherLargest), }; }