From 5bb72d90132ef2180c355d4d9bfdabb61fc6c34d Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 6 Oct 2026 23:15:40 -0700 Subject: [PATCH 1/8] quest: claim js-untimed-model From 32ba432cc1c0cb69fc6327ab83e0c3a7b8dc653e Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 6 Oct 2026 23:33:44 -0700 Subject: [PATCH 2/8] feat(js/net)!: carry untimed frames faithfully A track is timed or untimed as a whole: `Track.Info.timescale` is `null` for a track with no timeline, and a frame or datagram carries a timestamp exactly when its track has a timescale. A write that disagrees throws `TimestampMismatch` (stream code 0x39, as in Rust and the lite draft). No receive path fills in arrival time anymore. moq-lite before 05 and moq-transport without TIMESCALE (always so on drafts 14-16) deliver untimed tracks; a TIMESCALE track's object without a Timestamp is a malformed track, and an object-scope Timescale is never applied. Lite-05 and lite-06 can't declare an untimed track, so it goes out at milliseconds with send times. An untimed group is never stale, so an unfloored subscription to an untimed track starts at its latest group, while an explicit start still holds. Mirrors moq-dev/moq#4822 under the per-track decision. Co-Authored-By: Claude Opus 5.5 --- doc/lib/js/net.md | 1 + js/flate/src/snapshot/snapshot.test.ts | 2 +- js/flate/src/stream/stream.test.ts | 4 +- js/json/src/snapshot/snapshot.test.ts | 4 +- js/json/src/stream/stream.test.ts | 4 +- js/net/src/datagram.ts | 6 +- js/net/src/error.test.ts | 4 + js/net/src/error.ts | 24 +++- js/net/src/errors.ts | 1 + js/net/src/group.ts | 38 ++++-- js/net/src/ietf/object.ts | 54 +++++--- js/net/src/ietf/properties.ts | 2 +- js/net/src/ietf/publisher.ts | 51 ++++---- js/net/src/ietf/subscriber.test.ts | 67 +++++++++- js/net/src/ietf/subscriber.ts | 25 ++-- js/net/src/integration.test.ts | 8 +- js/net/src/internal.ts | 10 +- js/net/src/lite/group.test.ts | 2 +- js/net/src/lite/group.ts | 4 +- js/net/src/lite/publisher.ts | 28 ++++- js/net/src/lite/subscriber.ts | 4 +- js/net/src/lite/track.test.ts | 3 +- js/net/src/track.test.ts | 89 +++++++++++++- js/net/src/track.ts | 94 ++++++++++---- js/net/src/untimed.test.ts | 156 ++++++++++++++++++++++++ test/interop/clients/js/src/contract.ts | 1 + test/interop/lite-varint.ts | 1 + 27 files changed, 566 insertions(+), 121 deletions(-) create mode 100644 js/net/src/untimed.test.ts diff --git a/doc/lib/js/net.md b/doc/lib/js/net.md index a16b9de00c2..9c5d0734958 100644 --- a/doc/lib/js/net.md +++ b/doc/lib/js/net.md @@ -53,6 +53,7 @@ for (;;) { - **Bandwidth** (`Bandwidth.Allocator`) divides the connection's send-rate estimate by track priority, max-min fair within a tier. An idle track claims nothing. The receive side is untouched. - **Discovery** by any pattern scope (`origin.announced(scope)`, such as `room/*/chat`; default everything). A route event's `kind` says whether the route started, updated, or ended; its `prefix` is the covered prefix relative to the origin, and `captures` reports what the scope's wildcards matched when the prefix pins them. The consumer is an async iterable. `origin.broadcasts(scope)` is a live `Getter>` of the same covered prefixes for UIs that need the current set. A borrowed `Connection.origin` also exposes `dynamic(prefix, route)` for serving paths on demand. - **Publisher retention** is optional `Track.Info.maxAge`, measured against media timestamps: omission sets no limit, while zero serves only the live edge. It clamps every subscriber's max age, and stalled media does not age out merely because wall time passes. Separately, cached groups nobody writes for 30 seconds are reclaimed, except a live track's newest group, which stays replayable until the track closes. +- **Timing** is per track. `Track.Info.timescale` defaults to milliseconds; `null` declares an untimed track. A frame or datagram carries a `timestamp` exactly when its track has a timescale, and a write that disagrees throws `Error.TimestampMismatch`. Nothing fills in a time on receive: moq-lite before 05, and moq-transport without TIMESCALE (always so on drafts 14-16), deliver untimed tracks. moq-lite 05 and 06 can't declare an untimed track, so it goes out at milliseconds with each frame's send time. An untimed group is never stale, so a subscription without a `groups.start` begins at the latest group. - **Subscriptions** carry a priority, a `Time.Milli` max age measured against media timestamps, and optional `groups` bounds. Groups arrive out of order and are read frame by frame, with `Error.TooFarBehind` when a reader asks for a frame the group never held and `Error.GroupTooLarge` when a write exceeds the cache budget and aborts the group. - **Track ends**: `close()` ends a track at its live edge, while `finishAt(n)` declares the exclusive end ahead of it and still accepts the groups below. A subscriber reads the end with `final()` or awaits `finished()`. Group and datagram readers end once the live edge reaches the declared boundary, even while missing lower groups wait out the grace. The `closed` signal settles separately once every group below the end has arrived or was dropped; one reset before its header arrived is skipped after the subscription's max age on moq-lite (one second without one), or after one second on IETF. - **Datagrams** on moq-lite 05+ and fetch-by-sequence for history. `track.fetchGroup(sequence)` on moq-lite resolves when the publisher sends the first response byte or finishes an empty group. A missing group rejects the fetch with `StreamCode.NotFound`, including every concurrent caller sharing that fetch. `fetchGroup(sequence, { signal })` abandons a pending fetch with the signal's reason; the shared stream is cancelled only once every caller has left. Once resolved, close the group instead. diff --git a/js/flate/src/snapshot/snapshot.test.ts b/js/flate/src/snapshot/snapshot.test.ts index 19a68aac199..6fc50887dfd 100644 --- a/js/flate/src/snapshot/snapshot.test.ts +++ b/js/flate/src/snapshot/snapshot.test.ts @@ -147,5 +147,5 @@ test("a capture timestamp is written as the frame timestamp", async () => { producer.finish(); const frame = await (await track.subscribe().ordered().nextGroup())?.readFrame(); - expect(frame?.timestamp.as(Time.Timescale.MILLI)).toBe(1_234); + expect(frame?.timestamp?.as(Time.Timescale.MILLI)).toBe(1_234); }); diff --git a/js/flate/src/stream/stream.test.ts b/js/flate/src/stream/stream.test.ts index ebe4278cac0..fca30976201 100644 --- a/js/flate/src/stream/stream.test.ts +++ b/js/flate/src/stream/stream.test.ts @@ -194,6 +194,6 @@ test("each record keeps its capture timestamp", async () => { producer.finish(); const group = await track.subscribe().ordered().nextGroup(); - expect((await group?.readFrame())?.timestamp.as(Time.Timescale.MILLI)).toBe(1_000); - expect((await group?.readFrame())?.timestamp.as(Time.Timescale.MILLI)).toBe(2_000); + expect((await group?.readFrame())?.timestamp?.as(Time.Timescale.MILLI)).toBe(1_000); + expect((await group?.readFrame())?.timestamp?.as(Time.Timescale.MILLI)).toBe(2_000); }); diff --git a/js/json/src/snapshot/snapshot.test.ts b/js/json/src/snapshot/snapshot.test.ts index 8b2f3457c6a..e246898a694 100644 --- a/js/json/src/snapshot/snapshot.test.ts +++ b/js/json/src/snapshot/snapshot.test.ts @@ -417,6 +417,6 @@ test("a capture timestamp is written on snapshots and deltas alike", async () => producer.finish(); const group = await track.subscribe().ordered().nextGroup(); - expect((await group?.readFrame())?.timestamp.as(Time.Timescale.MILLI)).toBe(1_000); - expect((await group?.readFrame())?.timestamp.as(Time.Timescale.MILLI)).toBe(2_000); + expect((await group?.readFrame())?.timestamp?.as(Time.Timescale.MILLI)).toBe(1_000); + expect((await group?.readFrame())?.timestamp?.as(Time.Timescale.MILLI)).toBe(2_000); }); diff --git a/js/json/src/stream/stream.test.ts b/js/json/src/stream/stream.test.ts index 1e14c3cb2a9..24ec954e142 100644 --- a/js/json/src/stream/stream.test.ts +++ b/js/json/src/stream/stream.test.ts @@ -158,6 +158,6 @@ test("each record keeps its capture timestamp", async () => { producer.finish(); const group = await track.subscribe().ordered().nextGroup(); - expect((await group?.readFrame())?.timestamp.as(Time.Timescale.MILLI)).toBe(1_000); - expect((await group?.readFrame())?.timestamp.as(Time.Timescale.MILLI)).toBe(2_000); + expect((await group?.readFrame())?.timestamp?.as(Time.Timescale.MILLI)).toBe(1_000); + expect((await group?.readFrame())?.timestamp?.as(Time.Timescale.MILLI)).toBe(2_000); }); diff --git a/js/net/src/datagram.ts b/js/net/src/datagram.ts index 16b26841c5c..4e20e5c3cf3 100644 --- a/js/net/src/datagram.ts +++ b/js/net/src/datagram.ts @@ -6,7 +6,7 @@ import type { Timestamp } from "./time.ts"; /** - * A single unreliable payload on a track: a sequence number, a presentation timestamp, and the bytes. + * A single unreliable payload on a track: a sequence number, a presentation timestamp on a timed track, and the bytes. * * Unlike a {@link Group} (an ordered stream of frames over a QUIC stream), a datagram is one * self-contained payload carried in a single QUIC datagram: best-effort, unordered, never @@ -16,8 +16,8 @@ import type { Timestamp } from "./time.ts"; export interface Datagram { /** Per-track sequence number, shared with the group namespace. */ sequence: number; - /** Presentation timestamp in the track's timescale. */ - timestamp: Timestamp; + /** Presentation timestamp, present exactly when the track has a timescale. */ + timestamp?: Timestamp; /** The datagram payload. */ payload: Uint8Array; } diff --git a/js/net/src/error.test.ts b/js/net/src/error.test.ts index a12f12144d8..210d39efa71 100644 --- a/js/net/src/error.test.ts +++ b/js/net/src/error.test.ts @@ -14,6 +14,7 @@ import { SessionError, StreamCode, StreamError, + TimestampMismatch, toStreamCode, toTransport, } from "./error.ts"; @@ -228,6 +229,7 @@ test("the code tables match the spec", () => { StreamCode.Evicted, StreamCode.Unroutable, StreamCode.FrameTooLarge, + StreamCode.TimestampMismatch, ]; for (const code of Object.values(StreamCode)) { if (assignedLite.includes(code)) { @@ -245,6 +247,7 @@ test("the code tables match the spec", () => { expect(Number(StreamCode.Evicted)).toBe(0x35); expect(Number(StreamCode.Unroutable)).toBe(0x36); expect(Number(StreamCode.FrameTooLarge)).toBe(0x38); + expect(Number(StreamCode.TimestampMismatch)).toBe(0x39); // The spaces are disjoint: 0 ends a session cleanly but fails a stream. expect(Number(SessionCode.Cancel)).not.toBe(Number(StreamCode.Cancel)); @@ -379,6 +382,7 @@ test("toStreamCode and fromTransport agree on what a code means", () => { expect(new FrameTooLarge()).toBeInstanceOf(StreamError); expect(fromTransport(toTransport(StreamCode.GroupTooLarge, "overflow"))).toBeInstanceOf(GroupTooLarge); expect(new GroupTooLarge()).toBeInstanceOf(StreamError); + expect(fromTransport(toTransport(StreamCode.TimestampMismatch, "mismatch"))).toBeInstanceOf(TimestampMismatch); // The values the four codes were sent from before they were assigned stay reserved: // a peer still emitting one is not read as anything. diff --git a/js/net/src/error.ts b/js/net/src/error.ts index 91873b21394..6c103ecfd72 100644 --- a/js/net/src/error.ts +++ b/js/net/src/error.ts @@ -96,6 +96,8 @@ export const StreamCode = Object.freeze( Unroutable: 0x36 as StreamCode, /** A group grew past its cache budget and was aborted. */ GroupTooLarge: 0x32 as StreamCode, + /** A frame's timedness or timestamp doesn't match its track's timescale. */ + TimestampMismatch: 0x39 as StreamCode, } as const), ); @@ -151,7 +153,7 @@ export interface StreamOptions { * This surfaces on every transport, so catch this type rather than feature-detecting * `WebTransportError`, which a non-browser runtime never defines and the WebSocket fallback * never throws. Local conditions with a code of their own subclass it ({@link TooFarBehind}, - * {@link FrameTooLarge}, {@link GroupTooLarge}, {@link NotFound}), so the same `code` check catches a condition + * {@link FrameTooLarge}, {@link GroupTooLarge}, {@link TimestampMismatch}, {@link NotFound}), so the same `code` check catches a condition * whether it was raised here or reported by the peer. * * ```ts @@ -234,6 +236,25 @@ export class GroupTooLarge extends Stream { } } +/** + * A frame's timedness doesn't match its track: a timestamp on a track with no timescale, or + * none on a track that has one. + * + * Raised locally by a frame or datagram write, and decoded from a moq-lite peer's + * `TIMESTAMP_MISMATCH` reset. Mirrors the Rust `Error::TimestampMismatch`. + * + * @public + */ +export class TimestampMismatch extends Stream { + constructor(options?: { cause?: unknown }) { + super(StreamCode.TimestampMismatch, { + ...options, + message: "frame timestamp doesn't match track timescale", + }); + this.name = "TimestampMismatch"; + } +} + /** * The requested broadcast or track is not served here. * @@ -376,6 +397,7 @@ export function fromTransport(err: unknown, options?: TransportErrorOptions): Er if (code === StreamCode.TooFarBehind) return new TooFarBehind({ cause: err }); if (code === StreamCode.FrameTooLarge) return new FrameTooLarge({ cause: err }); if (code === StreamCode.GroupTooLarge) return new GroupTooLarge({ cause: err }); + if (code === StreamCode.TimestampMismatch) return new TimestampMismatch({ cause: err }); return new Stream(code, { cause: err }); } diff --git a/js/net/src/errors.ts b/js/net/src/errors.ts index d84bf02d1e9..09ffa12816c 100644 --- a/js/net/src/errors.ts +++ b/js/net/src/errors.ts @@ -12,5 +12,6 @@ export { Session, Stream, type StreamOptions, + TimestampMismatch, TooFarBehind, } from "./error.ts"; diff --git a/js/net/src/group.ts b/js/net/src/group.ts index b018a690891..90b5073a279 100644 --- a/js/net/src/group.ts +++ b/js/net/src/group.ts @@ -4,7 +4,7 @@ * @module */ import { type Dispose, type GetPromise, type Getter, Once, Signal } from "@moq/signals"; -import { FrameTooLarge, GroupTooLarge, TooFarBehind } from "./error.ts"; +import { FrameTooLarge, GroupTooLarge, TimestampMismatch, TooFarBehind } from "./error.ts"; import { hooks, type ReadGroupFrame } from "./internal.ts"; import { Timestamp } from "./time.ts"; @@ -15,7 +15,7 @@ export const MAX_GROUP_CACHE_BYTES = 32 * 1024 * 1024; export const MAX_GROUP_FRAMES = 8192; /** - * A frame buffered in a group: its presentation {@link Timestamp} and payload bytes. + * A frame buffered in a group: its presentation {@link Timestamp}, if any, and payload bytes. * * The timestamp carries its own scale, so a track can pick its units; the wire layer * converts it into the track's negotiated timescale. @@ -24,10 +24,11 @@ export interface Frame { /** The frame payload. */ payload: Uint8Array; /** - * Presentation timestamp. Required: for a payload with no presentation time of its own - * (a JSON catalog, control state) pass {@link Timestamp.now} explicitly. + * Presentation timestamp, present exactly when the track has a timescale. A frame on a + * track without one is untimed and omits it; a write that disagrees with its track is + * refused with {@link TimestampMismatch}. */ - timestamp: Timestamp; + timestamp?: Timestamp; } /** Options for a sequence-aware frame read. */ @@ -59,7 +60,11 @@ class GroupState { start = 0; cacheBytes = 0; - // The first frame's timestamp, retained after reads. + // Whether the owning track has a timescale, so every frame must carry a timestamp (true) + // or none may (false). Undefined for a group no track has claimed yet, which takes either. + timed?: boolean; + // The first frame's timestamp, retained after reads. Media time only: an untimed group + // never has one, so it says nothing about whether a frame was written. timestamp?: Timestamp; // The newest frame's timestamp: where a reader that has taken every frame sits. latest?: Timestamp; @@ -69,6 +74,11 @@ class GroupState { } } +// Refuse a frame whose timedness disagrees with the track's. +function checkTimed(timed: boolean | undefined, frame: Frame) { + if (timed !== undefined && timed !== (frame.timestamp !== undefined)) throw new TimestampMismatch(); +} + function appendFrame(state: GroupState, frame: Frame) { if (state.closed.peek() !== undefined) throw new Error("group is closed"); @@ -147,6 +157,15 @@ export class Producer { this.#demand = makeDemand(sequence, this.#used, this.#state); } + static { + hooks.bindGroupTimed = (group, timed) => { + const state = group.#state; + if (state.timed === timed) return; + for (const frame of state.frames.peek()) checkTimed(timed, frame); + state.timed = timed; + }; + } + /** * When the group was created or last written, in `performance.now()` milliseconds. * @@ -224,6 +243,7 @@ export class Producer { // accepting it would report success for a write nothing can ever read. Rust rejects // it up front with `Error::FrameTooLarge`; do the same rather than silently dropping it. if (frame.payload.byteLength > MAX_GROUP_CACHE_BYTES) throw new FrameTooLarge(); + checkTimed(this.#state.timed, frame); if ( this.#state.total.peek() >= MAX_GROUP_FRAMES || this.#state.cacheBytes + frame.payload.byteLength > MAX_GROUP_CACHE_BYTES @@ -252,17 +272,17 @@ export class Producer { } } - /** Write a string as a single UTF-8 encoded frame, stamped with {@link Timestamp.now}. */ + /** Write a string as a single UTF-8 encoded frame, stamped with {@link Timestamp.now}, so the track must be timed. */ writeString(str: string) { this.writeFrame({ payload: new TextEncoder().encode(str), timestamp: Timestamp.now() }); } - /** Write a value as a single JSON-encoded frame, stamped with {@link Timestamp.now}. */ + /** Write a value as a single JSON-encoded frame, stamped with {@link Timestamp.now}, so the track must be timed. */ writeJson(json: unknown) { this.writeString(JSON.stringify(json)); } - /** Write a boolean as a single one-byte frame, stamped with {@link Timestamp.now}. */ + /** Write a boolean as a single one-byte frame, stamped with {@link Timestamp.now}, so the track must be timed. */ writeBool(bool: boolean) { this.writeFrame({ payload: new Uint8Array([bool ? 1 : 0]), timestamp: Timestamp.now() }); } diff --git a/js/net/src/ietf/object.ts b/js/net/src/ietf/object.ts index 769c9332526..1fa65814db7 100644 --- a/js/net/src/ietf/object.ts +++ b/js/net/src/ietf/object.ts @@ -1,6 +1,6 @@ import { ProtocolViolation, StreamCode, Stream as StreamError } from "../error.ts"; import { asIetf, type Cursor, type Reader, Writer } from "../stream.ts"; -import { Timescale, Timestamp } from "../time.ts"; +import { type Timescale, Timestamp } from "../time.ts"; import { type IetfVersion, Version } from "./version.ts"; // Implementation limit for object extension blocks, independent of the IETF draft. @@ -9,8 +9,8 @@ const MAX_OBJECT_EXTENSIONS = 64 * 1024; const GROUP_END = 0x03; const END_OF_TRACK = 0x04; -// MOQ Object Property ids, shared with draft-ietf-moq-loc-04. -const PROP_TIMESCALE = 0x08n; +// MOQ Object Property ids, shared with draft-ietf-moq-loc-04. An object-scope Timescale +// (0x08) is never applied: a track's timeline is its TIMESCALE Track Property alone. const PROP_TIMESTAMP = 0x10n; // The Timestamp id from draft-ietf-moq-loc-03, accepted on decode only. Draft-03's @@ -67,12 +67,13 @@ async function encodeObjectTime( await w.u62(BigInt(value)); } +// Without units (`timescale` undefined) there is no Timestamp to write, even if the frame has one. async function encodeObjectExtensions( timestamp: Timestamp | undefined, - timescale: Timescale, + timescale: Timescale | undefined, version: IetfVersion, ): Promise { - if (timestamp === undefined) { + if (timestamp === undefined || timescale === undefined) { return new Uint8Array(); } @@ -101,7 +102,6 @@ async function encodeObjectExtensions( function decodeObjectTime(c: Cursor, timescale: Timescale): Timestamp | undefined { let timestamp: bigint | undefined; - let overrideScale: bigint | undefined; let prevType = 0n; let first = true; @@ -115,8 +115,6 @@ function decodeObjectTime(c: Cursor, timescale: Timescale): Timestamp | undefine const value = c.u62(); if (id === PROP_TIMESTAMP || id === PROP_TIMESTAMP_DRAFT03) { timestamp = value; - } else if (id === PROP_TIMESCALE) { - overrideScale = value; } } else { c.read(c.u53()); @@ -127,8 +125,7 @@ function decodeObjectTime(c: Cursor, timescale: Timescale): Timestamp | undefine return undefined; } - // An object-scope Timescale (which LOC permits) overrides the track's for this object. - return new Timestamp(Number(timestamp), overrideScale !== undefined ? Timescale(Number(overrideScale)) : timescale); + return new Timestamp(Number(timestamp), timescale); } export interface GroupFlags { @@ -277,10 +274,18 @@ export class Frame { /** * Encode this frame using the group flags and negotiated IETF version. * - * `idDelta` is the first object's absolute Object ID and zero for every later one, so a - * group whose head was trimmed by a filter still puts the true numbering on the wire. + * The timestamp goes out in `timescale`, the units the track declared, and not at all when + * it declared none. `idDelta` is the first object's absolute Object ID and zero for every + * later one, so a group whose head was trimmed by a filter still puts the true numbering + * on the wire. */ - async encode(w: Writer, flags: GroupFlags, timescale: Timescale, version: IetfVersion, idDelta = 0): Promise { + async encode( + w: Writer, + flags: GroupFlags, + timescale: Timescale | undefined, + version: IetfVersion, + idDelta = 0, + ): Promise { await w.u53(idDelta); if (flags.hasExtensions) { @@ -323,8 +328,8 @@ export class Frame { if (extensionsLength > MAX_OBJECT_EXTENSIONS) { throw new StreamError(StreamCode.MalformedTrack, { message: "object extensions exceed 64 KiB" }); } - // A track that declared no timescale opted out of timestamps, so its objects - // are stamped on arrival even if one carries a Timestamp we cannot interpret. + // A track that declared no timescale is untimed, so its objects stay untimed even + // if one carries a Timestamp: there are no units to read it in. if (timescale !== undefined) { timestamp = c.exact(extensionsLength, (e) => decodeObjectTime(e, timescale)); } else { @@ -392,23 +397,32 @@ export class FetchFrame { this.timestamp = timestamp; } - /** Encode this object at `position`, stamping it in the track's timescale. */ - async encode(w: Writer, position: FetchPosition, timescale: Timescale, version: IetfVersion): Promise { + /** + * Encode this object at `position`, stamping it in the track's timescale, or not at all + * when the track declared none. + */ + async encode( + w: Writer, + position: FetchPosition, + timescale: Timescale | undefined, + version: IetfVersion, + ): Promise { + const stamped = this.timestamp !== undefined && timescale !== undefined; if (position.first) { // Include the priority too: "same as the prior object" has no prior to refer to. - const properties = this.timestamp !== undefined ? FETCH_PROPERTIES : 0; + const properties = stamped ? FETCH_PROPERTIES : 0; await w.u53(FETCH_GROUP_ID | FETCH_OBJECT_ID | FETCH_PRIORITY | properties); await w.u53(position.group); await w.u53(position.object); await w.u8(0); } else { // Same group and priority; the Object ID is the prior one plus one. - await w.u53(this.timestamp !== undefined ? FETCH_PROPERTIES : 0); + await w.u53(stamped ? FETCH_PROPERTIES : 0); } // Omitted entirely rather than written empty when the object carries no timestamp: // the track declared no units, so there is no property to send. - if (this.timestamp !== undefined) { + if (stamped) { const extensions = await encodeObjectExtensions(this.timestamp, timescale, version); await w.u53(extensions.byteLength); await w.write(extensions); diff --git a/js/net/src/ietf/properties.ts b/js/net/src/ietf/properties.ts index 88d7e35f871..35829832178 100644 --- a/js/net/src/ietf/properties.ts +++ b/js/net/src/ietf/properties.ts @@ -27,7 +27,7 @@ export interface Properties { /// The track's Timescale, which declares the units of every object Timestamp on it. /// - /// `undefined` declares no timeline, so the subscriber times objects by arrival. + /// `undefined` declares no timeline, so the track and its objects are untimed. timescale?: Timescale; /// Publisher priority for a group header without its priority flag. The wire default is 128. diff --git a/js/net/src/ietf/publisher.ts b/js/net/src/ietf/publisher.ts index 061b976fe6b..9ddd05638ac 100644 --- a/js/net/src/ietf/publisher.ts +++ b/js/net/src/ietf/publisher.ts @@ -156,21 +156,19 @@ interface RunGroup { /** The group to serve. */ group: group.Consumer; - /** The track's advertised timescale, applied to every frame timestamp. */ - timescale: Timescale; - - /** The publisher's tie-break priority, already converted to the IETF wire convention. */ - publisherPriority: number; - /** - * Whether objects carry their presentation timestamp. + * The units each object's presentation timestamp is written in, or undefined when objects + * carry none. * - * False when SUBSCRIBE_OK carries no TIMESCALE: the subscriber sent INCLUDE_PROPERTIES=0, - * or the draft (14-16) cannot send the property. A timestamp whose units were never - * declared is worse than none. Our own reader discards it; another may read it as some - * default and time the media wrong. + * Undefined when SUBSCRIBE_OK carries no TIMESCALE: the track has no timeline, the + * subscriber sent INCLUDE_PROPERTIES=0, or the draft (14-16) cannot send the property. A + * timestamp whose units were never declared is worse than none. Our own reader discards + * it; another may read it as some default and time the media wrong. */ - stamped: boolean; + timescale?: Timescale; + + /** The publisher's tie-break priority, already converted to the IETF wire convention. */ + publisherPriority: number; /** The objects of this group the subscription's filter selects. */ slice: GroupSlice; @@ -208,11 +206,8 @@ interface RunFill { */ cache: TrackSubscriber; - /** The track's advertised timescale, applied to every frame timestamp. */ - timescale: Timescale; - - /** Whether objects carry their presentation timestamp; see {@link RunGroup.stamped}. */ - stamped: boolean; + /** The units objects are stamped in, if any; see {@link RunGroup.timescale}. */ + timescale?: Timescale; /** Settles when the subscriber leaves, releasing a fill still waiting on its group. */ unsubscribed: Promise; @@ -366,10 +361,10 @@ export class Publisher { try { const info = await track.info(); - const timescale = info.timescale; // A Timestamp goes out only when this SUBSCRIBE_OK actually carries TIMESCALE. // Drafts 14-16 never write that property, so their objects stay unstamped. - const stamped = msg.propertiesWanted && Properties.sendsTimescale(version); + const timescale = + msg.propertiesWanted && Properties.sendsTimescale(version) ? (info.timescale ?? undefined) : undefined; // The model ranks higher-first, the IETF wire lower-first. Every group this // subscription serves carries the same publisher priority, which is what lets a // relay prefer catalog and audio over video when it has no subscriber preference @@ -430,7 +425,8 @@ export class Publisher { ? // TIMESCALE is what opts the track into timestamps, on drafts that can // send it. We serve the newest group first, matching moq-lite. { - timescale, + // An untimed track declares none, so it stays untimed downstream. + timescale: info.timescale ?? undefined, priority: publisherPriority, groupOrder: Properties.DESCENDING, maxCacheDuration: info.maxAge === undefined ? undefined : BigInt(info.maxAge), @@ -524,7 +520,6 @@ export class Publisher { group, timescale, publisherPriority, - stamped, slice: groupSlice(range, group.sequence), unsubscribed, streams, @@ -544,7 +539,6 @@ export class Publisher { fill, cache, timescale, - stamped, unsubscribed, streams, }) @@ -629,7 +623,7 @@ export class Publisher { * Runs a group and sends its frames using ObjectStream (Subgroup delivery mode). */ async #runGroup(options: RunGroup) { - const { requestId, group, timescale, publisherPriority, stamped, slice, unsubscribed, streams } = options; + const { requestId, group, timescale, publisherPriority, slice, unsubscribed, streams } = options; try { // One stream per group is faster than a peer at its limit can retire them, so this // is the one path that doesn't wait for a slot: the transport would serve the opens @@ -654,7 +648,7 @@ export class Publisher { flags: { // The object properties carry the timestamp, so there is nothing to write // when the track declared no units to read one in. - hasExtensions: stamped, + hasExtensions: timescale !== undefined, hasSubgroup: false, hasSubgroupObject: false, hasEnd: true, @@ -764,7 +758,7 @@ export class Publisher { * fill-failure signal. Nothing here touches the subscription either way. */ async #runFill(options: RunFill) { - const { requestId, fill, cache, timescale, stamped, unsubscribed, streams } = options; + const { requestId, fill, cache, timescale, unsubscribed, streams } = options; const version = this.#session.version; // Everything is inside the try so the cache fork is released on every path out, @@ -789,7 +783,7 @@ export class Publisher { const group = takeGroup(cache, Number(fill.sequence)); try { - await this.#writeFillGroup(stream, group, fill, timescale, stamped, unsubscribed); + await this.#writeFillGroup(stream, group, fill, timescale, unsubscribed); } finally { group.close(); } @@ -816,8 +810,7 @@ export class Publisher { stream: Writer, group: group.Consumer, fill: FillGroup, - timescale: Timescale, - stamped: boolean, + timescale: Timescale | undefined, unsubscribed: Promise, ) { let first = true; @@ -845,7 +838,7 @@ export class Publisher { next = BigInt(frame.sequence) + 1n; if (fill.until !== undefined && BigInt(frame.sequence) >= fill.until) break; - const obj = new FetchFrame({ payload: frame.payload, timestamp: stamped ? frame.timestamp : undefined }); + const obj = new FetchFrame({ payload: frame.payload, timestamp: frame.timestamp }); await obj.encode( stream, { group: Number(fill.sequence), object: frame.sequence, first }, diff --git a/js/net/src/ietf/subscriber.test.ts b/js/net/src/ietf/subscriber.test.ts index fb0b80cce9e..ea0615c3369 100644 --- a/js/net/src/ietf/subscriber.test.ts +++ b/js/net/src/ietf/subscriber.test.ts @@ -5,11 +5,13 @@ import { type Hop, HopSchema, UNKNOWN_HOP } from "../hop.ts"; import { createMockTransportPair } from "../mock.ts"; import * as Path from "../path.ts"; import { Reader, Stream } from "../stream.ts"; +import { Timescale } from "../time.ts"; import type * as track from "../track.ts"; import { ControlStreamAdapter, NativeSession } from "./adapter.ts"; import type * as Cluster from "./cluster.ts"; import { Connection } from "./connection.ts"; import { type GroupFlags, Group as GroupMessage } from "./object.ts"; +import type { Properties } from "./properties.ts"; import { PublishNamespace, PublishNamespaceUpdate } from "./publish_namespace.ts"; import { RequestError, RequestOk } from "./request.ts"; import { Subscribe, SubscribeOk, Unsubscribe } from "./subscribe.ts"; @@ -872,7 +874,9 @@ function encodeObjects(deltas: number[]): Uint8Array { * A subscriber with one track subscribed and answered, which is what registers {@link ALIAS} * and lets a group stream naming it be handled. */ -async function subscribeTrack(): Promise<{ subscriber: Subscriber; track: track.Subscriber }> { +async function subscribeTrack( + properties: Properties = {}, +): Promise<{ subscriber: Subscriber; track: track.Subscriber }> { const pair = createMockTransportPair(ALPN.DRAFT_19); const session = new NativeSession(pair.server, VERSION, true); const subscriber = new Subscriber({ session }); @@ -885,11 +889,70 @@ async function subscribeTrack(): Promise<{ subscriber: Subscriber; track: track. 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 }).encode(peer.writer, VERSION); + await new SubscribeOk({ requestId: request.requestId, trackAlias: ALIAS, properties }).encode(peer.writer, VERSION); return { subscriber, track }; } +/** One object carrying `properties` as its raw extension bytes, then a one-byte payload. */ +function encodeStamped(properties: number[]): Uint8Array { + // Every field here is under 64, so each is a one-byte varint. + return new Uint8Array([0, properties.length, ...properties, 1, 42]); +} + +/** A group stream header whose objects carry extensions. */ +function stampedGroup(groupId: number): GroupMessage { + return new GroupMessage({ + trackAlias: ALIAS, + groupId, + subGroupId: 0, + publisherPriority: 0, + flags: { ...groupFlags(true), hasExtensions: true }, + }); +} + +test("a track without TIMESCALE arrives untimed, even if an object carries a Timestamp", async () => { + const { subscriber, track } = await subscribeTrack(); + expect((await track.info()).timescale).toBeNull(); + + // Property 0x10 (Timestamp) = 5, with no units to read it in. + await subscriber.handleGroup(stampedGroup(0), new Reader(undefined, encodeStamped([0x10, 5]), VERSION)); + const group = await track.ordered().nextGroup(); + const frame = await group?.readFrame(); + expect(frame?.payload).toEqual(new Uint8Array([42])); + expect(frame?.timestamp).toBeUndefined(); + track.close(); +}); + +test("an object-scope Timescale is never applied", async () => { + const { subscriber, track } = await subscribeTrack({ timescale: Timescale.MICRO }); + expect((await track.info()).timescale).toBe(Timescale.MICRO); + + // Property 0x08 (Timescale) = 1 per second, then 0x10 (Timestamp) = 5 as a type delta of 8. + await subscriber.handleGroup(stampedGroup(0), new Reader(undefined, encodeStamped([0x08, 1, 0x08, 5]), VERSION)); + const group = await track.ordered().nextGroup(); + const frame = await group?.readFrame(); + expect(frame?.timestamp?.scale).toBe(Timescale.MICRO); + expect(frame?.timestamp?.value).toBe(5); + track.close(); +}); + +test("an object without a Timestamp on a TIMESCALE track is malformed", async () => { + const { subscriber, track } = await subscribeTrack({ timescale: Timescale.MICRO }); + const reader = new Reader(undefined, encodeStamped([]), VERSION); + const stop = spyOn(reader, "stop"); + + await subscriber.handleGroup(stampedGroup(0), reader); + + expect(stop).toHaveBeenCalledTimes(1); + const err = stop.mock.calls[0][0]; + expect(err).toBeInstanceOf(StreamError); + expect((err as StreamError).code).toBe(StreamCode.MalformedTrack); + // The track can't be trusted past it, so it ends rather than skipping one group. + expect(track.closed.peek()).toBe(err as StreamError); + stop.mockRestore(); +}); + test("older peer without priority property inherits wire priority 128", async () => { const { subscriber, track } = await subscribeTrack(); expect((await track.info()).priority).toBe(0xff - 128); diff --git a/js/net/src/ietf/subscriber.ts b/js/net/src/ietf/subscriber.ts index 1c8ff683677..14670e71f0d 100644 --- a/js/net/src/ietf/subscriber.ts +++ b/js/net/src/ietf/subscriber.ts @@ -18,7 +18,7 @@ import { hiddenBelow, hooks, scopeCaptures, scopeHead, scopeOverlaps } from "../ import * as Path from "../path.ts"; import type { Cursor, Reader, Stream } from "../stream.ts"; import { Tail } from "../tail.ts"; -import { Milli, type Timescale, Timestamp } from "../time.ts"; +import { Milli, type Timescale } from "../time.ts"; import type * as track from "../track.ts"; import { TimeoutError, withTimeout } from "../util/timeout.ts"; import { overrideBroadcastWire, wireOf } from "../wire.ts"; @@ -123,8 +123,8 @@ export class Subscriber { #aliases = new TrackAliases(); // Units for each track's object Timestamps, from the TIMESCALE Track Property in - // SUBSCRIBE_OK. A track missing from this map declared no timeline, so the publisher - // opted out of timestamps and its frames are stamped on arrival instead. + // SUBSCRIBE_OK. A track missing from this map declared no timeline, so its frames + // arrive untimed. #timescales = new Map(); // Dedup consumed broadcasts per path: repeat consume() calls share one subscription. @@ -797,6 +797,9 @@ export class Subscriber { throw new RangeError("max cache duration exceeds safe milliseconds"); } request.accept({ + // No TIMESCALE (always so on drafts 14-16, which can't carry it) means no timeline, + // and the track must not claim one when served onward. + timescale: ok.properties.timescale ?? null, priority: fromWire(ok.properties.priority ?? 128), maxAge: maxCacheDuration === undefined ? undefined : Milli(Number(maxCacheDuration)), }); @@ -1086,7 +1089,8 @@ export class Subscriber { // header priority inherits it (draft-21 section 10.4). if (!group.flags.hasPriority) group.publisherPriority = toWire((await track.info()).priority); - const decode = (c: Cursor) => Frame.decode(c, group.flags, this.#timescales.get(group.trackAlias)); + const timescale = this.#timescales.get(group.trackAlias); + const decode = (c: Cursor) => Frame.decode(c, group.flags, timescale); for (;;) { // Every object already buffered is written without an await, so the reader wakes // once per batch rather than once per object. Only the group's own stream ends it: @@ -1114,15 +1118,22 @@ export class Subscriber { } if (frame.payload === undefined) break; - open().writeFrame({ payload: frame.payload, timestamp: frame.timestamp ?? Timestamp.now() }); + // A track that declared TIMESCALE stamps every object, so one without a Timestamp is + // malformed rather than something to invent a time for. + if (timescale !== undefined && frame.timestamp === undefined) { + throw new StreamError(StreamCode.MalformedTrack, { + message: `object without a Timestamp on a track with TIMESCALE: group=${group.groupId}`, + }); + } + open().writeFrame({ payload: frame.payload, timestamp: frame.timestamp }); } // A group with no objects still exists. open().close(); } catch (err: unknown) { const e = await sessionCause(this.#quic, err); - if (e instanceof ProtocolViolation) { - // The publisher broke the track's end, which no later group can repair. + if (e instanceof ProtocolViolation || (e instanceof StreamError && e.code === StreamCode.MalformedTrack)) { + // The publisher broke the track's end or its content, which no later group can repair. producer?.close(e); track.close(e); } else { diff --git a/js/net/src/integration.test.ts b/js/net/src/integration.test.ts index 3811b540b88..7c828cb486f 100644 --- a/js/net/src/integration.test.ts +++ b/js/net/src/integration.test.ts @@ -861,11 +861,11 @@ test("integration: lite draft-05 fetches a cached group", async () => { const first = await fetched.readFrame(); expect(dec.decode(first?.payload)).toBe("alpha"); - expect(first?.timestamp.asMillis()).toBe(10); + expect(first?.timestamp?.asMillis()).toBe(10); const second = await fetched.readFrame(); expect(dec.decode(second?.payload)).toBe("beta"); - expect(second?.timestamp.asMillis()).toBe(15); + expect(second?.timestamp?.asMillis()).toBe(15); expect(await fetched.readFrame()).toBeUndefined(); @@ -1036,7 +1036,7 @@ test("integration: lite draft-05 fetches an in-progress group", async () => { group0.writeFrame({ payload: enc.encode("beta"), timestamp: Timestamp.fromMillis(15) }); const second = await fetched.readFrame(); expect(dec.decode(second?.payload)).toBe("beta"); - expect(second?.timestamp.asMillis()).toBe(15); + expect(second?.timestamp?.asMillis()).toBe(15); group0.close(); expect(await fetched.readFrame()).toBeUndefined(); @@ -1118,7 +1118,7 @@ test("integration: lite draft-05 fetch uses the republished track's timescale", // A millisecond timescale would round this to 1000us. const fetched = await remote.track("video").fetchGroup(0); const frame = await fetched.readFrame(); - expect(frame?.timestamp.asMicros()).toBe(1234); + expect(frame?.timestamp?.asMicros()).toBe(1234); first.close(); second.close(); diff --git a/js/net/src/internal.ts b/js/net/src/internal.ts index 153fe38a997..2cb2319cc5e 100644 --- a/js/net/src/internal.ts +++ b/js/net/src/internal.ts @@ -7,7 +7,7 @@ */ import type { Dispose, Getter } from "@moq/signals"; import type { Consumer as BroadcastConsumer, Producer as BroadcastProducer } from "./broadcast.ts"; -import type { Frame, Consumer as GroupConsumer } from "./group.ts"; +import type { Frame, Consumer as GroupConsumer, Producer as GroupProducer } from "./group.ts"; import type { Route } from "./hop.ts"; import * as Path from "./path.ts"; import type { Timestamp } from "./time.ts"; @@ -160,6 +160,11 @@ export const hooks: { * `setGroups`, which never rewinds. */ replaceGroups: (subscriber: Subscriber, groups: Groups) => void; + /** + * Bind a group to its track's timedness, so a frame whose timestamp disagrees is refused. + * Throws `TimestampMismatch` if a buffered frame already disagrees. + */ + bindGroupTimed: (group: GroupProducer, timed: boolean) => void; /** Return a group's first timestamp, retained even after its first frame is read. */ groupTimestamp: (group: GroupConsumer) => Timestamp | undefined; groupLatest: (group: GroupConsumer) => Timestamp | undefined; @@ -200,6 +205,9 @@ export const hooks: { replaceGroups: () => { throw new Error("track.ts not loaded"); }, + bindGroupTimed: () => { + throw new Error("group.ts not loaded"); + }, groupTimestamp: () => { throw new Error("group.ts not loaded"); }, diff --git a/js/net/src/lite/group.test.ts b/js/net/src/lite/group.test.ts index 44e2c9b64e7..d073dffe967 100644 --- a/js/net/src/lite/group.test.ts +++ b/js/net/src/lite/group.test.ts @@ -65,7 +65,7 @@ test("frames split at every byte keep their payloads and timestamps", async () = const frame = await consumer.readFrame(); ts += delta; expect(frame?.payload).toEqual(new Uint8Array(payload)); - expect(frame?.timestamp.value).toBe(ts); + expect(frame?.timestamp?.value).toBe(ts); } expect(await consumer.readFrame()).toBeUndefined(); }); diff --git a/js/net/src/lite/group.ts b/js/net/src/lite/group.ts index dd85e2de6e6..b7e57567db1 100644 --- a/js/net/src/lite/group.ts +++ b/js/net/src/lite/group.ts @@ -74,11 +74,11 @@ function unzigzag(v: bigint): bigint { * * A non-zero `scale` means every frame is prefixed with a zigzag-delta timestamp (the lite-05 * FRAME format), decoded into a Timestamp at that scale. Scale 0 (pre-lite-05) carries no - * timestamp, so frames are wall-clock stamped on arrival. + * timestamp, so frames arrive untimed. */ export function frameDecoder(scale: number): (c: Cursor) => netGroup.Frame { if (scale === 0) { - return (c) => ({ payload: c.read(c.u53()), timestamp: Time.Timestamp.now() }); + return (c) => ({ payload: c.read(c.u53()) }); } const timescale = Time.Timescale(scale); diff --git a/js/net/src/lite/publisher.ts b/js/net/src/lite/publisher.ts index 09a67a90a41..e1fa202e6d2 100644 --- a/js/net/src/lite/publisher.ts +++ b/js/net/src/lite/publisher.ts @@ -8,7 +8,7 @@ import { hiddenBelow, hooks, presented } from "../internal.ts"; import type { Consumer as OriginConsumer } from "../origin.ts"; import type * as Path from "../path.ts"; import { type Reader, type Stream, Writer } from "../stream.ts"; -import { Milli, Timescale } from "../time.ts"; +import { Milli, Timescale, Timestamp } from "../time.ts"; import type * as track from "../track.ts"; import { type Advertised, type Advertisements, wireOf } from "../wire.ts"; import { AnnounceInit, AnnounceOk, type AnnounceRequest, encodeAnnounceBroadcast } from "./announce.ts"; @@ -51,6 +51,22 @@ function zigzag(delta: bigint): bigint { return delta >= 0n ? delta << 1n : (-delta << 1n) - 1n; } +/** + * The timescale TRACK_INFO declares for a track. Lite05+ requires one, so a track without a + * timeline declares the default, the scale its frames' send times go out at. + */ +function wireTimescale(info: track.Info): Timescale { + return info.timescale ?? Timescale.MILLI; +} + +/** + * A frame or datagram timestamp as its raw value at the wire `timescale`. No lite version + * encodes an absent timestamp yet, so an untimed payload carries its send time instead. + */ +function wireTime(timestamp: Timestamp | undefined, timescale: Timescale): number { + return Math.round((timestamp ?? Timestamp.now()).as(timescale)); +} + /** * Settles once the peer acknowledged everything written before the FIN, or the stream failed. * Closing the session sooner would discard bytes still in flight. @@ -622,7 +638,7 @@ export class Publisher { // (accept never called, track closed) as an error here, which resets the // stream. const info = await track.info(); - timescale = info.timescale; + timescale = wireTimescale(info); } else { // Older drafts acknowledge with SUBSCRIBE_OK and stream frames verbatim. const ok = new SubscribeOk({ @@ -1012,7 +1028,7 @@ export class Publisher { maxAge: info.maxAge, // Lite05 mandates per-frame timestamps. Advertise the track's timescale; // `#serveGroup` emits each frame converted to it. - timescale: info.timescale, + timescale: wireTimescale(info), }); })(); @@ -1041,7 +1057,7 @@ export class Publisher { if (!datagram) return; // Track finished; #runTrack tears the subscription down. // Convert the timestamp to the track's advertised timescale, matching #serveGroup. - const ts = Math.round(datagram.timestamp.as(timescale)); + const ts = wireTime(datagram.timestamp, timescale); const body = new DatagramMessage(sub, datagram.sequence, ts, datagram.payload).encode(this.version); // No group fallback: drop anything that doesn't fit a single datagram. @@ -1080,7 +1096,7 @@ export class Publisher { const frame = await race([group.readFrame(), stream.closed]); if (!frame) break; - const ts = BigInt(Math.round(frame.timestamp.as(timescale))); + const ts = BigInt(wireTime(frame.timestamp, timescale)); await stream.u62(zigzag(ts - prevTs)); prevTs = ts; @@ -1170,7 +1186,7 @@ export class Publisher { if (timestamps) { // Convert each frame to the track's advertised timescale. - const ts = BigInt(Math.round(read.frame.timestamp.as(timescale))); + const ts = BigInt(wireTime(read.frame.timestamp, timescale)); await hooks.guardGroup(group, () => stream.u62(zigzag(ts - prevTs))); prevTs = ts; } diff --git a/js/net/src/lite/subscriber.ts b/js/net/src/lite/subscriber.ts index eb2bae2d213..9df49edec23 100644 --- a/js/net/src/lite/subscriber.ts +++ b/js/net/src/lite/subscriber.ts @@ -655,8 +655,8 @@ export class Subscriber { producer = request.accept(this.#toModelInfo(info)); timescale.set(info.timescale); } else { - // Older drafts negotiate nothing per-track: verbatim frames, no timescale. - producer = request.accept(); + // Older drafts negotiate nothing per-track: verbatim frames with no timeline. + producer = request.accept({ timescale: null }); timescale.set(0); drainOk = true; } diff --git a/js/net/src/lite/track.test.ts b/js/net/src/lite/track.test.ts index 034642fc9ab..a980cd193e5 100644 --- a/js/net/src/lite/track.test.ts +++ b/js/net/src/lite/track.test.ts @@ -47,7 +47,8 @@ test("TrackInfo round-trips on draft-05", async () => { }); test("TrackInfo defaults match cross-language wire bytes", async () => { - const info = new TrackInfo(infoDefaults()); + const defaults = infoDefaults(); + const info = new TrackInfo({ ...defaults, timescale: defaults.timescale ?? undefined }); expect(await bytes((w) => info.encode(w, Version.DRAFT_05), Version.DRAFT_05)).toEqual( new Uint8Array([0x0c, 0x7f, 0x00, 0xc0, 0x1f, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0x43, 0xe8]), ); diff --git a/js/net/src/track.test.ts b/js/net/src/track.test.ts index 59006030379..779cdd1af88 100644 --- a/js/net/src/track.test.ts +++ b/js/net/src/track.test.ts @@ -1,5 +1,5 @@ import { expect, setSystemTime, spyOn, test } from "bun:test"; -import { TooFarBehind } from "./error.ts"; +import { TimestampMismatch, TooFarBehind } from "./error.ts"; import { Producer as GroupProducer, MAX_GROUP_FRAMES } from "./group.ts"; import { hooks } from "./internal.ts"; import { Milli, Timescale, Timestamp } from "./time.ts"; @@ -803,7 +803,7 @@ test("a budget is measured from the reader's position", async () => { // A straggler from the old group, still inside the budget. open.writeFrame({ payload: enc.encode("late"), timestamp: Timestamp.fromMillis(1950) }); const frame = await late; - expect(frame?.timestamp.asMillis()).toBe(1950); + expect(frame?.timestamp?.asMillis()).toBe(1950); }); test("a handed-out group still expires while its first frame is stalled", async () => { @@ -840,7 +840,7 @@ test("committing track info wakes a group newly outside the retention window", a const group = await track.recvGroup(); if (!group) throw new Error("missing group"); - expect((await group.readFrame())?.timestamp.asMillis()).toBe(0); + expect((await group.readFrame())?.timestamp?.asMillis()).toBe(0); const waiting = group.readFrame(); producer.writeFrame({ payload: enc.encode("edge"), timestamp: Timestamp.fromMillis(1_000) }); @@ -2028,3 +2028,86 @@ test("an abort leaves a group already taken readable, then reports the abort", a await expect(group?.readFrame()).rejects.toBe(boom); } }); + +/** Every group a subscriber can take right now, by sequence. */ +function drain(track: { tryRecvGroup(): { sequence: number } | undefined }): number[] { + const sequences: number[] = []; + for (let group = track.tryRecvGroup(); group; group = track.tryRecvGroup()) sequences.push(group.sequence); + return sequences; +} + +/** An untimed track holding `count` single-frame groups. */ +function untimedTrack(count: number): TrackProducer { + const producer = new TrackProducer("test").accept({ timescale: null }); + for (let i = 0; i < count; i++) producer.writeFrame({ payload: enc.encode(`${i}`) }); + return producer; +} + +test("a track is timed by default and untimed only when declared", () => { + expect(infoDefaults().timescale).toBe(Timescale.MILLI); + expect(infoDefaults({ timescale: null }).timescale).toBeNull(); +}); + +test("a frame whose timedness disagrees with its track is refused", async () => { + const timed = new TrackProducer("timed").accept({}); + const group = timed.appendGroup(); + expect(() => group.writeFrame({ payload: enc.encode("x") })).toThrow(TimestampMismatch); + group.writeFrame({ payload: enc.encode("x"), timestamp: Timestamp.fromMillis(1) }); + + const untimed = new TrackProducer("untimed").accept({ timescale: null }); + const subscriber = untimed.subscribe(); + const other = untimed.appendGroup(); + expect(() => other.writeFrame({ payload: enc.encode("x"), timestamp: Timestamp.fromMillis(1) })).toThrow( + TimestampMismatch, + ); + other.writeFrame({ payload: enc.encode("y") }); + other.close(); + + // The untimed frame reaches the subscriber as it was written: no time filled in. + const frame = await (await subscriber.recvGroup())?.readFrame(); + expect(frame && dec.decode(frame.payload)).toBe("y"); + expect(frame?.timestamp).toBeUndefined(); +}); + +test("a group joining a track it disagrees with is refused", () => { + const producer = new TrackProducer("test").accept({ timescale: null }); + const group = new GroupProducer(0); + group.writeFrame({ payload: enc.encode("x"), timestamp: Timestamp.fromMillis(1) }); + expect(() => producer.writeGroup(group)).toThrow(TimestampMismatch); +}); + +test("a datagram whose timedness disagrees with its track is refused", async () => { + const timed = new TrackProducer("timed").accept({}); + expect(() => timed.appendDatagram(undefined, enc.encode("x"))).toThrow(TimestampMismatch); + + const untimed = new TrackProducer("untimed").accept({ timescale: null }); + const subscriber = untimed.subscribe(); + expect(() => untimed.insertDatagram(0, Timestamp.fromMillis(1), enc.encode("x"))).toThrow(TimestampMismatch); + untimed.appendDatagram(undefined, enc.encode("y")); + const got = await subscriber.recvDatagram(); + expect(got?.timestamp).toBeUndefined(); +}); + +test("an untimed track starts at its latest group", () => { + const producer = untimedTrack(5); + + // Nothing on an untimed track is ever stale, so no budget can say where to start. + const live = producer.subscribe(); + expect(drain(live)).toEqual([4]); + const patient = producer.subscribe({ maxAge: Milli(60_000) }); + expect(drain(patient)).toEqual([4]); + + producer.writeFrame({ payload: enc.encode("5") }); + expect(drain(live)).toEqual([5]); +}); + +test("an explicit start holds on an untimed track, and nothing there is stale", () => { + const producer = untimedTrack(5); + + // A named start says how far back to reach (a resume names the group it lacks), and a + // zero budget convicts nothing that has no place in media time. + const resumed = producer.subscribe({ groups: { start: { included: 2 } } }); + expect(drain(resumed)).toEqual([2, 3, 4]); + const replay = producer.subscribe({ groups: { start: { included: 0 } } }); + expect(drain(replay)).toEqual([0, 1, 2, 3, 4]); +}); diff --git a/js/net/src/track.ts b/js/net/src/track.ts index 1ad168ad060..070952499c6 100644 --- a/js/net/src/track.ts +++ b/js/net/src/track.ts @@ -5,7 +5,7 @@ */ import { type Dispose, type GetPromise, type Getter, Once, Signal } from "@moq/signals"; import type { Datagram } from "./datagram.ts"; -import { GroupTooLarge, TooFarBehind } from "./error.ts"; +import { GroupTooLarge, TimestampMismatch, TooFarBehind } from "./error.ts"; import { type Frame, type Consumer as GroupConsumer, Producer as GroupProducer } from "./group.ts"; import { groupBounds, @@ -58,11 +58,15 @@ export interface Location { */ export interface Info { /** - * Units per second for this track's frame timestamps (reported in TRACK_INFO on - * Lite05+). Defaults to milliseconds; set it finer (e.g. {@link Timescale.MICRO}) - * for media that needs sub-millisecond timing. + * Units per second for this track's frame timestamps, or `null` for a track with no + * timeline, whose frames and datagrams carry no timestamp. + * + * Defaults to milliseconds; set it finer (e.g. {@link Timescale.MICRO}) for media that + * needs sub-millisecond timing. Reported in TRACK_INFO on Lite05+ and as the TIMESCALE + * property on moq-transport. A track received without one (moq-lite before Lite05, or + * moq-transport without TIMESCALE) is `null`, and stays untimed when served onward. */ - timescale: Timescale; + timescale: Timescale | null; /** * Publisher Max Age: how far behind the live edge a group may fall in media * timestamps, in milliseconds, before it is stale. Reported in TRACK_INFO (Lite05+) @@ -104,7 +108,7 @@ function priorityByte(value: number): number { /** Fill in any unset {@link Info} fields with their defaults. */ export function infoDefaults(info: Partial = {}): Info { return { - timescale: Timescale(info.timescale ?? Timescale.MILLI), + timescale: info.timescale === null ? null : Timescale(info.timescale ?? Timescale.MILLI), maxAge: info.maxAge === undefined ? undefined : maxAgeMillis(info.maxAge), priority: priorityByte(info.priority ?? DEFAULT_PRIORITY), }; @@ -139,9 +143,10 @@ export interface Subscription { * The lowest group the publisher may deliver (a floor), or omit for none. * * A floor, not a request: only {@link maxAge} asks for data, and the floor bounds how - * far back it may reach. Omitting it and a floor of 0 mean the same thing, and a floor - * above the live edge simply waits there (a resumed subscription naming where it left - * off). + * far back it may reach. Omitting it and a floor of 0 differ only on an untimed track, + * where nothing is ever stale: omitted starts at the latest group, and an explicit floor + * replays from there. A floor above the live edge simply waits there (a resumed + * subscription naming where it left off). */ groups?: Groups; } @@ -287,7 +292,8 @@ export class Consumer { * The cursor starts at the group the subscription named (its floor), or 0. * {@link Subscription.maxAge} is what asks for data: delivery skips everything above * the floor that the budget convicts, so the default budget of zero delivers only the - * latest group and a larger one reaches back over what it can still use. + * latest group and a larger one reaches back over what it can still use. An untimed + * track has nothing to convict, so without a floor it starts at its latest group. */ subscribe(options?: Subscription): Subscriber { return this.#broadcast.subscribe(this.name, options); @@ -376,8 +382,9 @@ function closeTrackState(state: TrackState, abort?: Error): boolean { // Resolve the track's immutable publisher properties, or reject if it closes first. // On a producer this resolves once info is committed (at accept time); on a consumer -// once the wire layer commits the TRACK_INFO it received (lite-05+) or defaults (older -// drafts), so awaiting it never yields a placeholder. +// once the wire layer commits the properties it received (TRACK_INFO on lite-05+, +// SUBSCRIBE_OK on moq-transport) or an untimed default (older lite drafts), so awaiting it +// never yields a placeholder. async function resolveInfo(state: TrackState): Promise { for (;;) { const info = state.info.peek(); @@ -574,6 +581,7 @@ export class Producer { accept(info: Partial = {}): this { if (this.#state.closed.peek() !== undefined) return this; const resolved = infoDefaults(info); + for (const { group } of this.#cache) hooks.bindGroupTimed(group, resolved.timescale !== null); this.#state.info.set(resolved); // Propagate to any sink handed out before accept (the on-demand path). for (const sink of this.#sinks) sink.info.set(resolved); @@ -587,7 +595,8 @@ export class Producer { * Its cursor starts at the group the subscription named (its floor), or 0. * {@link Subscription.maxAge} is what asks for data: delivery skips everything above * the floor that the budget convicts, so the default budget of zero delivers only the - * latest group and a larger one reaches back over what it can still use. + * latest group and a larger one reaches back over what it can still use. An untimed + * track has nothing to convict, so without a floor it starts at its latest group. */ subscribe(options: Subscription = {}): Subscriber { const sink = new TrackState(options); @@ -806,6 +815,18 @@ export class Producer { this.#prune(); } + // Hold a group to this track's timedness, once the track has committed it. + #bind(group: GroupProducer): void { + const info = this.#state.info.peek(); + if (info) hooks.bindGroupTimed(group, info.timescale !== null); + } + + // Refuse a datagram whose timedness disagrees with this track's. + #checkDatagram(timestamp: Timestamp | undefined): void { + const info = this.#state.info.peek(); + if (info && (info.timescale !== null) !== (timestamp !== undefined)) throw new TimestampMismatch(); + } + // Refuse a write once the track is closed, or at or past its declared end. #writable(sequence: number): void { if (this.#state.closed.peek() !== undefined) throw new Error("track is closed"); @@ -815,11 +836,17 @@ export class Producer { } } - /** Append a new group with the next sequence number. */ + /** + * Append a new group with the next sequence number. + * + * Its frames must match the track's {@link Info.timescale}: a timestamp on every frame of + * a timed track and none on an untimed one, or the write throws {@link TimestampMismatch}. + */ appendGroup(): GroupProducer { const sequence = this.#sequence; this.#writable(sequence.next); const group = new GroupProducer(sequence.next); + this.#bind(group); sequence.next = group.sequence + 1; this.#publish(group); @@ -832,10 +859,13 @@ export class Producer { * Throws on a sequence that is still cached: a live duplicate would fan out to every * subscriber twice. An aborted incarnation is evicted so a fresh group can serve the * sequence again. Best effort (mirrors Rust): nothing remembers a sequence whose cache - * entry is already gone, so a long-evicted sequence is accepted as new. + * entry is already gone, so a long-evicted sequence is accepted as new. Throws + * {@link TimestampMismatch} if the group already holds a frame whose timedness + * disagrees with the track's {@link Info.timescale}. */ writeGroup(group: GroupProducer) { this.#writable(group.sequence); + this.#bind(group); const existing = this.#cached.get(group.sequence); if (existing) { @@ -879,12 +909,16 @@ export class Producer { * over IETF moq-transport or stream-only transports (the WebSocket fallback). A payload over * 65535 bytes (the QUIC datagram frame ceiling) throws. An origin publisher uses this; a * relay preserving upstream numbering uses {@link insertDatagram}. + * + * Pass `undefined` for the timestamp on an untimed track; a timestamp whose presence + * disagrees with the track's {@link Info.timescale} throws {@link TimestampMismatch}. */ - appendDatagram(timestamp: Timestamp, payload: Uint8Array): number { + appendDatagram(timestamp: Timestamp | undefined, payload: Uint8Array): number { const counter = this.#sequence; const sequence = counter.next; this.#writable(sequence); if (payload.byteLength > MAX_DATAGRAM_BYTES) throw new Error("datagram payload too large"); + this.#checkDatagram(timestamp); counter.next = sequence + 1; this.#publishDatagram({ sequence, timestamp, payload }); @@ -895,12 +929,13 @@ export class Producer { * Insert a datagram with an explicit sequence number. * * Preserves the supplied sequence (advancing the shared counter if needed) so a relay can - * forward a datagram without renumbering it. The size limits of {@link appendDatagram} - * apply. Most origin publishers want {@link appendDatagram} instead. + * forward a datagram without renumbering it. The size and timestamp rules of + * {@link appendDatagram} apply. Most origin publishers want {@link appendDatagram} instead. */ - insertDatagram(sequence: number, timestamp: Timestamp, payload: Uint8Array) { + insertDatagram(sequence: number, timestamp: Timestamp | undefined, payload: Uint8Array) { this.#writable(sequence); if (payload.byteLength > MAX_DATAGRAM_BYTES) throw new Error("datagram payload too large"); + this.#checkDatagram(timestamp); const counter = this.#sequence; if (sequence >= counter.next) { @@ -1139,7 +1174,21 @@ export class Subscriber { // The cursor's floor is the group the subscription named, or 0. A floor is the // only thing a start contributes; {@link Subscription.maxAge} is what asks for // data, and delivery skips everything above the floor that the budget convicts. - this.#cursor.set({ start: groupBounds(state.update.peek()?.groups ?? {}).start }); + // Nothing on an untimed track is ever stale, so there the budget would replay the + // whole cache: an unfloored subscriber starts at the latest group instead. + const groups = state.update.peek()?.groups ?? {}; + const start = groups.start === undefined ? this.#untimedStart() : undefined; + this.#cursor.set({ start: start ?? groupBounds(groups).start }); + } + + // The newest servable group, when the track is known to be untimed. + #untimedStart(): number | undefined { + if (this.#state.info.peek()?.timescale !== null) return undefined; + const timeline = this.#state.timeline; + for (let i = timeline.length - 1; i >= 0; i--) { + if (!(timeline[i].closed.peek() instanceof Error)) return timeline[i].sequence; + } + return undefined; } static { @@ -1171,8 +1220,9 @@ export class Subscriber { /** * Resolve this track's immutable publisher properties. * - * Resolves once the wire layer commits the TRACK_INFO it received (lite-05+) or - * defaults (older drafts), so awaiting it never yields a placeholder. Rejects if + * Resolves once the wire layer commits the properties it received (TRACK_INFO on + * lite-05+, SUBSCRIBE_OK on moq-transport) or an untimed default (older lite drafts), + * so awaiting it never yields a placeholder. Rejects if * the track is closed before the properties are known (e.g. a rejected subscription). */ info(): Promise { diff --git a/js/net/src/untimed.test.ts b/js/net/src/untimed.test.ts new file mode 100644 index 00000000000..79b25d2e1d7 --- /dev/null +++ b/js/net/src/untimed.test.ts @@ -0,0 +1,156 @@ +// A track keeps its timedness end to end: no receive path fills in arrival time, and a +// wire that can't declare a timeline delivers frames untimed. Mirrors rs/moq-net/tests/untimed.rs. +import { expect, test } from "bun:test"; +import { accept, connect } from "./connection/index.ts"; +import * as Ietf from "./ietf/index.ts"; +import * as Lite from "./lite/index.ts"; +import { createMockTransportPair } from "./mock.ts"; +import { Producer as OriginProducer } from "./origin.ts"; +import * as Path from "./path.ts"; +import { Timescale, Timestamp } from "./time.ts"; +import { wireOf } from "./wire.ts"; + +const url = new URL("https://localhost:4443/test"); + +/** A negotiated wire: the protocol to offer, and an explicit version where no ALPN names one. */ +interface Wire { + name: string; + protocol: string; + version?: number; + /** Whether the wire can declare a track's timeline. */ + declares: boolean; + /** Whether the wire carries a timestamp on every frame, a send time for an untimed one. */ + stamps: boolean; +} + +const WIRES: Wire[] = [ + { name: "lite-01", protocol: "", version: Lite.Version.DRAFT_01, declares: false, stamps: false }, + { name: "lite-03", protocol: Lite.ALPN_03, declares: false, stamps: false }, + { name: "lite-04", protocol: Lite.ALPN_04, declares: false, stamps: false }, + { name: "lite-05", protocol: Lite.ALPN_05, declares: true, stamps: true }, + { name: "lite-06", protocol: Lite.ALPN_06, declares: true, stamps: true }, + { name: "lite-07-wip", protocol: Lite.ALPN_07_WIP, declares: true, stamps: true }, + { name: "ietf-14", protocol: "", version: Ietf.Version.DRAFT_14, declares: false, stamps: false }, + { name: "ietf-16", protocol: Ietf.ALPN.DRAFT_16, declares: false, stamps: false }, + { name: "ietf-17", protocol: Ietf.ALPN.DRAFT_17, declares: true, stamps: false }, + { name: "ietf-20", protocol: Ietf.ALPN.DRAFT_20, declares: true, stamps: false }, +]; + +/** Serve one group of `timestamps` on a track with `timescale`, and read it back over `wire`. */ +async function roundTrip(wire: Wire, timescale: Timescale | null, timestamps: (Timestamp | undefined)[]) { + const pair = createMockTransportPair(wire.protocol); + const origin = new OriginProducer(); + const [client, server] = await Promise.all([ + connect({ url, transport: pair.client }), + accept({ transport: pair.server, url, version: wire.version, publish: origin.consume() }), + ]); + + const broadcast = origin.createBroadcast(Path.from("test")); + broadcast.announce(); + // Every request is answered, including the TRACK lookup lite-05+ makes before subscribing. + const serving = (async () => { + for (;;) { + const request = await wireOf(broadcast).requested(); + if (!request) break; + const group = request.accept({ timescale }).appendGroup(); + for (const [i, timestamp] of timestamps.entries()) { + group.writeFrame({ payload: new Uint8Array([i]), timestamp }); + } + group.close(); + } + })(); + + const remote = wireOf(client).consume(Path.from("test")); + const subscriber = remote.track("video").subscribe(); + const info = await subscriber.info(); + const group = await subscriber.ordered().nextGroup(); + const frames = []; + for (let frame = await group?.readFrame(); frame; frame = await group?.readFrame()) frames.push(frame); + + broadcast.close(); + await serving; + remote.close(); + client.abort(); + server.abort(); + return { info, frames }; +} + +test("a forwarded untimed track stays untimed", async () => { + // The publisher's hop (lite-04) can't declare a timeline, and the forwarding node must + // not claim one on its moq-transport hop either. + const upstream = createMockTransportPair(Lite.ALPN_04); + const downstream = createMockTransportPair(Ietf.ALPN.DRAFT_20); + const source = new OriginProducer(); + const relay = new OriginProducer(); + const [publisher, ingest, serve, subscriber] = await Promise.all([ + connect({ url, transport: upstream.client, publish: source.consume() }), + accept({ transport: upstream.server, url }), + accept({ transport: downstream.server, url, publish: relay.consume() }), + connect({ url, transport: downstream.client }), + ]); + + const broadcast = source.createBroadcast(Path.from("test")); + broadcast.announce(); + const serving = (async () => { + for (;;) { + const request = await wireOf(broadcast).requested(); + if (!request) break; + const group = request.accept({ timescale: Timescale.MICRO }).appendGroup(); + group.writeFrame({ payload: new Uint8Array([7]), timestamp: Timestamp.fromMicros(1_234) }); + group.close(); + } + })(); + + // Serve the downstream session from the upstream one. + const dynamic = relay.dynamic(Path.from("test")); + const forwarding = (async () => { + for await (const request of dynamic.requested()) request.accept(wireOf(ingest).consume(request.path)); + })(); + + const remote = wireOf(subscriber).consume(Path.from("test")); + const track = remote.track("video").subscribe(); + expect((await track.info()).timescale).toBeNull(); + const frame = await (await track.ordered().nextGroup())?.readFrame(); + expect(frame?.payload).toEqual(new Uint8Array([7])); + expect(frame?.timestamp).toBeUndefined(); + + broadcast.close(); + await serving; + remote.close(); + dynamic.close(); + await forwarding; + for (const session of [publisher, ingest, serve, subscriber]) session.abort(); +}); + +for (const wire of WIRES) { + test(`${wire.name}: an untimed track arrives untimed, or with send times where the wire must stamp`, async () => { + const { info, frames } = await roundTrip(wire, null, [undefined, undefined]); + expect(frames.map((frame) => frame.payload[0])).toEqual([0, 1]); + + if (wire.stamps) { + // Lite-05 and lite-06 can't say a track is untimed, so it goes out timed at the default scale. + expect(info.timescale).toBe(Timescale.MILLI); + for (const frame of frames) expect(frame.timestamp).toBeDefined(); + } else { + expect(info.timescale).toBeNull(); + for (const frame of frames) expect(frame.timestamp).toBeUndefined(); + } + }); + + test(`${wire.name}: a timed track keeps its timestamps only where the wire declares units`, async () => { + const { info, frames } = await roundTrip(wire, Timescale.MICRO, [ + Timestamp.fromMicros(1_000), + Timestamp.fromMicros(1_234), + ]); + expect(frames.map((frame) => frame.payload[0])).toEqual([0, 1]); + + if (wire.declares) { + expect(info.timescale).toBe(Timescale.MICRO); + expect(frames.map((frame) => frame.timestamp?.asMicros())).toEqual([1_000, 1_234]); + } else { + // No units on the wire, and no arrival time made up in their place. + expect(info.timescale).toBeNull(); + for (const frame of frames) expect(frame.timestamp).toBeUndefined(); + } + }); +} diff --git a/test/interop/clients/js/src/contract.ts b/test/interop/clients/js/src/contract.ts index 43b0a1ee4fa..ae44d2ae99c 100644 --- a/test/interop/clients/js/src/contract.ts +++ b/test/interop/clients/js/src/contract.ts @@ -60,6 +60,7 @@ export async function readLiveGop(track: Moq.Track.Consumer): Promise { try { const frame = await group.readFrame(); if (!frame) throw new Error("the fixture GOP has no keyframe"); + if (!frame.timestamp) throw new Error("the fixture video arrived untimed"); return { timestamp: frame.timestamp.asMillis() }; } finally { group.close(); diff --git a/test/interop/lite-varint.ts b/test/interop/lite-varint.ts index 75d06a17430..df3797fbf01 100644 --- a/test/interop/lite-varint.ts +++ b/test/interop/lite-varint.ts @@ -71,6 +71,7 @@ const frames: { timestamp: bigint; payload: Uint8Array }[] = []; for (;;) { const frame = await g.decodeMaybe(decode); if (!frame) break; + if (!frame.timestamp) throw new Error("a lite-05+ frame decoded without its timestamp"); frames.push({ timestamp: BigInt(frame.timestamp.value), payload: frame.payload }); } const zigzag = (d: bigint) => (d << 1n) ^ (d >> 63n); From b8149a6ddbea268c2196ac4ccdb537dd17d1923a Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 6 Oct 2026 23:34:43 -0700 Subject: [PATCH 3/8] quest: finish js-untimed-model Co-Authored-By: Claude Opus 5.5 --- quest/m1/README.md | 1 - quest/m1/js-data-consumer-timestamps.md | 1 - quest/m1/js-publish-timestamp.md | 8 ++-- quest/m1/js-untimed-model.md | 51 ------------------------- quest/m1/lite-untimed.md | 1 - quest/m1/untimed-model.md | 4 +- 6 files changed, 5 insertions(+), 61 deletions(-) delete mode 100644 quest/m1/js-untimed-model.md diff --git a/quest/m1/README.md b/quest/m1/README.md index a8e456bb74c..939610cfc4a 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -29,7 +29,6 @@ blocks. The quests that gated m0 lines moved under them. - [Untimed model](/quest/m1/untimed-model.md) - a track is all timed or all untimed (`Info.timescale` is optional, frames carry an optional timestamp), and an untimed track reaches every subscriber untimed; no receiver fills in arrival time - [One max_age meaning](/quest/m1/cache-max-age.md) - a superseded group goes stale on wall clock since its successor arrived or on media time, whichever is first, in Rust and js/net; fixes the untimed failover stall -- [JS untimed model](/quest/m1/js-untimed-model.md) - the untimed model in @moq/net - [CMAF frame timestamp](/quest/m1/cmaf-frame-timestamp.md) - CMAF decoders time samples from the moq-lite frame timestamp, using `tfdt` only within the fragment - [Shared import clock](/quest/m1/shared-clock.md) - an importer joining a clock already in use offsets its PTS instead of moving it, so captures and imports share one timeline - [FFI shape](/quest/m1/ffi-shape/README.md) - the bindings mirror Rust's layers: net at the root, then media, json, flate, audio, and video namespaces built from the handle below diff --git a/quest/m1/js-data-consumer-timestamps.md b/quest/m1/js-data-consumer-timestamps.md index 62638560381..cd24f4c35c3 100644 --- a/quest/m1/js-data-consumer-timestamps.md +++ b/quest/m1/js-data-consumer-timestamps.md @@ -31,7 +31,6 @@ Public API: breaking. Wire: none. ## Required - [JS publishing never invents a timestamp](/quest/m1/js-publish-timestamp.md) - adds `Timed` to `@moq/net` -- [@moq/net carries untimed frames faithfully](/quest/m1/js-untimed-model.md) - js/net stops filling arrival time, so `at` can be absent ## Related diff --git a/quest/m1/js-publish-timestamp.md b/quest/m1/js-publish-timestamp.md index 84754beec46..916cc8e8fb7 100644 --- a/quest/m1/js-publish-timestamp.md +++ b/quest/m1/js-publish-timestamp.md @@ -25,10 +25,8 @@ Decided (2026-10-05, types settled 2026-10-06): timedness is per track, as the [untimed model](/quest/m1/untimed-model.md) decided and `@moq/net` mirrors: `timescale` is optional, frames keep an optional timestamp, and a frame whose timedness doesn't match its track is refused. An absent -`at` therefore belongs on an untimed track. +`at` therefore belongs on an untimed track. `@moq/net` already refuses a +mismatched frame, so the group helpers, which still stamp now, only work on a +timed track today. Public API: breaking. Wire: none. - -## Required - -- [@moq/net carries untimed frames faithfully](/quest/m1/js-untimed-model.md) - the model must hold an untimed payload before producers stop filling in now diff --git a/quest/m1/js-untimed-model.md b/quest/m1/js-untimed-model.md deleted file mode 100644 index aa4ff75607a..00000000000 --- a/quest/m1/js-untimed-model.md +++ /dev/null @@ -1,51 +0,0 @@ -# [M] @moq/net carries untimed frames faithfully - -## Goal - -`@moq/net` mirrors [moq-net carries untimed frames -faithfully](/quest/m1/untimed-model.md). An untimed track stays untimed from -publisher to consumer, and js/net never fills in `Timestamp.now()` on -receive. Covers `@moq/net` and its in-repo callers -(`@moq/hang`, `@moq/loc`, `@moq/watch`). - -## Plan - -Decided (2026-10-02): a hand-written change now, rather than -waiting for [Generated @moq/net](/quest/m1/rs2ts/README.md). That line is -long-running and would stall the JS timestamp quests. Whichever lands second -absorbs the other. The semantics, the end-marker rule and the reasons are in -the Rust quest; keep the two in step. - -Decided (2026-10-05, types settled 2026-10-06): timedness is per track, as -the [untimed model](/quest/m1/untimed-model.md) decided and `@moq/net` -mirrors: `timescale` is optional, frames keep an optional timestamp, and a -frame whose timedness doesn't match its track is refused. Where the -notes below assume groups that mix timed and untimed frames, this wins. - -Things to look out for: - -- Receive-side fills: lite frames on a track with no timescale, and IETF - objects without a timestamp, both default to now today. -- The track's drift, reach, staleness and expiry logic skips unstamped groups - the way Rust does. Check that untimed frames still count as frames, and - that an untimed track starts at the latest group. -- A track's `Info.timescale` is required today, with a default. Like Rust, - a track that never declared one must not claim a timeline downstream. -- A FETCH is timed only when it learns the track's units when accepted. -- Tracks on drafts 14-16, where SUBSCRIBE_OK can't carry TIMESCALE, are - untimed (decided 2026-10-05), so the publisher sends no Timestamp there. - This replaces the earlier plan to write an object-scope TIMESCALE beside - each Timestamp. -- Update callers in js/hang and js/loc (end markers) and anything in - js/watch that reads frame timestamps. - -Test: an untimed frame survives a JS subscribe on each receive path. Run -`just test interop --all`. - -Public API: breaking. Wire: none beyond what IETF timestamp units -changes. - -## Related - -- [moq-net carries untimed frames faithfully](/quest/m1/untimed-model.md) - the Rust side and the decisions -- [Generated @moq/net](/quest/m1/rs2ts/README.md) - will replace this code with generated code diff --git a/quest/m1/lite-untimed.md b/quest/m1/lite-untimed.md index bf6c1be7e16..098936c5e57 100644 --- a/quest/m1/lite-untimed.md +++ b/quest/m1/lite-untimed.md @@ -51,4 +51,3 @@ Public API: none. Wire: lite-07-wip only, which is unpublished. ## Required - [moq-net carries untimed frames faithfully](/quest/m1/untimed-model.md) - the Rust model must hold an absent timestamp before the wire can carry one -- [@moq/net carries untimed frames faithfully](/quest/m1/js-untimed-model.md) - the same for JS diff --git a/quest/m1/untimed-model.md b/quest/m1/untimed-model.md index 93387fa29c7..102114db5dc 100644 --- a/quest/m1/untimed-model.md +++ b/quest/m1/untimed-model.md @@ -17,8 +17,8 @@ moq-net, moq-relay, every in-repo caller of the model, and Out of scope: publishers that fill in now ([Publishing never invents a timestamp](/quest/m1/publish-timestamp.md)), the lite-07 encoding of absence ([lite-07 encodes an absent -timestamp](/quest/m1/lite-untimed.md)), and JS -([@moq/net carries untimed frames faithfully](/quest/m1/js-untimed-model.md)). +timestamp](/quest/m1/lite-untimed.md)), and JS, where `@moq/net` already +carries untimed tracks this way. ## Plan From 6535b727697398a8ca99f1b178f88c2ec366f3ff Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 7 Oct 2026 09:08:20 -0700 Subject: [PATCH 4/8] feat(js/net)!: omitting Track.Info.timescale declares an untimed track There is no implicit millisecond default anymore: `timescale` is `Timescale | undefined`, and every timed publisher declares its units. In-repo publishers (catalog, room, moq-boy, clock, demo, examples, test fixtures) now pass an explicit timescale. Co-Authored-By: Claude Opus 5.5 --- demo/web/src/publish.ts | 5 +- doc/lib/js/flate.md | 3 +- doc/lib/js/json.md | 3 +- doc/lib/js/net.md | 4 +- doc/lib/js/publish.md | 9 +- js/clock/src/main.ts | 2 +- js/hang/src/catalog/consumer.test.ts | 8 +- .../src/container/consumer.outoforder.test.ts | 6 +- js/hang/src/timeline.test.ts | 8 +- js/moq-boy/src/game.ts | 2 +- js/net/bench/track.ts | 4 +- js/net/examples/publish.ts | 3 +- js/net/src/broadcast.test.ts | 68 +++++------ js/net/src/connection/pool.test.ts | 2 +- js/net/src/ietf/publisher.test.ts | 42 +++---- js/net/src/ietf/publisher.ts | 5 +- js/net/src/ietf/subscriber.test.ts | 2 +- js/net/src/ietf/subscriber.ts | 2 +- js/net/src/integration.test.ts | 72 +++++------ js/net/src/lite/connection.test.ts | 9 +- js/net/src/lite/priority.test.ts | 3 +- js/net/src/lite/publisher.test.ts | 30 ++--- js/net/src/lite/publisher.ts | 4 +- js/net/src/lite/subscriber.ts | 2 +- js/net/src/lite/track.test.ts | 8 +- js/net/src/origin.test.ts | 15 +-- js/net/src/retention.test.ts | 4 +- js/net/src/tail.test.ts | 4 +- js/net/src/track.test.ts | 114 +++++++++--------- js/net/src/track.ts | 26 ++-- js/net/src/untimed.test.ts | 12 +- js/publish/src/audio/encoder.test.ts | 2 +- js/publish/src/broadcast.ts | 2 + js/publish/src/video/capture.test.ts | 2 +- js/publish/src/video/encoder.test.ts | 14 +-- js/room/src/chat.test.ts | 4 +- js/room/src/chat.ts | 8 +- js/room/src/metadata.test.ts | 8 +- js/room/src/metadata.ts | 9 +- js/watch/src/broadcast.test.ts | 2 +- js/watch/src/retention.test.ts | 2 +- quest/m1/js-publish-timestamp.md | 4 + .../clients/js/src/capture.test.ts | 4 +- test/drain/drain.ts | 2 +- test/interop/clients/js/src/contract.test.ts | 2 +- test/wasm/src/main.ts | 2 +- 46 files changed, 289 insertions(+), 259 deletions(-) diff --git a/demo/web/src/publish.ts b/demo/web/src/publish.ts index 0beab8a8ea5..324e4a55e58 100644 --- a/demo/web/src/publish.ts +++ b/demo/web/src/publish.ts @@ -401,7 +401,10 @@ meta.run((effect) => { if (!net) return; // A day-long cache so a viewer joining long after the last edit still replays the value. - const track = net.createTrack(META_TRACK, { maxAge: Net.Time.Milli(86_400_000) }); + const track = net.createTrack(META_TRACK, { + timescale: Net.Time.Timescale.MILLI, + maxAge: Net.Time.Milli(86_400_000), + }); effect.cleanup(() => track.close()); const producer = new Json.Snapshot.Producer({ track }); diff --git a/doc/lib/js/flate.md b/doc/lib/js/flate.md index a128b850984..7ddf9e5b80a 100644 --- a/doc/lib/js/flate.md +++ b/doc/lib/js/flate.md @@ -25,7 +25,8 @@ producer.update(payload); ``` A payload is stamped when written, unless you pass its capture time: -`producer.update(payload, at)`. +`producer.update(payload, at)`. Every frame carries a timestamp, so the track must +declare a timescale, such as `createTrack(name, { timescale: Time.Timescale.MILLI })`. The codec underneath is exported as `Encoder`/`Decoder`. Create one pair per group and feed frames in order. diff --git a/doc/lib/js/json.md b/doc/lib/js/json.md index a7f56953d1e..56c9811d251 100644 --- a/doc/lib/js/json.md +++ b/doc/lib/js/json.md @@ -34,6 +34,7 @@ for await (const value of consumer) { ``` A value is stamped when written, unless you pass its capture time: -`producer.update(value, at)`. +`producer.update(value, at)`. Every frame carries a timestamp, so the track must +declare a timescale, such as `createTrack(name, { timescale: Time.Timescale.MILLI })`. The Rust twin is [`moq-json`](/lib/rs/moq-json). diff --git a/doc/lib/js/net.md b/doc/lib/js/net.md index 9c5d0734958..3ecbd096778 100644 --- a/doc/lib/js/net.md +++ b/doc/lib/js/net.md @@ -27,7 +27,7 @@ const connection = await Moq.Connection.connect({ }); const broadcast = origin.createBroadcast(Moq.Path.from("chat.room")); -const track = broadcast.createTrack("messages"); +const track = broadcast.createTrack("messages", { timescale: Moq.Time.Timescale.MILLI }); const group = track.appendGroup(); group.writeString("hello"); // or writeFrame({ payload, timestamp }) group.close(); @@ -53,7 +53,7 @@ for (;;) { - **Bandwidth** (`Bandwidth.Allocator`) divides the connection's send-rate estimate by track priority, max-min fair within a tier. An idle track claims nothing. The receive side is untouched. - **Discovery** by any pattern scope (`origin.announced(scope)`, such as `room/*/chat`; default everything). A route event's `kind` says whether the route started, updated, or ended; its `prefix` is the covered prefix relative to the origin, and `captures` reports what the scope's wildcards matched when the prefix pins them. The consumer is an async iterable. `origin.broadcasts(scope)` is a live `Getter>` of the same covered prefixes for UIs that need the current set. A borrowed `Connection.origin` also exposes `dynamic(prefix, route)` for serving paths on demand. - **Publisher retention** is optional `Track.Info.maxAge`, measured against media timestamps: omission sets no limit, while zero serves only the live edge. It clamps every subscriber's max age, and stalled media does not age out merely because wall time passes. Separately, cached groups nobody writes for 30 seconds are reclaimed, except a live track's newest group, which stays replayable until the track closes. -- **Timing** is per track. `Track.Info.timescale` defaults to milliseconds; `null` declares an untimed track. A frame or datagram carries a `timestamp` exactly when its track has a timescale, and a write that disagrees throws `Error.TimestampMismatch`. Nothing fills in a time on receive: moq-lite before 05, and moq-transport without TIMESCALE (always so on drafts 14-16), deliver untimed tracks. moq-lite 05 and 06 can't declare an untimed track, so it goes out at milliseconds with each frame's send time. An untimed group is never stale, so a subscription without a `groups.start` begins at the latest group. +- **Timing** is per track. A timed track declares `Track.Info.timescale` (such as `Time.Timescale.MILLI`); omitting it declares an untimed track. There is no default, unlike Rust's millisecond default. A frame or datagram carries a `timestamp` exactly when its track has a timescale, and a write that disagrees throws `Error.TimestampMismatch`. Nothing fills in a time on receive: moq-lite before 05, and moq-transport without TIMESCALE (always so on drafts 14-16), deliver untimed tracks. moq-lite 05 and 06 can't declare an untimed track, so it goes out at milliseconds with each frame's send time. An untimed group is never stale, so a subscription without a `groups.start` begins at the latest group. - **Subscriptions** carry a priority, a `Time.Milli` max age measured against media timestamps, and optional `groups` bounds. Groups arrive out of order and are read frame by frame, with `Error.TooFarBehind` when a reader asks for a frame the group never held and `Error.GroupTooLarge` when a write exceeds the cache budget and aborts the group. - **Track ends**: `close()` ends a track at its live edge, while `finishAt(n)` declares the exclusive end ahead of it and still accepts the groups below. A subscriber reads the end with `final()` or awaits `finished()`. Group and datagram readers end once the live edge reaches the declared boundary, even while missing lower groups wait out the grace. The `closed` signal settles separately once every group below the end has arrived or was dropped; one reset before its header arrived is skipped after the subscription's max age on moq-lite (one second without one), or after one second on IETF. - **Datagrams** on moq-lite 05+ and fetch-by-sequence for history. `track.fetchGroup(sequence)` on moq-lite resolves when the publisher sends the first response byte or finishes an empty group. A missing group rejects the fetch with `StreamCode.NotFound`, including every concurrent caller sharing that fetch. `fetchGroup(sequence, { signal })` abandons a pending fetch with the signal's reason; the shared stream is cancelled only once every caller has left. Once resolved, close the group instead. diff --git a/doc/lib/js/publish.md b/doc/lib/js/publish.md index 8b496b9cea3..0fed40b24c1 100644 --- a/doc/lib/js/publish.md +++ b/doc/lib/js/publish.md @@ -102,13 +102,18 @@ can serve its own tracks alongside the media. It is recreated on each ```ts import * as Json from "@moq/json"; +import * as Moq from "@moq/net"; signals.run((effect) => { const net = effect.get(broadcast.net); if (!net) return; - // A day-long retention so a late viewer still replays the last value. - const track = net.createTrack("meta.json", { maxAge: 86_400_000 }); + // A day-long retention so a late viewer still replays the last value. JSON + // values are stamped when written, so the track declares a timescale. + const track = net.createTrack("meta.json", { + timescale: Moq.Time.Timescale.MILLI, + maxAge: Moq.Time.Milli(86_400_000), + }); effect.cleanup(() => track.close()); const meta = new Json.Snapshot.Producer({ track }); diff --git a/js/clock/src/main.ts b/js/clock/src/main.ts index 6d32da417a1..66e9974cd54 100755 --- a/js/clock/src/main.ts +++ b/js/clock/src/main.ts @@ -84,7 +84,7 @@ async function publish(config: Config) { console.log("✅ Published broadcast:", config.broadcast); - void publishTrack(broadcast.createTrack(config.track)); + void publishTrack(broadcast.createTrack(config.track, { timescale: Moq.Time.Timescale.MILLI })); await connection.closed; } diff --git a/js/hang/src/catalog/consumer.test.ts b/js/hang/src/catalog/consumer.test.ts index 39ecac5811d..5ae70309590 100644 --- a/js/hang/src/catalog/consumer.test.ts +++ b/js/hang/src/catalog/consumer.test.ts @@ -57,7 +57,7 @@ test("the shared containment check covers every section carrying a broadcast ref test("watch refuses an oversized catalog update", async () => { const broadcast = new Moq.Broadcast.Producer(); - const track = broadcast.createTrack(TRACK); + const track = broadcast.createTrack(TRACK, { timescale: Moq.Time.Timescale.MILLI }); const producer = new Json.Snapshot.Producer({ track, deltaRatio: 0 }); const consumer = watch(broadcast.consume())[Symbol.asyncIterator](); producer.update(catalog(MAX_RENDITIONS + 1)); @@ -78,7 +78,7 @@ function referencing(broadcast: string): Root { async function watchRequested(root: Root) { const origin = new Moq.Origin.Producer(); const broadcast = origin.createBroadcast(Moq.Path.from("room/alice")); - const track = broadcast.createTrack(TRACK); + const track = broadcast.createTrack(TRACK, { timescale: Moq.Time.Timescale.MILLI }); const producer = new Json.Snapshot.Producer({ track, deltaRatio: 0 }); broadcast.announce(); const request = origin.request(Moq.Path.from("room/alice")); @@ -107,7 +107,7 @@ test("watch accepts a sibling reference under the same root and yields it unreso test("watch on a standalone broadcast refuses any parent reference", async () => { const broadcast = new Moq.Broadcast.Producer(); - const track = broadcast.createTrack(TRACK); + const track = broadcast.createTrack(TRACK, { timescale: Moq.Time.Timescale.MILLI }); const producer = new Json.Snapshot.Producer({ track, deltaRatio: 0 }); const consumer = watch(broadcast.consume())[Symbol.asyncIterator](); producer.update(referencing("../bob")); @@ -118,7 +118,7 @@ test("watch on a standalone broadcast refuses any parent reference", async () => test("watch subscribes and yields typed catalog updates", async () => { const broadcast = new Moq.Broadcast.Producer(); - const track = broadcast.createTrack(TRACK); + const track = broadcast.createTrack(TRACK, { timescale: Moq.Time.Timescale.MILLI }); const producer = new Json.Snapshot.Producer({ track, deltaRatio: 0 }); const consumer = watch(broadcast.consume())[Symbol.asyncIterator](); producer.update(catalog(1)); diff --git a/js/hang/src/container/consumer.outoforder.test.ts b/js/hang/src/container/consumer.outoforder.test.ts index 37ddbbec68a..20475d5762a 100644 --- a/js/hang/src/container/consumer.outoforder.test.ts +++ b/js/hang/src/container/consumer.outoforder.test.ts @@ -47,7 +47,7 @@ async function drain(consumer: Consumer): Promise<[number, number | undefined][] // audio writes into a timestamp-indexed ring and video drops a late frame at render, and the // subscription's own max age already bounds how far back one can be. test("out-of-order groups are delivered rather than dropped", async () => { - const track = new Track.Producer("test").accept({ maxAge: Time.Milli(30_000) }); + const track = new Track.Producer("test").accept({ timescale: Time.Timescale.MILLI, maxAge: Time.Milli(30_000) }); const consumer = new Consumer(track.subscribe({ maxAge: Time.Milli(5000) }), { format: new LegacyFormat("data"), maxAge: 5000 as Time.Milli, @@ -77,7 +77,7 @@ test("out-of-order groups are delivered rather than dropped", async () => { // drained (the decode loop consumes faster than the network delivers). Removing it at that // instant silently truncates its tail, so removal must wait for the group to finish. test("a below-cursor group still downloading is not truncated", async () => { - const track = new Track.Producer("test").accept({ maxAge: Time.Milli(30_000) }); + const track = new Track.Producer("test").accept({ timescale: Time.Timescale.MILLI, maxAge: Time.Milli(30_000) }); const consumer = new Consumer(track.subscribe({ maxAge: Time.Milli(5000) }), { format: new LegacyFormat("data"), maxAge: 5000 as Time.Milli, @@ -115,7 +115,7 @@ test("a below-cursor group still downloading is not truncated", async () => { // The floor belongs to the latest group, not to delayed history within max age. test("delayed older groups survive a floor established by two newer groups", async () => { const clock = spyOn(performance, "now").mockReturnValue(200); - const track = new Track.Producer("test").accept({ maxAge: Time.Milli(30_000) }); + const track = new Track.Producer("test").accept({ timescale: Time.Timescale.MILLI, maxAge: Time.Milli(30_000) }); const consumer = new Consumer(track.subscribe({ maxAge: Time.Milli(5000) }), { format: new LegacyFormat("data"), maxAge: Time.Milli(5000), diff --git a/js/hang/src/timeline.test.ts b/js/hang/src/timeline.test.ts index 6c78ba91d06..a3edae69742 100644 --- a/js/hang/src/timeline.test.ts +++ b/js/hang/src/timeline.test.ts @@ -1,6 +1,6 @@ import { expect, test } from "bun:test"; import * as Json from "@moq/json"; -import { Broadcast, type Time } from "@moq/net"; +import { Broadcast, Time } from "@moq/net"; import { u53 } from "./catalog"; import { Consumer, type Record } from "./timeline.ts"; @@ -10,7 +10,7 @@ const archive = (timescale: number) => ({ timelines: { video: "video.timeline.z" test("timeline consumer yields converted push and pop events", async () => { const broadcast = new Broadcast.Producer(); - const track = broadcast.createTrack("video.timeline.z"); + const track = broadcast.createTrack("video.timeline.z", { timescale: Time.Timescale.MILLI }); const producer = new Json.Window.Producer({ track, compression: true }); const consumer = Consumer.subscribe(broadcast.consume(), archive(1000), "video"); producer.push({ sequence: 0, pts: 250, duration: 1250, start: { group: 1 }, end: { group: 2, frame: 3 } }); @@ -29,7 +29,7 @@ test("timeline consumer yields converted push and pop events", async () => { test("timeline consumer floors fractional microseconds without floating point drift", async () => { const broadcast = new Broadcast.Producer(); - const track = broadcast.createTrack("video.timeline.z"); + const track = broadcast.createTrack("video.timeline.z", { timescale: Time.Timescale.MILLI }); const producer = new Json.Window.Producer({ track, compression: true }); const consumer = Consumer.subscribe(broadcast.consume(), archive(3), "video"); producer.push({ sequence: 0, pts: 1, duration: 2, start: { group: 0 }, end: { group: 1 } }); @@ -52,7 +52,7 @@ test("timeline consumer floors fractional microseconds without floating point dr test("a record numbered unlike its window index is refused", async () => { const broadcast = new Broadcast.Producer(); - const track = broadcast.createTrack("video.timeline.z"); + const track = broadcast.createTrack("video.timeline.z", { timescale: Time.Timescale.MILLI }); const producer = new Json.Window.Producer({ track, compression: true }); const consumer = Consumer.subscribe(broadcast.consume(), archive(1000), "video"); producer.push({ sequence: 5, pts: 0, duration: 1000, start: { group: 0 }, end: { group: 1 } }); diff --git a/js/moq-boy/src/game.ts b/js/moq-boy/src/game.ts index 660026da76f..59a4f2aecee 100644 --- a/js/moq-boy/src/game.ts +++ b/js/moq-boy/src/game.ts @@ -308,7 +308,7 @@ export class Game { this.viewerId.set(undefined); }); - const track = viewerBroadcast.createTrack("command"); + const track = viewerBroadcast.createTrack("command", { timescale: Moq.Time.Timescale.MILLI }); const producer = new Json.Snapshot.Producer>({ track }); effect.cleanup(() => producer.finish()); effect.run(this.#runCommandTrack.bind(this, track, producer)); diff --git a/js/net/bench/track.ts b/js/net/bench/track.ts index 184a0383be0..09980819946 100644 --- a/js/net/bench/track.ts +++ b/js/net/bench/track.ts @@ -1,6 +1,6 @@ /** Sweep retained groups and subscribers for one group published through a track and received. */ import { type Consumer as GroupConsumer, Producer as GroupProducer } from "../src/group.ts"; -import { Milli, Timestamp } from "../src/time.ts"; +import { Milli, Timescale, Timestamp } from "../src/time.ts"; import { Producer, type Subscriber } from "../src/track.ts"; const retainedCounts = [25, 100, 400, 1500]; @@ -47,7 +47,7 @@ async function measure( ): Promise<{ publish: number; end: number; idle: number }> { // Held rows stay within the idle window while the media budget keeps their frames usable. const window = Milli(held > 0 ? 3_600_000 : retained); - const producer = new Producer("bench").accept({ maxAge: window }); + const producer = new Producer("bench").accept({ timescale: Timescale.MILLI, maxAge: window }); const subscribers = Array.from({ length: subscriberCount }, () => producer.subscribe({ maxAge: window })); let sequence = 0; // Inserted by sequence, the way the wire hands a subscribed track its groups. diff --git a/js/net/examples/publish.ts b/js/net/examples/publish.ts index 1fe6a6d8799..617906484fe 100644 --- a/js/net/examples/publish.ts +++ b/js/net/examples/publish.ts @@ -13,7 +13,8 @@ async function main() { // Insert the "chat" track up front. A subscriber is served directly from this // track, no requested() round-trip needed. Mirrors the Rust createTrack/insertTrack. - void publishTrack(broadcast.createTrack("chat")); + // writeString stamps each frame with the current time, so the track declares a timescale. + void publishTrack(broadcast.createTrack("chat", { timescale: Moq.Time.Timescale.MILLI })); console.log("Published broadcast: my-broadcast"); await connection.closed; diff --git a/js/net/src/broadcast.test.ts b/js/net/src/broadcast.test.ts index 9a365db6bfe..499b79ff522 100644 --- a/js/net/src/broadcast.test.ts +++ b/js/net/src/broadcast.test.ts @@ -3,7 +3,7 @@ import { Signal } from "@moq/signals"; import { Consumer as BroadcastConsumer, Producer as BroadcastProducer } from "./broadcast.ts"; import { GroupTooLarge } from "./error.ts"; import { Producer as GroupProducer, MAX_GROUP_FRAMES } from "./group.ts"; -import { Milli, Timestamp } from "./time.ts"; +import { Milli, Timescale, Timestamp } from "./time.ts"; import type { Request as TrackRequest } from "./track.ts"; import { Producer as TrackProducer } from "./track.ts"; import { wireOf } from "./wire.ts"; @@ -39,7 +39,7 @@ test("consumer dedupes repeat subscriptions onto one upstream request", async () // Serving that single request fans out to both subscribers. if (!request) throw new Error("expected request"); - const producer = request.accept(); + const producer = request.accept({ timescale: Timescale.MILLI }); producer.writeString("hello"); expect(await a.readString()).toBe("hello"); expect(await b.readString()).toBe("hello"); @@ -62,7 +62,7 @@ test("dynamic track sequences continue across producer replacements", async () = const firstSubscriber = broadcast.track("media").subscribe(); const firstRequest = await wireOf(broadcast).requested(); if (!firstRequest) throw new Error("expected first request"); - const firstProducer = firstRequest.accept(); + const firstProducer = firstRequest.accept({ timescale: Timescale.MILLI }); expect(firstProducer.appendGroup().sequence).toBe(0); expect(firstProducer.appendDatagram(Timestamp.fromMillis(0), new Uint8Array())).toBe(1); firstProducer.writeGroup(new GroupProducer(8)); @@ -73,14 +73,14 @@ test("dynamic track sequences continue across producer replacements", async () = const secondSubscriber = broadcast.track("media").subscribe(); const secondRequest = await wireOf(broadcast).requested(); if (!secondRequest) throw new Error("expected second request"); - const secondProducer = secondRequest.accept(); + const secondProducer = secondRequest.accept({ timescale: Timescale.MILLI }); expect(secondProducer.appendGroup().sequence).toBe(13); const nextGeneration = new BroadcastProducer(); const nextSubscriber = nextGeneration.track("media").subscribe(); const nextRequest = await wireOf(nextGeneration).requested(); if (!nextRequest) throw new Error("expected next-generation request"); - expect(nextRequest.accept().appendGroup().sequence).toBe(0); + expect(nextRequest.accept({ timescale: Timescale.MILLI }).appendGroup().sequence).toBe(0); secondSubscriber.close(); secondProducer.close(); @@ -96,8 +96,8 @@ test("concurrent dynamic producers share a sequence namespace", async () => { const firstRequest = await wireOf(broadcast).requested(); const secondRequest = await wireOf(broadcast).requested(); if (!firstRequest || !secondRequest) throw new Error("expected requests"); - const firstProducer = firstRequest.accept(); - const secondProducer = secondRequest.accept(); + const firstProducer = firstRequest.accept({ timescale: Timescale.MILLI }); + const secondProducer = secondRequest.accept({ timescale: Timescale.MILLI }); expect(firstProducer.appendGroup().sequence).toBe(0); expect(secondProducer.appendGroup().sequence).toBe(1); @@ -117,8 +117,8 @@ test("a sibling producer's groups do not settle an aborted end", async () => { const firstRequest = await wireOf(broadcast).requested(); const secondRequest = await wireOf(broadcast).requested(); if (!firstRequest || !secondRequest) throw new Error("expected requests"); - const firstProducer = firstRequest.accept(); - const secondProducer = secondRequest.accept(); + const firstProducer = firstRequest.accept({ timescale: Timescale.MILLI }); + const secondProducer = secondRequest.accept({ timescale: Timescale.MILLI }); const reader = firstProducer.subscribe(); firstProducer.finishAt(3); @@ -143,8 +143,8 @@ test("a clean close ends at the track's own last group, not a sibling's", async const firstRequest = await wireOf(broadcast).requested(); const secondRequest = await wireOf(broadcast).requested(); if (!firstRequest || !secondRequest) throw new Error("expected requests"); - const firstProducer = firstRequest.accept(); - const secondProducer = secondRequest.accept(); + const firstProducer = firstRequest.accept({ timescale: Timescale.MILLI }); + const secondProducer = secondRequest.accept({ timescale: Timescale.MILLI }); const reader = firstProducer.subscribe(); firstProducer.appendGroup().close(); @@ -167,8 +167,8 @@ test("finishAt accepts an end below a sibling's groups", async () => { const firstRequest = await wireOf(broadcast).requested(); const secondRequest = await wireOf(broadcast).requested(); if (!firstRequest || !secondRequest) throw new Error("expected requests"); - const firstProducer = firstRequest.accept(); - const secondProducer = secondRequest.accept(); + const firstProducer = firstRequest.accept({ timescale: Timescale.MILLI }); + const secondProducer = secondRequest.accept({ timescale: Timescale.MILLI }); const reader = firstProducer.subscribe(); firstProducer.appendGroup().close(); @@ -192,7 +192,7 @@ test("closing a broadcast rejects a dequeued request", async () => { broadcast.close(); await expect(subscriber.info()).rejects.toThrow("track closed before info was known"); - const producer = request.accept(); + const producer = request.accept({ timescale: Timescale.MILLI }); expect(() => producer.appendGroup()).toThrow("track is closed"); await expect(subscriber.info()).rejects.toThrow("track closed before info was known"); subscriber.close(); @@ -275,7 +275,7 @@ test("consumer track subscriptions fan out and close independently", async () => if (!request) throw new Error("expected request"); expect(await pendingRequest(consumer)).toBeUndefined(); - const producer = request.accept(); + const producer = request.accept({ timescale: Timescale.MILLI }); producer.writeString("one"); expect(await a.readString()).toBe("one"); expect(await b.readString()).toBe("one"); @@ -289,7 +289,7 @@ test("consumer track subscriptions fan out and close independently", async () => test("subscribe serves a statically inserted track without a request", async () => { const broadcast = new BroadcastProducer(); - const track1 = new TrackProducer("track1").accept(); + const track1 = new TrackProducer("track1").accept({ timescale: Timescale.MILLI }); broadcast.insertTrack(track1); track1.appendGroup().close(); @@ -301,7 +301,7 @@ test("subscribe serves a statically inserted track without a request", async () expect(await pendingRequest(broadcast)).toBeUndefined(); // A second static track behaves the same. - const track2 = new TrackProducer("track2").accept(); + const track2 = new TrackProducer("track2").accept({ timescale: Timescale.MILLI }); broadcast.insertTrack(track2); const sub2 = broadcast.track("track2").subscribe().ordered(); @@ -311,7 +311,7 @@ test("subscribe serves a statically inserted track without a request", async () test("two subscribers to one inserted track each get a full copy", async () => { const broadcast = new BroadcastProducer(); - const producer = broadcast.createTrack("video"); + const producer = broadcast.createTrack("video", { timescale: Timescale.MILLI }); const a = broadcast .track("video") @@ -334,7 +334,7 @@ test("two subscribers to one inserted track each get a full copy", async () => { test("a late subscriber replays the cached window", async () => { const broadcast = new BroadcastProducer(); - const producer = broadcast.createTrack("video"); + const producer = broadcast.createTrack("video", { timescale: Timescale.MILLI }); // Written before anyone subscribes; retained in the cache for replay. producer.writeString("early"); @@ -348,7 +348,7 @@ test("a late subscriber replays the cached window", async () => { test("a read throws GroupTooLarge on an overflow, then resyncs to the next group", async () => { const broadcast = new BroadcastProducer(); - const producer = broadcast.createTrack("video"); + const producer = broadcast.createTrack("video", { timescale: Timescale.MILLI }); const sub = broadcast .track("video") .subscribe({ maxAge: Milli(5000) }) @@ -376,7 +376,7 @@ test("a stalled consumer does not pin evicted groups", async () => { setSystemTime(new Date(10_000)); const broadcast = new BroadcastProducer(); - const producer = broadcast.createTrack("video", { maxAge: Milli(1000) }); + const producer = broadcast.createTrack("video", { timescale: Timescale.MILLI, maxAge: Milli(1000) }); // A subscriber that never reads. Its sink must not grow without bound. const stalled = broadcast.track("video").subscribe(); @@ -405,7 +405,7 @@ test("a stalled consumer does not pin evicted groups", async () => { test("createTrack commits info up front", async () => { const broadcast = new BroadcastProducer(); - const producer = broadcast.createTrack("video", { maxAge: Milli(2000), priority: 3 }); + const producer = broadcast.createTrack("video", { timescale: Timescale.MILLI, maxAge: Milli(2000), priority: 3 }); expect(producer.name).toBe("video"); const info = await broadcast.track("video").info(); @@ -415,14 +415,14 @@ test("createTrack commits info up front", async () => { test("insertTrack rejects a duplicate live name", () => { const broadcast = new BroadcastProducer(); - broadcast.createTrack("dup"); - expect(() => broadcast.insertTrack(new TrackProducer("dup").accept())).toThrow(); + broadcast.createTrack("dup", { timescale: Timescale.MILLI }); + expect(() => broadcast.insertTrack(new TrackProducer("dup").accept({ timescale: Timescale.MILLI }))).toThrow(); }); test("a closed track is evicted and re-subscribing falls through to a request", async () => { const broadcast = new BroadcastProducer(); - const track1 = broadcast.createTrack("track1"); + const track1 = broadcast.createTrack("track1", { timescale: Timescale.MILLI }); track1.close(); // The stale entry is gone, so subscribe creates an on-demand request instead. @@ -437,13 +437,13 @@ test("a closed track is evicted and re-subscribing falls through to a request", test("removeTrack drops the static entry", async () => { // While the static entry exists, subscribing takes the fast path: no on-demand request. const kept = new BroadcastProducer(); - kept.createTrack("track1"); + kept.createTrack("track1", { timescale: Timescale.MILLI }); kept.track("track1").subscribe(); expect(await pendingRequest(kept)).toBeUndefined(); // With the entry removed, subscribing falls through to an on-demand request. const removed = new BroadcastProducer(); - removed.createTrack("track1"); + removed.createTrack("track1", { timescale: Timescale.MILLI }); removed.removeTrack("track1"); removed.track("track1").subscribe(); expect((await pendingRequest(removed))?.name).toBe("track1"); @@ -470,7 +470,7 @@ test("close rejects a still-pending track request so its subscriber unblocks", a // wants a group that already exists, and waiting for one that is gone would never return. test("a fetch waits for a group still to come", async () => { const broadcast = new BroadcastProducer(); - const track = broadcast.createTrack("video"); + const track = broadcast.createTrack("video", { timescale: Timescale.MILLI }); const pending = wireOf(broadcast).fetchGroup("video", 1); @@ -491,7 +491,7 @@ test("a fetch waits for a group still to come", async () => { test("aborting a fetch rejects with the signal's reason", async () => { const broadcast = new BroadcastProducer(); - broadcast.createTrack("video"); + broadcast.createTrack("video", { timescale: Timescale.MILLI }); const early = new Error("early"); await expect(wireOf(broadcast).fetchGroup("video", 0, { signal: AbortSignal.abort(early) })).rejects.toBe(early); @@ -510,7 +510,7 @@ test("broadcast demand watches static and pending tracks rather than broadcast h const demand = broadcast.demand(); const consumer = broadcast.consume(); expect(demand.used.peek()).toBe(false); - const video = broadcast.createTrack("video"); + const video = broadcast.createTrack("video", { timescale: Timescale.MILLI }); const first = video.subscribe(); await Promise.resolve(); expect(demand.used.peek()).toBe(true); @@ -535,7 +535,7 @@ test("broadcast demand watches static and pending tracks rather than broadcast h test("broadcast closure clears active demand and subscriptions", async () => { const broadcast = new BroadcastProducer(); - const track = broadcast.createTrack("video"); + const track = broadcast.createTrack("video", { timescale: Timescale.MILLI }); const subscriber = track.subscribe(); const demand = broadcast.demand(); await Promise.resolve(); @@ -558,7 +558,7 @@ test("a pending track info query counts as broadcast demand", async () => { if (!request) throw new Error("expected request"); // Nobody subscribes to the queried track itself. expect(request.demand().used.peek()).toBe(false); - request.accept({ priority: 2 }); + request.accept({ timescale: Timescale.MILLI, priority: 2 }); expect((await info).priority).toBe(2); await demand.unused(); expect(demand.used.peek()).toBe(false); @@ -574,7 +574,7 @@ test("a pending track info query counts as broadcast demand", async () => { test("removeTrack stops counting the removed track's demand at once", async () => { const broadcast = new BroadcastProducer(); const demand = broadcast.demand(); - const video = broadcast.createTrack("video"); + const video = broadcast.createTrack("video", { timescale: Timescale.MILLI }); const subscriber = video.subscribe(); await Promise.resolve(); expect(demand.used.peek()).toBe(true); @@ -593,7 +593,7 @@ test("removeTrack stops counting the removed track's demand at once", async () = test("inserting a closed track leaves no demand watcher behind", () => { const broadcast = new BroadcastProducer(); - const track = new TrackProducer("video").accept(); + const track = new TrackProducer("video").accept({ timescale: Timescale.MILLI }); track.close(); // Count the listeners insertTrack attaches and never disposes. diff --git a/js/net/src/connection/pool.test.ts b/js/net/src/connection/pool.test.ts index b3298ee9687..d670fae8aa3 100644 --- a/js/net/src/connection/pool.test.ts +++ b/js/net/src/connection/pool.test.ts @@ -217,7 +217,7 @@ test("a publish through one handle resolves locally for another", async () => { const origin = publisher.origin.peek(); if (!origin) throw new Error("expected an origin"); const broadcast = publish(origin, Path.from("mine")); - broadcast.createTrack("chat"); + broadcast.createTrack("chat", { timescale: Time.Timescale.MILLI }); // Loopback: the shared origin serves the page's own publish with no round trip, so the // request resolves synchronously instead of waiting on the relay to announce it back. diff --git a/js/net/src/ietf/publisher.test.ts b/js/net/src/ietf/publisher.test.ts index 0acea570e76..2499131d72a 100644 --- a/js/net/src/ietf/publisher.test.ts +++ b/js/net/src/ietf/publisher.test.ts @@ -9,7 +9,7 @@ import { createMockTransportPair } from "../mock.ts"; import { Producer as OriginProducer } from "../origin.ts"; import * as Path from "../path.ts"; import { Reader, Stream } from "../stream.ts"; -import { Milli, Timestamp } from "../time.ts"; +import { Milli, Timescale, Timestamp } from "../time.ts"; import type { Producer as TrackProducer } from "../track.ts"; import { wireOf } from "../wire.ts"; import { NativeSession, type Session } from "./adapter.ts"; @@ -256,7 +256,7 @@ test("a blocked group header is reset when the group expires", async () => { const { pub, origin } = publisher(pair.server); const broadcast = publish(origin, Path.from("test")); - const track = broadcast.createTrack("video", { maxAge: Milli(5000) }); + const track = broadcast.createTrack("video", { timescale: Timescale.MILLI, maxAge: Milli(5000) }); const client = await Stream.open(pair.client, { version: VERSION }); const server = await Stream.accept(pair.server, VERSION); if (!server) throw new Error("publisher never accepted the subscribe stream"); @@ -340,7 +340,7 @@ test("a group that goes stale while its stream opens writes nothing", async () = const { pub, origin } = publisher(pair.server); const broadcast = publish(origin, Path.from("test")); - const track = broadcast.createTrack("video", { maxAge: Milli(5000) }); + const track = broadcast.createTrack("video", { timescale: Timescale.MILLI, maxAge: Milli(5000) }); const client = await Stream.open(pair.client, { version: VERSION }); const server = await Stream.accept(pair.server, VERSION); if (!server) throw new Error("publisher never accepted the subscribe stream"); @@ -1482,7 +1482,7 @@ test("subscription completion sends PUBLISH_DONE on every supported draft", asyn const path = Path.from("test"); const { pub, origin } = publisher(pair.server, { session }); const broadcast = publish(origin, path); - const track = broadcast.createTrack("video"); + const track = broadcast.createTrack("video", { timescale: Timescale.MILLI }); const client = await Stream.open(pair.client, { version }); const server = await Stream.accept(pair.server, version); @@ -1719,7 +1719,7 @@ async function readFill(stream: ReadableStream): Promise */ test("draft-20: an absolute filter trims the range it serves", async () => { const fx = fixture(); - const track = fx.broadcast.createTrack("video"); + const track = fx.broadcast.createTrack("video", { timescale: Timescale.MILLI }); for (let i = 0; i < 4; i++) writeGroup(track, 3); const { client } = await runSubscribe( @@ -1775,7 +1775,7 @@ test("draft-20: an absolute filter trims the range it serves", async () => { */ test("draft-20: a fill serves the current group's head on a fetch stream", async () => { const fx = fixture(); - const track = fx.broadcast.createTrack("video"); + const track = fx.broadcast.createTrack("video", { timescale: Timescale.MILLI }); const group = track.appendGroup(); for (let i = 0; i < 2; i++) { @@ -1832,7 +1832,7 @@ test("draft-20: a fill serves the current group's head on a fetch stream", async */ test("draft-20: an open group that outgrew its cache aborts instead of serving a tail", async () => { const fx = fixture(); - const track = fx.broadcast.createTrack("video"); + const track = fx.broadcast.createTrack("video", { timescale: Timescale.MILLI }); const group = track.appendGroup(); for (let i = 0; i < MAX_GROUP_FRAMES; i++) { @@ -1872,7 +1872,7 @@ test("draft-20: an open group that outgrew its cache aborts instead of serving a */ test("draft-20: a backwards range within one group serves nothing and ends the stream", async () => { const fx = fixture(); - const track = fx.broadcast.createTrack("video"); + const track = fx.broadcast.createTrack("video", { timescale: Timescale.MILLI }); // Deliberately left open: a hang here would outlive the group rather than end with it. const group = track.appendGroup(); @@ -1908,7 +1908,7 @@ test("draft-20: a backwards range within one group serves nothing and ends the s */ test("draft-20: a fill spanning several groups resets its stream", async () => { const fx = fixture(); - const track = fx.broadcast.createTrack("video"); + const track = fx.broadcast.createTrack("video", { timescale: Timescale.MILLI }); for (let i = 0; i < 3; i++) writeGroup(track, 2); const { client } = await runSubscribe( @@ -1939,7 +1939,7 @@ test("draft-20: a fill spanning several groups resets its stream", async () => { /** A fill against a track with nothing published has an empty range: no stream is owed. */ test("draft-20: an empty track opens no fill stream", async () => { const fx = fixture(); - fx.broadcast.createTrack("video"); + fx.broadcast.createTrack("video", { timescale: Timescale.MILLI }); const { client, ok } = await runSubscribe( fx, @@ -1968,7 +1968,7 @@ test("draft-20: an empty track opens no fill stream", async () => { */ async function subscribeOkLargest(version: IetfVersion): Promise { const fx = fixture(version); - const track = fx.broadcast.createTrack("video"); + const track = fx.broadcast.createTrack("video", { timescale: Timescale.MILLI }); const group = new GroupProducer(5); track.writeGroup(group); @@ -2025,7 +2025,7 @@ test("draft-20: LARGEST_OBJECT is the live edge", async () => { test("draft-20: an opt-out peer gets no track properties", async () => { for (const propertiesWanted of [true, false]) { const fx = fixture(); - const track = fx.broadcast.createTrack("video"); + const track = fx.broadcast.createTrack("video", { timescale: Timescale.MILLI }); const { client, ok } = await runSubscribe( fx, @@ -2071,7 +2071,7 @@ test("draft-20: an opt-out peer gets no track properties", async () => { test("drafts 14-16 send no Timestamp without TIMESCALE", async () => { for (const version of [Version.DRAFT_14, Version.DRAFT_15, Version.DRAFT_16, Version.DRAFT_17] as const) { const fx = fixture(version); - const track = fx.broadcast.createTrack("video"); + const track = fx.broadcast.createTrack("video", { timescale: Timescale.MILLI }); const { client, ok } = await runSubscribe( fx, new Subscribe({ @@ -2113,7 +2113,7 @@ test("drafts 14-16 send no Timestamp without TIMESCALE", async () => { */ test("draft-20: a clean close past a bounded filter's end still sends PUBLISH_DONE", async () => { const fx = fixture(); - const track = fx.broadcast.createTrack("video"); + const track = fx.broadcast.createTrack("video", { timescale: Timescale.MILLI }); writeGroup(track, 1); // group 0, the whole requested range const { client } = await runSubscribe( @@ -2160,7 +2160,7 @@ test("draft-20: a clean close past a bounded filter's end still sends PUBLISH_DO */ test("draft-20: the subscriber leaving ends a fill still reading its group", async () => { const fx = fixture(); - const track = fx.broadcast.createTrack("video"); + const track = fx.broadcast.createTrack("video", { timescale: Timescale.MILLI }); // Group 0 stays open, so a fill over it has no end of its own to wait for. Group 1 puts // the live edge above it, which is what leaves the requested end object unset. @@ -2218,7 +2218,7 @@ test("draft-20: a fill works on a dynamically requested track", async () => { const serving = (async () => { const request = await wireOf(fx.broadcast).requested(); if (!request) throw new Error("no track was requested"); - const track = request.accept(); + const track = request.accept({ timescale: Timescale.MILLI }); const group = track.appendGroup(); for (let i = 0; i < 2; i++) { group.writeFrame({ payload: new TextEncoder().encode(`0.${i}`), timestamp: Timestamp.now() }); @@ -2263,7 +2263,7 @@ test("draft-20: a fill works on a dynamically requested track", async () => { // Stream Count is final. A group still queued for a stream slot when the track ends is one. test("draft-20: PUBLISH_DONE waits for a queued group and counts every stream", async () => { const fx = fixture(); - const track = fx.broadcast.createTrack("video"); + const track = fx.broadcast.createTrack("video", { timescale: Timescale.MILLI }); // Park the first stream open, the way a transport at its stream cap does. const slot = Promise.withResolvers(); @@ -2386,7 +2386,7 @@ for (const version of [Version.DRAFT_15, Version.DRAFT_19] as const) { test("requester FIN keeps a draft-19 subscription serving; STOP_SENDING cancels it", async () => { const fx = fixture(Version.DRAFT_19); - const track = fx.broadcast.createTrack("video"); + const track = fx.broadcast.createTrack("video", { timescale: Timescale.MILLI }); const client = await Stream.open(fx.pair.client, { version: fx.version }); const server = await Stream.accept(fx.pair.server, fx.version); if (!server) throw new Error("missing stream"); @@ -2423,7 +2423,7 @@ test("requester FIN keeps a draft-19 subscription serving; STOP_SENDING cancels for (const version of [Version.DRAFT_17, Version.DRAFT_18] as const) { test(`requester FIN cancels a ${version.toString(16)} subscription`, async () => { const fx = fixture(version); - const track = fx.broadcast.createTrack("video"); + const track = fx.broadcast.createTrack("video", { timescale: Timescale.MILLI }); const client = await Stream.open(fx.pair.client, { version: fx.version }); const server = await Stream.accept(fx.pair.server, fx.version); if (!server) throw new Error("missing stream"); @@ -2452,7 +2452,7 @@ for (const version of [Version.DRAFT_17, Version.DRAFT_18] as const) { test("REQUEST_UPDATE applies priority and preserves it when omitted", async () => { const fx = fixture(Version.DRAFT_19); - const track = fx.broadcast.createTrack("video"); + const track = fx.broadcast.createTrack("video", { timescale: Timescale.MILLI }); const { client } = await runSubscribe( fx, new Subscribe({ @@ -2484,7 +2484,7 @@ test("REQUEST_UPDATE applies priority and preserves it when omitted", async () = test("unsupported REQUEST_UPDATE is refused and ends with UPDATE_FAILED", async () => { const fx = fixture(Version.DRAFT_19); - const track = fx.broadcast.createTrack("video"); + const track = fx.broadcast.createTrack("video", { timescale: Timescale.MILLI }); const { client } = await runSubscribe( fx, new Subscribe({ diff --git a/js/net/src/ietf/publisher.ts b/js/net/src/ietf/publisher.ts index 9ddd05638ac..6b3837821e9 100644 --- a/js/net/src/ietf/publisher.ts +++ b/js/net/src/ietf/publisher.ts @@ -363,8 +363,7 @@ export class Publisher { const info = await track.info(); // A Timestamp goes out only when this SUBSCRIBE_OK actually carries TIMESCALE. // Drafts 14-16 never write that property, so their objects stay unstamped. - const timescale = - msg.propertiesWanted && Properties.sendsTimescale(version) ? (info.timescale ?? undefined) : undefined; + const timescale = msg.propertiesWanted && Properties.sendsTimescale(version) ? info.timescale : undefined; // The model ranks higher-first, the IETF wire lower-first. Every group this // subscription serves carries the same publisher priority, which is what lets a // relay prefer catalog and audio over video when it has no subscriber preference @@ -426,7 +425,7 @@ export class Publisher { // send it. We serve the newest group first, matching moq-lite. { // An untimed track declares none, so it stays untimed downstream. - timescale: info.timescale ?? undefined, + timescale: info.timescale, priority: publisherPriority, groupOrder: Properties.DESCENDING, maxCacheDuration: info.maxAge === undefined ? undefined : BigInt(info.maxAge), diff --git a/js/net/src/ietf/subscriber.test.ts b/js/net/src/ietf/subscriber.test.ts index ea0615c3369..4116d756b86 100644 --- a/js/net/src/ietf/subscriber.test.ts +++ b/js/net/src/ietf/subscriber.test.ts @@ -913,7 +913,7 @@ function stampedGroup(groupId: number): GroupMessage { test("a track without TIMESCALE arrives untimed, even if an object carries a Timestamp", async () => { const { subscriber, track } = await subscribeTrack(); - expect((await track.info()).timescale).toBeNull(); + expect((await track.info()).timescale).toBeUndefined(); // Property 0x10 (Timestamp) = 5, with no units to read it in. await subscriber.handleGroup(stampedGroup(0), new Reader(undefined, encodeStamped([0x10, 5]), VERSION)); diff --git a/js/net/src/ietf/subscriber.ts b/js/net/src/ietf/subscriber.ts index 14670e71f0d..f38e9f3be0b 100644 --- a/js/net/src/ietf/subscriber.ts +++ b/js/net/src/ietf/subscriber.ts @@ -799,7 +799,7 @@ export class Subscriber { request.accept({ // No TIMESCALE (always so on drafts 14-16, which can't carry it) means no timeline, // and the track must not claim one when served onward. - timescale: ok.properties.timescale ?? null, + timescale: ok.properties.timescale, priority: fromWire(ok.properties.priority ?? 128), maxAge: maxCacheDuration === undefined ? undefined : Milli(Number(maxCacheDuration)), }); diff --git a/js/net/src/integration.test.ts b/js/net/src/integration.test.ts index 7c828cb486f..af59cfa3412 100644 --- a/js/net/src/integration.test.ts +++ b/js/net/src/integration.test.ts @@ -86,7 +86,7 @@ async function runPublishSubscribeFlow(protocol: string, version?: number) { continue; } served++; - req.accept().writeString("hello"); + req.accept({ timescale: Timescale.MILLI }).writeString("hello"); } })(); @@ -160,7 +160,7 @@ test("integration: lite subscription options and updates reach the publisher", a for (;;) { const request = await wireOf(broadcast).requested(); if (!request) return; - const producer = request.accept(); + const producer = request.accept({ timescale: Timescale.MILLI }); if (request.subscription.groups?.start?.included === 1) resolveProducer?.(producer); } })(); @@ -218,7 +218,7 @@ test("integration: lite carries a fractional maxAge as a whole millisecond", asy for (;;) { const request = await wireOf(broadcast).requested(); if (!request) return; - const producer = request.accept(); + const producer = request.accept({ timescale: Timescale.MILLI }); if (request.subscription.groups?.start?.included === 1) resolveProducer?.(producer); } })(); @@ -269,7 +269,7 @@ test("integration: lite applies initial and updated group bounds", async () => { ]); const broadcast = publish(origin, Path.from("test")); - const producer = broadcast.createTrack("video"); + const producer = broadcast.createTrack("video", { timescale: Timescale.MILLI }); for (let sequence = 0; sequence < GROUP_COUNT; sequence++) producer.appendGroup().close(); const remote = wireOf(client).consume(Path.from("test")); @@ -319,7 +319,7 @@ test("integration: lite refuses an empty requested range on open and on update", ]); const broadcast = publish(origin, Path.from("test")); - const producer = broadcast.createTrack("video"); + const producer = broadcast.createTrack("video", { timescale: Timescale.MILLI }); for (let sequence = 0; sequence < GROUP_COUNT; sequence++) producer.appendGroup().close(); const remote = wireOf(client).consume(Path.from("test")); @@ -844,7 +844,7 @@ test("integration: lite draft-05 fetches a cached group", async () => { ]); const broadcast = publish(origin, Path.from("test")); - const producer = broadcast.createTrack("video"); + const producer = broadcast.createTrack("video", { timescale: Timescale.MILLI }); const group0 = producer.appendGroup(); group0.writeFrame({ payload: enc.encode("alpha"), timestamp: Timestamp.fromMillis(10) }); @@ -885,7 +885,7 @@ test.each(["gap", "end"])("integration: lite fetch rejects coalesced misses at % const broadcast = publish(origin, Path.from("test")); let serving: Promise | undefined; if (missing === "gap") { - const producer = broadcast.createTrack("video"); + const producer = broadcast.createTrack("video", { timescale: Timescale.MILLI }); const group = new GroupProducer(1); producer.writeGroup(group); group.close(); @@ -894,7 +894,7 @@ test.each(["gap", "end"])("integration: lite fetch rejects coalesced misses at % for (;;) { const request = await wireOf(broadcast).requested(); if (!request) return; - request.accept().close(); + request.accept({ timescale: Timescale.MILLI }).close(); } })(); } @@ -929,7 +929,7 @@ test.each(["frame", "FIN"])("integration: lite fetch waits for the publisher's f accept(pair.server, url, { publish: origin.consume() }), ]); const broadcast = publish(origin, Path.from("test")); - const producer = broadcast.createTrack("video"); + const producer = broadcast.createTrack("video", { timescale: Timescale.MILLI }); const group = producer.appendGroup(); const remote = wireOf(client).consume(Path.from("test")); try { @@ -976,7 +976,7 @@ test("integration: lite draft-05 coalesces concurrent fetches of one group", asy ]); const broadcast = publish(origin, Path.from("test")); - const producer = broadcast.createTrack("video"); + const producer = broadcast.createTrack("video", { timescale: Timescale.MILLI }); const group0 = producer.appendGroup(); group0.writeFrame({ payload: enc.encode("alpha"), timestamp: Timestamp.fromMillis(10) }); @@ -1020,7 +1020,7 @@ test("integration: lite draft-05 fetches an in-progress group", async () => { ]); const broadcast = publish(origin, Path.from("test")); - const producer = broadcast.createTrack("video"); + const producer = broadcast.createTrack("video", { timescale: Timescale.MILLI }); // Open the group and write one frame, but leave it open (in-progress). const group0 = producer.appendGroup(); @@ -1171,7 +1171,7 @@ test("integration: ietf SUBSCRIBE_TRACKS is refused per request", async () => { for (;;) { const req = await wireOf(broadcast).requested(); if (!req) break; - const track = req.accept(); + const track = req.accept({ timescale: Timescale.MILLI }); track.writeString("before"); served.push(track); } @@ -1280,7 +1280,7 @@ async function runSubscriberTeardown(protocol: string, version?: number) { ]); const broadcast = publish(origin, Path.from("test")); - const video = broadcast.createTrack("video"); + const video = broadcast.createTrack("video", { timescale: Timescale.MILLI }); video.writeString("hello"); const remote = wireOf(client).consume(Path.from("test")); @@ -1327,7 +1327,7 @@ test("integration: ietf draft-14 subscriber teardown on last unsubscribe", async for (;;) { const req = await wireOf(broadcast).requested(); if (!req) break; - served = req.accept(); + served = req.accept({ timescale: Timescale.MILLI }); served.writeString("hello"); } })(); @@ -1364,7 +1364,7 @@ test("integration: lite fetch teardown when the reader abandons an open group", ]); const broadcast = publish(origin, Path.from("test")); - const video = broadcast.createTrack("video"); + const video = broadcast.createTrack("video", { timescale: Timescale.MILLI }); const group = video.appendGroup(); // deliberately left open: an indefinite group. group.writeString("hello"); @@ -1404,7 +1404,7 @@ test("integration: lite fan-out keeps the upstream until the last subscriber lea ]); const broadcast = publish(origin, Path.from("test")); - const video = broadcast.createTrack("video"); + const video = broadcast.createTrack("video", { timescale: Timescale.MILLI }); video.writeString("hello"); const remote = wireOf(client).consume(Path.from("test")); @@ -1441,7 +1441,7 @@ test("integration: lite re-subscribe re-opens the upstream after each teardown", ]); const broadcast = publish(origin, Path.from("test")); - const video = broadcast.createTrack("video"); + const video = broadcast.createTrack("video", { timescale: Timescale.MILLI }); const remote = wireOf(client).consume(Path.from("test")); @@ -1472,7 +1472,7 @@ test("integration: lite coalesced fetch stays until every reader abandons the op ]); const broadcast = publish(origin, Path.from("test")); - const video = broadcast.createTrack("video"); + const video = broadcast.createTrack("video", { timescale: Timescale.MILLI }); const group = video.appendGroup(); // open group.writeString("hello"); @@ -1512,7 +1512,7 @@ test("integration: lite fetch re-armed by a late reader keeps every frame", asyn ]); const broadcast = publish(origin, Path.from("test")); - const video = broadcast.createTrack("video"); + const video = broadcast.createTrack("video", { timescale: Timescale.MILLI }); const remote = wireOf(client).consume(Path.from("test")); for (let delay = 0; delay <= 12; delay++) { @@ -1555,7 +1555,7 @@ test("integration: lite fetch delivers every frame of a finite multi-frame group ]); const broadcast = publish(origin, Path.from("test")); - const video = broadcast.createTrack("video"); + const video = broadcast.createTrack("video", { timescale: Timescale.MILLI }); const group = video.appendGroup(); const count = 50; for (let i = 0; i < count; i++) group.writeString(`f${i}`); @@ -1596,7 +1596,7 @@ async function runSubscribeWithoutWarmup(version: number) { const broadcast = publish(origin, Path.from("test")); const serving = (async () => { const req = await wireOf(broadcast).requested(); - if (req) req.accept().writeString("hello"); + if (req) req.accept({ timescale: Timescale.MILLI }).writeString("hello"); })(); const remote = wireOf(client).consume(Path.from("test")); @@ -1675,7 +1675,7 @@ test("integration: an announced request waits for a late publisher", async () => for (;;) { const req = await wireOf(broadcast).requested(); if (!req) break; - req.accept().writeString(payload); + req.accept({ timescale: Timescale.MILLI }).writeString(payload); } }; @@ -1732,7 +1732,7 @@ test("integration: an announced request consumes blind without discovery", async for (;;) { const req = await wireOf(broadcast).requested(); if (!req) break; - req.accept().writeString("blind"); + req.accept({ timescale: Timescale.MILLI }).writeString("blind"); } })(); @@ -1763,7 +1763,7 @@ test("integration: a republish is not served from the previous generation's cach for (;;) { const req = await wireOf(broadcast).requested(); if (!req) break; - req.accept().writeString(payload); + req.accept({ timescale: Timescale.MILLI }).writeString(payload); } }; @@ -1823,7 +1823,7 @@ async function runRepublishCycle(protocol: string, version?: number) { for (;;) { const req = await wireOf(broadcast).requested(); if (!req) break; - req.accept().writeString(payload); + req.accept({ timescale: Timescale.MILLI }).writeString(payload); } }; @@ -1895,7 +1895,7 @@ test("integration: a blind handle picks up a publisher that arrives late", async for (;;) { const req = await wireOf(producer).requested(); if (!req) break; - req.accept().writeString("late"); + req.accept({ timescale: Timescale.MILLI }).writeString("late"); } })(); @@ -1955,7 +1955,7 @@ test("integration: ietf blind handle picks up a publisher that arrives late", as for (;;) { const req = await wireOf(producer).requested(); if (!req) break; - req.accept().writeString("ietf-late"); + req.accept({ timescale: Timescale.MILLI }).writeString("ietf-late"); } })(); @@ -2002,7 +2002,7 @@ async function runOriginFlow(protocol: string, version?: number) { req.reject(new Error(`unexpected track: ${req.name}`)); continue; } - req.accept().writeString("hello"); + req.accept({ timescale: Timescale.MILLI }).writeString("hello"); } })(); @@ -2095,7 +2095,7 @@ test("origin: one origin on both directions consumes locally and never echoes", // The client publishes; consuming its own path through the shared origin is local, no wire. const mine = publish(shared, Path.from("from-client")); - mine.createTrack("chat"); + mine.createTrack("chat", { timescale: Timescale.MILLI }); const reader = shared.consume(); const loopback = await routed(reader, Path.from("from-client")); if (!loopback) throw new Error("expected a local route"); @@ -2137,7 +2137,7 @@ test("origin: a request resolves blind on a relay without discovery", async () = for (;;) { const req = await wireOf(broadcast).requested(); if (!req) break; - req.accept().writeString("found you"); + req.accept({ timescale: Timescale.MILLI }).writeString("found you"); } })(); @@ -2265,7 +2265,7 @@ test("origin: overlapping sessions carrying one path fail over", async () => { for (;;) { const req = await wireOf(broadcast).requested(); if (!req) break; - req.accept().writeString("still here"); + req.accept({ timescale: Timescale.MILLI }).writeString("still here"); } })(); return { client, server, serverOrigin, broadcast, serving }; @@ -2315,7 +2315,7 @@ test("origin: a standby session re-answers a request when the answerer dies", as for (;;) { const req = await wireOf(broadcast).requested(); if (!req) break; - req.accept().writeString(payload); + req.accept({ timescale: Timescale.MILLI }).writeString(payload); } })(); return { client, server, serverOrigin, broadcast, serving }; @@ -2364,7 +2364,7 @@ test("create then announce is discoverable on the wire", async () => { const announced = client.announced(); const broadcast = origin.createBroadcast(Path.from("later")); - broadcast.createTrack("chat"); + broadcast.createTrack("chat", { timescale: Timescale.MILLI }); const pending = announced.next(); broadcast.announce(); @@ -2387,7 +2387,7 @@ test("a handle serves a request under live/** over the wire", async () => { const serving = (async () => { for await (const request of handle.requested()) { const produced = new BroadcastProducer(); - produced.createTrack("chat").writeString("hello"); + produced.createTrack("chat", { timescale: Timescale.MILLI }).writeString("hello"); request.accept(produced); } })(); @@ -2441,7 +2441,7 @@ async function runSessionDeath( for (;;) { const req = await wireOf(broadcast).requested(); if (!req) break; - req.accept().appendGroup().writeString("head"); + req.accept({ timescale: Timescale.MILLI }).appendGroup().writeString("head"); } })(); @@ -2501,7 +2501,7 @@ test("integration: lite draft-05 ends a track with the publisher's reset", async for (;;) { const req = await wireOf(broadcast).requested(); if (!req) break; - const producer = req.accept(); + const producer = req.accept({ timescale: Timescale.MILLI }); producer.appendGroup().writeString("head"); served.push(producer); } diff --git a/js/net/src/lite/connection.test.ts b/js/net/src/lite/connection.test.ts index 5bc9afd83ad..67f0591596e 100644 --- a/js/net/src/lite/connection.test.ts +++ b/js/net/src/lite/connection.test.ts @@ -6,6 +6,7 @@ import { createMockTransportPair, type MockTransport } from "../mock.ts"; import { Producer } from "../origin.ts"; import * as Path from "../path.ts"; import { Stream, Writer } from "../stream.ts"; +import { Timescale } from "../time.ts"; import { wireOf } from "../wire.ts"; import { Connection, probeLevel } from "./connection.ts"; import { Fetch } from "./fetch.ts"; @@ -209,7 +210,7 @@ for (const alpn of [ALPN_05, ALPN_06, ALPN_07_WIP]) { const origin = new Producer(); const broadcast = origin.createBroadcast(Path.from("room")); broadcast.announce(); - const producer = broadcast.createTrack("video"); + const producer = broadcast.createTrack("video", { timescale: Timescale.MILLI }); const url = new URL("https://localhost/test"); const [client, server] = await Promise.all([ connect({ url, transport: pair.client }), @@ -259,7 +260,7 @@ async function servedRawSubscription() { const origin = new Producer(); const broadcast = origin.createBroadcast(Path.from("room")); broadcast.announce(); - const producer = broadcast.createTrack("video"); + const producer = broadcast.createTrack("video", { timescale: Timescale.MILLI }); const server = new Connection({ url: new URL("https://relay.example/"), quic: pair.server, @@ -366,7 +367,7 @@ test("close waits for a served FETCH to be acknowledged", async () => { const origin = new Producer(); const broadcast = origin.createBroadcast(Path.from("room")); broadcast.announce(); - const producer = broadcast.createTrack("video"); + const producer = broadcast.createTrack("video", { timescale: Timescale.MILLI }); const group = producer.appendGroup(); group.writeString("last"); group.close(); @@ -418,7 +419,7 @@ test("close waits for a request served while withdrawals are in flight", async ( const destination = new Producer(); const broadcast = source.createBroadcast(Path.from("room")); broadcast.announce(); - const producer = broadcast.createTrack("video"); + const producer = broadcast.createTrack("video", { timescale: Timescale.MILLI }); const group = producer.appendGroup(); group.writeString("last"); group.close(); diff --git a/js/net/src/lite/priority.test.ts b/js/net/src/lite/priority.test.ts index 25733b381de..db70ad2a906 100644 --- a/js/net/src/lite/priority.test.ts +++ b/js/net/src/lite/priority.test.ts @@ -1,6 +1,7 @@ import { expect, test } from "bun:test"; import { Producer as BroadcastProducer } from "../broadcast.ts"; import { type SendStream, Writer } from "../stream.ts"; +import { Timescale } from "../time.ts"; import { Priority, sendOrder } from "./priority.ts"; import { Version } from "./version.ts"; @@ -57,7 +58,7 @@ test("out of range ranks stay inside their own bits", () => { // group already on the wire keeps writing after the track stops handing out new ones. function ranking(options: { priority?: number; ordered?: boolean } = {}) { const broadcast = new BroadcastProducer(); - const track = broadcast.createTrack("video"); + const track = broadcast.createTrack("video", { timescale: Timescale.MILLI }); const subscriber = track.subscribe(options); // The send order lands on the underlying stream, exactly as it would on a real one. diff --git a/js/net/src/lite/publisher.test.ts b/js/net/src/lite/publisher.test.ts index 81492ed6a91..92060861cda 100644 --- a/js/net/src/lite/publisher.test.ts +++ b/js/net/src/lite/publisher.test.ts @@ -7,7 +7,7 @@ import { createMockTransportPair } from "../mock.ts"; import { Producer as OriginProducer } from "../origin.ts"; import * as Path from "../path.ts"; import { Reader, Stream, Writer } from "../stream.ts"; -import { Milli, Timestamp } from "../time.ts"; +import { Milli, Timescale, Timestamp } from "../time.ts"; import { AnnounceRequest } from "./announce.ts"; import { Fetch } from "./fetch.ts"; import { Group as GroupMessage } from "./group.ts"; @@ -131,7 +131,7 @@ async function subscribeEnd(sequences: number[], version: Version = Version.DRAF const publisher = new Publisher(pair.server, version, randomHop(), origin.consume()); const broadcast = publish(origin, Path.from("test")); - const track = broadcast.createTrack("video"); + const track = broadcast.createTrack("video", { timescale: Timescale.MILLI }); const client = await Stream.open(pair.client, { version }); const server = await Stream.accept(pair.server, version); @@ -194,7 +194,7 @@ async function groupSendOrders(options: { priority: number; sequences: number[]; const publisher = new Publisher(pair.server, Version.DRAFT_05, randomHop(), origin.consume()); const broadcast = publish(origin, Path.from("test")); - const track = broadcast.createTrack("video"); + const track = broadcast.createTrack("video", { timescale: Timescale.MILLI }); const client = await Stream.open(pair.client, { version: Version.DRAFT_05 }); const server = await Stream.accept(pair.server, Version.DRAFT_05); @@ -278,7 +278,7 @@ test("lite draft-05: a subscribe update re-ranks a group already on the wire", a const publisher = new Publisher(pair.server, Version.DRAFT_05, randomHop(), origin.consume()); const broadcast = publish(origin, Path.from("test")); - const track = broadcast.createTrack("video"); + const track = broadcast.createTrack("video", { timescale: Timescale.MILLI }); const client = await Stream.open(pair.client, { version: Version.DRAFT_05 }); const server = await Stream.accept(pair.server, Version.DRAFT_05); @@ -331,7 +331,7 @@ test("lite draft-05: a subscribe update during the stream open still ranks the g const publisher = new Publisher(pair.server, Version.DRAFT_05, randomHop(), origin.consume()); const broadcast = publish(origin, Path.from("test")); - const track = broadcast.createTrack("video"); + const track = broadcast.createTrack("video", { timescale: Timescale.MILLI }); // Hold the group's stream open call until the test releases it. let release: () => void = () => {}; @@ -391,7 +391,7 @@ test("lite draft-05: many concurrent groups share one subscription listener", as const publisher = new Publisher(pair.server, Version.DRAFT_05, randomHop(), origin.consume()); const broadcast = publish(origin, Path.from("test")); - const track = broadcast.createTrack("video"); + const track = broadcast.createTrack("video", { timescale: Timescale.MILLI }); const client = await Stream.open(pair.client, { version: Version.DRAFT_05 }); const server = await Stream.accept(pair.server, Version.DRAFT_05); @@ -445,7 +445,7 @@ test("lite draft-05: the fetch response ranks the publisher's own writes", async const publisher = new Publisher(pair.server, Version.DRAFT_05, randomHop(), origin.consume()); const broadcast = publish(origin, Path.from("test")); - const track = broadcast.createTrack("video"); + const track = broadcast.createTrack("video", { timescale: Timescale.MILLI }); const group = new GroupProducer(7); group.writeString("hello"); @@ -544,7 +544,7 @@ async function servedSubscription( const publisher = new Publisher(pair.server, version, randomHop(), origin.consume()); const broadcast = publish(origin, Path.from("test")); - const track = broadcast.createTrack("video", { maxAge: options.maxAge }); + const track = broadcast.createTrack("video", { timescale: Timescale.MILLI, maxAge: options.maxAge }); const client = await Stream.open(pair.client, { version: version }); @@ -1045,7 +1045,7 @@ test("lite draft-07: subscribe end waits for groups below a declared finish", as const origin = new OriginProducer(); const publisher = new Publisher(pair.server, Version.DRAFT_07, randomHop(), origin.consume()); const broadcast = publish(origin, Path.from("test")); - const track = broadcast.createTrack("video"); + const track = broadcast.createTrack("video", { timescale: Timescale.MILLI }); const client = await Stream.open(pair.client, { version: Version.DRAFT_07 }); const server = await Stream.accept(pair.server, Version.DRAFT_07); @@ -1090,7 +1090,7 @@ async function heldOpenEnd() { const origin = new OriginProducer(); const publisher = new Publisher(pair.server, Version.DRAFT_07, randomHop(), origin.consume()); const broadcast = publish(origin, Path.from("test")); - const track = broadcast.createTrack("video"); + const track = broadcast.createTrack("video", { timescale: Timescale.MILLI }); let open!: (ok: boolean) => void; const opened = new Promise((resolve) => { @@ -1177,7 +1177,7 @@ async function serve( const publisher = new Publisher(pair.server, Version.DRAFT_06, randomHop(), origin.consume()); const broadcast = publish(origin, Path.from("test")); - const track = broadcast.createTrack("video"); + const track = broadcast.createTrack("video", { timescale: Timescale.MILLI }); const client = await Stream.open(pair.client, { version: Version.DRAFT_06 }); const server = await Stream.accept(pair.server, Version.DRAFT_06); @@ -1366,7 +1366,7 @@ async function saturatedGroup() { const origin = new OriginProducer(); const publisher = new Publisher(pair.server, Version.DRAFT_05, randomHop(), origin.consume()); const broadcast = publish(origin, Path.from("test")); - const track = broadcast.createTrack("video"); + const track = broadcast.createTrack("video", { timescale: Timescale.MILLI }); const client = await Stream.open(pair.client, { version: Version.DRAFT_05 }); const server = await Stream.accept(pair.server, Version.DRAFT_05); @@ -1446,7 +1446,7 @@ test("lite draft-05: a blocked group header is reset when the group expires", as const origin = new OriginProducer(); const publisher = new Publisher(pair.server, Version.DRAFT_05, randomHop(), origin.consume()); const broadcast = publish(origin, Path.from("test")); - const track = broadcast.createTrack("video"); + const track = broadcast.createTrack("video", { timescale: Timescale.MILLI }); const client = await Stream.open(pair.client, { version: Version.DRAFT_05 }); const server = await Stream.accept(pair.server, Version.DRAFT_05); if (!server) throw new Error("publisher never accepted the subscribe stream"); @@ -1576,7 +1576,7 @@ test("lite draft-05: a group that goes stale while its stream opens writes nothi const origin = new OriginProducer(); const publisher = new Publisher(pair.server, Version.DRAFT_05, randomHop(), origin.consume()); const broadcast = publish(origin, Path.from("test")); - const track = broadcast.createTrack("video"); + const track = broadcast.createTrack("video", { timescale: Timescale.MILLI }); let requested!: () => void; const opening = new Promise((resolve) => { @@ -1649,7 +1649,7 @@ test.each([0, 1])("lite draft-07 reports the cached largest position when starti const origin = new OriginProducer(); const publisher = new Publisher(pair.server, version, randomHop(), origin.consume()); const broadcast = publish(origin, Path.from("quiet")); - const track = broadcast.createTrack("video"); + const track = broadcast.createTrack("video", { timescale: Timescale.MILLI }); const group = new GroupProducer(0); group.writeString("cached"); group.close(); diff --git a/js/net/src/lite/publisher.ts b/js/net/src/lite/publisher.ts index e1fa202e6d2..049bb5262f0 100644 --- a/js/net/src/lite/publisher.ts +++ b/js/net/src/lite/publisher.ts @@ -52,8 +52,8 @@ function zigzag(delta: bigint): bigint { } /** - * The timescale TRACK_INFO declares for a track. Lite05+ requires one, so a track without a - * timeline declares the default, the scale its frames' send times go out at. + * The timescale TRACK_INFO declares for a track. Lite05+ requires one, so an untimed track + * declares milliseconds, the scale its frames' send times go out at. */ function wireTimescale(info: track.Info): Timescale { return info.timescale ?? Timescale.MILLI; diff --git a/js/net/src/lite/subscriber.ts b/js/net/src/lite/subscriber.ts index 9df49edec23..f0517fc650d 100644 --- a/js/net/src/lite/subscriber.ts +++ b/js/net/src/lite/subscriber.ts @@ -656,7 +656,7 @@ export class Subscriber { timescale.set(info.timescale); } else { // Older drafts negotiate nothing per-track: verbatim frames with no timeline. - producer = request.accept({ timescale: null }); + producer = request.accept(); timescale.set(0); drainOk = true; } diff --git a/js/net/src/lite/track.test.ts b/js/net/src/lite/track.test.ts index a980cd193e5..f60ffcaab9f 100644 --- a/js/net/src/lite/track.test.ts +++ b/js/net/src/lite/track.test.ts @@ -1,7 +1,7 @@ import { expect, test } from "bun:test"; import * as Path from "../path.ts"; import { Reader, Writer } from "../stream.ts"; -import { Milli } from "../time.ts"; +import { Milli, Timescale } from "../time.ts"; import { infoDefaults } from "../track.ts"; import { Track, TrackInfo } from "./track.ts"; import { Version } from "./version.ts"; @@ -46,9 +46,9 @@ test("TrackInfo round-trips on draft-05", async () => { expect(got.timescale).toBe(90000); }); -test("TrackInfo defaults match cross-language wire bytes", async () => { - const defaults = infoDefaults(); - const info = new TrackInfo({ ...defaults, timescale: defaults.timescale ?? undefined }); +test("TrackInfo for Rust's default Info matches cross-language wire bytes", async () => { + // Rust's `Info::default()` is millisecond-timed; JS has no default timescale. + const info = new TrackInfo(infoDefaults({ timescale: Timescale.MILLI })); expect(await bytes((w) => info.encode(w, Version.DRAFT_05), Version.DRAFT_05)).toEqual( new Uint8Array([0x0c, 0x7f, 0x00, 0xc0, 0x1f, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0x43, 0xe8]), ); diff --git a/js/net/src/origin.test.ts b/js/net/src/origin.test.ts index f1254022dd9..9d71b65a4b4 100644 --- a/js/net/src/origin.test.ts +++ b/js/net/src/origin.test.ts @@ -8,6 +8,7 @@ import { spreadHash } from "./internal.ts"; import type { Consumer, Table } from "./origin.ts"; import { Producer } from "./origin.ts"; import * as Path from "./path.ts"; +import { Timescale } from "./time.ts"; import { wireOf } from "./wire.ts"; function publish(origin: Producer, path: Path.Valid) { @@ -191,7 +192,7 @@ test("a published broadcast resolves by path", async () => { expect(wireOf(consumer).routes(path)).toBe(false); const broadcast = publish(origin, path); - broadcast.createTrack("video"); + broadcast.createTrack("video", { timescale: Timescale.MILLI }); const handle = await routed(consumer, path); expect(handle).toBeDefined(); @@ -423,11 +424,11 @@ test("a local publish shadows a remote entry", async () => { const path = Path.from("room"); const upstream = new BroadcastProducer(); - upstream.createTrack("remote-track"); + upstream.createTrack("remote-track", { timescale: Timescale.MILLI }); const dispose = serve(origin, path, provider(upstream), { hops: [], cost: { warm: 9n, cold: 9n } }); const local = publish(origin, path); - local.createTrack("local-track"); + local.createTrack("local-track", { timescale: Timescale.MILLI }); // Local wins: the handle reaches the local track, not the remote one. const handle = await routed(consumer, path); @@ -553,7 +554,7 @@ test("disposing the newest remote route promotes the fallback", async () => { // Two sessions announced the same path; the older one is still alive when the newer // one goes away, so the route must fail over rather than black-hole. const older = new BroadcastProducer(); - older.createTrack("chat"); + older.createTrack("chat", { timescale: Timescale.MILLI }); const keepOlder = older.consume(); const disposeOlder = serve(origin, path, provider(older)); @@ -1161,7 +1162,7 @@ test("a handle serves a request under live", async () => { expect(req?.path).toBe(Path.from("live/cam")); const produced = new BroadcastProducer(); - produced.createTrack("video"); + produced.createTrack("video", { timescale: Timescale.MILLI }); req?.accept(produced); await settle(); @@ -1198,7 +1199,7 @@ test("an accepted dynamic broadcast is retired when it closes", async () => { const first = await it.next(); const produced = new BroadcastProducer(); - produced.createTrack("video"); + produced.createTrack("video", { timescale: Timescale.MILLI }); first.value?.accept(produced); await settle(); expect(request.active.peek()?.track("video").subscribe()).toBeDefined(); @@ -1210,7 +1211,7 @@ test("an accepted dynamic broadcast is retired when it closes", async () => { const second = await it.next(); expect(second.value?.path).toBe(path); const replacement = new BroadcastProducer(); - replacement.createTrack("video"); + replacement.createTrack("video", { timescale: Timescale.MILLI }); second.value?.accept(replacement); await settle(); expect(request.active.peek()?.track("video").subscribe()).toBeDefined(); diff --git a/js/net/src/retention.test.ts b/js/net/src/retention.test.ts index 4ee3880ba14..30b0d771a6c 100644 --- a/js/net/src/retention.test.ts +++ b/js/net/src/retention.test.ts @@ -7,7 +7,7 @@ import * as Lite from "./lite/index.ts"; import { createMockTransportPair } from "./mock.ts"; import { Producer as OriginProducer } from "./origin.ts"; import * as Path from "./path.ts"; -import { Timestamp } from "./time.ts"; +import { Timescale, Timestamp } from "./time.ts"; import { wireOf } from "./wire.ts"; // A subscription races its track's `closed` once per frame. These count the listeners left on @@ -83,7 +83,7 @@ async function session(alpn: string) { const broadcast = origin.createBroadcast(Path.from("test")); broadcast.announce(); - const producer = broadcast.createTrack("video"); + const producer = broadcast.createTrack("video", { timescale: Timescale.MILLI }); const remote = wireOf(client).consume(Path.from("test")); const track = remote.track("video").subscribe().ordered(); diff --git a/js/net/src/tail.test.ts b/js/net/src/tail.test.ts index 972df8faec9..6b7a315d94a 100644 --- a/js/net/src/tail.test.ts +++ b/js/net/src/tail.test.ts @@ -7,7 +7,7 @@ import { createMockTransportPair } from "./mock.ts"; import { Producer as OriginProducer } from "./origin.ts"; import * as Path from "./path.ts"; import { TAIL_GRACE_MS, Tail } from "./tail.ts"; -import { Milli } from "./time.ts"; +import { Milli, Timescale } from "./time.ts"; import type { Ordered } from "./track.ts"; import { wireOf } from "./wire.ts"; @@ -26,7 +26,7 @@ async function session(protocol: string) { ]); const broadcast = origin.createBroadcast(Path.from("test")); broadcast.announce(); - const video = broadcast.createTrack("video"); + const video = broadcast.createTrack("video", { timescale: Timescale.MILLI }); const remote = wireOf(client).consume(Path.from("test")); const reader = remote.track("video").subscribe({ maxAge: MAX_AGE }).ordered(); diff --git a/js/net/src/track.test.ts b/js/net/src/track.test.ts index 779cdd1af88..203fd78f21d 100644 --- a/js/net/src/track.test.ts +++ b/js/net/src/track.test.ts @@ -364,7 +364,7 @@ test("the producer aggregate is clamped without changing subscriber options", as const track = producer.subscribe({ maxAge: Milli(10_000) }); const clamped = producer.subscription.changed(); - producer.accept({ maxAge: Milli(2_000) }); + producer.accept({ timescale: Timescale.MILLI, maxAge: Milli(2_000) }); expect((await clamped)?.maxAge).toBe(Milli(2_000)); expect(track.subscription.peek()?.maxAge).toBe(Milli(10_000)); @@ -403,7 +403,7 @@ test("nextGroup returns buffered groups in sequence", async () => { // is level with the live edge still owes the reader every frame in it, so judging it by // its first timestamp would discard exactly the group being filled. test("a long group is not stale while its tail reaches the edge", async () => { - const producer = new TrackProducer("test").accept({ maxAge: Milli(5000) }); + const producer = new TrackProducer("test").accept({ timescale: Timescale.MILLI, maxAge: Milli(5000) }); const sub = producer.subscribe({ maxAge: Milli(500) }); // Group 0 spans 0..2000ms; group 1 starts at 2000ms, where group 0 ends. @@ -419,7 +419,7 @@ test("a long group is not stale while its tail reaches the edge", async () => { }); test("a long group is stale once its successor falls behind", async () => { - const producer = new TrackProducer("test").accept({ maxAge: Milli(5000) }); + const producer = new TrackProducer("test").accept({ timescale: Timescale.MILLI, maxAge: Milli(5000) }); const sub = producer.subscribe({ maxAge: Milli(500) }); const long = producer.appendGroup(); @@ -454,7 +454,7 @@ test("the ordered handle carries datagrams", async () => { // Both cursors write a backlog off: a buffered group is not free to deliver, since a // consumer reading one that is already too old plays it at 1x and never catches up. test("the latency budget skips a buffered timeline on either cursor", async () => { - const producer = new TrackProducer("test").accept({ maxAge: Milli(5000) }); + const producer = new TrackProducer("test").accept({ timescale: Timescale.MILLI, maxAge: Milli(5000) }); const arrival = producer.subscribe(); const ordered = producer.subscribe().ordered(); @@ -476,7 +476,7 @@ test("the latency budget skips a buffered timeline on either cursor", async () = // group proves nothing about where the successor will begin, and shrinking the bound // is the unsafe direction. test("an unstamped immediate successor leaves reach unbounded", async () => { - const producer = new TrackProducer("test").accept({ maxAge: Milli(5000) }); + const producer = new TrackProducer("test").accept({ timescale: Timescale.MILLI, maxAge: Milli(5000) }); const track = producer.subscribe(); producer.writeFrame({ payload: enc.encode("0"), timestamp: Timestamp.fromMillis(0) }); @@ -492,7 +492,7 @@ test("an unstamped immediate successor leaves reach unbounded", async () => { // Groups can arrive out of sequence order; the immediate successor bounds reach even when it // arrived last. test("a late-arriving successor bounds a group's reach", async () => { - const producer = new TrackProducer("test").accept({ maxAge: Milli(5000) }); + const producer = new TrackProducer("test").accept({ timescale: Timescale.MILLI, maxAge: Milli(5000) }); const track = producer.subscribe({ maxAge: Milli(500) }); for (const [sequence, ms] of [ @@ -515,7 +515,7 @@ test("a late-arriving successor bounds a group's reach", async () => { // The ordered frame helpers ride the same cursor, so they see the same budget: a // backlog inside it is drained in full, and what is past it is skipped. test("ordered frame reads follow the budget", async () => { - const producer = new TrackProducer("test").accept({ maxAge: Milli(5000) }); + const producer = new TrackProducer("test").accept({ timescale: Timescale.MILLI, maxAge: Milli(5000) }); const ordered = producer.subscribe({ maxAge: Milli(5000) }).ordered(); const live = producer.subscribe().ordered(); @@ -591,7 +591,7 @@ test("ordered frame reads skip a late lower-sequence group", async () => { test("zero latency takes the latest group when ages are equal", async () => { const clock = mockMonotonicTime(10_000); try { - const producer = new TrackProducer("test").accept({ maxAge: Milli(5000) }); + const producer = new TrackProducer("test").accept({ timescale: Timescale.MILLI, maxAge: Milli(5000) }); const track = producer.subscribe(); producer.writeString("old"); producer.writeString("new"); @@ -603,7 +603,7 @@ test("zero latency takes the latest group when ages are equal", async () => { }); test("latency budget admits groups within its presentation-time window", async () => { - const producer = new TrackProducer("test").accept({ maxAge: Milli(5000) }); + const producer = new TrackProducer("test").accept({ timescale: Timescale.MILLI, maxAge: Milli(5000) }); const track = producer.subscribe({ maxAge: Milli(1500) }); for (const timestamp of [0, 1000, 2000]) { @@ -617,7 +617,7 @@ test("latency budget admits groups within its presentation-time window", async ( }); test("a late lower group within the budget is delivered", async () => { - const producer = new TrackProducer("test").accept({ maxAge: Milli(30_000) }); + const producer = new TrackProducer("test").accept({ timescale: Timescale.MILLI, maxAge: Milli(30_000) }); for (const [sequence, timestamp] of [ [5, 0], [6, 1000], @@ -648,7 +648,7 @@ test("a late lower group within the budget is delivered", async () => { }); test("a named start is a floor, not a request", async () => { - const producer = new TrackProducer("test").accept({ maxAge: Milli(30_000) }); + const producer = new TrackProducer("test").accept({ timescale: Timescale.MILLI, maxAge: Milli(30_000) }); for (const timestamp of [0, 1000, 2000, 3000, 4000]) { producer.writeFrame({ payload: enc.encode(`${timestamp}`), timestamp: Timestamp.fromMillis(timestamp) }); } @@ -666,7 +666,7 @@ test("a named start is a floor, not a request", async () => { }); test("the ordered cursor sheds a stale backlog", async () => { - const producer = new TrackProducer("test").accept({ maxAge: Milli(30_000) }); + const producer = new TrackProducer("test").accept({ timescale: Timescale.MILLI, maxAge: Milli(30_000) }); for (const timestamp of [0, 1000, 2000, 3000]) { producer.writeFrame({ payload: enc.encode(`${timestamp}`), timestamp: Timestamp.fromMillis(timestamp) }); } @@ -691,7 +691,7 @@ test("the ordered cursor sheds a stale backlog", async () => { }); test("the budget is clamped to the publisher's window", async () => { - const producer = new TrackProducer("test").accept({ maxAge: Milli(1500) }); + const producer = new TrackProducer("test").accept({ timescale: Timescale.MILLI, maxAge: Milli(1500) }); const track = producer.subscribe({ maxAge: Milli(60_000) }); // Spaced so group 0's reach (2s) sits 2s behind the edge (4s): outside the @@ -710,7 +710,7 @@ test("the budget is clamped to the publisher's window", async () => { test("a stamped successor expires a group stalled before its first frame", async () => { const clock = mockMonotonicTime(10_000); try { - const producer = new TrackProducer("test").accept({ maxAge: Milli(5000) }); + const producer = new TrackProducer("test").accept({ timescale: Timescale.MILLI, maxAge: Milli(5000) }); const track = producer.subscribe(); producer.appendGroup(); // seq 0 has no timestamp @@ -733,7 +733,7 @@ test("real time reads a live stream without truncating it", async () => { // The reader is always a little behind the edge (that is what reading live means), // and it is parked at its group's end when the next one opens, because a group's // close and the next group's first frame are separate events. - const producer = new TrackProducer("test").accept({ maxAge: Milli(60_000) }); + const producer = new TrackProducer("test").accept({ timescale: Timescale.MILLI, maxAge: Milli(60_000) }); const track = producer.subscribe(); let open = producer.appendGroup(); @@ -782,7 +782,7 @@ test("a budget is measured from the reader's position", async () => { // for. A straggling frame of the old group must still reach it. Measuring from the // group's first frame instead makes the drift 2000ms, so a budget shorter than one // GOP would drop the tail of every GOP. - const producer = new TrackProducer("test").accept({ maxAge: Milli(60_000) }); + const producer = new TrackProducer("test").accept({ timescale: Timescale.MILLI, maxAge: Milli(60_000) }); const track = producer.subscribe({ maxAge: Milli(1000) }); const open = producer.appendGroup(); @@ -809,7 +809,7 @@ test("a budget is measured from the reader's position", async () => { test("a handed-out group still expires while its first frame is stalled", async () => { const clock = mockMonotonicTime(10_000); try { - const producer = new TrackProducer("test").accept({ maxAge: Milli(5000) }); + const producer = new TrackProducer("test").accept({ timescale: Timescale.MILLI, maxAge: Milli(5000) }); const track = producer.subscribe(); producer.appendGroup(); @@ -848,13 +848,13 @@ test("committing track info wakes a group newly outside the retention window", a // bounded by where its successor begins, so the successor alone never convicts it. producer.writeFrame({ payload: enc.encode("later"), timestamp: Timestamp.fromMillis(2_000) }); await settle(); - producer.accept({ maxAge: Milli(100) }); + producer.accept({ timescale: Timescale.MILLI, maxAge: Milli(100) }); await expect(waiting).resolves.toBeUndefined(); }); test("a handed-out frame cancels its in-flight operation when it expires", async () => { - const producer = new TrackProducer("test").accept({ maxAge: Milli(5000) }); + const producer = new TrackProducer("test").accept({ timescale: Timescale.MILLI, maxAge: Milli(5000) }); const track = producer.subscribe(); producer.writeString("old"); @@ -874,7 +874,7 @@ test("a handed-out frame cancels its in-flight operation when it expires", async }); test("a guarded write keeps the position of the frame removed from the buffer", async () => { - const producer = new TrackProducer("test").accept({ maxAge: Milli(100) }); + const producer = new TrackProducer("test").accept({ timescale: Timescale.MILLI, maxAge: Milli(100) }); const track = producer.subscribe({ maxAge: Milli(100) }); const source = producer.appendGroup(); source.writeFrame({ payload: enc.encode("old"), timestamp: Timestamp.fromMillis(0) }); @@ -901,7 +901,7 @@ test("a guarded write keeps the position of the frame removed from the buffer", }); test("clean source closure stays provisional while a frame write can expire", async () => { - const producer = new TrackProducer("test").accept({ maxAge: Milli(100) }); + const producer = new TrackProducer("test").accept({ timescale: Timescale.MILLI, maxAge: Milli(100) }); const track = producer.subscribe({ maxAge: Milli(100) }); const source = producer.appendGroup(); source.writeFrame({ payload: enc.encode("old"), timestamp: Timestamp.fromMillis(0) }); @@ -933,7 +933,7 @@ test("clean source closure stays provisional while a frame write can expire", as }); test("a drained group finishes cleanly after the live edge advances", async () => { - const producer = new TrackProducer("test").accept({ maxAge: Milli(5000) }); + const producer = new TrackProducer("test").accept({ timescale: Timescale.MILLI, maxAge: Milli(5000) }); const track = producer.subscribe(); producer.writeString("old"); @@ -949,7 +949,7 @@ test("a drained group finishes cleanly after the live edge advances", async () = test("a stalled track retains cached groups past its media maxAge", async () => { const clock = mockMonotonicTime(10_000); - const producer = new TrackProducer("test").accept({ maxAge: Milli(100) }); + const producer = new TrackProducer("test").accept({ timescale: Timescale.MILLI, maxAge: Milli(100) }); try { for (const value of ["first", "second"]) { producer.writeFrame({ payload: enc.encode(value), timestamp: Timestamp.fromMillis(0) }); @@ -968,7 +968,7 @@ test("a stalled track retains cached groups past its media maxAge", async () => test("a live track retains its newest closed group through idle expiry", () => { const clock = mockCacheTime(10_000); - const producer = new TrackProducer("test").accept({ maxAge: Milli(100) }); + const producer = new TrackProducer("test").accept({ timescale: Timescale.MILLI, maxAge: Milli(100) }); try { // A late older group must not replace the protected newest snapshot. for (const sequence of [2, 1]) { @@ -995,7 +995,7 @@ test("a live track retains its newest closed group through idle expiry", () => { test("retention eviction surfaces as a gap for a handed-out group", async () => { const clock = mockMonotonicTime(10_000); try { - const producer = new TrackProducer("test").accept({ maxAge: Milli(100) }); + const producer = new TrackProducer("test").accept({ timescale: Timescale.MILLI, maxAge: Milli(100) }); const track = producer.subscribe({ maxAge: Milli(100) }); const source = producer.appendGroup(); source.writeString("first"); @@ -1018,7 +1018,7 @@ test("retention eviction surfaces as a gap for a handed-out group", async () => test("idle expiry reclaims an ended track's held mirror", async () => { const clock = mockMonotonicTime(10_000); try { - const producer = new TrackProducer("test").accept({ maxAge: Milli(100) }); + const producer = new TrackProducer("test").accept({ timescale: Timescale.MILLI, maxAge: Milli(100) }); const track = producer.subscribe({ maxAge: Milli(100) }); const source = producer.appendGroup(); source.writeString("first"); @@ -1042,7 +1042,7 @@ test("idle expiry reclaims an ended track's held mirror", async () => { test("retention reclaims a group the publisher abandoned open", async () => { const clock = mockMonotonicTime(10_000); try { - const producer = new TrackProducer("test").accept({ maxAge: Milli(100) }); + const producer = new TrackProducer("test").accept({ timescale: Timescale.MILLI, maxAge: Milli(100) }); const track = producer.subscribe({ maxAge: Milli(100) }); const stalled = producer.appendGroup(); stalled.writeString("first"); @@ -1067,7 +1067,7 @@ test("retention reclaims a group the publisher abandoned open", async () => { test("an idle live edge ages out once a newer group arrives", async () => { const clock = mockMonotonicTime(10_000); try { - const producer = new TrackProducer("test").accept({ maxAge: Milli(100) }); + const producer = new TrackProducer("test").accept({ timescale: Timescale.MILLI, maxAge: Milli(100) }); const track = producer.subscribe({ maxAge: Milli(100) }); const edge = producer.appendGroup(); edge.writeString("first"); @@ -1096,7 +1096,7 @@ test("an idle live edge ages out once a newer group arrives", async () => { test("an abandoned open group ages out with no further write", async () => { const clock = mockCacheTime(10_000); - const producer = new TrackProducer("test").accept({ maxAge: Milli(30) }); + const producer = new TrackProducer("test").accept({ timescale: Timescale.MILLI, maxAge: Milli(30) }); try { const track = producer.subscribe({ maxAge: Milli(30) }); const stalled = producer.appendGroup(); @@ -1118,7 +1118,7 @@ test("an abandoned open group ages out with no further write", async () => { test("publisher maxAge does not change the idle cache deadline", () => { for (const maxAge of [Milli(30), Milli(2 ** 31 + 10_000)]) { const clock = mockCacheTime(10_000); - const producer = new TrackProducer("test").accept({ maxAge }); + const producer = new TrackProducer("test").accept({ timescale: Timescale.MILLI, maxAge }); try { producer.writeString("cached"); producer.appendGroup(); @@ -1133,7 +1133,7 @@ test("publisher maxAge does not change the idle cache deadline", () => { test("retention pruning preserves clean EOF for a drained mirror", async () => { const clock = mockMonotonicTime(10_000); try { - const producer = new TrackProducer("test").accept({ maxAge: Milli(100) }); + const producer = new TrackProducer("test").accept({ timescale: Timescale.MILLI, maxAge: Milli(100) }); const track = producer.subscribe({ maxAge: Milli(100) }); const source = producer.appendGroup(); source.writeString("only"); @@ -1159,7 +1159,7 @@ test("system clock changes do not affect the latency budget", async () => { const clock = mockMonotonicTime(10_000); setSystemTime(new Date(10_000)); try { - const producer = new TrackProducer("test").accept({ maxAge: Milli(100) }); + const producer = new TrackProducer("test").accept({ timescale: Timescale.MILLI, maxAge: Milli(100) }); const track = producer.subscribe({ maxAge: Milli(100) }); producer.writeString("old"); @@ -1175,7 +1175,7 @@ test("system clock changes do not affect the latency budget", async () => { }); test("frame readiness cancels the losing latency waiter", async () => { - const producer = new TrackProducer("test").accept({ maxAge: Milli(5000) }); + const producer = new TrackProducer("test").accept({ timescale: Timescale.MILLI, maxAge: Milli(5000) }); const track = producer.subscribe({ maxAge: Milli(5000) }); const source = producer.appendGroup(); const group = await track.recvGroup(); @@ -1189,7 +1189,7 @@ test("frame readiness cancels the losing latency waiter", async () => { }); test("latency budget retains a consumed live-edge anchor", async () => { - const producer = new TrackProducer("test").accept({ maxAge: Milli(5000) }); + const producer = new TrackProducer("test").accept({ timescale: Timescale.MILLI, maxAge: Milli(5000) }); const track = producer.subscribe(); const edge = new GroupProducer(2); @@ -1208,7 +1208,7 @@ test("latency budget retains a consumed live-edge anchor", async () => { }); test("an aborted live-edge anchor does not make older content stale", async () => { - const producer = new TrackProducer("test").accept({ maxAge: Milli(5000) }); + const producer = new TrackProducer("test").accept({ timescale: Timescale.MILLI, maxAge: Milli(5000) }); const track = producer.subscribe(); const edge = new GroupProducer(2); @@ -1246,7 +1246,7 @@ test("setGroups with an excluded end of 0 is the empty range and does not ride a }); test("setGroups caps the live edge used by the latency budget", async () => { - const producer = new TrackProducer("test").accept({ maxAge: Milli(5000) }); + const producer = new TrackProducer("test").accept({ timescale: Timescale.MILLI, maxAge: Milli(5000) }); const track = producer.subscribe(); track.setGroups({ end: { excluded: 2 } }); @@ -1262,7 +1262,7 @@ test("setGroups caps the live edge used by the latency budget", async () => { // The frame helpers ride the group cursor, so its bounds apply to them too: a group // above the cap parks (surviving a clean close) until the cap admits it. test("setGroups caps frame-level reads like the group cursor", async () => { - const producer = new TrackProducer("test").accept({ maxAge: Milli(5000) }); + const producer = new TrackProducer("test").accept({ timescale: Timescale.MILLI, maxAge: Milli(5000) }); const track = producer.subscribe({ maxAge: Milli(5000) }).ordered(); track.setGroups({ end: { excluded: 1 } }); @@ -1603,7 +1603,7 @@ test("readFrame does not livelock when a sole group finishes before the next arr // The IETF publisher resolves Largest Object from this, so it has to name a frame, not just // a group: a filter is applied down to the object. test("largest names the newest frame written", async () => { - const producer = new TrackProducer("test").accept(); + const producer = new TrackProducer("test").accept({ timescale: Timescale.MILLI }); const subscriber = producer.subscribe({ maxAge: Milli(1_000) }); // Nothing published yet. @@ -1634,7 +1634,7 @@ test("largest names the newest frame written", async () => { // A subscriber that arrives after the frames were written reads mirrors. largest is the // last frame successfully written, even after an overflow aborts the group. test("largest survives a mirror replay of an aborted group", async () => { - const producer = new TrackProducer("test").accept(); + const producer = new TrackProducer("test").accept({ timescale: Timescale.MILLI }); const group = producer.appendGroup(); for (let i = 0; i < MAX_GROUP_FRAMES; i++) { @@ -1833,7 +1833,7 @@ test("publisher max age is absent unless explicitly declared", () => { // limit only removes the media-time clamp, never the wall-clock bound on memory. test("an omitted publisher limit still ages idle groups out", async () => { const clock = mockMonotonicTime(10_000); - const producer = new TrackProducer("unlimited").accept(); + const producer = new TrackProducer("unlimited").accept({ timescale: Timescale.MILLI }); try { const source = producer.appendGroup(); source.writeString("old"); @@ -1858,7 +1858,7 @@ test("an omitted publisher limit still ages idle groups out", async () => { test("a live track does not pin an aborted newest group", () => { const clock = mockMonotonicTime(10_000); - const producer = new TrackProducer("test").accept(); + const producer = new TrackProducer("test").accept({ timescale: Timescale.MILLI }); try { const good = producer.appendGroup(); good.writeString("snapshot"); @@ -1880,7 +1880,7 @@ test("a live track does not pin an aborted newest group", () => { test("closing a track keeps an idle newest group for subscribers to drain", async () => { const clock = mockMonotonicTime(10_000); try { - const producer = new TrackProducer("catalog").accept(); + const producer = new TrackProducer("catalog").accept({ timescale: Timescale.MILLI }); const subscriber = producer.subscribe({ maxAge: Milli(100_000) }); const snapshot = producer.appendGroup(); snapshot.writeString("snapshot"); @@ -1905,7 +1905,7 @@ test("closing a track keeps an idle newest group for subscribers to drain", asyn test("a late subscriber to a closed unlimited track is released once the cache ages out", async () => { const clock = mockMonotonicTime(10_000); try { - const producer = new TrackProducer("unlimited").accept(); + const producer = new TrackProducer("unlimited").accept({ timescale: Timescale.MILLI }); const source = producer.appendGroup(); source.writeString("last"); source.close(); @@ -1941,7 +1941,7 @@ test("a late subscriber to a closed unlimited track is released once the cache a }); test("an abort keeps finished groups for a slow reader, then reports it", async () => { - const producer = new TrackProducer("test").accept({ maxAge: Milli(10_000) }); + const producer = new TrackProducer("test").accept({ timescale: Timescale.MILLI, maxAge: Milli(10_000) }); const arrival = producer.subscribe({ maxAge: Milli(10_000) }); const ordered = producer.subscribe({ maxAge: Milli(10_000) }).ordered(); for (let i = 0; i < 2; i++) { @@ -1965,7 +1965,7 @@ test("an abort keeps finished groups for a slow reader, then reports it", async }); test("an abort after the declared end settles ends clean", async () => { - const producer = new TrackProducer("test").accept({ maxAge: Milli(10_000) }); + const producer = new TrackProducer("test").accept({ timescale: Timescale.MILLI, maxAge: Milli(10_000) }); const arrival = producer.subscribe({ maxAge: Milli(10_000) }); const ordered = producer.subscribe({ maxAge: Milli(10_000) }).ordered(); for (let i = 0; i < 2; i++) { @@ -1984,7 +1984,7 @@ test("an abort after the declared end settles ends clean", async () => { }); test("an abort after the declared end reached by a datagram ends clean", () => { - const producer = new TrackProducer("test").accept(); + const producer = new TrackProducer("test").accept({ timescale: Timescale.MILLI }); producer.appendDatagram(Timestamp.fromMillis(0), enc.encode("d")); producer.finishAt(1); producer.close(new Error("boom")); @@ -1994,7 +1994,7 @@ test("an abort after the declared end reached by a datagram ends clean", () => { test("an ended track's buffered groups age out for a stale subscriber", () => { for (const abort of [undefined, new Error("boom")]) { const clock = mockCacheTime(10_000); - const producer = new TrackProducer("test").accept({ maxAge: Milli(30) }); + const producer = new TrackProducer("test").accept({ timescale: Timescale.MILLI, maxAge: Milli(30) }); try { const stale = producer.subscribe({ maxAge: Milli(30) }); const group = producer.appendGroup(); @@ -2014,7 +2014,7 @@ test("an ended track's buffered groups age out for a stale subscriber", () => { }); test("an abort leaves a group already taken readable, then reports the abort", async () => { - const producer = new TrackProducer("test").accept({ maxAge: Milli(10_000) }); + const producer = new TrackProducer("test").accept({ timescale: Timescale.MILLI, maxAge: Milli(10_000) }); const arrival = producer.subscribe({ maxAge: Milli(10_000) }); const ordered = producer.subscribe({ maxAge: Milli(10_000) }).ordered(); producer.appendGroup().writeString("held"); @@ -2038,23 +2038,23 @@ function drain(track: { tryRecvGroup(): { sequence: number } | undefined }): num /** An untimed track holding `count` single-frame groups. */ function untimedTrack(count: number): TrackProducer { - const producer = new TrackProducer("test").accept({ timescale: null }); + const producer = new TrackProducer("test").accept({}); for (let i = 0; i < count; i++) producer.writeFrame({ payload: enc.encode(`${i}`) }); return producer; } -test("a track is timed by default and untimed only when declared", () => { - expect(infoDefaults().timescale).toBe(Timescale.MILLI); - expect(infoDefaults({ timescale: null }).timescale).toBeNull(); +test("a track is untimed unless it declares a timescale", () => { + expect(infoDefaults().timescale).toBeUndefined(); + expect(infoDefaults({ timescale: Timescale.MICRO }).timescale).toBe(Timescale.MICRO); }); test("a frame whose timedness disagrees with its track is refused", async () => { - const timed = new TrackProducer("timed").accept({}); + const timed = new TrackProducer("timed").accept({ timescale: Timescale.MILLI }); const group = timed.appendGroup(); expect(() => group.writeFrame({ payload: enc.encode("x") })).toThrow(TimestampMismatch); group.writeFrame({ payload: enc.encode("x"), timestamp: Timestamp.fromMillis(1) }); - const untimed = new TrackProducer("untimed").accept({ timescale: null }); + const untimed = new TrackProducer("untimed").accept({}); const subscriber = untimed.subscribe(); const other = untimed.appendGroup(); expect(() => other.writeFrame({ payload: enc.encode("x"), timestamp: Timestamp.fromMillis(1) })).toThrow( @@ -2070,17 +2070,17 @@ test("a frame whose timedness disagrees with its track is refused", async () => }); test("a group joining a track it disagrees with is refused", () => { - const producer = new TrackProducer("test").accept({ timescale: null }); + const producer = new TrackProducer("test").accept({}); const group = new GroupProducer(0); group.writeFrame({ payload: enc.encode("x"), timestamp: Timestamp.fromMillis(1) }); expect(() => producer.writeGroup(group)).toThrow(TimestampMismatch); }); test("a datagram whose timedness disagrees with its track is refused", async () => { - const timed = new TrackProducer("timed").accept({}); + const timed = new TrackProducer("timed").accept({ timescale: Timescale.MILLI }); expect(() => timed.appendDatagram(undefined, enc.encode("x"))).toThrow(TimestampMismatch); - const untimed = new TrackProducer("untimed").accept({ timescale: null }); + const untimed = new TrackProducer("untimed").accept({}); const subscriber = untimed.subscribe(); expect(() => untimed.insertDatagram(0, Timestamp.fromMillis(1), enc.encode("x"))).toThrow(TimestampMismatch); untimed.appendDatagram(undefined, enc.encode("y")); diff --git a/js/net/src/track.ts b/js/net/src/track.ts index 070952499c6..84a789eb5e5 100644 --- a/js/net/src/track.ts +++ b/js/net/src/track.ts @@ -58,15 +58,16 @@ export interface Location { */ export interface Info { /** - * Units per second for this track's frame timestamps, or `null` for a track with no - * timeline, whose frames and datagrams carry no timestamp. + * Units per second for this track's frame timestamps, or omitted for an untimed track, + * whose frames and datagrams carry no timestamp. * - * Defaults to milliseconds; set it finer (e.g. {@link Timescale.MICRO}) for media that - * needs sub-millisecond timing. Reported in TRACK_INFO on Lite05+ and as the TIMESCALE - * property on moq-transport. A track received without one (moq-lite before Lite05, or - * moq-transport without TIMESCALE) is `null`, and stays untimed when served onward. + * There is no default: a timed track declares its scale, such as {@link Timescale.MILLI}, + * or {@link Timescale.MICRO} for media that needs sub-millisecond timing. Reported in + * TRACK_INFO on Lite05+ and as the TIMESCALE property on moq-transport. A track received + * without one (moq-lite before Lite05, or moq-transport without TIMESCALE) is untimed, + * and stays untimed when served onward. */ - timescale: Timescale | null; + timescale?: Timescale; /** * Publisher Max Age: how far behind the live edge a group may fall in media * timestamps, in milliseconds, before it is stale. Reported in TRACK_INFO (Lite05+) @@ -108,7 +109,7 @@ function priorityByte(value: number): number { /** Fill in any unset {@link Info} fields with their defaults. */ export function infoDefaults(info: Partial = {}): Info { return { - timescale: info.timescale === null ? null : Timescale(info.timescale ?? Timescale.MILLI), + timescale: info.timescale === undefined ? undefined : Timescale(info.timescale), maxAge: info.maxAge === undefined ? undefined : maxAgeMillis(info.maxAge), priority: priorityByte(info.priority ?? DEFAULT_PRIORITY), }; @@ -581,7 +582,7 @@ export class Producer { accept(info: Partial = {}): this { if (this.#state.closed.peek() !== undefined) return this; const resolved = infoDefaults(info); - for (const { group } of this.#cache) hooks.bindGroupTimed(group, resolved.timescale !== null); + for (const { group } of this.#cache) hooks.bindGroupTimed(group, resolved.timescale !== undefined); this.#state.info.set(resolved); // Propagate to any sink handed out before accept (the on-demand path). for (const sink of this.#sinks) sink.info.set(resolved); @@ -818,13 +819,13 @@ export class Producer { // Hold a group to this track's timedness, once the track has committed it. #bind(group: GroupProducer): void { const info = this.#state.info.peek(); - if (info) hooks.bindGroupTimed(group, info.timescale !== null); + if (info) hooks.bindGroupTimed(group, info.timescale !== undefined); } // Refuse a datagram whose timedness disagrees with this track's. #checkDatagram(timestamp: Timestamp | undefined): void { const info = this.#state.info.peek(); - if (info && (info.timescale !== null) !== (timestamp !== undefined)) throw new TimestampMismatch(); + if (info && (info.timescale !== undefined) !== (timestamp !== undefined)) throw new TimestampMismatch(); } // Refuse a write once the track is closed, or at or past its declared end. @@ -1183,7 +1184,8 @@ export class Subscriber { // The newest servable group, when the track is known to be untimed. #untimedStart(): number | undefined { - if (this.#state.info.peek()?.timescale !== null) return undefined; + const info = this.#state.info.peek(); + if (!info || info.timescale !== undefined) return undefined; const timeline = this.#state.timeline; for (let i = timeline.length - 1; i >= 0; i--) { if (!(timeline[i].closed.peek() instanceof Error)) return timeline[i].sequence; diff --git a/js/net/src/untimed.test.ts b/js/net/src/untimed.test.ts index 79b25d2e1d7..8c8c2e3f3c7 100644 --- a/js/net/src/untimed.test.ts +++ b/js/net/src/untimed.test.ts @@ -37,7 +37,7 @@ const WIRES: Wire[] = [ ]; /** Serve one group of `timestamps` on a track with `timescale`, and read it back over `wire`. */ -async function roundTrip(wire: Wire, timescale: Timescale | null, timestamps: (Timestamp | undefined)[]) { +async function roundTrip(wire: Wire, timescale: Timescale | undefined, timestamps: (Timestamp | undefined)[]) { const pair = createMockTransportPair(wire.protocol); const origin = new OriginProducer(); const [client, server] = await Promise.all([ @@ -109,7 +109,7 @@ test("a forwarded untimed track stays untimed", async () => { const remote = wireOf(subscriber).consume(Path.from("test")); const track = remote.track("video").subscribe(); - expect((await track.info()).timescale).toBeNull(); + expect((await track.info()).timescale).toBeUndefined(); const frame = await (await track.ordered().nextGroup())?.readFrame(); expect(frame?.payload).toEqual(new Uint8Array([7])); expect(frame?.timestamp).toBeUndefined(); @@ -124,15 +124,15 @@ test("a forwarded untimed track stays untimed", async () => { for (const wire of WIRES) { test(`${wire.name}: an untimed track arrives untimed, or with send times where the wire must stamp`, async () => { - const { info, frames } = await roundTrip(wire, null, [undefined, undefined]); + const { info, frames } = await roundTrip(wire, undefined, [undefined, undefined]); expect(frames.map((frame) => frame.payload[0])).toEqual([0, 1]); if (wire.stamps) { - // Lite-05 and lite-06 can't say a track is untimed, so it goes out timed at the default scale. + // Lite-05 and lite-06 can't say a track is untimed, so it goes out timed at milliseconds. expect(info.timescale).toBe(Timescale.MILLI); for (const frame of frames) expect(frame.timestamp).toBeDefined(); } else { - expect(info.timescale).toBeNull(); + expect(info.timescale).toBeUndefined(); for (const frame of frames) expect(frame.timestamp).toBeUndefined(); } }); @@ -149,7 +149,7 @@ for (const wire of WIRES) { expect(frames.map((frame) => frame.timestamp?.asMicros())).toEqual([1_000, 1_234]); } else { // No units on the wire, and no arrival time made up in their place. - expect(info.timescale).toBeNull(); + expect(info.timescale).toBeUndefined(); for (const frame of frames) expect(frame.timestamp).toBeUndefined(); } }); diff --git a/js/publish/src/audio/encoder.test.ts b/js/publish/src/audio/encoder.test.ts index 41cef170803..2be8928dc18 100644 --- a/js/publish/src/audio/encoder.test.ts +++ b/js/publish/src/audio/encoder.test.ts @@ -206,7 +206,7 @@ function configured(): Promise { async function setup(baseline = new Baseline(), codec?: Codec) { const configuring = configured(); - const track = new Moq.Track.Producer("audio").accept(); + const track = new Moq.Track.Producer("audio").accept({ timescale: Moq.Time.Timescale.MILLI }); const written: [number, number][] = []; const writes = { onWrite: undefined as (() => void) | undefined }; const appendGroup = track.appendGroup.bind(track); diff --git a/js/publish/src/broadcast.ts b/js/publish/src/broadcast.ts index 58aecf739b0..55269b1330e 100644 --- a/js/publish/src/broadcast.ts +++ b/js/publish/src/broadcast.ts @@ -252,6 +252,8 @@ export class Broadcast { // that sole closed snapshot replayable so a viewer arriving after the ordinary media // retention window can still bootstrap. const track = broadcast.createTrack(name, { + // Each catalog snapshot is stamped when written. + timescale: Moq.Time.Timescale.MILLI, maxAge: Moq.Time.Milli(Number.MAX_SAFE_INTEGER), priority: Catalog.PRIORITY.catalog, }); diff --git a/js/publish/src/video/capture.test.ts b/js/publish/src/video/capture.test.ts index faa247aae83..e23ae9301a5 100644 --- a/js/publish/src/video/capture.test.ts +++ b/js/publish/src/video/capture.test.ts @@ -226,7 +226,7 @@ test("an encoder resuming on a still source encodes a keyframe of the current pi }); const capture = new Capture({ source: input.source }); - const track = new Moq.Track.Producer("video").accept(); + const track = new Moq.Track.Producer("video").accept({ timescale: Moq.Time.Timescale.MILLI }); // No subscriber yet, so the encoder idles while the source sends its only frame. const live = new Signal(undefined); const rendition = { config: new Signal(undefined), track: live, close: () => {} }; diff --git a/js/publish/src/video/encoder.test.ts b/js/publish/src/video/encoder.test.ts index 60f7ea50102..fe66ce0eb73 100644 --- a/js/publish/src/video/encoder.test.ts +++ b/js/publish/src/video/encoder.test.ts @@ -86,7 +86,7 @@ test("encoding tracks encoder config in its child effect", async () => { using _videoEncoder = installFakeVideoEncoder(); const warn = spyOn(console, "warn").mockImplementation(() => {}); - const track = new Moq.Track.Producer("video/hd").accept(); + const track = new Moq.Track.Producer("video/hd").accept({ timescale: Moq.Time.Timescale.MILLI }); const rendition = { config: new Signal(undefined), track: new Signal(track), @@ -123,7 +123,7 @@ test("a demand gap marks a discontinuity and leaves the broadcast-owned track op using _videoEncoder = installFakeVideoEncoder(); const discontinuity = spyOn(Container.Legacy.Producer.prototype, "discontinuity"); - const track = new Moq.Track.Producer("video").accept({ priority: 60 }); + const track = new Moq.Track.Producer("video").accept({ timescale: Moq.Time.Timescale.MILLI, priority: 60 }); const live = new Signal(track); const rendition = { config: new Signal(undefined), @@ -172,7 +172,7 @@ test("a demand gap marks a discontinuity and leaves the broadcast-owned track op test("a bandwidth estimate updates the bitrate without blanking the config or re-probing", async () => { using _videoEncoder = installFakeVideoEncoder(); - const track = new Moq.Track.Producer("video").accept({ priority: 60 }); + const track = new Moq.Track.Producer("video").accept({ timescale: Moq.Time.Timescale.MILLI, priority: 60 }); const sub = track.subscribe(); const rendition = { config: new Signal(undefined), @@ -253,7 +253,7 @@ test("every published config was probed for its own codec and dimensions", async using _videoEncoder = installFakeVideoEncoder(); FakeVideoEncoder.accepted = []; - const track = new Moq.Track.Producer("video").accept({ priority: 60 }); + const track = new Moq.Track.Producer("video").accept({ timescale: Moq.Time.Timescale.MILLI, priority: 60 }); const sub = track.subscribe(); const rendition = { config: new Signal(undefined), @@ -521,7 +521,7 @@ test.each(["encoder lag", "quiet startup"])("marks a rendition stalled for %s", release: (frame) => frame.close(), }); - const track = new Moq.Track.Producer("video/hd").accept(); + const track = new Moq.Track.Producer("video/hd").accept({ timescale: Moq.Time.Timescale.MILLI }); const rendition = { config: new Signal(undefined), track: new Signal(track), @@ -662,7 +662,7 @@ test("the probe encodes with the frame rate and bitrate ceiling", async () => { using _videoEncoder = installFakeVideoEncoder(); const probe = spyOn(FakeVideoEncoder, "isConfigSupported"); - const track = new Moq.Track.Producer("video").accept({ priority: 60 }); + const track = new Moq.Track.Producer("video").accept({ timescale: Moq.Time.Timescale.MILLI, priority: 60 }); const sub = track.subscribe(); const rendition = { config: new Signal(undefined), @@ -821,7 +821,7 @@ test("cut forces a keyframe, coalescing requests and spacing them at least 500ms { clone: (frame) => frame.clone(), release: (frame) => frame.close() }, ); - const track = new Moq.Track.Producer("video").accept(); + const track = new Moq.Track.Producer("video").accept({ timescale: Moq.Time.Timescale.MILLI }); const rendition = { config: new Signal(undefined), track: new Signal(track), diff --git a/js/room/src/chat.test.ts b/js/room/src/chat.test.ts index 9b025be278f..aef83ea6263 100644 --- a/js/room/src/chat.test.ts +++ b/js/room/src/chat.test.ts @@ -1,6 +1,6 @@ import { expect, spyOn, test } from "bun:test"; import { Broadcast } from "@moq/net"; -import { HISTORY, Publisher, Subscriber, TRACK } from "./chat.ts"; +import { HISTORY, info, Publisher, Subscriber, TRACK } from "./chat.ts"; test("chat expires ten-second history and late readers only see retained messages", async () => { const clock = spyOn(performance, "now").mockReturnValue(0); @@ -31,7 +31,7 @@ test("chat expires ten-second history and late readers only see retained message test("chat rejects non-string window records and propagates track failures", async () => { const broadcast = new Broadcast.Producer(); - const track = broadcast.createTrack(TRACK); + const track = broadcast.createTrack(TRACK, info()); const subscriber = Subscriber.subscribe(broadcast.consume()); try { track.writeString('{"offset":0,"records":[42]}'); diff --git a/js/room/src/chat.ts b/js/room/src/chat.ts index 00a02968b35..33c25679a70 100644 --- a/js/room/src/chat.ts +++ b/js/room/src/chat.ts @@ -5,7 +5,7 @@ */ import * as Json from "@moq/json"; -import type { Broadcast, Track } from "@moq/net"; +import { type Broadcast, Time, type Track } from "@moq/net"; import { Effect, Signal } from "@moq/signals"; /** Name of the track carrying the chat window. */ @@ -17,9 +17,9 @@ export const HISTORY = 10_000; /** A message entering, leaving, or missed from the window. */ export type Event = Json.Window.Event; -/** Track settings for the latest chat window. */ -export function info(): Pick { - return { priority: PRIORITY }; +/** Track settings for the latest chat window, timed in milliseconds since each message is stamped when sent. */ +export function info(): Pick { + return { priority: PRIORITY, timescale: Time.Timescale.MILLI }; } /** Publishes chat messages and retires them after ten seconds, including while idle. */ diff --git a/js/room/src/metadata.test.ts b/js/room/src/metadata.test.ts index 2810272813a..47875966a64 100644 --- a/js/room/src/metadata.test.ts +++ b/js/room/src/metadata.test.ts @@ -56,8 +56,12 @@ test("metadata clears when entries disappear or broadcast becomes inactive", asy hang: { user: { track: TRACK.user }, preview: { track: TRACK.preview } }, }); const active = new Signal(net.consume()); - const user = new Json.Snapshot.Producer({ track: net.createTrack(TRACK.user) }); - const preview = new Json.Snapshot.Producer({ track: net.createTrack(TRACK.preview) }); + const user = new Json.Snapshot.Producer({ + track: net.createTrack(TRACK.user, { timescale: Net.Time.Timescale.MILLI }), + }); + const preview = new Json.Snapshot.Producer({ + track: net.createTrack(TRACK.preview, { timescale: Net.Time.Timescale.MILLI }), + }); user.update({ name: "Alice" }); preview.update({ info: { video: true } }); const consumed = consume({ out: { catalog, active } } as unknown as Watch.Broadcast); diff --git a/js/room/src/metadata.ts b/js/room/src/metadata.ts index 7ff0a458c9f..190f0e52c25 100644 --- a/js/room/src/metadata.ts +++ b/js/room/src/metadata.ts @@ -151,8 +151,13 @@ function serveSnapshot( const net = effect.get(broadcast.net); if (!net) return; - // A day-long cache so a late joiner still replays the latest value. - const track = net.createTrack(name, { maxAge: Moq.Time.Milli(86_400_000), priority: PRIORITY }); + // A day-long cache so a late joiner still replays the latest value. Each value is stamped + // when written, so the track is timed. + const track = net.createTrack(name, { + timescale: Moq.Time.Timescale.MILLI, + maxAge: Moq.Time.Milli(86_400_000), + priority: PRIORITY, + }); effect.cleanup(() => track.close()); const producer = new Json.Snapshot.Producer({ track }); diff --git a/js/watch/src/broadcast.test.ts b/js/watch/src/broadcast.test.ts index 6762fc8c28f..f536c93684e 100644 --- a/js/watch/src/broadcast.test.ts +++ b/js/watch/src/broadcast.test.ts @@ -425,7 +425,7 @@ describe("wildcard renditions", () => { expect(active).toBeUndefined(); const produced = new Moq.Broadcast.Producer(); - produced.createTrack("video").writeString("frame"); + produced.createTrack("video", { timescale: Moq.Time.Timescale.MILLI }).writeString("frame"); request?.accept(produced); await settle(); expect(active).toBeDefined(); diff --git a/js/watch/src/retention.test.ts b/js/watch/src/retention.test.ts index 3afeee39ea6..0b870745126 100644 --- a/js/watch/src/retention.test.ts +++ b/js/watch/src/retention.test.ts @@ -80,7 +80,7 @@ test("waits on a stable clock leave nothing behind", async () => { test("a long subscription through the player path leaves nothing behind", async () => { const broadcast = new Moq.Broadcast.Producer(); // A tiny publisher window, so the track's own replay cache stays flat too. - const track = broadcast.createTrack("audio", { maxAge: Time.Milli(1) }); + const track = broadcast.createTrack("audio", { timescale: Time.Timescale.MILLI, maxAge: Time.Milli(1) }); const format = new Container.Legacy.Format("audio"); const producer = new Container.Legacy.Producer(track, format); diff --git a/quest/m1/js-publish-timestamp.md b/quest/m1/js-publish-timestamp.md index 916cc8e8fb7..fdfc99648fb 100644 --- a/quest/m1/js-publish-timestamp.md +++ b/quest/m1/js-publish-timestamp.md @@ -29,4 +29,8 @@ frame whose timedness doesn't match its track is refused. An absent mismatched frame, so the group helpers, which still stamp now, only work on a timed track today. +Decided (2026-10-07): `@moq/net` has no default timescale. Omitting +`Track.Info.timescale` declares an untimed track, so every timed publisher +names its units, unlike Rust's millisecond default. + Public API: breaking. Wire: none. diff --git a/test/audio-quality/clients/js/src/capture.test.ts b/test/audio-quality/clients/js/src/capture.test.ts index b674de62685..6d39b4f82ee 100644 --- a/test/audio-quality/clients/js/src/capture.test.ts +++ b/test/audio-quality/clients/js/src/capture.test.ts @@ -64,7 +64,7 @@ test("arrival capture refuses an unsupported container", () => { test("the observer shares playback demand and closes without ending playback", async () => { const origin = new Origin.Producer(); const published = origin.createBroadcast(Path.from("tone.hang")); - const track = published.createTrack("audio"); + const track = published.createTrack("audio", { timescale: Time.Timescale.MILLI }); published.announce(); const source = new Broadcast({ origin, name: Path.from("tone.hang"), announced: false, catalogFormat: "manual" }); const capture = new Capture({ @@ -101,7 +101,7 @@ test("the observer shares playback demand and closes without ending playback", a async function captureGroupEnd(end: (group: Group.Producer) => void): Promise { const origin = new Origin.Producer(); const published = origin.createBroadcast(Path.from("tone.hang")); - const track = published.createTrack("audio"); + const track = published.createTrack("audio", { timescale: Time.Timescale.MILLI }); published.announce(); const source = new Broadcast({ origin, name: Path.from("tone.hang"), announced: false, catalogFormat: "manual" }); const capture = new Capture({ diff --git a/test/drain/drain.ts b/test/drain/drain.ts index 59716364ebc..b4e960bd0c9 100644 --- a/test/drain/drain.ts +++ b/test/drain/drain.ts @@ -109,7 +109,7 @@ await new Promise((resolve, reject) => { // ── publisher on B ──────────────────────────────────────────────────────────── const published = new Moq.Origin.Producer(); const broadcast = published.createBroadcast(path); -const track = broadcast.createTrack(trackName); +const track = broadcast.createTrack(trackName, { timescale: Moq.Time.Timescale.MILLI }); broadcast.announce(); const publisher = new Moq.Connection({ url: new URL(`http://127.0.0.1:${bPort}/`), publish: published.consume() }); diff --git a/test/interop/clients/js/src/contract.test.ts b/test/interop/clients/js/src/contract.test.ts index 4afa6e19a6d..33deb26acc4 100644 --- a/test/interop/clients/js/src/contract.test.ts +++ b/test/interop/clients/js/src/contract.test.ts @@ -22,7 +22,7 @@ test("unchanged counts are not a leak start", () => { test("late join uses the published GOP when painting is ahead of capture", async () => { const broadcast = new Moq.Broadcast.Producer(); - const track = broadcast.createTrack("video"); + const track = broadcast.createTrack("video", { timescale: Moq.Time.Timescale.MILLI }); try { const old = track.appendGroup(); old.writeFrame({ payload: new Uint8Array([1]), timestamp: Moq.Time.Timestamp.fromMillis(3000) }); diff --git a/test/wasm/src/main.ts b/test/wasm/src/main.ts index 38a6930daed..51bcaf3e47c 100644 --- a/test/wasm/src/main.ts +++ b/test/wasm/src/main.ts @@ -141,7 +141,7 @@ async function withPublisher(relay: RelayFixture, path: string, run: () => Pr // published into the origin and the session announces the table. const origin = new Moq.Origin.Producer(); const broadcast = origin.createBroadcast(Moq.Path.from(path)); - const track = broadcast.createTrack(TRACK); + const track = broadcast.createTrack(TRACK, { timescale: Moq.Time.Timescale.MILLI }); const missing = broadcast.createTrack("missing"); const used = track.demand().used; const missingUsed = missing.demand().used; From 83ec9c63fb200b08b97eb4e4bac0e6c788f452e9 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 7 Oct 2026 10:42:46 -0700 Subject: [PATCH 5/8] feat(js/net): a null Track.Info.timescale is untimed, like an omitted one Co-Authored-By: Claude Opus 5.5 --- doc/lib/js/net.md | 2 +- js/net/src/ietf/publisher.ts | 5 +++-- js/net/src/lite/track.test.ts | 3 ++- js/net/src/track.test.ts | 13 +++++++++++++ js/net/src/track.ts | 16 ++++++++-------- 5 files changed, 27 insertions(+), 12 deletions(-) diff --git a/doc/lib/js/net.md b/doc/lib/js/net.md index 3ecbd096778..0831d0c5b5b 100644 --- a/doc/lib/js/net.md +++ b/doc/lib/js/net.md @@ -53,7 +53,7 @@ for (;;) { - **Bandwidth** (`Bandwidth.Allocator`) divides the connection's send-rate estimate by track priority, max-min fair within a tier. An idle track claims nothing. The receive side is untouched. - **Discovery** by any pattern scope (`origin.announced(scope)`, such as `room/*/chat`; default everything). A route event's `kind` says whether the route started, updated, or ended; its `prefix` is the covered prefix relative to the origin, and `captures` reports what the scope's wildcards matched when the prefix pins them. The consumer is an async iterable. `origin.broadcasts(scope)` is a live `Getter>` of the same covered prefixes for UIs that need the current set. A borrowed `Connection.origin` also exposes `dynamic(prefix, route)` for serving paths on demand. - **Publisher retention** is optional `Track.Info.maxAge`, measured against media timestamps: omission sets no limit, while zero serves only the live edge. It clamps every subscriber's max age, and stalled media does not age out merely because wall time passes. Separately, cached groups nobody writes for 30 seconds are reclaimed, except a live track's newest group, which stays replayable until the track closes. -- **Timing** is per track. A timed track declares `Track.Info.timescale` (such as `Time.Timescale.MILLI`); omitting it declares an untimed track. There is no default, unlike Rust's millisecond default. A frame or datagram carries a `timestamp` exactly when its track has a timescale, and a write that disagrees throws `Error.TimestampMismatch`. Nothing fills in a time on receive: moq-lite before 05, and moq-transport without TIMESCALE (always so on drafts 14-16), deliver untimed tracks. moq-lite 05 and 06 can't declare an untimed track, so it goes out at milliseconds with each frame's send time. An untimed group is never stale, so a subscription without a `groups.start` begins at the latest group. +- **Timing** is per track. A timed track declares `Track.Info.timescale` (such as `Time.Timescale.MILLI`); omitting it (or passing `null`, which means the same) declares an untimed track. There is no default, unlike Rust's millisecond default. A frame or datagram carries a `timestamp` exactly when its track has a timescale, and a write that disagrees throws `Error.TimestampMismatch`. Nothing fills in a time on receive: moq-lite before 05, and moq-transport without TIMESCALE (always so on drafts 14-16), deliver untimed tracks. moq-lite 05 and 06 can't declare an untimed track, so it goes out at milliseconds with each frame's send time. An untimed group is never stale, so a subscription without a `groups.start` begins at the latest group. - **Subscriptions** carry a priority, a `Time.Milli` max age measured against media timestamps, and optional `groups` bounds. Groups arrive out of order and are read frame by frame, with `Error.TooFarBehind` when a reader asks for a frame the group never held and `Error.GroupTooLarge` when a write exceeds the cache budget and aborts the group. - **Track ends**: `close()` ends a track at its live edge, while `finishAt(n)` declares the exclusive end ahead of it and still accepts the groups below. A subscriber reads the end with `final()` or awaits `finished()`. Group and datagram readers end once the live edge reaches the declared boundary, even while missing lower groups wait out the grace. The `closed` signal settles separately once every group below the end has arrived or was dropped; one reset before its header arrived is skipped after the subscription's max age on moq-lite (one second without one), or after one second on IETF. - **Datagrams** on moq-lite 05+ and fetch-by-sequence for history. `track.fetchGroup(sequence)` on moq-lite resolves when the publisher sends the first response byte or finishes an empty group. A missing group rejects the fetch with `StreamCode.NotFound`, including every concurrent caller sharing that fetch. `fetchGroup(sequence, { signal })` abandons a pending fetch with the signal's reason; the shared stream is cancelled only once every caller has left. Once resolved, close the group instead. diff --git a/js/net/src/ietf/publisher.ts b/js/net/src/ietf/publisher.ts index 6b3837821e9..9ddd05638ac 100644 --- a/js/net/src/ietf/publisher.ts +++ b/js/net/src/ietf/publisher.ts @@ -363,7 +363,8 @@ export class Publisher { const info = await track.info(); // A Timestamp goes out only when this SUBSCRIBE_OK actually carries TIMESCALE. // Drafts 14-16 never write that property, so their objects stay unstamped. - const timescale = msg.propertiesWanted && Properties.sendsTimescale(version) ? info.timescale : undefined; + const timescale = + msg.propertiesWanted && Properties.sendsTimescale(version) ? (info.timescale ?? undefined) : undefined; // The model ranks higher-first, the IETF wire lower-first. Every group this // subscription serves carries the same publisher priority, which is what lets a // relay prefer catalog and audio over video when it has no subscriber preference @@ -425,7 +426,7 @@ export class Publisher { // send it. We serve the newest group first, matching moq-lite. { // An untimed track declares none, so it stays untimed downstream. - timescale: info.timescale, + timescale: info.timescale ?? undefined, priority: publisherPriority, groupOrder: Properties.DESCENDING, maxCacheDuration: info.maxAge === undefined ? undefined : BigInt(info.maxAge), diff --git a/js/net/src/lite/track.test.ts b/js/net/src/lite/track.test.ts index f60ffcaab9f..c1dd73f3ae7 100644 --- a/js/net/src/lite/track.test.ts +++ b/js/net/src/lite/track.test.ts @@ -48,7 +48,8 @@ test("TrackInfo round-trips on draft-05", async () => { test("TrackInfo for Rust's default Info matches cross-language wire bytes", async () => { // Rust's `Info::default()` is millisecond-timed; JS has no default timescale. - const info = new TrackInfo(infoDefaults({ timescale: Timescale.MILLI })); + const model = infoDefaults({ timescale: Timescale.MILLI }); + const info = new TrackInfo({ ...model, timescale: model.timescale ?? undefined }); expect(await bytes((w) => info.encode(w, Version.DRAFT_05), Version.DRAFT_05)).toEqual( new Uint8Array([0x0c, 0x7f, 0x00, 0xc0, 0x1f, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0x43, 0xe8]), ); diff --git a/js/net/src/track.test.ts b/js/net/src/track.test.ts index 203fd78f21d..3e256360175 100644 --- a/js/net/src/track.test.ts +++ b/js/net/src/track.test.ts @@ -2048,6 +2048,19 @@ test("a track is untimed unless it declares a timescale", () => { expect(infoDefaults({ timescale: Timescale.MICRO }).timescale).toBe(Timescale.MICRO); }); +test("a null timescale declares an untimed track, like an omitted one", () => { + expect(infoDefaults({ timescale: null }).timescale).toBeUndefined(); + + const producer = new TrackProducer("test").accept({ timescale: null }); + const group = producer.appendGroup(); + expect(() => group.writeFrame({ payload: enc.encode("x"), timestamp: Timestamp.fromMillis(1) })).toThrow( + TimestampMismatch, + ); + group.writeFrame({ payload: enc.encode("y") }); + expect(() => producer.appendDatagram(Timestamp.fromMillis(1), enc.encode("x"))).toThrow(TimestampMismatch); + producer.appendDatagram(undefined, enc.encode("y")); +}); + test("a frame whose timedness disagrees with its track is refused", async () => { const timed = new TrackProducer("timed").accept({ timescale: Timescale.MILLI }); const group = timed.appendGroup(); diff --git a/js/net/src/track.ts b/js/net/src/track.ts index 84a789eb5e5..6ff228d826d 100644 --- a/js/net/src/track.ts +++ b/js/net/src/track.ts @@ -58,8 +58,8 @@ export interface Location { */ export interface Info { /** - * Units per second for this track's frame timestamps, or omitted for an untimed track, - * whose frames and datagrams carry no timestamp. + * Units per second for this track's frame timestamps, or omitted (`undefined` or `null`, + * which mean the same) for an untimed track, whose frames and datagrams carry no timestamp. * * There is no default: a timed track declares its scale, such as {@link Timescale.MILLI}, * or {@link Timescale.MICRO} for media that needs sub-millisecond timing. Reported in @@ -67,7 +67,7 @@ export interface Info { * without one (moq-lite before Lite05, or moq-transport without TIMESCALE) is untimed, * and stays untimed when served onward. */ - timescale?: Timescale; + timescale?: Timescale | null; /** * Publisher Max Age: how far behind the live edge a group may fall in media * timestamps, in milliseconds, before it is stale. Reported in TRACK_INFO (Lite05+) @@ -109,7 +109,7 @@ function priorityByte(value: number): number { /** Fill in any unset {@link Info} fields with their defaults. */ export function infoDefaults(info: Partial = {}): Info { return { - timescale: info.timescale === undefined ? undefined : Timescale(info.timescale), + timescale: info.timescale == null ? undefined : Timescale(info.timescale), maxAge: info.maxAge === undefined ? undefined : maxAgeMillis(info.maxAge), priority: priorityByte(info.priority ?? DEFAULT_PRIORITY), }; @@ -582,7 +582,7 @@ export class Producer { accept(info: Partial = {}): this { if (this.#state.closed.peek() !== undefined) return this; const resolved = infoDefaults(info); - for (const { group } of this.#cache) hooks.bindGroupTimed(group, resolved.timescale !== undefined); + for (const { group } of this.#cache) hooks.bindGroupTimed(group, resolved.timescale != null); this.#state.info.set(resolved); // Propagate to any sink handed out before accept (the on-demand path). for (const sink of this.#sinks) sink.info.set(resolved); @@ -819,13 +819,13 @@ export class Producer { // Hold a group to this track's timedness, once the track has committed it. #bind(group: GroupProducer): void { const info = this.#state.info.peek(); - if (info) hooks.bindGroupTimed(group, info.timescale !== undefined); + if (info) hooks.bindGroupTimed(group, info.timescale != null); } // Refuse a datagram whose timedness disagrees with this track's. #checkDatagram(timestamp: Timestamp | undefined): void { const info = this.#state.info.peek(); - if (info && (info.timescale !== undefined) !== (timestamp !== undefined)) throw new TimestampMismatch(); + if (info && (info.timescale != null) !== (timestamp !== undefined)) throw new TimestampMismatch(); } // Refuse a write once the track is closed, or at or past its declared end. @@ -1185,7 +1185,7 @@ export class Subscriber { // The newest servable group, when the track is known to be untimed. #untimedStart(): number | undefined { const info = this.#state.info.peek(); - if (!info || info.timescale !== undefined) return undefined; + if (!info || info.timescale != null) return undefined; const timeline = this.#state.timeline; for (let i = timeline.length - 1; i >= 0; i--) { if (!(timeline[i].closed.peek() instanceof Error)) return timeline[i].sequence; From 2b23aa35cd25f159e8e8b97d2268c6857e5f97e7 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 7 Oct 2026 11:14:13 -0700 Subject: [PATCH 6/8] fix(js/net): abort a failed single-frame write's group; settle an early subscriber's untimed start Co-Authored-By: Claude Opus 5.5 --- js/net/src/track.test.ts | 25 ++++++++++++++++++++++++ js/net/src/track.ts | 42 ++++++++++++++++++++++++++++++---------- 2 files changed, 57 insertions(+), 10 deletions(-) diff --git a/js/net/src/track.test.ts b/js/net/src/track.test.ts index b981671d05a..96425224281 100644 --- a/js/net/src/track.test.ts +++ b/js/net/src/track.test.ts @@ -2133,6 +2133,31 @@ test("an untimed track starts at its latest group", () => { expect(drain(live)).toEqual([5]); }); +test("an unfloored subscriber made before accept starts at the latest group once untimed", () => { + const producer = new TrackProducer("test"); + for (let i = 0; i < 3; i++) producer.appendGroup().close(); + const early = producer.subscribe(); + const floored = producer.subscribe({ groups: { start: { included: 0 } } }); + + producer.accept({}); + expect(drain(early)).toEqual([2]); + expect(drain(floored)).toEqual([0, 1, 2]); +}); + +test("a single-frame write that throws aborts its group", () => { + const producer = new TrackProducer("test").accept({}); + const subscriber = producer.subscribe(); + // writeString stamps the frame, which an untimed track refuses. + expect(() => producer.writeString("x")).toThrow(TimestampMismatch); + producer.writeFrame({ payload: enc.encode("y") }); + + // The failed group ends in that error instead of leaving a reader waiting on it. + const failed = subscriber.tryRecvGroup(); + expect(failed?.sequence).toBe(0); + expect(failed?.closed.peek()).toBeInstanceOf(TimestampMismatch); + expect(drain(subscriber)).toEqual([1]); +}); + test("an explicit start holds on an untimed track, and nothing there is stale", () => { const producer = untimedTrack(5); diff --git a/js/net/src/track.ts b/js/net/src/track.ts index 7dd6cb42f61..e2fd121ef5f 100644 --- a/js/net/src/track.ts +++ b/js/net/src/track.ts @@ -1020,30 +1020,35 @@ export class Producer { /** Append a frame as its own single-frame group. */ writeFrame(frame: Frame) { + this.#writeSingle((group) => group.writeFrame(frame)); + } + + // Write one frame as its own group, aborting the group if the write throws so no + // subscriber waits on a group that will never get its frame. + #writeSingle(write: (group: GroupProducer) => void): void { const group = this.appendGroup(); - group.writeFrame(frame); + try { + write(group); + } catch (err) { + group.close(err instanceof Error ? err : new Error(String(err))); + throw err; + } group.close(); } /** Appends a string to the track as its own single-frame group. */ writeString(str: string) { - const group = this.appendGroup(); - group.writeString(str); - group.close(); + this.#writeSingle((group) => group.writeString(str)); } /** Appends a JSON value to the track as its own single-frame group. */ writeJson(json: unknown) { - const group = this.appendGroup(); - group.writeJson(json); - group.close(); + this.#writeSingle((group) => group.writeJson(json)); } /** Appends a boolean to the track as its own single-frame group. */ writeBool(bool: boolean) { - const group = this.appendGroup(); - group.writeBool(bool); - group.close(); + this.#writeSingle((group) => group.writeBool(bool)); } } @@ -1061,6 +1066,8 @@ export class Subscriber { #state: TrackState; #nextSequence = 0; #cursor = new Signal<{ start: number; end?: number }>({ start: 0 }); + // Unfloored and made before accept(); see #settleStart. + #unsettled = false; #enforceLatency = true; // Which cursor owns this subscription. Both cursors draw from one buffer, so the // first group read commits the track to arrival order and {@link ordered} commits @@ -1184,6 +1191,19 @@ export class Subscriber { const groups = state.update.peek()?.groups ?? {}; const start = groups.start === undefined ? this.#untimedStart() : undefined; this.#cursor.set({ start: start ?? groupBounds(groups).start }); + // Timedness is unknown until accept(), so an unfloored subscriber made before it + // settles its start at the first read after. + this.#unsettled = groups.start === undefined && !state.info.peek(); + } + + // Raise the floor of an unfloored subscriber made before accept(), once the track is + // known to be untimed. Called before any read consults the cursor. + #settleStart(): void { + if (!this.#unsettled || !this.#state.info.peek()) return; + this.#unsettled = false; + const start = this.#untimedStart(); + if (start === undefined) return; + this.#cursor.update((cursor) => ({ ...cursor, start: Math.max(cursor.start, start) })); } // The newest servable group, when the track is known to be untimed. @@ -1410,6 +1430,7 @@ export class Subscriber { // Package-internal synchronous half of recvGroup. The lite publisher uses this so applying // control state, popping the group, and positioning its frames are one JavaScript turn. #tryRecvGroup(): Recv { + this.#settleStart(); const groups = this.#state.groups.peek(); const { start, end } = this.#cursor.peek(); while (groups.length > 0 && groups[0].sequence < start) groups.shift()?.close(); @@ -1513,6 +1534,7 @@ export class Subscriber { // The sequence cursor behind {@link Ordered}, which owns the only public door to it. async #nextGroup(): Promise { for (;;) { + this.#settleStart(); const groups = this.#state.groups.peek(); const cursor = this.#cursor.peek(); const start = Math.max(cursor.start, this.#nextSequence); From 61e2a2add148a6a55e7bef253ce3e96858844a56 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 7 Oct 2026 11:32:03 -0700 Subject: [PATCH 7/8] fix(js/net): settle an early untimed start at accept, under the end cap; accept refuses mismatched early writes Co-Authored-By: Claude Opus 5.5 --- js/net/src/track.test.ts | 30 +++++++++++++++++++++-- js/net/src/track.ts | 51 ++++++++++++++++++++++++++-------------- js/net/src/zod.ts | 2 +- 3 files changed, 63 insertions(+), 20 deletions(-) diff --git a/js/net/src/track.test.ts b/js/net/src/track.test.ts index 96425224281..bebea2b2630 100644 --- a/js/net/src/track.test.ts +++ b/js/net/src/track.test.ts @@ -2138,10 +2138,36 @@ test("an unfloored subscriber made before accept starts at the latest group once for (let i = 0; i < 3; i++) producer.appendGroup().close(); const early = producer.subscribe(); const floored = producer.subscribe({ groups: { start: { included: 0 } } }); + const named = producer.subscribe(); + named.setGroups({ start: { included: 1 } }); producer.accept({}); - expect(drain(early)).toEqual([2]); - expect(drain(floored)).toEqual([0, 1, 2]); + // Settled at accept(), so groups written before the first read still arrive. + producer.writeFrame({ payload: enc.encode("3") }); + producer.writeFrame({ payload: enc.encode("4") }); + expect(drain(early)).toEqual([2, 3, 4]); + expect(drain(floored)).toEqual([0, 1, 2, 3, 4]); + expect(drain(named)).toEqual([1, 2, 3, 4]); +}); + +test("an untimed subscriber without a start begins at the latest group under its end", () => { + const producer = untimedTrack(5); + // As the lite publisher serves a SUBSCRIBE with an end and no start. + const subscriber = producer.subscribe({ groups: { end: { excluded: 3 } } }); + subscriber.setGroups({ end: { excluded: 3 } }); + expect(drain(subscriber)).toEqual([2]); +}); + +test("accept closes the track when something written before it disagrees", async () => { + const timed = new TrackProducer("groups"); + timed.appendGroup().writeFrame({ payload: enc.encode("x"), timestamp: Timestamp.fromMillis(1) }); + expect(() => timed.accept({})).toThrow(TimestampMismatch); + await expect(timed.info()).rejects.toBeInstanceOf(TimestampMismatch); + + const datagrams = new TrackProducer("datagrams"); + datagrams.subscribe(); + datagrams.appendDatagram(Timestamp.fromMillis(1), enc.encode("x")); + expect(() => datagrams.accept({})).toThrow(TimestampMismatch); }); test("a single-frame write that throws aborts its group", () => { diff --git a/js/net/src/track.ts b/js/net/src/track.ts index e2fd121ef5f..bb94a2e4608 100644 --- a/js/net/src/track.ts +++ b/js/net/src/track.ts @@ -369,6 +369,9 @@ class TrackState { update: Signal; /** Resolved once the producer commits the immutable properties. */ info = new Signal(undefined); + // Set by an unfloored subscriber made before accept(), which calls it to settle its + // start the moment the track's timedness is known. + settle?: () => void; constructor(subscription?: Subscription) { this.update = new Signal(subscription === undefined ? undefined : subscriptionDefaults(subscription)); @@ -585,10 +588,26 @@ export class Producer { accept(info: Partial = {}): this { if (this.#state.closed.peek() !== undefined) return this; const resolved = infoDefaults(info); - for (const { group } of this.#cache) hooks.bindGroupTimed(group, resolved.timescale != null); + const timed = resolved.timescale != null; + // Anything written before accept() must match too. A mismatch closes the track, so + // nothing waiting on info() hangs on a half-bound cache. + try { + for (const { group } of this.#cache) hooks.bindGroupTimed(group, timed); + for (const sink of this.#sinks) { + for (const datagram of sink.datagrams.peek()) { + if ((datagram.timestamp !== undefined) !== timed) throw new TimestampMismatch(); + } + } + } catch (err) { + this.close(err instanceof Error ? err : new Error(String(err))); + throw err; + } this.#state.info.set(resolved); // Propagate to any sink handed out before accept (the on-demand path). - for (const sink of this.#sinks) sink.info.set(resolved); + for (const sink of this.#sinks) { + sink.info.set(resolved); + sink.settle?.(); + } this.#updateSubscription(); return this; } @@ -1066,8 +1085,6 @@ export class Subscriber { #state: TrackState; #nextSequence = 0; #cursor = new Signal<{ start: number; end?: number }>({ start: 0 }); - // Unfloored and made before accept(); see #settleStart. - #unsettled = false; #enforceLatency = true; // Which cursor owns this subscription. Both cursors draw from one buffer, so the // first group read commits the track to arrival order and {@link ordered} commits @@ -1189,29 +1206,29 @@ export class Subscriber { // Nothing on an untimed track is ever stale, so there the budget would replay the // whole cache: an unfloored subscriber starts at the latest group instead. const groups = state.update.peek()?.groups ?? {}; - const start = groups.start === undefined ? this.#untimedStart() : undefined; - this.#cursor.set({ start: start ?? groupBounds(groups).start }); + const bounds = groupBounds(groups); + const start = groups.start === undefined ? this.#untimedStart(bounds.end) : undefined; + this.#cursor.set({ start: start ?? bounds.start }); // Timedness is unknown until accept(), so an unfloored subscriber made before it - // settles its start at the first read after. - this.#unsettled = groups.start === undefined && !state.info.peek(); + // settles its start then, against the groups that existed at that moment. + if (groups.start === undefined && !state.info.peek()) state.settle = () => this.#settleStart(); } // Raise the floor of an unfloored subscriber made before accept(), once the track is - // known to be untimed. Called before any read consults the cursor. + // known to be untimed. #settleStart(): void { - if (!this.#unsettled || !this.#state.info.peek()) return; - this.#unsettled = false; - const start = this.#untimedStart(); + this.#state.settle = undefined; + const start = this.#untimedStart(this.#cursor.peek().end); if (start === undefined) return; this.#cursor.update((cursor) => ({ ...cursor, start: Math.max(cursor.start, start) })); } - // The newest servable group, when the track is known to be untimed. - #untimedStart(): number | undefined { + // The newest servable group below the `end` cap, when the track is known to be untimed. + #untimedStart(end: number | undefined): number | undefined { const info = this.#state.info.peek(); if (!info || info.timescale != null) return undefined; const timeline = this.#state.timeline; - for (let i = timeline.length - 1; i >= 0; i--) { + for (let i = (end === undefined ? timeline.length : timelineIndex(timeline, end)) - 1; i >= 0; i--) { if (!(timeline[i].closed.peek() instanceof Error)) return timeline[i].sequence; } return undefined; @@ -1355,6 +1372,7 @@ export class Subscriber { */ setGroups(groups: Groups): void { const { start, end } = groupBounds(groups); + if (groups.start !== undefined) this.#state.settle = undefined; this.#cursor.update((cursor) => ({ start: Math.max(cursor.start, start), end })); } @@ -1362,6 +1380,7 @@ export class Subscriber { // Rust `start_at`. Local readers stay monotonic; only the wire publisher lowers. #replaceGroups(groups: Groups): void { const { start, end } = groupBounds(groups); + if (groups.start !== undefined) this.#state.settle = undefined; this.#cursor.update((cursor) => ({ start: groups.start === undefined ? cursor.start : start, end, @@ -1430,7 +1449,6 @@ export class Subscriber { // Package-internal synchronous half of recvGroup. The lite publisher uses this so applying // control state, popping the group, and positioning its frames are one JavaScript turn. #tryRecvGroup(): Recv { - this.#settleStart(); const groups = this.#state.groups.peek(); const { start, end } = this.#cursor.peek(); while (groups.length > 0 && groups[0].sequence < start) groups.shift()?.close(); @@ -1534,7 +1552,6 @@ export class Subscriber { // The sequence cursor behind {@link Ordered}, which owns the only public door to it. async #nextGroup(): Promise { for (;;) { - this.#settleStart(); const groups = this.#state.groups.peek(); const cursor = this.#cursor.peek(); const start = Math.max(cursor.start, this.#nextSequence); diff --git a/js/net/src/zod.ts b/js/net/src/zod.ts index ccc56720c18..abca3cd278c 100644 --- a/js/net/src/zod.ts +++ b/js/net/src/zod.ts @@ -18,7 +18,7 @@ export async function read( return schema.parse(next); } -/** Validate a value against the schema, then write it as a JSON frame. */ +/** Validate a value against the schema, then write it as a JSON frame stamped now, so the track must be timed. */ export function write(source: track.Producer | group.Producer, value: T, schema: z.ZodMiniType) { const valid = schema.parse(value); source.writeJson(valid); From 4cee4bf0b1b6d7eb015950ce94a7d41ab4e8d574 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 7 Oct 2026 14:04:27 -0700 Subject: [PATCH 8/8] fix(js/net): a group bound to one track's timedness can't join a track of the other An empty group appended to a timed track could be written into an untimed one, which flipped its binding and let an untimed frame through the timed track. Refuse the second bind with TimestampMismatch. Co-Authored-By: Claude Opus 5.5 --- js/net/src/group.ts | 2 ++ js/net/src/track.test.ts | 10 ++++++++++ 2 files changed, 12 insertions(+) diff --git a/js/net/src/group.ts b/js/net/src/group.ts index b76efdb083d..7684e19df63 100644 --- a/js/net/src/group.ts +++ b/js/net/src/group.ts @@ -161,6 +161,8 @@ export class Producer { hooks.bindGroupTimed = (group, timed) => { const state = group.#state; if (state.timed === timed) return; + // Another track already holds it to the opposite timedness, empty or not. + if (state.timed !== undefined) throw new TimestampMismatch(); for (const frame of state.frames.peek()) checkTimed(timed, frame); state.timed = timed; }; diff --git a/js/net/src/track.test.ts b/js/net/src/track.test.ts index bebea2b2630..3adf7a93689 100644 --- a/js/net/src/track.test.ts +++ b/js/net/src/track.test.ts @@ -2108,6 +2108,16 @@ test("a group joining a track it disagrees with is refused", () => { expect(() => producer.writeGroup(group)).toThrow(TimestampMismatch); }); +test("an empty group bound to a timed track can't join an untimed one", () => { + const timed = new TrackProducer("timed").accept({ timescale: Timescale.MILLI }); + const untimed = new TrackProducer("untimed").accept({}); + const group = timed.appendGroup(); + expect(() => untimed.writeGroup(group)).toThrow(TimestampMismatch); + // Still held to the timed track it was bound to first. + expect(() => group.writeFrame({ payload: enc.encode("x") })).toThrow(TimestampMismatch); + group.writeFrame({ payload: enc.encode("x"), timestamp: Timestamp.fromMillis(1) }); +}); + test("a datagram whose timedness disagrees with its track is refused", async () => { const timed = new TrackProducer("timed").accept({ timescale: Timescale.MILLI }); expect(() => timed.appendDatagram(undefined, enc.encode("x"))).toThrow(TimestampMismatch);