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), }; }