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 0d5ae63626a..1ae7662e2ac 100644 --- a/doc/lib/js/json.md +++ b/doc/lib/js/json.md @@ -34,7 +34,8 @@ 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 })`. A Stream rides one group, so the whole log shares `@moq/net`'s group budget: 32 MiB of payload and 8192 records. An `append` that might not fit throws diff --git a/doc/lib/js/net.md b/doc/lib/js/net.md index bf33ec0defc..1a67f3ba283 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,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 delay, 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 (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 delay measured against media timestamps, and optional `groups` bounds. Subscription options use `maxDelay`; supplying the obsolete subscriber `maxAge` key throws a `TypeError` naming its replacement, including on `update()`. 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 finished track stays on its broadcast and serves its cache to late subscribers until `removeTrack`; an aborted one is removed, and subscribing to a track the broadcast does not have rejects with `Error.NotFound` when no on-demand handler is pulling requests, as in Rust. With a pulling handler, an absent track queues an on-demand request. 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 delay 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 abe91e70c5c..572c7d86a3a 100644 --- a/doc/lib/js/publish.md +++ b/doc/lib/js/publish.md @@ -115,13 +115,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/flate/src/snapshot/snapshot.test.ts b/js/flate/src/snapshot/snapshot.test.ts index 6de4bf30cc5..7c54bd9721f 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 ee8e961a5d3..5cf435db8cc 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/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 6e6a6bebeb4..89453f3d1f6 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 delay 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({ maxDelay: Time.Milli(5000) }), { format: new LegacyFormat("data"), maxDelay: 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({ maxDelay: Time.Milli(5000) }), { format: new LegacyFormat("data"), maxDelay: 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 delay. 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({ maxDelay: Time.Milli(5000) }), { format: new LegacyFormat("data"), maxDelay: 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/json/src/snapshot/snapshot.test.ts b/js/json/src/snapshot/snapshot.test.ts index f97ddcc3482..e97875ce468 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 c8ec883b8cf..154a5a30191 100644 --- a/js/json/src/stream/stream.test.ts +++ b/js/json/src/stream/stream.test.ts @@ -158,8 +158,8 @@ 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); }); // A record past the group budget is refused before anything is written, so the log carries on: the 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 70c4742f965..e2eae3156f0 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({ maxDelay: 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 08cc430d17a..cfeac3e8c3c 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, NotFound } 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"); @@ -64,7 +64,7 @@ test("dynamic track sequences continue across producer replacements", async () = const firstSubscriber = broadcast.track("media").subscribe(); const firstRequest = await firstPull; 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)); @@ -75,7 +75,7 @@ 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(); @@ -83,7 +83,7 @@ test("dynamic track sequences continue across producer replacements", async () = const nextSubscriber = nextGeneration.track("media").subscribe(); const nextRequest = await nextPull; 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(); @@ -100,8 +100,8 @@ test("concurrent dynamic producers share a sequence namespace", async () => { const firstRequest = await pulled; 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); @@ -122,8 +122,8 @@ test("a sibling producer's groups do not settle an aborted end", async () => { const firstRequest = await pulled; 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); @@ -149,8 +149,8 @@ test("a clean close ends at the track's own last group, not a sibling's", async const firstRequest = await pulled; 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(); @@ -174,8 +174,8 @@ test("finishAt accepts an end below a sibling's groups", async () => { const firstRequest = await pulled; 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(); @@ -200,7 +200,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(); @@ -283,7 +283,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"); @@ -297,7 +297,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(); @@ -309,7 +309,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(); @@ -319,7 +319,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") @@ -342,7 +342,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"); @@ -356,7 +356,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({ maxDelay: Milli(5000) }) @@ -384,7 +384,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(); @@ -413,7 +413,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(); @@ -423,13 +423,13 @@ 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 finished track is still served from its cache", async () => { const broadcast = new BroadcastProducer(); - const track = broadcast.createTrack("track1"); + const track = broadcast.createTrack("track1", { timescale: Timescale.MILLI }); track.writeString("last"); track.close(); @@ -468,13 +468,13 @@ test("an aborted track falls through to a request when a handler is serving", as 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 and nothing serving on demand, the track is not found. const removed = new BroadcastProducer(); - removed.createTrack("track1"); + removed.createTrack("track1", { timescale: Timescale.MILLI }); removed.removeTrack("track1"); await expect(removed.track("track1").subscribe().info()).rejects.toBeInstanceOf(NotFound); }); @@ -500,7 +500,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); @@ -521,7 +521,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); @@ -540,7 +540,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); @@ -566,7 +566,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(); @@ -590,7 +590,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); @@ -606,7 +606,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); @@ -625,7 +625,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/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 58226443ad7..7684e19df63 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,17 @@ 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; + // 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; + }; + } + /** * When the group was created or last written, in `performance.now()` milliseconds. * @@ -224,6 +245,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 +274,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.test.ts b/js/net/src/ietf/publisher.test.ts index 310eb85f945..55815dc3f9f 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 941b6ba67a3..ced1f823bff 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 @@ -431,7 +426,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), @@ -525,7 +521,6 @@ export class Publisher { group, timescale, publisherPriority, - stamped, slice: groupSlice(range, group.sequence), unsubscribed, streams, @@ -545,7 +540,6 @@ export class Publisher { fill, cache, timescale, - stamped, unsubscribed, streams, }) @@ -630,7 +624,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 @@ -655,7 +649,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, @@ -765,7 +759,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, @@ -790,7 +784,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(); } @@ -817,8 +811,7 @@ export class Publisher { stream: Writer, group: group.Consumer, fill: FillGroup, - timescale: Timescale, - stamped: boolean, + timescale: Timescale | undefined, unsubscribed: Promise, ) { let first = true; @@ -846,7 +839,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 ff6415c9d58..68096f7b61d 100644 --- a/js/net/src/ietf/subscriber.test.ts +++ b/js/net/src/ietf/subscriber.test.ts @@ -6,11 +6,13 @@ import { hooks } from "../internal.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"; @@ -873,7 +875,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 }); @@ -886,11 +890,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).toBeUndefined(); + + // 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 dbffb1c1f73..6ad28f43c42 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. @@ -807,6 +807,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, priority: fromWire(ok.properties.priority ?? 128), maxAge: maxCacheDuration === undefined ? undefined : Milli(Number(maxCacheDuration)), }); @@ -1096,7 +1099,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: @@ -1124,15 +1128,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 ad88cfc153b..2a0b8edb12c 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 maxDelay as a whole millisecond", 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); } })(); @@ -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) }); @@ -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(); @@ -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(); @@ -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(); @@ -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/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/connection.test.ts b/js/net/src/lite/connection.test.ts index 6409c056d5b..ebe48b84b02 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/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/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 5ec6325c380..b1130a8f2ab 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 b7cafb81d07..756dcefd87e 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 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; +} + +/** + * 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 2a2ddb5f993..cbefd485645 100644 --- a/js/net/src/lite/subscriber.ts +++ b/js/net/src/lite/subscriber.ts @@ -661,7 +661,7 @@ export class Subscriber { producer = request.accept(this.#toModelInfo(info)); timescale.set(info.timescale); } else { - // Older drafts negotiate nothing per-track: verbatim frames, no timescale. + // Older drafts negotiate nothing per-track: verbatim frames with no timeline. 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 034642fc9ab..c1dd73f3ae7 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,8 +46,10 @@ test("TrackInfo round-trips on draft-05", async () => { expect(got.timescale).toBe(90000); }); -test("TrackInfo defaults match cross-language wire bytes", async () => { - const info = new TrackInfo(infoDefaults()); +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 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/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 478caa64718..c2f8f9cdd10 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({ maxDelay: MAX_DELAY }).ordered(); diff --git a/js/net/src/track.test.ts b/js/net/src/track.test.ts index 96971498307..3adf7a93689 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"; @@ -383,7 +383,7 @@ test("the producer aggregate is clamped without changing subscriber options", as const track = producer.subscribe({ maxDelay: 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)?.maxDelay).toBe(Milli(2_000)); expect(track.subscription.peek()?.maxDelay).toBe(Milli(10_000)); @@ -422,7 +422,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({ maxDelay: Milli(500) }); // Group 0 spans 0..2000ms; group 1 starts at 2000ms, where group 0 ends. @@ -438,7 +438,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({ maxDelay: Milli(500) }); const long = producer.appendGroup(); @@ -473,7 +473,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(); @@ -495,7 +495,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) }); @@ -511,7 +511,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({ maxDelay: Milli(500) }); for (const [sequence, ms] of [ @@ -534,7 +534,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({ maxDelay: Milli(5000) }).ordered(); const live = producer.subscribe().ordered(); @@ -610,7 +610,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"); @@ -622,7 +622,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({ maxDelay: Milli(1500) }); for (const timestamp of [0, 1000, 2000]) { @@ -636,7 +636,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], @@ -667,7 +667,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) }); } @@ -685,7 +685,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) }); } @@ -710,7 +710,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({ maxDelay: Milli(60_000) }); // Spaced so group 0's reach (2s) sits 2s behind the edge (4s): outside the @@ -729,7 +729,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 @@ -752,7 +752,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(); @@ -801,7 +801,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({ maxDelay: Milli(1000) }); const open = producer.appendGroup(); @@ -822,13 +822,13 @@ 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 () => { 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(); @@ -859,7 +859,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) }); @@ -867,13 +867,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"); @@ -893,7 +893,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({ maxDelay: Milli(100) }); const source = producer.appendGroup(); source.writeFrame({ payload: enc.encode("old"), timestamp: Timestamp.fromMillis(0) }); @@ -920,7 +920,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({ maxDelay: Milli(100) }); const source = producer.appendGroup(); source.writeFrame({ payload: enc.encode("old"), timestamp: Timestamp.fromMillis(0) }); @@ -952,7 +952,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"); @@ -968,7 +968,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) }); @@ -987,7 +987,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]) { @@ -1014,7 +1014,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({ maxDelay: Milli(100) }); const source = producer.appendGroup(); source.writeString("first"); @@ -1037,7 +1037,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({ maxDelay: Milli(100) }); const source = producer.appendGroup(); source.writeString("first"); @@ -1061,7 +1061,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({ maxDelay: Milli(100) }); const stalled = producer.appendGroup(); stalled.writeString("first"); @@ -1086,7 +1086,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({ maxDelay: Milli(100) }); const edge = producer.appendGroup(); edge.writeString("first"); @@ -1115,7 +1115,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({ maxDelay: Milli(30) }); const stalled = producer.appendGroup(); @@ -1137,7 +1137,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(); @@ -1152,7 +1152,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({ maxDelay: Milli(100) }); const source = producer.appendGroup(); source.writeString("only"); @@ -1178,7 +1178,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({ maxDelay: Milli(100) }); producer.writeString("old"); @@ -1194,7 +1194,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({ maxDelay: Milli(5000) }); const source = producer.appendGroup(); const group = await track.recvGroup(); @@ -1208,7 +1208,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); @@ -1227,7 +1227,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); @@ -1265,7 +1265,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 } }); @@ -1281,7 +1281,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({ maxDelay: Milli(5000) }).ordered(); track.setGroups({ end: { excluded: 1 } }); @@ -1622,7 +1622,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({ maxDelay: Milli(1_000) }); // Nothing published yet. @@ -1653,7 +1653,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++) { @@ -1852,7 +1852,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"); @@ -1877,7 +1877,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"); @@ -1899,7 +1899,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({ maxDelay: Milli(100_000) }); const snapshot = producer.appendGroup(); snapshot.writeString("snapshot"); @@ -1924,7 +1924,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(); @@ -1960,7 +1960,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({ maxDelay: Milli(10_000) }); const ordered = producer.subscribe({ maxDelay: Milli(10_000) }).ordered(); for (let i = 0; i < 2; i++) { @@ -1984,7 +1984,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({ maxDelay: Milli(10_000) }); const ordered = producer.subscribe({ maxDelay: Milli(10_000) }).ordered(); for (let i = 0; i < 2; i++) { @@ -2003,7 +2003,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")); @@ -2013,7 +2013,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({ maxDelay: Milli(30) }); const group = producer.appendGroup(); @@ -2033,7 +2033,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({ maxDelay: Milli(10_000) }); const ordered = producer.subscribe({ maxDelay: Milli(10_000) }).ordered(); producer.appendGroup().writeString("held"); @@ -2047,3 +2047,160 @@ 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({}); + for (let i = 0; i < count; i++) producer.writeFrame({ payload: enc.encode(`${i}`) }); + return producer; +} + +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 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(); + 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({}); + 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({}); + const group = new GroupProducer(0); + group.writeFrame({ payload: enc.encode("x"), timestamp: Timestamp.fromMillis(1) }); + 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); + + 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")); + 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({ maxDelay: Milli(60_000) }); + expect(drain(patient)).toEqual([4]); + + producer.writeFrame({ payload: enc.encode("5") }); + 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 } } }); + const named = producer.subscribe(); + named.setGroups({ start: { included: 1 } }); + + producer.accept({}); + // 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", () => { + 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); + + // 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 54c42587b90..bb94a2e4608 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,16 @@ 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 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 + * 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; + 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 +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: Timescale(info.timescale ?? Timescale.MILLI), + timescale: info.timescale == null ? undefined : Timescale(info.timescale), maxAge: info.maxAge === undefined ? undefined : wireMillis("maxAge", info.maxAge), priority: priorityByte(info.priority ?? DEFAULT_PRIORITY), }; @@ -141,9 +146,10 @@ export interface Subscription { * The lowest group the publisher may deliver (a floor), or omit for none. * * A floor, not a request: only {@link maxDelay} 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; } @@ -290,7 +296,8 @@ export class Consumer { * The cursor starts at the group the subscription named (its floor), or 0. * {@link Subscription.maxDelay} 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); @@ -362,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)); @@ -379,8 +389,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(); @@ -577,9 +588,26 @@ export class Producer { accept(info: Partial = {}): this { if (this.#state.closed.peek() !== undefined) return this; const resolved = infoDefaults(info); + 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; } @@ -590,7 +618,8 @@ export class Producer { * Its cursor starts at the group the subscription named (its floor), or 0. * {@link Subscription.maxDelay} 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); @@ -810,6 +839,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"); @@ -819,11 +860,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); @@ -836,10 +883,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) { @@ -883,12 +933,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 }); @@ -899,12 +953,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) { @@ -984,30 +1039,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)); } } @@ -1143,7 +1203,35 @@ 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.maxDelay} 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 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 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. + #settleStart(): void { + 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 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 = (end === undefined ? timeline.length : timelineIndex(timeline, end)) - 1; i >= 0; i--) { + if (!(timeline[i].closed.peek() instanceof Error)) return timeline[i].sequence; + } + return undefined; } static { @@ -1175,8 +1263,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 { @@ -1283,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 })); } @@ -1290,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, diff --git a/js/net/src/untimed.test.ts b/js/net/src/untimed.test.ts new file mode 100644 index 00000000000..8c8c2e3f3c7 --- /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 | undefined, 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).toBeUndefined(); + 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, 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 milliseconds. + expect(info.timescale).toBe(Timescale.MILLI); + for (const frame of frames) expect(frame.timestamp).toBeDefined(); + } else { + expect(info.timescale).toBeUndefined(); + 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).toBeUndefined(); + for (const frame of frames) expect(frame.timestamp).toBeUndefined(); + } + }); +} 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); diff --git a/js/publish/src/audio/encoder.test.ts b/js/publish/src/audio/encoder.test.ts index 48a442efb36..c8415751b12 100644 --- a/js/publish/src/audio/encoder.test.ts +++ b/js/publish/src/audio/encoder.test.ts @@ -207,7 +207,7 @@ function configured(): Promise { async function setup(baseline = new Baseline(), codec?: Codec, groupDuration?: Time.Milli) { 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 groups: number[] = []; const appended: ReturnType[] = []; 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 e7de4e13ab5..453c545f137 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/README.md b/quest/m1/README.md index 76699d10e74..cd1bd50789b 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. - [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 - [Untimed decisions](/quest/m1/untimed-decisions.md) - the maintainer decides whether moq-archive keeps refusing untimed tracks, and whether a malformed FETCH object ends its track -- [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 6cae2c87689..aed3340a669 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 3f3fd54be08..1158f3b282f 100644 --- a/quest/m1/js-publish-timestamp.md +++ b/quest/m1/js-publish-timestamp.md @@ -25,10 +25,12 @@ Decided (2026-10-05, types settled 2026-10-06): timedness is per track, as the untimed model ([#4822](https://github.com/moq-dev/moq/pull/4822)) 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 +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. -- [@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 +Public API: breaking. Wire: none. diff --git a/quest/m1/js-untimed-model.md b/quest/m1/js-untimed-model.md deleted file mode 100644 index dfa93b899f1..00000000000 --- a/quest/m1/js-untimed-model.md +++ /dev/null @@ -1,49 +0,0 @@ -# [M] @moq/net carries untimed frames faithfully - -## Goal - -`@moq/net` mirrors the Rust untimed model ([#4822](https://github.com/moq-dev/moq/pull/4822)). 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, deleted by [#4822](https://github.com/moq-dev/moq/pull/4822); keep the two in step. - -Decided (2026-10-05, types settled 2026-10-06): timedness is per track, as -the untimed model 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 - -- [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 f5e6b1562cf..a3f8962fdf0 100644 --- a/quest/m1/lite-untimed.md +++ b/quest/m1/lite-untimed.md @@ -47,7 +47,3 @@ JS-to-Rust on lite-07. lite-06 still receives a timestamp. Run `just drafts check` and `just test interop --all`. Public API: none. Wire: lite-07-wip only, which is unpublished. - -## Required - -- [@moq/net carries untimed frames faithfully](/quest/m1/js-untimed-model.md) - the same for JS diff --git a/test/audio-quality/clients/js/src/capture.test.ts b/test/audio-quality/clients/js/src/capture.test.ts index af642abe828..6548ffcb714 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 e69302b8577..e4ec44c9eb0 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/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); 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;