Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 29 additions & 1 deletion js/net/src/ietf/subscriber.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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);
Expand All @@ -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 };
}
Expand Down Expand Up @@ -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();
});
27 changes: 27 additions & 0 deletions js/net/src/ietf/subscriber.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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 {
Expand Down Expand Up @@ -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 = {
Expand Down Expand Up @@ -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 {
Expand Down
50 changes: 49 additions & 1 deletion js/net/src/track.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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 {
/**
Expand All @@ -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.
Expand All @@ -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> = {}): 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),
};
}

Expand Down