From 605e7db69cae8aabf906805ed89eaa3d3fae7245 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Thu, 8 Oct 2026 16:29:59 -0700 Subject: [PATCH 1/3] quest: claim m1/js-publish-timestamp Co-Authored-By: Claude Opus 5.5 From 16a67f64aa0ffec0e8ae33d26c9b6ebb55b0acff Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Thu, 8 Oct 2026 16:42:07 -0700 Subject: [PATCH 2/3] feat(js)!: publishing never invents a timestamp @moq/json and @moq/flate producers take a Timed ({ value, at? }) exported from @moq/net; an absent at goes out untimed instead of stamped now. The json window producer's push and pop take the timestamp too, and snapshot mutate takes an optional at. @moq/net drops writeString, writeJson, and writeBool from the group and track producers, and zod.write with them; writeFrame already takes a timestamp. In-repo publishers pass Time.Timestamp.now() explicitly. Co-Authored-By: Claude Opus 5.5 --- demo/web/src/publish.ts | 4 +- doc/lib/js/flate.md | 10 ++- doc/lib/js/json.md | 7 +- doc/lib/js/net.md | 4 +- doc/lib/js/publish.md | 6 +- js/clock/src/main.ts | 5 +- js/flate/README.md | 5 +- js/flate/src/snapshot/producer.ts | 7 +- js/flate/src/snapshot/snapshot.test.ts | 26 ++++-- js/flate/src/stream/producer.ts | 7 +- js/flate/src/stream/stream.test.ts | 30 ++++--- js/hang/src/catalog/consumer.test.ts | 8 +- js/hang/src/timeline.test.ts | 17 +++- js/json/README.md | 9 +- js/json/src/snapshot/codec.test.ts | 6 +- js/json/src/snapshot/compression.test.ts | 30 +++---- js/json/src/snapshot/producer.ts | 16 ++-- js/json/src/snapshot/snapshot.test.ts | 100 +++++++++++++---------- js/json/src/stream/codec.test.ts | 8 +- js/json/src/stream/producer.ts | 7 +- js/json/src/stream/stream.test.ts | 40 +++++---- js/json/src/window/producer.ts | 26 ++++-- js/json/src/window/window.test.ts | 27 ++++-- js/moq-boy/src/game.ts | 2 +- js/net/examples/publish.ts | 6 +- js/net/src/broadcast.test.ts | 25 +++--- js/net/src/goaway-requests.test.ts | 10 +-- js/net/src/group.test.ts | 19 +++-- js/net/src/group.ts | 17 +--- js/net/src/index.ts | 1 + js/net/src/integration.test.ts | 72 ++++++++-------- js/net/src/lite/connection.test.ts | 12 +-- js/net/src/lite/publisher.test.ts | 28 +++---- js/net/src/mock.ts | 9 +- js/net/src/tail.test.ts | 14 ++-- js/net/src/timed.ts | 14 ++++ js/net/src/track.test.ts | 89 ++++++++++---------- js/net/src/track.ts | 24 +----- js/net/src/zod.ts | 8 +- js/publish/src/catalog.ts | 6 +- js/room/src/chat.test.ts | 7 +- js/room/src/chat.ts | 4 +- js/room/src/metadata.test.ts | 4 +- js/room/src/metadata.ts | 2 +- js/watch/src/broadcast.test.ts | 4 +- quest/m1/README.md | 1 - quest/m1/js-data-consumer-timestamps.md | 7 +- quest/m1/js-publish-timestamp.md | 46 ----------- quest/m1/publish-timestamp.md | 1 - 49 files changed, 435 insertions(+), 402 deletions(-) create mode 100644 js/net/src/timed.ts delete mode 100644 quest/m1/js-publish-timestamp.md diff --git a/demo/web/src/publish.ts b/demo/web/src/publish.ts index 324e4a55e58..af904ee1584 100644 --- a/demo/web/src/publish.ts +++ b/demo/web/src/publish.ts @@ -391,7 +391,7 @@ let activeMeta: Json.Snapshot.Producer | undefined; const setMeta = (value: unknown) => { currentMeta = value; - activeMeta?.update(value); + activeMeta?.update({ value, at: Net.Time.Timestamp.now() }); }; const meta = new Signals.Effect(); @@ -408,7 +408,7 @@ meta.run((effect) => { effect.cleanup(() => track.close()); const producer = new Json.Snapshot.Producer({ track }); - producer.update(currentMeta); + producer.update({ value: currentMeta, at: Net.Time.Timestamp.now() }); activeMeta = producer; effect.cleanup(() => { if (activeMeta === producer) activeMeta = undefined; diff --git a/doc/lib/js/flate.md b/doc/lib/js/flate.md index 7ddf9e5b80a..917de5fc291 100644 --- a/doc/lib/js/flate.md +++ b/doc/lib/js/flate.md @@ -19,14 +19,16 @@ group-scoped DEFLATE `@moq/json` uses. ```ts import { Snapshot } from "@moq/flate"; +import { Time } from "@moq/net"; const producer = new Snapshot.Producer({ track, compression: "deflate" }); -producer.update(payload); +producer.update({ value: payload, at: Time.Timestamp.now() }); ``` -A payload is stamped when written, unless you pass its capture time: -`producer.update(payload, at)`. Every frame carries a timestamp, so the track must -declare a timescale, such as `createTrack(name, { timescale: Time.Timescale.MILLI })`. +Producers take a `Timed` value, `{ value, at }`, where `at` is the capture +time written as the frame timestamp. Nothing fills in now: a timed track, such +as `createTrack(name, { timescale: Time.Timescale.MILLI })`, needs `at` on +every write, and an untimed track (no `timescale`) takes none. 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 1a7b5d91297..a3d42106d74 100644 --- a/doc/lib/js/json.md +++ b/doc/lib/js/json.md @@ -16,9 +16,10 @@ reader will not pick it up. - **Stream**: lossless append-log in a single group. A reader that falls behind fails the read rather than resuming mid-log. - **Window**: a bounded run of records a reader can join at any point. A new group restates what it keeps explicitly, so a reader that was keeping up is not handed a record twice. -Both sides choose the same compression, `"none"` or `"deflate"`. A value is -stamped when written, unless you pass its capture time, so the track must -declare a timescale. +Both sides choose the same compression, `"none"` or `"deflate"`. Producers take +a `Timed` value, `{ value, at }`, where `at` is the capture time written as +the frame timestamp. Nothing fills in now: a timed track needs `at` on every +write, and an untimed track (no `timescale`) takes none. 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 is refused diff --git a/doc/lib/js/net.md b/doc/lib/js/net.md index 8db354e6654..2294fb07be8 100644 --- a/doc/lib/js/net.md +++ b/doc/lib/js/net.md @@ -28,7 +28,7 @@ const connection = await Moq.Connection.connect({ const broadcast = origin.createBroadcast(Moq.Path.from("chat.room")); const track = broadcast.createTrack("messages", { timescale: Moq.Time.Timescale.MILLI }); const group = track.appendGroup(); -group.writeString("hello"); +group.writeFrame({ payload: new TextEncoder().encode("hello"), timestamp: Moq.Time.Timestamp.now() }); group.close(); broadcast.announce(); ``` @@ -39,7 +39,7 @@ broadcast.announce(); - **GOAWAY moves the session.** The connection dials the replacement at once while the old session keeps serving its groups, up to `goaway.handover` (default 10s, or the relay's deadline when that is sooner). New requests keep opening on the old session until the replacement's route outranks it. An empty GOAWAY redials the same URL. A redirect stays on the same host unless `goaway.redirect` is `"follow"`. - **One send estimate per connection.** `Bandwidth.Allocator` divides it by track priority, max-min fair within a tier. An idle track claims nothing. Publishers reserve against it so their targets sum to the estimate. - **One track per name.** Concurrent subscriptions share one request and producer. An on-demand producer that replaces an ended one continues the name's group and datagram sequences; only a new broadcast restarts them. `createTrack` and `insertTrack` start at 0. -- **Timing is per track, with no default.** A track that declares a `timescale` carries a `timestamp` on every frame; one without is [untimed](/concept/moq-lite#subscriptions) and its frames carry none. Unlike Rust, omitting it means untimed. +- **Timing is per track, with no default.** A track that declares a `timescale` carries a `timestamp` on every frame; one without is [untimed](/concept/moq-lite#subscriptions) and its frames carry none. Unlike Rust, omitting it means untimed. Nothing stamps a frame for you: the publisher passes the timestamp, and the `Timed` type (`{ value, at }`) carries one into the `@moq/json` and `@moq/flate` producers. - **Subscriber staleness is `maxDelay`.** It is media time. Passing the old `maxAge` key throws a `TypeError` naming `maxDelay`. Publisher retention is the separate `Track.Info.maxAge`. - **Hidden paths** stay out of discovery unless the announce request opts in. See [hidden broadcasts](/concept/moq-lite#hidden-broadcasts). - **A graceful close waits.** `await connection.close()` withdraws announcements and gives finished tracks up to one second. `abort()` ends immediately. diff --git a/doc/lib/js/publish.md b/doc/lib/js/publish.md index df70c8320ed..c26e34b6243 100644 --- a/doc/lib/js/publish.md +++ b/doc/lib/js/publish.md @@ -75,8 +75,8 @@ 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. JSON - // values are stamped when written, so the track declares a timescale. + // A day-long retention so a late viewer still replays the last value. Each + // value is stamped with when it was 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), @@ -84,7 +84,7 @@ signals.run((effect) => { effect.cleanup(() => track.close()); const meta = new Json.Snapshot.Producer({ track }); - meta.update(current); + meta.update({ value: current, at: Moq.Time.Timestamp.now() }); }); ``` diff --git a/js/clock/src/main.ts b/js/clock/src/main.ts index 66e9974cd54..f1123dfc3ef 100755 --- a/js/clock/src/main.ts +++ b/js/clock/src/main.ts @@ -91,6 +91,7 @@ async function publish(config: Config) { async function publishTrack(track: Moq.Track.Producer) { // Send timestamps over the wire, matching the Rust implementation format console.log("✅ Publishing clock data on track:", track.name); + const encoder = new TextEncoder(); for (;;) { const now = new Date(); @@ -100,7 +101,7 @@ async function publishTrack(track: Moq.Track.Producer) { // Send the base timestamp (everything but seconds) - matching Rust format const base = `${now.toISOString().slice(0, 16).replace("T", " ")}:`; - group.writeString(base); + group.writeFrame({ payload: encoder.encode(base), timestamp: Moq.Time.Timestamp.now() }); // Send individual seconds for this minute const currentMinute = now.getMinutes(); @@ -109,7 +110,7 @@ async function publishTrack(track: Moq.Track.Producer) { const secondsNow = new Date(); const seconds = secondsNow.getSeconds().toString().padStart(2, "0"); - group.writeString(seconds); + group.writeFrame({ payload: encoder.encode(seconds), timestamp: Moq.Time.Timestamp.now() }); // Wait until next second const nextSecond = new Date(secondsNow); diff --git a/js/flate/README.md b/js/flate/README.md index de88ec1ac0d..02642752f9a 100644 --- a/js/flate/README.md +++ b/js/flate/README.md @@ -16,9 +16,10 @@ The bytes are opaque: the tracks frame them onto a [`@moq/net`](../net) track an ```ts import { Snapshot, Stream } from "@moq/flate"; +import { Time } from "@moq/net"; const thumbnail = new Snapshot.Producer({ track, compression: "deflate" }); -thumbnail.update(jpeg); +thumbnail.update({ value: jpeg, at: Time.Timestamp.now() }); const log = new Stream.Consumer({ track: subscriber, compression: "deflate" }); for (;;) { @@ -29,6 +30,8 @@ for (;;) { Compression is opt-in per track (`compression: "none" | "deflate"`, default `"none"`); a consumer must set the same value as the producer. +Producers take `{ value, at }`, where `at` is the capture time written as the frame timestamp. Nothing fills in now: a timed track needs `at` on every write, and an untimed track takes none. + ## Codec A sequence of frame payloads is compressed into a single raw DEFLATE ([RFC 1951](https://www.rfc-editor.org/rfc/rfc1951.html)) stream, sync-flushed at each frame boundary. Every frame is self-delimited (byte-aligned, the window retained) while later frames reuse the earlier ones as context, so a stream of similar payloads (a snapshot followed by deltas, repeated records, log lines) compresses far better than each payload alone. diff --git a/js/flate/src/snapshot/producer.ts b/js/flate/src/snapshot/producer.ts index 60c8547aa9a..e4ff4b9fb8e 100644 --- a/js/flate/src/snapshot/producer.ts +++ b/js/flate/src/snapshot/producer.ts @@ -1,5 +1,5 @@ +import type { Timed } from "@moq/net"; import * as Moq from "@moq/net"; -import { Time } from "@moq/net"; import { DEFAULT_MAX_FRAME_SIZE, Encoder as Flate } from "../codec.ts"; import { type Compression, isDeflate } from "../compression.ts"; @@ -39,9 +39,10 @@ export class Producer { * Unlike `@moq/json`, an identical value is republished rather than skipped: comparing two * opaque blobs costs a full scan, and only the caller knows whether its bytes changed. * - * `at` is when the payload was captured, written as its frame timestamp. Defaults to now. + * `at` is when the payload was captured, written as its frame timestamp. Omit it only on an + * untimed track: it is never filled in. */ - update(payload: Uint8Array, at: Time.Timestamp = Time.Timestamp.now()): void { + update({ value: payload, at }: Timed): void { // Consumers all decode with `@moq/flate`'s default cap, so publishing past it would advertise // a value that always fails to read. Rejected before anything is published; unlike a stream // this is not terminal, since the previous value still stands and the next update supersedes. diff --git a/js/flate/src/snapshot/snapshot.test.ts b/js/flate/src/snapshot/snapshot.test.ts index 7c54bd9721f..2969cdf18dd 100644 --- a/js/flate/src/snapshot/snapshot.test.ts +++ b/js/flate/src/snapshot/snapshot.test.ts @@ -23,8 +23,8 @@ async function drain(track: Track.Subscriber, compression: boolean): Promise { const track = new Track.Producer("test"); const producer = new Producer({ track }); - producer.update(bytes(1)); - producer.update(bytes(2)); + producer.update({ value: bytes(1) }); + producer.update({ value: bytes(2) }); producer.finish(); // Two updates => two self-contained groups, so a consumer never needs an older one: a reader @@ -49,7 +49,7 @@ test("a live consumer sees each update", async () => { const consumer = new Consumer({ track: track.subscribe() }); for (let n = 0; n < 3; n++) { - producer.update(bytes(n)); + producer.update({ value: bytes(n) }); expect(await consumer.next()).toEqual(bytes(n)); } producer.finish(); @@ -59,7 +59,7 @@ test("compressed roundtrip", async () => { const track = new Track.Producer("test"); const producer = new Producer({ track, compression: "deflate" }); const payload = new TextEncoder().encode("the quick brown fox".repeat(64)); - producer.update(payload); + producer.update({ value: payload }); producer.finish(); expect(await drain(track.subscribe(), true)).toEqual([payload]); @@ -71,7 +71,7 @@ test("compression shrinks the frame on the wire", async () => { const track = new Track.Producer("test"); const producer = new Producer({ track, compression: "deflate" }); const payload = new TextEncoder().encode("the quick brown fox".repeat(64)); - producer.update(payload); + producer.update({ value: payload }); producer.finish(); const group = await track.subscribe().ordered().nextGroup(); @@ -82,7 +82,7 @@ test("compression shrinks the frame on the wire", async () => { test("a finished track ends the consumer", async () => { const track = new Track.Producer("test"); const producer = new Producer({ track }); - producer.update(bytes(7)); + producer.update({ value: bytes(7) }); producer.finish(); const consumer = new Consumer({ track: track.subscribe() }); @@ -97,7 +97,7 @@ test("a backlog collapses to the newest value", async () => { const producer = new Producer({ track }); const consumer = new Consumer({ track: track.subscribe() }); - for (let n = 0; n < 10; n++) producer.update(bytes(n)); + for (let n = 0; n < 10; n++) producer.update({ value: bytes(n) }); producer.finish(); expect(await consumer.next()).toEqual(bytes(9)); @@ -139,11 +139,21 @@ test("an aborted track surfaces its error instead of spinning", async () => { await expect(consumer.next()).rejects.toThrow("subscription aborted"); }); +test("a payload without a timestamp goes out untimed", async () => { + const track = new Track.Producer("test").accept({}); + const producer = new Producer({ track }); + producer.update({ value: bytes(1) }); + producer.finish(); + + const frame = await (await track.subscribe().ordered().nextGroup())?.readFrame(); + expect(frame?.timestamp).toBeUndefined(); +}); + test("a capture timestamp is written as the frame timestamp", async () => { const track = new Track.Producer("test"); const producer = new Producer({ track }); const captured = Time.Timestamp.fromMillis(1_234); - producer.update(bytes(1), captured); + producer.update({ value: bytes(1), at: captured }); producer.finish(); const frame = await (await track.subscribe().ordered().nextGroup())?.readFrame(); diff --git a/js/flate/src/stream/producer.ts b/js/flate/src/stream/producer.ts index c63a14bd327..9f4619fd69c 100644 --- a/js/flate/src/stream/producer.ts +++ b/js/flate/src/stream/producer.ts @@ -1,5 +1,5 @@ import type * as Moq from "@moq/net"; -import { Time } from "@moq/net"; +import type { Timed } from "@moq/net"; import { DEFAULT_MAX_FRAME_SIZE, Encoder as Flate } from "../codec.ts"; import { type Compression, isDeflate } from "../compression.ts"; @@ -41,9 +41,10 @@ export class Producer { * group. The group is aborted rather than closed cleanly, so a consumer sees the failure * instead of a log that merely looks complete. Every later append fails on the closed track. * - * `at` is when the payload was captured, written as its frame timestamp. Defaults to now. + * `at` is when the payload was captured, written as its frame timestamp. Omit it only on an + * untimed track: it is never filled in. */ - append(payload: Uint8Array, at: Time.Timestamp = Time.Timestamp.now()): void { + append({ value: payload, at }: Timed): void { // A payload no consumer could decode is as terminal as one the track rejects: consumers all // decode with `@moq/flate`'s default cap, so this would publish a record none of them could // read. Ends the track like any other lost record, and aborts the group the same way the diff --git a/js/flate/src/stream/stream.test.ts b/js/flate/src/stream/stream.test.ts index 5cf435db8cc..307378eb6f9 100644 --- a/js/flate/src/stream/stream.test.ts +++ b/js/flate/src/stream/stream.test.ts @@ -25,7 +25,7 @@ test("every payload survives in order", async () => { const track = new Track.Producer("test"); const producer = new Producer({ track }); const expected = payloads(5); - for (const payload of expected) producer.append(payload); + for (const payload of expected) producer.append({ value: payload }); producer.finish(); expect(await drain(track.subscribe(), false)).toEqual(expected); @@ -35,7 +35,7 @@ test("compressed roundtrip in order", async () => { const track = new Track.Producer("test"); const producer = new Producer({ track, compression: "deflate" }); const expected = payloads(20); - for (const payload of expected) producer.append(payload); + for (const payload of expected) producer.append({ value: payload }); producer.finish(); expect(await drain(track.subscribe(), true)).toEqual(expected); @@ -44,7 +44,7 @@ test("compressed roundtrip in order", async () => { test("the whole log rides one group, never rolled", async () => { const track = new Track.Producer("test"); const producer = new Producer({ track, compression: "deflate" }); - for (const payload of payloads(50)) producer.append(payload); + for (const payload of payloads(50)) producer.append({ value: payload }); producer.finish(); const subscriber = track.subscribe().ordered(); @@ -56,7 +56,7 @@ test("the shared window shrinks repetitive payloads", async () => { const track = new Track.Producer("test"); const producer = new Producer({ track, compression: "deflate" }); const payload = new TextEncoder().encode("the quick brown fox".repeat(16)); - for (let n = 0; n < 8; n++) producer.append(payload); + for (let n = 0; n < 8; n++) producer.append({ value: payload }); producer.finish(); const group = await track.subscribe().ordered().nextGroup(); @@ -94,7 +94,7 @@ test("a second concurrent read is refused rather than served the first one's gro // group for a second one and fail a perfectly good log. Rust gets this from `&mut self`. const track = new Track.Producer("test"); const producer = new Producer({ track }); - producer.append(payloads(1)[0]); + producer.append({ value: payloads(1)[0] }); producer.finish(); const consumer = new Consumer({ track: track.subscribe() }); @@ -135,13 +135,13 @@ test("an undecodable payload ends the log for a reader already inside the group" // failure rather than park on a group nothing will ever finish. const track = new Track.Producer("test"); const producer = new Producer({ track, compression: "deflate" }); - producer.append(payloads(1)[0]); + producer.append({ value: payloads(1)[0] }); const consumer = new Consumer({ track: track.subscribe(), compression: "deflate" }); expect(await consumer.next()).toBeDefined(); const oversized = new Uint8Array(DEFAULT_MAX_FRAME_SIZE + 1); - expect(() => producer.append(oversized)).toThrow("limit"); + expect(() => producer.append({ value: oversized })).toThrow("limit"); // Surfaces the terminal error rather than hanging on the still-open group. await expect(consumer.next()).rejects.toThrow("limit"); @@ -176,7 +176,7 @@ test("blocked reads leave nothing behind on the pending group read", async () => const reactions = await pendingReactions(async () => { for (let n = 0; n < 1000; n++) { const next = consumer.next(); - producer.append(new Uint8Array([n & 0xff])); + producer.append({ value: new Uint8Array([n & 0xff]) }); expect((await next)?.[0]).toBe(n & 0xff); } }); @@ -186,11 +186,21 @@ test("blocked reads leave nothing behind on the pending group read", async () => producer.finish(); }); +test("a payload without a timestamp goes out untimed", async () => { + const track = new Track.Producer("test").accept({}); + const producer = new Producer({ track }); + producer.append({ value: new Uint8Array([1]) }); + producer.finish(); + + const group = await track.subscribe().ordered().nextGroup(); + expect((await group?.readFrame())?.timestamp).toBeUndefined(); +}); + test("each record keeps its capture timestamp", async () => { const track = new Track.Producer("test"); const producer = new Producer({ track }); - producer.append(new Uint8Array([1]), Time.Timestamp.fromMillis(1_000)); - producer.append(new Uint8Array([2]), Time.Timestamp.fromMillis(2_000)); + producer.append({ value: new Uint8Array([1]), at: Time.Timestamp.fromMillis(1_000) }); + producer.append({ value: new Uint8Array([2]), at: Time.Timestamp.fromMillis(2_000) }); producer.finish(); const group = await track.subscribe().ordered().nextGroup(); diff --git a/js/hang/src/catalog/consumer.test.ts b/js/hang/src/catalog/consumer.test.ts index 5ae70309590..1a8a9a34f9d 100644 --- a/js/hang/src/catalog/consumer.test.ts +++ b/js/hang/src/catalog/consumer.test.ts @@ -60,7 +60,7 @@ test("watch refuses an oversized catalog update", async () => { 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)); + producer.update({ value: catalog(MAX_RENDITIONS + 1), at: Moq.Time.Timestamp.now() }); await expect(consumer.next()).rejects.toBeInstanceOf(TooManyRenditions); producer.finish(); broadcast.close(); @@ -85,7 +85,7 @@ async function watchRequested(root: Root) { const active = request.active.peek(); if (!active) throw new Error("request did not resolve"); const consumer = watch(active)[Symbol.asyncIterator](); - producer.update(root); + producer.update({ value: root, at: Moq.Time.Timestamp.now() }); try { return await consumer.next(); } finally { @@ -110,7 +110,7 @@ test("watch on a standalone broadcast refuses any parent reference", async () => 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")); + producer.update({ value: referencing("../bob"), at: Moq.Time.Timestamp.now() }); await expect(consumer.next()).rejects.toBeInstanceOf(EscapingBroadcast); producer.finish(); broadcast.close(); @@ -121,7 +121,7 @@ test("watch subscribes and yields typed catalog updates", async () => { 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)); + producer.update({ value: catalog(1), at: Moq.Time.Timestamp.now() }); expect(await consumer.next()).toMatchObject({ value: catalog(1) }); await consumer.return?.(); producer.finish(); diff --git a/js/hang/src/timeline.test.ts b/js/hang/src/timeline.test.ts index a3edae69742..9efd81d7415 100644 --- a/js/hang/src/timeline.test.ts +++ b/js/hang/src/timeline.test.ts @@ -13,14 +13,17 @@ test("timeline consumer yields converted push and pop events", async () => { 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 } }); + producer.push({ + value: { sequence: 0, pts: 250, duration: 1250, start: { group: 1 }, end: { group: 2, frame: 3 } }, + at: Time.Timestamp.now(), + }); expect(await consumer.next()).toEqual({ push: { index: 0, entry: { sequence: 0, pts: us(250), duration: us(1250), start: { group: 1 }, end: { group: 2, frame: 3 } }, }, }); - producer.pop(1); + producer.pop(1, Time.Timestamp.now()); expect(await consumer.next()).toEqual({ pop: { start: 0, end: 1 } }); producer.finish(); consumer.close(); @@ -32,7 +35,10 @@ test("timeline consumer floors fractional microseconds without floating point dr 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 } }); + producer.push({ + value: { sequence: 0, pts: 1, duration: 2, start: { group: 0 }, end: { group: 1 } }, + at: Time.Timestamp.now(), + }); expect(await consumer.next()).toEqual({ push: { index: 0, @@ -55,7 +61,10 @@ test("a record numbered unlike its window index is refused", async () => { 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 } }); + producer.push({ + value: { sequence: 5, pts: 0, duration: 1000, start: { group: 0 }, end: { group: 1 } }, + at: Time.Timestamp.now(), + }); await expect(consumer.next()).rejects.toThrow(); producer.finish(); consumer.close(); diff --git a/js/json/README.md b/js/json/README.md index 10eb2b80cf9..5b96a711098 100644 --- a/js/json/README.md +++ b/js/json/README.md @@ -26,10 +26,11 @@ A JSON value is published over a [`@moq/net`](../net) track as a series of group ```ts import { Snapshot } from "@moq/json"; +import { Time } from "@moq/net"; // Publish: each update supersedes the last. const producer = new Snapshot.Producer({ track }); -producer.update({ hello: "world" }); +producer.update({ value: { hello: "world" }, at: Time.Timestamp.now() }); // Consume: yields the latest reconstructed value, collapsing any backlog. const consumer = new Snapshot.Consumer({ track: track.subscribe() }); @@ -48,8 +49,8 @@ An ordered log of self-contained records, one JSON value per frame, all riding a import { Stream } from "@moq/json"; const producer = new Stream.Producer({ track }); -producer.append({ event: "started" }); -producer.append({ event: "stopped" }); +producer.append({ value: { event: "started" }, at: Time.Timestamp.now() }); +producer.append({ value: { event: "stopped" }, at: Time.Timestamp.now() }); const consumer = new Stream.Consumer({ track: track.subscribe() }); for await (const record of consumer) { @@ -57,4 +58,6 @@ for await (const record of consumer) { } ``` +Producers take `{ value, at }`, where `at` is the capture time written as the frame timestamp. Nothing fills in now: a timed track needs `at` on every write, and an untimed track takes none. + Both modes support optional group-scoped DEFLATE compression (`{ compression: "deflate" }` on both sides), interoperable with the Rust `moq-json` crate. `Config` is the codec options; `Producer.Config` / `Consumer.Config` add the track. diff --git a/js/json/src/snapshot/codec.test.ts b/js/json/src/snapshot/codec.test.ts index 834202ecc7f..2aa4eb5a729 100644 --- a/js/json/src/snapshot/codec.test.ts +++ b/js/json/src/snapshot/codec.test.ts @@ -283,11 +283,11 @@ test("update after finish reports the closed track", async () => { const track = new Track.Producer("test"); const producer = new Producer({ track, deltaRatio: 100 }); - producer.update({ a: 1 }); - producer.update({ a: 2 }); // a delta, so a group is open + producer.update({ value: { a: 1 } }); + producer.update({ value: { a: 2 } }); // a delta, so a group is open producer.finish(); - expect(() => producer.update({ a: 3 })).toThrow("track is closed"); + expect(() => producer.update({ value: { a: 3 } })).toThrow("track is closed"); }); // A root that isn't an object has no recursive merge patch, so it forces a snapshot regardless of diff --git a/js/json/src/snapshot/compression.test.ts b/js/json/src/snapshot/compression.test.ts index b0287e5c47a..63f53c22344 100644 --- a/js/json/src/snapshot/compression.test.ts +++ b/js/json/src/snapshot/compression.test.ts @@ -40,8 +40,8 @@ async function groupCount(track: Track.Ordered): Promise { test("compressed snapshot per group round-trips", async () => { const track = new Track.Producer("test"); const producer = new Producer({ track, deltaRatio: 0, compression: "deflate" }); - producer.update({ a: 1 }); - producer.update({ a: 2 }); + producer.update({ value: { a: 1 } }); + producer.update({ value: { a: 2 } }); producer.finish(); // Deltas off: one compressed snapshot per group. A consumer joining after the fact @@ -56,7 +56,7 @@ test("compressed live consumer sees each update in order", async () => { const consumer = new Consumer({ track: track.subscribe(), compression: "deflate" }); for (let n = 1; n <= 5; n++) { - producer.update({ a: n }); + producer.update({ value: { a: n } }); expect(await consumer.next()).toEqual({ a: n }); } }); @@ -64,9 +64,9 @@ test("compressed live consumer sees each update in order", async () => { test("compressed deltas share one group and reconstruct", async () => { const track = new Track.Producer("test"); const producer = new Producer({ track, deltaRatio: 100, compression: "deflate" }); - producer.update({ a: 1, b: 1 }); - producer.update({ a: 1, b: 2 }); - producer.update({ a: 5, b: 2 }); + producer.update({ value: { a: 1, b: 1 } }); + producer.update({ value: { a: 1, b: 2 } }); + producer.update({ value: { a: 5, b: 2 } }); producer.finish(); expect((await drainCompressed(track.subscribe())).at(-1)).toEqual({ a: 5, b: 2 }); @@ -75,9 +75,9 @@ test("compressed deltas share one group and reconstruct", async () => { test("compressed late joiner reconstructs from snapshot + deltas", async () => { const track = new Track.Producer("test"); const producer = new Producer({ track, deltaRatio: 100, compression: "deflate" }); - producer.update({ a: 1, b: 1 }); - producer.update({ a: 1, b: 2 }); - producer.update({ a: 5, b: 2 }); + producer.update({ value: { a: 1, b: 1 } }); + producer.update({ value: { a: 1, b: 2 } }); + producer.update({ value: { a: 5, b: 2 } }); producer.finish(); // A consumer created only now still rebuilds the final value from the snapshot + deltas. @@ -89,7 +89,7 @@ test("a group's snapshot decodes from a fresh decoder", async () => { // joiner (or the Rust consumer) start mid-stream at any group boundary. const track = new Track.Producer("test"); const producer = new Producer({ track, deltaRatio: 0, compression: "deflate" }); - producer.update({ hello: "world" }); + producer.update({ value: { hello: "world" } }); producer.finish(); const decoder = new Decoder(); @@ -103,8 +103,8 @@ test("compressed deltas reuse the window", async () => { const track = new Track.Producer("test"); const producer = new Producer({ track, deltaRatio: 100, compression: "deflate" }); const phrase = "Media over QUIC delivers real-time latency at massive scale"; - producer.update({ note: phrase }); - producer.update({ note: phrase, echo: phrase }); + producer.update({ value: { note: phrase } }); + producer.update({ value: { note: phrase, echo: phrase } }); producer.finish(); const group = await track.subscribe().ordered().nextGroup(); @@ -121,9 +121,9 @@ test("compression shrinks a repetitive frame", async () => { const value = { renditions: Array(3).fill("video".repeat(50)) }; const plain = new Track.Producer("plain"); - new Producer({ track: plain, deltaRatio: 0 }).update(value); + new Producer({ track: plain, deltaRatio: 0 }).update({ value: value }); const compressed = new Track.Producer("compressed"); - new Producer({ track: compressed, deltaRatio: 0, compression: "deflate" }).update(value); + new Producer({ track: compressed, deltaRatio: 0, compression: "deflate" }).update({ value: value }); const plainLen = (await firstFrame(plain.subscribe().ordered())).length; const compressedLen = (await firstFrame(compressed.subscribe().ordered())).length; @@ -138,7 +138,7 @@ test("compressed deltas roll on the compressed budget", async () => { // producers (deterministic output) keep the group-count and reconstruction reads independent. const fill = (track: Track.Producer) => { const producer = new Producer({ track, deltaRatio: 2, compression: "deflate" }); - for (let n = 0; n <= 40; n++) producer.update({ n }); + for (let n = 0; n <= 40; n++) producer.update({ value: { n } }); producer.finish(); }; diff --git a/js/json/src/snapshot/producer.ts b/js/json/src/snapshot/producer.ts index e5b35cb978e..72e91649c62 100644 --- a/js/json/src/snapshot/producer.ts +++ b/js/json/src/snapshot/producer.ts @@ -1,5 +1,5 @@ +import type { Time, Timed } from "@moq/net"; import * as Moq from "@moq/net"; -import { Time } from "@moq/net"; import { type Config as CodecConfig, DEFAULT_DELTA_RATIO, type Encoded, Encoder } from "./encoder.ts"; @@ -54,9 +54,10 @@ export class Producer { /** * Publish a new value, emitting a snapshot or delta automatically. No-op if unchanged. * - * `at` is when the value was captured, written as its frame timestamp. Defaults to now. + * `at` is when the value was captured, written as its frame timestamp. Omit it only on an + * untimed track: it is never filled in. */ - update(value: T, at: Time.Timestamp = Time.Timestamp.now()): void { + update({ value, at }: Timed): void { const frame = this.#encoder.update(value); if (!frame) return; @@ -66,7 +67,7 @@ export class Producer { frame.commit(); } - #write(encoded: Encoded, at: Time.Timestamp): void { + #write(encoded: Encoded, at: Time.Timestamp | undefined): void { // Check before touching a group. A keyframe closes the previous group and publishes its // replacement before the frame is written, so discovering the limit inside `writeFrame` would // leave an empty newest group behind: a snapshot consumer jumps to the newest, so the last @@ -106,7 +107,8 @@ export class Producer { } /** - * Mutate the current value in place and publish the result. + * Mutate the current value in place and publish the result, captured at `at` (omit it only on an + * untimed track). * * The callback receives a deep clone of the current value: everything published through this * producer so far, composed, falling back to {@link Config.initial} if nothing has been (throws if @@ -129,7 +131,7 @@ export class Producer { * failed sees the error, and the next successful publish is a full snapshot carrying the composed * value, so consumers converge on it either way. */ - mutate(fn: (value: T) => void): void { + mutate(fn: (value: T) => void, at?: Time.Timestamp): void { // Start from the last-published value, falling back to the configured initial value. We // don't invent an empty object: mutating with nothing to start from is a usage error. const base = this.#encoder.value ?? this.#initial; @@ -139,7 +141,7 @@ export class Producer { const value = structuredClone(base) as T; fn(value); - this.update(value); + this.update({ value, at }); } /** Finish the track, closing any open group. */ diff --git a/js/json/src/snapshot/snapshot.test.ts b/js/json/src/snapshot/snapshot.test.ts index e97875ce468..1e8bf0aa5f7 100644 --- a/js/json/src/snapshot/snapshot.test.ts +++ b/js/json/src/snapshot/snapshot.test.ts @@ -35,10 +35,10 @@ async function structure(track: Track.Ordered): Promise { test("a cut makes the next update a snapshot group", async () => { const track = new Track.Producer("test"); const producer = new Producer({ track, deltaRatio: 100 }); - producer.update({ a: 1, b: 1 }); - producer.update({ a: 1, b: 2 }); + producer.update({ value: { a: 1, b: 1 } }); + producer.update({ value: { a: 1, b: 2 } }); producer.cut(); - producer.update({ a: 1, b: 3 }); + producer.update({ value: { a: 1, b: 3 } }); producer.finish(); // The ratio would have kept every update in one group; the cut rolled it anyway. The replacement @@ -50,12 +50,12 @@ test("a cut makes the next update a snapshot group", async () => { test("a cut republishes an unchanged value", async () => { const track = new Track.Producer("test"); const producer = new Producer({ track, deltaRatio: 100 }); - producer.update({ a: 1 }); + producer.update({ value: { a: 1 } }); producer.cut(); // An unchanged value normally writes nothing. After a cut it must still open the replacement // group, or the value would only exist in a group no new consumer reads. - producer.update({ a: 1 }); + producer.update({ value: { a: 1 } }); producer.finish(); expect(await structure(track.subscribe({ maxDelay: REPLAY_LATENCY }).ordered())).toEqual([1, 1]); @@ -64,7 +64,7 @@ test("a cut republishes an unchanged value", async () => { test("a cut opens no replacement group", async () => { const track = new Track.Producer("test"); const producer = new Producer({ track, deltaRatio: 100 }); - producer.update({ a: 1 }); + producer.update({ value: { a: 1 } }); producer.cut(); producer.finish(); @@ -79,12 +79,12 @@ test("a cut is idempotent", async () => { // Nothing published yet, so there is no group to cut. producer.cut(); producer.cut(); - producer.update({ a: 1 }); + producer.update({ value: { a: 1 } }); // And a repeated cut rolls once, not once per call. producer.cut(); producer.cut(); - producer.update({ a: 2 }); + producer.update({ value: { a: 2 } }); producer.finish(); expect(await structure(track.subscribe({ maxDelay: REPLAY_LATENCY }).ordered())).toEqual([1, 1]); @@ -93,11 +93,11 @@ test("a cut is idempotent", async () => { test("a cut is inert without deltas", async () => { const track = new Track.Producer("test"); const producer = new Producer({ track, deltaRatio: 0 }); - producer.update({ a: 1 }); + producer.update({ value: { a: 1 } }); // With deltas off every frame already closes its own group, so there is never one to cut. producer.cut(); - producer.update({ a: 2 }); + producer.update({ value: { a: 2 } }); producer.finish(); expect(await structure(track.subscribe({ maxDelay: REPLAY_LATENCY }).ordered())).toEqual([1, 1]); @@ -106,8 +106,8 @@ test("a cut is inert without deltas", async () => { test("deltas off: a snapshot group per change", async () => { const track = new Track.Producer("test"); const producer = new Producer({ track, deltaRatio: 0 }); - producer.update({ a: 1 }); - producer.update({ a: 2 }); + producer.update({ value: { a: 1 } }); + producer.update({ value: { a: 2 } }); producer.finish(); // Two changes => two single-frame snapshot groups. A consumer joining after the fact @@ -119,8 +119,8 @@ test("deltas off: a snapshot group per change", async () => { test("deltaRatio 0 disables deltas, like off", async () => { const track = new Track.Producer("test"); const producer = new Producer({ track, deltaRatio: 0 }); - producer.update({ a: 1 }); - producer.update({ a: 2 }); + producer.update({ value: { a: 1 } }); + producer.update({ value: { a: 2 } }); producer.finish(); // `0` is treated as off, not a degenerate "enabled" value that keeps the group open: each change @@ -138,12 +138,12 @@ test("a held group is abandoned when a newer snapshot group rolls", async () => const producer = new Producer({ track, deltaRatio: 0.001 }); const consumer = new Consumer({ track: track.subscribe({ maxDelay: REPLAY_LATENCY }) }); - producer.update({ a: 1 }); + producer.update({ value: { a: 1 } }); expect(await consumer.next()).toEqual({ a: 1 }); // A delta lands in the held group, then the ratio rolls a new snapshot group. - producer.update({ a: 2 }); - producer.update({ a: 3 }); + producer.update({ value: { a: 2 } }); + producer.update({ value: { a: 3 } }); producer.finish(); expect(await consumer.next()).toEqual({ a: 3 }); @@ -155,7 +155,7 @@ test("live consumer sees each update", async () => { const consumer = new Consumer({ track: track.subscribe() }); for (let n = 1; n <= 3; n++) { - producer.update({ a: n }); + producer.update({ value: { a: n } }); expect(await consumer.next()).toEqual({ a: n }); } }); @@ -163,8 +163,8 @@ test("live consumer sees each update", async () => { test("unchanged value writes nothing", async () => { const track = new Track.Producer("test"); const producer = new Producer({ track }); - producer.update({ a: 1 }); - producer.update({ a: 1 }); + producer.update({ value: { a: 1 } }); + producer.update({ value: { a: 1 } }); producer.finish(); expect(await structure(track.subscribe().ordered())).toEqual([1]); @@ -173,9 +173,9 @@ test("unchanged value writes nothing", async () => { test("deltas share one group", async () => { const track = new Track.Producer("test"); const producer = new Producer({ track, deltaRatio: 100 }); - producer.update({ a: 1, b: 1 }); - producer.update({ a: 1, b: 2 }); - producer.update({ a: 1, b: 3 }); + producer.update({ value: { a: 1, b: 1 } }); + producer.update({ value: { a: 1, b: 2 } }); + producer.update({ value: { a: 1, b: 3 } }); producer.finish(); // All updates fit in a single group as snapshot + two deltas. @@ -185,9 +185,9 @@ test("deltas share one group", async () => { test("deltas reconstruct to the final value", async () => { const track = new Track.Producer("test"); const producer = new Producer({ track, deltaRatio: 100 }); - producer.update({ a: 1, b: 1 }); - producer.update({ a: 1, b: 2 }); - producer.update({ a: 5, b: 2 }); + producer.update({ value: { a: 1, b: 1 } }); + producer.update({ value: { a: 1, b: 2 } }); + producer.update({ value: { a: 5, b: 2 } }); producer.finish(); expect((await drain(track.subscribe())).at(-1)).toEqual({ a: 5, b: 2 }); @@ -254,10 +254,10 @@ test("tight ratio rolls snapshots", async () => { // the deltas already written, so the delta that tips the group over budget still lands (a one-frame // overshoot): group 0 takes two deltas (14 bytes) before the fourth update rolls group 1. const producer = new Producer({ track, deltaRatio: 1 }); - producer.update({ a: 1 }); // snapshot, group 0 - producer.update({ a: 2 }); // delta, group 0 (deltas = 7) - producer.update({ a: 3 }); // delta, group 0 (deltas = 14, now over budget) - producer.update({ a: 4 }); // budget already exceeded, rolls group 1 + producer.update({ value: { a: 1 } }); // snapshot, group 0 + producer.update({ value: { a: 2 } }); // delta, group 0 (deltas = 7) + producer.update({ value: { a: 3 } }); // delta, group 0 (deltas = 14, now over budget) + producer.update({ value: { a: 4 } }); // budget already exceeded, rolls group 1 producer.finish(); expect(await structure(track.subscribe({ maxDelay: REPLAY_LATENCY }).ordered())).toEqual([3, 1]); @@ -271,7 +271,7 @@ test("deltas stay within ratio times snapshot", async () => { // until they first exceed 56 (nine deltas = 63 bytes) and the next update rolls (a one-frame // overshoot past the 56-byte budget). const producer = new Producer({ track, deltaRatio: 8 }); - for (let n = 0; n <= 10; n++) producer.update({ n }); + for (let n = 0; n <= 10; n++) producer.update({ value: { n } }); producer.finish(); expect(await structure(track.subscribe({ maxDelay: REPLAY_LATENCY }).ordered())).toEqual([10, 1]); @@ -280,8 +280,8 @@ test("deltas stay within ratio times snapshot", async () => { test("array change is a wholesale delta", async () => { const track = new Track.Producer("test"); const producer = new Producer({ track, deltaRatio: 100 }); - producer.update({ list: [1, 2] }); - producer.update({ list: [1, 2, 3] }); + producer.update({ value: { list: [1, 2] } }); + producer.update({ value: { list: [1, 2, 3] } }); producer.finish(); // The array is replaced wholesale in a delta, so it stays in the same group. @@ -293,7 +293,7 @@ test("late joiner collapses a buffered backlog to the latest value", async () => const producer = new Producer({ track, deltaRatio: 100 }); const subscriber = track.subscribe(); for (let n = 0; n <= 20; n++) { - producer.update({ n }); + producer.update({ value: { n } }); } producer.finish(); @@ -307,7 +307,7 @@ test("frame cap rolls snapshot", async () => { const producer = new Producer({ track, deltaRatio: 1_000_000 }); // First update is the snapshot; deltas fill the group until the frame cap forces a roll. for (let i = 0; i <= 256; i++) { - producer.update({ n: i }); + producer.update({ value: { n: i } }); } producer.finish(); @@ -320,11 +320,11 @@ test("a rejected update leaves the previous value readable", async () => { // A snapshot consumer jumps to the newest, so that value would vanish on a failed update. const track = new Track.Producer("test"); const producer = new Producer({ track, deltaRatio: 0 }); - producer.update({ keep: true }); + producer.update({ value: { keep: true } }); // Serializes past the group cache limit, so the frame cannot be published. const oversized = { big: "x".repeat(Group.MAX_GROUP_CACHE_BYTES + 1) }; - expect(() => producer.update(oversized)).toThrow(NetError.FrameTooLarge); + expect(() => producer.update({ value: oversized })).toThrow(NetError.FrameTooLarge); producer.finish(); // A reader arriving now still finds the last good value, not an empty superseding group. @@ -347,8 +347,8 @@ test("a delta that would overflow the snapshot rolls a new one instead", async ( const track = new Track.Producer("test"); const producer = new Producer({ track, maxGroupBytes: 64 }); - producer.update({ v: "x".repeat(size) }); - producer.update({ v: "y".repeat(size) }); + producer.update({ value: { v: "x".repeat(size) } }); + producer.update({ value: { v: "y".repeat(size) } }); producer.finish(); // Two groups, a self-contained snapshot each, rather than one whose frame 0 was evicted. @@ -382,8 +382,8 @@ test("a compressed delta is gated on its encoded size, not its plaintext", async const maxGroupBytes = (snapshot?.payload.length ?? 0) + plaintext; const track = new Track.Producer("test"); const producer = new Producer({ track, compression: "deflate", maxGroupBytes }); - producer.update(value); - producer.update(patched); + producer.update({ value: value }); + producer.update({ value: patched }); producer.finish(); // The patch rolled into a fresh snapshot rather than joining the first group. @@ -409,11 +409,25 @@ test("snapshot consumer propagates a non-gap frame failure", async () => { await expect(consumer.next()).rejects.toMatchObject({ code: StreamCode.Internal }); }); +test("an update without a timestamp goes out untimed", async () => { + const track = new Track.Producer("test").accept({}); + const producer = new Producer({ track, deltaRatio: 100 }); + producer.update({ value: { a: 1, b: "x".repeat(64) } }); + producer.mutate((value) => { + value.a = 2; + }); + producer.finish(); + + const group = await track.subscribe().ordered().nextGroup(); + expect((await group?.readFrame())?.timestamp).toBeUndefined(); + expect((await group?.readFrame())?.timestamp).toBeUndefined(); +}); + test("a capture timestamp is written on snapshots and deltas alike", async () => { const track = new Track.Producer("test"); const producer = new Producer({ track, deltaRatio: 100 }); - producer.update({ a: 1, b: "x".repeat(64) }, Time.Timestamp.fromMillis(1_000)); - producer.update({ a: 2, b: "x".repeat(64) }, Time.Timestamp.fromMillis(2_000)); + producer.update({ value: { a: 1, b: "x".repeat(64) }, at: Time.Timestamp.fromMillis(1_000) }); + producer.update({ value: { a: 2, b: "x".repeat(64) }, at: Time.Timestamp.fromMillis(2_000) }); producer.finish(); const group = await track.subscribe().ordered().nextGroup(); diff --git a/js/json/src/stream/codec.test.ts b/js/json/src/stream/codec.test.ts index b3304271bc5..beea1d84c25 100644 --- a/js/json/src/stream/codec.test.ts +++ b/js/json/src/stream/codec.test.ts @@ -110,7 +110,7 @@ test("a rejected record ends the track without opening a group", async () => { const subscriber = track.subscribe().ordered(); const producer = new Producer({ track }); - expect(() => producer.append(undefined)).toThrow("not representable as JSON"); + expect(() => producer.append({ value: undefined })).toThrow("not representable as JSON"); // Nothing was appended, so the log has no group for a consumer to enter and wait in. expect(subscriber.latest()).toBeUndefined(); @@ -161,11 +161,11 @@ test("a rejected record leaves the producer able to retry", () => { // Closing the track makes every write fail, standing in for any post-appendGroup rejection. track.close(); - expect(() => producer.append({ n: 1 })).toThrow(); + expect(() => producer.append({ value: { n: 1 } })).toThrow(); // The retry fails on the same closed track, but it must fail for that reason rather than the // encoder having latched itself shut. - expect(() => producer.append({ n: 2 })).not.toThrow("compression desynchronized"); + expect(() => producer.append({ value: { n: 2 } })).not.toThrow("compression desynchronized"); }); test("a failed write on the very first record still ends the track", async () => { @@ -183,7 +183,7 @@ test("a failed write on the very first record still ends the track", async () => throw failure; }); try { - expect(() => producer.append("x")).toThrow(failure); + expect(() => producer.append({ value: "x" })).toThrow(failure); } finally { write.mockRestore(); } diff --git a/js/json/src/stream/producer.ts b/js/json/src/stream/producer.ts index ee752bfc640..be17354c7df 100644 --- a/js/json/src/stream/producer.ts +++ b/js/json/src/stream/producer.ts @@ -1,5 +1,5 @@ import type * as Moq from "@moq/net"; -import { Error as NetError, Time } from "@moq/net"; +import { Error as NetError, type Timed } from "@moq/net"; import { type Config as CodecConfig, Encoder, type Pending } from "./encoder.ts"; @@ -34,9 +34,10 @@ export class Producer { * second group. The track is aborted rather than closed cleanly, so a consumer sees the failure * instead of a log that merely looks complete. * - * `at` is when the value was captured, written as its frame timestamp. Defaults to now. + * `at` is when the value was captured, written as its frame timestamp. Omit it only on an + * untimed track: it is never filled in. */ - append(value: T, at: Time.Timestamp = Time.Timestamp.now()): void { + append({ value, at }: Timed): void { // Encode first, so a value that can't be serialized doesn't publish an empty group that // subscribers would advance into and wait on. Opening the group afterwards is safe because // the record stays uncommitted until the write lands. diff --git a/js/json/src/stream/stream.test.ts b/js/json/src/stream/stream.test.ts index 154a5a30191..6fd76eb5bfd 100644 --- a/js/json/src/stream/stream.test.ts +++ b/js/json/src/stream/stream.test.ts @@ -19,7 +19,7 @@ async function drain(track: Track.Subscriber, compression: boolean): Promise { const track = new Track.Producer("test"); const producer = new Producer({ track }); - for (let n = 0; n < 5; n++) producer.append({ n }); + for (let n = 0; n < 5; n++) producer.append({ value: { n } }); producer.finish(); expect(await drain(track.subscribe(), false)).toEqual([0, 1, 2, 3, 4]); @@ -28,7 +28,7 @@ test("plaintext roundtrip in order", async () => { test("compressed roundtrip in order", async () => { const track = new Track.Producer("test"); const producer = new Producer({ track, compression: "deflate" }); - for (let n = 0; n < 20; n++) producer.append({ n }); + for (let n = 0; n < 20; n++) producer.append({ value: { n } }); producer.finish(); expect(await drain(track.subscribe(), true)).toEqual(Array.from({ length: 20 }, (_, n) => n)); @@ -37,7 +37,7 @@ test("compressed roundtrip in order", async () => { test("the whole log rides one group, never rolled", async () => { const track = new Track.Producer("test"); const producer = new Producer({ track, compression: "deflate" }); - for (let n = 0; n < 50; n++) producer.append({ n }); + for (let n = 0; n < 50; n++) producer.append({ value: { n } }); producer.finish(); // A single group holds everything, and the consumer reads it all in order. @@ -54,7 +54,7 @@ test("records with embedded newlines round-trip (JSON escapes the newline)", asy const track = new Track.Producer("test"); const producer = new Producer<{ s: string }>({ track, compression: "deflate" }); const value = { s: "line1\nline2\ttab" }; - for (let i = 0; i < 4; i++) producer.append(value); + for (let i = 0; i < 4; i++) producer.append({ value: value }); producer.finish(); const consumer = new Consumer<{ s: string }>({ track: track.subscribe(), compression: "deflate" }); @@ -102,7 +102,7 @@ test("a second concurrent read is refused rather than served the first one's gro // group for a second one and fail a perfectly good log. Rust gets this from `&mut self`. const track = new Track.Producer("test"); const producer = new Producer({ track }); - producer.append({ n: 0 }); + producer.append({ value: { n: 0 } }); producer.finish(); const consumer = new Consumer({ track: track.subscribe() }); @@ -140,7 +140,7 @@ test("blocked reads leave nothing behind on the pending group read", async () => const reactions = await pendingReactions(async () => { for (let n = 0; n < 1000; n++) { const next = consumer.next(); - producer.append({ n }); + producer.append({ value: { n } }); expect((await next)?.n).toBe(n); } }); @@ -150,11 +150,21 @@ test("blocked reads leave nothing behind on the pending group read", async () => producer.finish(); }); +test("a record without a timestamp goes out untimed", async () => { + const track = new Track.Producer("test").accept({}); + const producer = new Producer({ track }); + producer.append({ value: 1 }); + producer.finish(); + + const group = await track.subscribe().ordered().nextGroup(); + expect((await group?.readFrame())?.timestamp).toBeUndefined(); +}); + test("each record keeps its capture timestamp", async () => { const track = new Track.Producer("test"); const producer = new Producer({ track }); - producer.append(1, Time.Timestamp.fromMillis(1_000)); - producer.append(2, Time.Timestamp.fromMillis(2_000)); + producer.append({ value: 1, at: Time.Timestamp.fromMillis(1_000) }); + producer.append({ value: 2, at: Time.Timestamp.fromMillis(2_000) }); producer.finish(); const group = await track.subscribe().ordered().nextGroup(); @@ -168,11 +178,13 @@ for (const compression of [false, true]) { test(`an oversized record is refused and the log continues (compression=${compression})`, async () => { const track = new Track.Producer("test"); const producer = new Producer({ track, compression: compression ? "deflate" : "none" }); - producer.append({ n: 0 }); + producer.append({ value: { n: 0 } }); - expect(() => producer.append("x".repeat(Group.MAX_GROUP_CACHE_BYTES))).toThrow(NetError.GroupTooLarge); + expect(() => producer.append({ value: "x".repeat(Group.MAX_GROUP_CACHE_BYTES) })).toThrow( + NetError.GroupTooLarge, + ); - producer.append({ n: 1 }); + producer.append({ value: { n: 1 } }); producer.finish(); expect(await drain(track.subscribe(), compression)).toEqual([0, 1]); }); @@ -184,10 +196,10 @@ for (const compression of [false, true]) { test(`a spent budget refuses every append (compression=${compression})`, async () => { const track = new Track.Producer("test"); const producer = new Producer({ track, compression: compression ? "deflate" : "none" }); - for (let n = 0; n < Group.MAX_GROUP_FRAMES; n++) producer.append({ n }); + for (let n = 0; n < Group.MAX_GROUP_FRAMES; n++) producer.append({ value: { n } }); - expect(() => producer.append({ n: -1 })).toThrow(NetError.GroupTooLarge); - expect(() => producer.append({ n: -2 })).toThrow(NetError.GroupTooLarge); + expect(() => producer.append({ value: { n: -1 } })).toThrow(NetError.GroupTooLarge); + expect(() => producer.append({ value: { n: -2 } })).toThrow(NetError.GroupTooLarge); producer.finish(); const records = await drain(track.subscribe(), compression); diff --git a/js/json/src/window/producer.ts b/js/json/src/window/producer.ts index 20457f5e134..1761de44f25 100644 --- a/js/json/src/window/producer.ts +++ b/js/json/src/window/producer.ts @@ -1,5 +1,5 @@ import type * as Moq from "@moq/net"; -import { Time } from "@moq/net"; +import type { Time, Timed } from "@moq/net"; import { type Config, type Encoded, Encoder } from "./encoder.ts"; @@ -39,10 +39,15 @@ export class Producer { return this.#encoder.offset; } - /** Append one record to the back of the window. */ - push(value: T): void { + /** + * Append one record to the back of the window. + * + * `at` is when the record was captured, written as its frame timestamp. Omit it only on an + * untimed track: it is never filled in. + */ + push({ value, at }: Timed): void { this.#assertOpen(); - this.#write(this.#encoder.push(value)); + this.#write(this.#encoder.push(value), at); } /** @@ -50,18 +55,21 @@ export class Producer { * * A no-op when the window is already empty, and clamped to what it holds, so a caller can trim * unconditionally. + * + * `at` is when the records were retired, written as the frame timestamp. Omit it only on an + * untimed track: it is never filled in. */ - pop(count: number): void { + pop(count: number, at?: Time.Timestamp): void { this.#assertOpen(); const frame = this.#encoder.pop(count); - if (frame) this.#write(frame); + if (frame) this.#write(frame, at); } #assertOpen(): void { if (this.#finished) throw new Error("track is closed"); } - #write(encoded: Encoded & { commit(): void }): void { + #write(encoded: Encoded & { commit(): void }, at: Time.Timestamp | undefined): void { // A throw leaves the edit uncommitted and the retained window unchanged. The next edit opens a // new group because the attempted frame advanced the group-local compression state. if (encoded.keyframe) { @@ -72,7 +80,7 @@ export class Producer { const group = this.#track.appendGroup(); try { - group.writeFrame({ payload: encoded.payload, timestamp: Time.Timestamp.now() }); + group.writeFrame({ payload: encoded.payload, timestamp: at }); } catch (err) { // The group carries no frames, so close it rather than leaving it open on the track. A // consumer that already advanced into it would otherwise block with nothing to read. @@ -86,7 +94,7 @@ export class Producer { } if (!this.#group) throw new Error("op with no open group"); - this.#group.writeFrame({ payload: encoded.payload, timestamp: Time.Timestamp.now() }); + this.#group.writeFrame({ payload: encoded.payload, timestamp: at }); encoded.commit(); } diff --git a/js/json/src/window/window.test.ts b/js/json/src/window/window.test.ts index f5bdb63cc57..81ca1adcff4 100644 --- a/js/json/src/window/window.test.ts +++ b/js/json/src/window/window.test.ts @@ -25,7 +25,7 @@ class Live { } async push(n: number): Promise { - this.producer.push({ n }); + this.producer.push({ value: { n } }); await this.read(); } @@ -110,10 +110,10 @@ test("concurrent consumer reads are rejected", async () => { test("writes after finish are rejected before encoding", () => { const track = new Track.Producer("test"); const producer = new Producer({ track }); - producer.push(1); + producer.push({ value: 1 }); producer.finish(); - expect(() => producer.push(2)).toThrow("track is closed"); + expect(() => producer.push({ value: 2 })).toThrow("track is closed"); expect(() => producer.pop(1)).toThrow("track is closed"); expect(producer.window).toEqual([1]); }); @@ -213,7 +213,7 @@ test("the window slides", async () => { const track = new Track.Producer("test"); const producer = new Producer({ track }); for (let n = 0; n < 5; n++) { - producer.push({ n }); + producer.push({ value: { n } }); if (n >= 2) producer.pop(1); } @@ -259,7 +259,7 @@ test("a lagging consumer is told what it missed", async () => { // The consumer stops reading while the window slides past everything it holds. for (let n = 2; n < 8; n++) { - producer.push({ n }); + producer.push({ value: { n } }); producer.pop(1); } subscriber.setGroups({ start: { included: subscriber.latest() as number } }); @@ -311,7 +311,7 @@ test("consumer resumes at a checkpoint after losing a group", async () => { test("a fresh consumer adopts the current offset", async () => { const track = new Track.Producer("test"); const producer = new Producer({ track, opRatio: 0 }); - for (let n = 0; n < 5; n++) producer.push({ n }); + for (let n = 0; n < 5; n++) producer.push({ value: { n } }); producer.pop(3); const subscriber = track.subscribe(); @@ -440,3 +440,18 @@ test("an uncommitted edit leaves the window unchanged", () => { popped.commit(); expect(encoder.window).toEqual([2, 3]); }); + +test("edits keep their timestamps, and an edit without one goes out untimed", async () => { + for (const at of [undefined, Time.Timestamp.fromMillis(1_000)]) { + const track = new Track.Producer("test").accept(at ? { timescale: Time.Timescale.MILLI } : {}); + const producer = new Producer({ track }); + producer.push({ value: { n: 0 }, at }); + producer.pop(1, at); + producer.finish(); + + const group = await track.subscribe().ordered().nextGroup(); + for (let i = 0; i < 2; i++) { + expect((await group?.readFrame())?.timestamp?.as(Time.Timescale.MILLI)).toBe(at?.as(Time.Timescale.MILLI)); + } + } +}); diff --git a/js/moq-boy/src/game.ts b/js/moq-boy/src/game.ts index 59a4f2aecee..87d82e4fb36 100644 --- a/js/moq-boy/src/game.ts +++ b/js/moq-boy/src/game.ts @@ -324,6 +324,6 @@ export class Game { const command = effect.get(this.#command); if (!command) return; - producer.update({ ...command.cmd, timestamps: command.timestamps }); + producer.update({ value: { ...command.cmd, timestamps: command.timestamps }, at: Moq.Time.Timestamp.now() }); } } diff --git a/js/net/examples/publish.ts b/js/net/examples/publish.ts index 617906484fe..b3bf6f23cb5 100644 --- a/js/net/examples/publish.ts +++ b/js/net/examples/publish.ts @@ -13,7 +13,7 @@ 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. - // writeString stamps each frame with the current time, so the track declares a timescale. + // Each frame is stamped with the time it was written, so the track declares a timescale. void publishTrack(broadcast.createTrack("chat", { timescale: Moq.Time.Timescale.MILLI })); console.log("Published broadcast: my-broadcast"); @@ -27,8 +27,8 @@ async function publishTrack(track: Moq.Track.Producer) { const group = track.appendGroup(); // Write two frames to the group - for (const frame of ["Hello", "MoQ!"]) { - group.writeString(frame); + for (const text of ["Hello", "MoQ!"]) { + group.writeFrame({ payload: new TextEncoder().encode(text), timestamp: Moq.Time.Timestamp.now() }); } // Mark the group as complete diff --git a/js/net/src/broadcast.test.ts b/js/net/src/broadcast.test.ts index 39d66f044ad..02a93b52e19 100644 --- a/js/net/src/broadcast.test.ts +++ b/js/net/src/broadcast.test.ts @@ -3,6 +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 { textFrame } from "./mock.ts"; import { Milli, Timescale, Timestamp } from "./time.ts"; import type { Request as TrackRequest } from "./track.ts"; import { Producer as TrackProducer } from "./track.ts"; @@ -40,7 +41,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({ timescale: Timescale.MILLI }); - producer.writeString("hello"); + producer.writeFrame(textFrame("hello")); expect(await a.readString()).toBe("hello"); expect(await b.readString()).toBe("hello"); @@ -106,7 +107,7 @@ test("publishing-side subscriptions coalesce onto one request", async () => { if (!request) throw new Error("expected request"); const producer = request.accept({ timescale: Timescale.MILLI }); - producer.writeString("hello"); + producer.writeFrame(textFrame("hello")); expect(await a.readString()).toBe("hello"); expect(await b.readString()).toBe("hello"); await info; @@ -199,7 +200,7 @@ test("an abandoned info lookup stops counting as demand, and its request goes on // The handler still gets an open track, and the answer lets it go. const producer = request.accept({ timescale: Timescale.MILLI }); - producer.writeString("late"); + producer.writeFrame(textFrame("late")); await producer.closed; broadcast.close(); }); @@ -358,13 +359,13 @@ test("consumer track subscriptions fan out and close independently", async () => expect(await pendingRequest(consumer)).toBeUndefined(); const producer = request.accept({ timescale: Timescale.MILLI }); - producer.writeString("one"); + producer.writeFrame(textFrame("one")); expect(await a.readString()).toBe("one"); expect(await b.readString()).toBe("one"); // ...and closing one subscriber leaves the other (and the shared upstream) delivering. a.close(); - producer.writeString("two"); + producer.writeFrame(textFrame("two")); expect(await b.readString()).toBe("two"); }); @@ -404,8 +405,8 @@ test("two subscribers to one inserted track each get a full copy", async () => { .subscribe({ maxDelay: Milli(5000) }) .ordered(); - producer.writeString("hello"); - producer.writeString("world"); + producer.writeFrame(textFrame("hello")); + producer.writeFrame(textFrame("world")); // Neither subscriber steals from the other: both see every frame in order. expect(await a.readString()).toBe("hello"); @@ -419,12 +420,12 @@ test("a late subscriber replays the cached window", async () => { const producer = broadcast.createTrack("video", { timescale: Timescale.MILLI }); // Written before anyone subscribes; retained in the cache for replay. - producer.writeString("early"); + producer.writeFrame(textFrame("early")); const late = broadcast.track("video").subscribe().ordered(); expect(await late.readString()).toBe("early"); - producer.writeString("later"); + producer.writeFrame(textFrame("later")); expect(await late.readString()).toBe("later"); }); @@ -463,12 +464,12 @@ test("a stalled consumer does not pin evicted groups", async () => { // A subscriber that never reads. Its sink must not grow without bound. const stalled = broadcast.track("video").subscribe(); - producer.writeString("old"); + producer.writeFrame(textFrame("old")); // Advance past the cache window and write again to trigger a prune. The old // (closed, aged-out) group is dropped from the stalled sink, not retained. setSystemTime(new Date(12_000)); - producer.writeString("fresh"); + producer.writeFrame(textFrame("fresh")); // The next group in arrival order is the fresh one (seq 1): the old (seq 0) group // was evicted, not still buffered ahead of it. @@ -504,7 +505,7 @@ test("insertTrack rejects a duplicate live name", () => { test("a finished track is still served from its cache", async () => { const broadcast = new BroadcastProducer(); const track = broadcast.createTrack("track1", { timescale: Timescale.MILLI }); - track.writeString("last"); + track.writeFrame(textFrame("last")); track.close(); // Like Rust, finishing keeps the track: a late subscriber reads the cache, then the clean end. diff --git a/js/net/src/goaway-requests.test.ts b/js/net/src/goaway-requests.test.ts index 772fb7b5a39..f13a862b8ce 100644 --- a/js/net/src/goaway-requests.test.ts +++ b/js/net/src/goaway-requests.test.ts @@ -10,7 +10,7 @@ import { ALPN, Version as IetfVersion } from "./ietf/version.ts"; import { Goaway } from "./lite/goaway.ts"; import { StreamId } from "./lite/stream.ts"; import { ALPN_06, Version as LiteVersion } from "./lite/version.ts"; -import { createMockTransportPair, type MockTransport } from "./mock.ts"; +import { createMockTransportPair, type MockTransport, textFrame } from "./mock.ts"; import { Producer as OriginProducer } from "./origin.ts"; import * as Path from "./path.ts"; import { Stream, Writer } from "./stream.ts"; @@ -115,9 +115,9 @@ async function handover(kind: "lite" | "ietf"): Promise { const req = await wireOf(broadcast).requested(); if (!req) break; const track = req.accept({ timescale: Timescale.MILLI }); - if (req.name === "video" && armVideo) track.writeString("one"); - if (req.name === "later") track.writeString("from-draining"); - if (req.name === "audio") track.writeString("from-replacement"); + if (req.name === "video" && armVideo) track.writeFrame(textFrame("one")); + if (req.name === "later") track.writeFrame(textFrame("from-draining")); + if (req.name === "audio") track.writeFrame(textFrame("from-replacement")); served.push(track); } })(); @@ -163,7 +163,7 @@ async function handover(kind: "lite" | "ietf"): Promise { expect(request.active.peek()).toBe(front); for (const producer of served) { - if (producer.closed.peek() === undefined) producer.writeString("two"); + if (producer.closed.peek() === undefined) producer.writeFrame(textFrame("two")); } expect(await video.readString()).toBe("two"); diff --git a/js/net/src/group.test.ts b/js/net/src/group.test.ts index d7b8b5733e4..33b199e1107 100644 --- a/js/net/src/group.test.ts +++ b/js/net/src/group.test.ts @@ -1,6 +1,7 @@ import { expect, test } from "bun:test"; import { FrameTooLarge, GroupTooLarge } from "./error.ts"; import { MAX_GROUP_CACHE_BYTES, MAX_GROUP_FRAMES, Producer } from "./group.ts"; +import { textFrame } from "./mock.ts"; import { Timestamp } from "./time.ts"; const dec = new TextDecoder(); @@ -124,8 +125,8 @@ test("a group with no eviction reads every frame without error", async () => { test("tryReadFrame drains buffered frames then returns undefined", () => { const { producer, consumer } = pair(0); - producer.writeString("a"); - producer.writeString("b"); + producer.writeFrame(textFrame("a")); + producer.writeFrame(textFrame("b")); expect(dec.decode(consumer.tryReadFrame()?.payload)).toBe("a"); expect(dec.decode(consumer.tryReadFrame()?.payload)).toBe("b"); @@ -135,8 +136,8 @@ test("tryReadFrame drains buffered frames then returns undefined", () => { test("tryReadFrameSequence reports per-frame sequence numbers", () => { const { producer, consumer } = pair(7); - producer.writeString("a"); - producer.writeString("b"); + producer.writeFrame(textFrame("a")); + producer.writeFrame(textFrame("b")); expect(consumer.tryReadFrameSequence()).toMatchObject({ sequence: 0, payload: new TextEncoder().encode("a") }); expect(consumer.tryReadFrameSequence()).toMatchObject({ sequence: 1, payload: new TextEncoder().encode("b") }); @@ -145,8 +146,8 @@ test("tryReadFrameSequence reports per-frame sequence numbers", () => { test("readFrameSequence reports per-frame sequence numbers", async () => { const { producer, consumer } = pair(7); - producer.writeString("a"); - producer.writeString("b"); + producer.writeFrame(textFrame("a")); + producer.writeFrame(textFrame("b")); expect(await consumer.readFrameSequence()).toMatchObject({ sequence: 0, payload: new TextEncoder().encode("a") }); expect(await consumer.readFrameSequence()).toMatchObject({ sequence: 1, payload: new TextEncoder().encode("b") }); @@ -158,7 +159,7 @@ test("done distinguishes a finished group from one that is merely empty", () => expect(consumer.tryReadFrame()).toBeUndefined(); expect(consumer.done).toBe(false); - producer.writeString("a"); + producer.writeFrame(textFrame("a")); // Buffered but closed: still not done until the frame is drained. producer.close(); expect(consumer.done).toBe(false); @@ -190,7 +191,7 @@ test("readable resolves once a frame is buffered", async () => { expect(settled).toBe(false); // Writing makes it resolve. - producer.writeString("hi"); + producer.writeFrame(textFrame("hi")); await readable; // must not hang expect(dec.decode(consumer.tryReadFrame()?.payload)).toBe("hi"); }); @@ -205,7 +206,7 @@ test("readable resolves once the group closes, even with nothing buffered", asyn test("buffered frames are still readable after the group closes", async () => { const { producer, consumer } = pair(0); - producer.writeString("a"); + producer.writeFrame(textFrame("a")); producer.close(); // Closing doesn't discard buffered frames; the blocking reader drains them before ending. diff --git a/js/net/src/group.ts b/js/net/src/group.ts index 7684e19df63..244ff332caf 100644 --- a/js/net/src/group.ts +++ b/js/net/src/group.ts @@ -6,7 +6,7 @@ import { type Dispose, type GetPromise, type Getter, Once, Signal } from "@moq/signals"; import { FrameTooLarge, GroupTooLarge, TimestampMismatch, TooFarBehind } from "./error.ts"; import { hooks, type ReadGroupFrame } from "./internal.ts"; -import { Timestamp } from "./time.ts"; +import type { Timestamp } from "./time.ts"; /** Maximum bytes of frames in a group. A write that would exceed this aborts with {@link GroupTooLarge}. */ export const MAX_GROUP_CACHE_BYTES = 32 * 1024 * 1024; @@ -274,21 +274,6 @@ export class Producer { } } - /** 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}, 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}, so the track must be timed. */ - writeBool(bool: boolean) { - this.writeFrame({ payload: new Uint8Array([bool ? 1 : 0]), timestamp: Timestamp.now() }); - } - /** True once the group has been closed. */ get isClosed(): boolean { return this.#state.closed.peek() !== undefined; diff --git a/js/net/src/index.ts b/js/net/src/index.ts index 76afefcc344..3d516a60718 100644 --- a/js/net/src/index.ts +++ b/js/net/src/index.ts @@ -28,6 +28,7 @@ export * as Origin from "./origin.ts"; export * as Path from "./path.ts"; /** Branded time types (nanoseconds, microseconds, milliseconds, seconds) with conversions. */ export * as Time from "./time.ts"; +export type { Timed } from "./timed.ts"; /** Track role handles. */ export * as Track from "./track.ts"; /** Varint encoding and decoding, in QUIC's format and moq-transport's leading-ones format. */ diff --git a/js/net/src/integration.test.ts b/js/net/src/integration.test.ts index e4781b22ab4..11949553db6 100644 --- a/js/net/src/integration.test.ts +++ b/js/net/src/integration.test.ts @@ -15,7 +15,7 @@ import { SessionCode, SessionError, StreamCode, StreamError, TooFarBehind } from import { Producer as GroupProducer } from "./group.ts"; import * as Ietf from "./ietf/index.ts"; import * as Lite from "./lite/index.ts"; -import { createMockTransportPair } from "./mock.ts"; +import { createMockTransportPair, textFrame } from "./mock.ts"; import type { Consumer as OriginConsumer } from "./origin.ts"; import { Producer as OriginProducer } from "./origin.ts"; import * as Path from "./path.ts"; @@ -86,7 +86,7 @@ async function runPublishSubscribeFlow(protocol: string, version?: number) { continue; } served++; - req.accept({ timescale: Timescale.MILLI }).writeString("hello"); + req.accept({ timescale: Timescale.MILLI }).writeFrame(textFrame("hello")); } })(); @@ -398,7 +398,7 @@ test.each([Lite.ALPN_05, Lite.ALPN_06, Lite.ALPN_07_WIP])( const request = await wireOf(broadcast).requested(); if (!request) return; requests++; - request.accept({ timescale: Timescale.MILLI }).writeString("hello"); + request.accept({ timescale: Timescale.MILLI }).writeFrame(textFrame("hello")); } })(); @@ -591,7 +591,7 @@ test("integration: lite draft-05 datagrams not sent on a non-datagram transport" const pump = (async () => { for (let i = 0; !stop; i++) { producer.appendDatagram(Timestamp.fromMillis(i), enc.encode("dgram")); - producer.writeString("group"); + producer.writeFrame(textFrame("group")); await sleep(2); } })(); @@ -672,7 +672,7 @@ test("integration: lite draft-05 missing datagram writer does not close streams" const track = remote.track("video").subscribe().ordered(); producer.appendDatagram(Timestamp.fromMillis(0), enc.encode("dgram")); - producer.writeString("group"); + producer.writeFrame(textFrame("group")); expect(await track.readString()).toBe("group"); @@ -752,7 +752,7 @@ test("integration: lite draft-05 missing datagram reader does not close streams" const track = remote.track("video").subscribe().ordered(); producer.appendDatagram(Timestamp.fromMillis(0), enc.encode("dgram")); - producer.writeString("group"); + producer.writeFrame(textFrame("group")); expect(await track.readString()).toBe("group"); @@ -789,7 +789,7 @@ test("integration: a group reset carries the peer's code to the subscriber", asy const track = remote.track("video").subscribe().ordered(); const group = producer.appendGroup(); - group.writeString("frame"); + group.writeFrame(textFrame("frame")); const consumer = await track.nextGroup(); if (!consumer) throw new Error("expected a group"); @@ -829,7 +829,7 @@ test("integration: a locally raised group error reaches the peer as its own code const track = remote.track("video").subscribe().ordered(); const group = producer.appendGroup(); - group.writeString("frame"); + group.writeFrame(textFrame("frame")); const consumer = await track.nextGroup(); if (!consumer) throw new Error("expected a group"); @@ -1025,7 +1025,7 @@ test.each(["frame", "FIN"])("integration: lite fetch waits for the publisher's f // Let the in-memory peer process the request with no response available yet. await sleep(0); expect(settled).toBe(0); - if (answer === "frame") group.writeString("accepted"); + if (answer === "frame") group.writeFrame(textFrame("accepted")); else group.close(); const consumers = await Promise.all([a, b]); for (const consumer of consumers) { @@ -1250,7 +1250,7 @@ test("integration: ietf SUBSCRIBE_TRACKS is refused per request", async () => { const req = await wireOf(broadcast).requested(); if (!req) break; const track = req.accept({ timescale: Timescale.MILLI }); - track.writeString("before"); + track.writeFrame(textFrame("before")); served.push(track); } })(); @@ -1268,7 +1268,7 @@ test("integration: ietf SUBSCRIBE_TRACKS is refused per request", async () => { expect(reply[0]).toBe(0x05); expect(reply[3]).toBe(0x03); - for (const producer of served) producer.writeString("after"); + for (const producer of served) producer.writeFrame(textFrame("after")); expect(await track.readString()).toBe("after"); broadcast.close(); @@ -1359,7 +1359,7 @@ async function runSubscriberTeardown(protocol: string, version?: number) { const broadcast = publish(origin, Path.from("test")); const video = broadcast.createTrack("video", { timescale: Timescale.MILLI }); - video.writeString("hello"); + video.writeFrame(textFrame("hello")); const remote = wireOf(client).consume(Path.from("test")); const sub = remote.track("video").subscribe().ordered(); @@ -1406,7 +1406,7 @@ test("integration: ietf draft-14 subscriber teardown on last unsubscribe", async const req = await wireOf(broadcast).requested(); if (!req) break; served = req.accept({ timescale: Timescale.MILLI }); - served.writeString("hello"); + served.writeFrame(textFrame("hello")); } })(); @@ -1444,7 +1444,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", { timescale: Timescale.MILLI }); const group = video.appendGroup(); // deliberately left open: an indefinite group. - group.writeString("hello"); + group.writeFrame(textFrame("hello")); const remote = wireOf(client).consume(Path.from("test")); const fetched = await remote.track("video").fetchGroup(group.sequence); @@ -1483,7 +1483,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", { timescale: Timescale.MILLI }); - video.writeString("hello"); + video.writeFrame(textFrame("hello")); const remote = wireOf(client).consume(Path.from("test")); const a = remote.track("video").subscribe().ordered(); @@ -1494,7 +1494,7 @@ test("integration: lite fan-out keeps the upstream until the last subscriber lea // Closing one leaves the shared upstream serving the other. a.close(); - video.writeString("more"); + video.writeFrame(textFrame("more")); expect(await b.readString()).toBe("more"); expect(video.demand().used.peek()).toBe(true); @@ -1524,7 +1524,7 @@ test("integration: lite re-subscribe re-opens the upstream after each teardown", const remote = wireOf(client).consume(Path.from("test")); for (let i = 0; i < 8; i++) { - video.writeString(`hello-${i}`); + video.writeFrame(textFrame(`hello-${i}`)); const sub = remote.track("video").subscribe().ordered(); expect(await sub.readString()).toBe(`hello-${i}`); await waitUntil(() => video.demand().used.peek()); @@ -1552,7 +1552,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", { timescale: Timescale.MILLI }); const group = video.appendGroup(); // open - group.writeString("hello"); + group.writeFrame(textFrame("hello")); const remote = wireOf(client).consume(Path.from("test")); const f1 = await remote.track("video").fetchGroup(group.sequence); @@ -1563,7 +1563,7 @@ test("integration: lite coalesced fetch stays until every reader abandons the op // Closing one coalesced reader keeps the shared FETCH flowing for the other. f1.close(); - group.writeString("more"); + group.writeFrame(textFrame("more")); expect(await f2.readString()).toBe("more"); expect(group.demand().used.peek()).toBe(true); @@ -1595,7 +1595,7 @@ test("integration: lite fetch re-armed by a late reader keeps every frame", asyn for (let delay = 0; delay <= 12; delay++) { const group = video.appendGroup(); // open - group.writeString("hello"); + group.writeFrame(textFrame("hello")); const f1 = await remote.track("video").fetchGroup(group.sequence); expect(await f1.readString()).toBe("hello"); @@ -1605,7 +1605,7 @@ test("integration: lite fetch re-armed by a late reader keeps every frame", asyn const f2 = await remote.track("video").fetchGroup(group.sequence); expect(await f2.readString()).toBe("hello"); - group.writeString("more"); + group.writeFrame(textFrame("more")); const more = await Promise.race([ f2.readString(), new Promise((resolve) => setTimeout(() => resolve("dropped"), 500)), @@ -1636,7 +1636,7 @@ test("integration: lite fetch delivers every frame of a finite multi-frame group 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}`); + for (let i = 0; i < count; i++) group.writeFrame(textFrame(`f${i}`)); group.close(); // finite const remote = wireOf(client).consume(Path.from("test")); @@ -1674,7 +1674,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({ timescale: Timescale.MILLI }).writeString("hello"); + if (req) req.accept({ timescale: Timescale.MILLI }).writeFrame(textFrame("hello")); })(); const remote = wireOf(client).consume(Path.from("test")); @@ -1753,7 +1753,7 @@ test("integration: an announced request waits for a late publisher", async () => for (;;) { const req = await wireOf(broadcast).requested(); if (!req) break; - req.accept({ timescale: Timescale.MILLI }).writeString(payload); + req.accept({ timescale: Timescale.MILLI }).writeFrame(textFrame(payload)); } }; @@ -1810,7 +1810,7 @@ test("integration: an announced request consumes blind without discovery", async for (;;) { const req = await wireOf(broadcast).requested(); if (!req) break; - req.accept({ timescale: Timescale.MILLI }).writeString("blind"); + req.accept({ timescale: Timescale.MILLI }).writeFrame(textFrame("blind")); } })(); @@ -1841,7 +1841,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({ timescale: Timescale.MILLI }).writeString(payload); + req.accept({ timescale: Timescale.MILLI }).writeFrame(textFrame(payload)); } }; @@ -1901,7 +1901,7 @@ async function runRepublishCycle(protocol: string, version?: number) { for (;;) { const req = await wireOf(broadcast).requested(); if (!req) break; - req.accept({ timescale: Timescale.MILLI }).writeString(payload); + req.accept({ timescale: Timescale.MILLI }).writeFrame(textFrame(payload)); } }; @@ -1973,7 +1973,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({ timescale: Timescale.MILLI }).writeString("late"); + req.accept({ timescale: Timescale.MILLI }).writeFrame(textFrame("late")); } })(); @@ -2033,7 +2033,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({ timescale: Timescale.MILLI }).writeString("ietf-late"); + req.accept({ timescale: Timescale.MILLI }).writeFrame(textFrame("ietf-late")); } })(); @@ -2080,7 +2080,7 @@ async function runOriginFlow(protocol: string, version?: number) { req.reject(new Error(`unexpected track: ${req.name}`)); continue; } - req.accept({ timescale: Timescale.MILLI }).writeString("hello"); + req.accept({ timescale: Timescale.MILLI }).writeFrame(textFrame("hello")); } })(); @@ -2215,7 +2215,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({ timescale: Timescale.MILLI }).writeString("found you"); + req.accept({ timescale: Timescale.MILLI }).writeFrame(textFrame("found you")); } })(); @@ -2343,7 +2343,7 @@ test("origin: overlapping sessions carrying one path fail over", async () => { for (;;) { const req = await wireOf(broadcast).requested(); if (!req) break; - req.accept({ timescale: Timescale.MILLI }).writeString("still here"); + req.accept({ timescale: Timescale.MILLI }).writeFrame(textFrame("still here")); } })(); return { client, server, serverOrigin, broadcast, serving }; @@ -2393,7 +2393,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({ timescale: Timescale.MILLI }).writeString(payload); + req.accept({ timescale: Timescale.MILLI }).writeFrame(textFrame(payload)); } })(); return { client, server, serverOrigin, broadcast, serving }; @@ -2465,7 +2465,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", { timescale: Timescale.MILLI }).writeString("hello"); + produced.createTrack("chat", { timescale: Timescale.MILLI }).writeFrame(textFrame("hello")); request.accept(produced); } })(); @@ -2519,7 +2519,7 @@ async function runSessionDeath( for (;;) { const req = await wireOf(broadcast).requested(); if (!req) break; - req.accept({ timescale: Timescale.MILLI }).appendGroup().writeString("head"); + req.accept({ timescale: Timescale.MILLI }).appendGroup().writeFrame(textFrame("head")); } })(); @@ -2580,7 +2580,7 @@ test("integration: lite draft-05 ends a track with the publisher's reset", async const req = await wireOf(broadcast).requested(); if (!req) break; const producer = req.accept({ timescale: Timescale.MILLI }); - producer.appendGroup().writeString("head"); + producer.appendGroup().writeFrame(textFrame("head")); served.push(producer); } })(); diff --git a/js/net/src/lite/connection.test.ts b/js/net/src/lite/connection.test.ts index ebe48b84b02..552ed2b5359 100644 --- a/js/net/src/lite/connection.test.ts +++ b/js/net/src/lite/connection.test.ts @@ -2,7 +2,7 @@ import { expect, spyOn, test } from "bun:test"; import { accept } from "../connection/accept.ts"; import { connect } from "../connection/connect.ts"; import { SessionCode } from "../error.ts"; -import { createMockTransportPair, type MockTransport } from "../mock.ts"; +import { createMockTransportPair, type MockTransport, textFrame } from "../mock.ts"; import { Producer } from "../origin.ts"; import * as Path from "../path.ts"; import { Stream, Writer } from "../stream.ts"; @@ -223,12 +223,12 @@ for (const alpn of [ALPN_05, ALPN_06, ALPN_07_WIP]) { closed = true; }); try { - producer.appendGroup().writeString("first"); + producer.appendGroup().writeFrame(textFrame("first")); expect(await (await track.nextGroup())?.readString()).toBe("first"); fin.enable(); const last = producer.appendGroup(); - last.writeString("last"); + last.writeFrame(textFrame("last")); last.close(); producer.close(); const closing = server.close(); @@ -269,7 +269,7 @@ async function servedRawSubscription() { }); const group = producer.appendGroup(); - group.writeString("last"); + group.writeFrame(textFrame("last")); group.close(); const subscriber = await Stream.open(pair.client, { version }); @@ -369,7 +369,7 @@ test("close waits for a served FETCH to be acknowledged", async () => { broadcast.announce(); const producer = broadcast.createTrack("video", { timescale: Timescale.MILLI }); const group = producer.appendGroup(); - group.writeString("last"); + group.writeFrame(textFrame("last")); group.close(); const server = new Connection({ url: new URL("https://relay.example/"), @@ -421,7 +421,7 @@ test("close waits for a request served while withdrawals are in flight", async ( broadcast.announce(); const producer = broadcast.createTrack("video", { timescale: Timescale.MILLI }); const group = producer.appendGroup(); - group.writeString("last"); + group.writeFrame(textFrame("last")); group.close(); const url = new URL("https://localhost/test"); const [client, server] = await Promise.all([ diff --git a/js/net/src/lite/publisher.test.ts b/js/net/src/lite/publisher.test.ts index b1130a8f2ab..e6643f8803b 100644 --- a/js/net/src/lite/publisher.test.ts +++ b/js/net/src/lite/publisher.test.ts @@ -3,7 +3,7 @@ import { Signal } from "@moq/signals"; import { Producer as GroupProducer } from "../group.ts"; import { randomHop } from "../hop.ts"; import { hooks } from "../internal.ts"; -import { createMockTransportPair } from "../mock.ts"; +import { createMockTransportPair, textFrame } from "../mock.ts"; import { Producer as OriginProducer } from "../origin.ts"; import * as Path from "../path.ts"; import { Reader, Stream, Writer } from "../stream.ts"; @@ -144,7 +144,7 @@ async function subscribeEnd(sequences: number[], version: Version = Version.DRAF // track ending rather than resolving a subscribe against an already-closed one. for (const sequence of sequences) { const group = new GroupProducer(sequence); - group.writeString("hello"); + group.writeFrame(textFrame("hello")); group.close(); track.writeGroup(group); @@ -219,7 +219,7 @@ async function groupSendOrders(options: { priority: number; sequences: number[]; while (track.subscription.peek()?.priority !== update) await track.subscription.changed(); } - group.writeString("hello"); + group.writeFrame(textFrame("hello")); track.writeGroup(group); // One stream per group, in the order given: wait for this one before queuing the next. @@ -294,7 +294,7 @@ test("lite draft-05: a subscribe update re-ranks a group already on the wire", a // Leave the group open, so its stream is still being served when the update lands. const group = new GroupProducer(4); - group.writeString("hello"); + group.writeFrame(textFrame("hello")); track.writeGroup(group); const opened = pair.client.incomingUnidirectionalStreams.getReader(); @@ -357,7 +357,7 @@ test("lite draft-05: a subscribe update during the stream open still ranks the g void publisher.runSubscribe(msg, server); const group = new GroupProducer(4); - group.writeString("hello"); + group.writeFrame(textFrame("hello")); track.writeGroup(group); try { @@ -411,7 +411,7 @@ test("lite draft-05: many concurrent groups share one subscription listener", as try { for (const group of groups) { - group.writeString("hello"); + group.writeFrame(textFrame("hello")); track.writeGroup(group); await servingNextGroup(opened); } @@ -448,7 +448,7 @@ test("lite draft-05: the fetch response ranks the publisher's own writes", async const track = broadcast.createTrack("video", { timescale: Timescale.MILLI }); const group = new GroupProducer(7); - group.writeString("hello"); + group.writeFrame(textFrame("hello")); group.close(); track.writeGroup(group); @@ -582,7 +582,7 @@ async function servedSubscription( release: gate.release, serve(sequence: number) { const group = new GroupProducer(sequence); - for (const frame of frames) group.writeString(frame); + for (const frame of frames) group.writeFrame(textFrame(frame)); group.close(); track.writeGroup(group); }, @@ -1057,7 +1057,7 @@ test("lite draft-07: subscribe end waits for groups below a declared finish", as try { const first = new GroupProducer(0); - first.writeString("hello"); + first.writeFrame(textFrame("hello")); first.close(); track.writeGroup(first); track.finishAt(2); @@ -1069,7 +1069,7 @@ test("lite draft-07: subscribe end waits for groups below a declared finish", as expect(early).toBeUndefined(); const second = new GroupProducer(1); - second.writeString("hello"); + second.writeFrame(textFrame("hello")); second.close(); track.writeGroup(second); track.close(); @@ -1111,7 +1111,7 @@ async function heldOpenEnd() { ); const group = new GroupProducer(0); - group.writeString("hello"); + group.writeFrame(textFrame("hello")); group.close(); track.writeGroup(group); track.close(); @@ -1197,7 +1197,7 @@ async function serve( for (const [sequence, frames] of Object.entries(groups)) { const group = new GroupProducer(Number(sequence)); - for (const frame of frames) group.writeString(frame); + for (const frame of frames) group.writeFrame(textFrame(frame)); group.close(); track.writeGroup(group); @@ -1377,7 +1377,7 @@ async function saturatedGroup() { // A finished group still has frames to send, so its own close must not drop it. const group = new GroupProducer(0); - group.writeString("hello"); + group.writeFrame(textFrame("hello")); group.close(); track.writeGroup(group); @@ -1651,7 +1651,7 @@ test.each([0, 1])("lite draft-07 reports the cached largest position when starti const broadcast = publish(origin, Path.from("quiet")); const track = broadcast.createTrack("video", { timescale: Timescale.MILLI }); const group = new GroupProducer(0); - group.writeString("cached"); + group.writeFrame(textFrame("cached")); group.close(); track.writeGroup(group); const client = await Stream.open(pair.client, { version }); diff --git a/js/net/src/mock.ts b/js/net/src/mock.ts index 78fdd6d1916..d817e695c1b 100644 --- a/js/net/src/mock.ts +++ b/js/net/src/mock.ts @@ -1,11 +1,18 @@ /** - * Mock WebTransport implementation for in-process testing. + * Test doubles for in-process testing. * * Creates paired client/server transports connected via TransformStreams. */ import type { TransportStats } from "./connection/stats.ts"; +import type { Frame } from "./group.ts"; import type { SendStream } from "./stream.ts"; +import { Timestamp } from "./time.ts"; + +/** A UTF-8 text frame stamped now, for a test writing to a timed track. */ +export function textFrame(text: string): Frame { + return { payload: new TextEncoder().encode(text), timestamp: Timestamp.now() }; +} // High watermark to prevent writes from blocking on backpressure. // Real WebTransport has kernel buffers; we simulate this with a large queue. diff --git a/js/net/src/tail.test.ts b/js/net/src/tail.test.ts index c2f8f9cdd10..a22854c1132 100644 --- a/js/net/src/tail.test.ts +++ b/js/net/src/tail.test.ts @@ -3,7 +3,7 @@ import { Once } from "@moq/signals"; 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 { createMockTransportPair, textFrame } from "./mock.ts"; import { Producer as OriginProducer } from "./origin.ts"; import * as Path from "./path.ts"; import { TAIL_GRACE_MS, Tail } from "./tail.ts"; @@ -58,15 +58,15 @@ test.each([Lite.ALPN_05, Lite.ALPN_06])( async (alpn) => { const { video, reader, close } = await session(alpn); try { - video.writeString("0"); + video.writeFrame(textFrame("0")); expect(await reader.readString()).toBe("0"); - video.writeString("1"); + video.writeFrame(textFrame("1")); expect(await reader.readString()).toBe("1"); video.finishAt(3); expect(await reader.finished()).toBe(3); - video.writeString("2"); + video.writeFrame(textFrame("2")); video.close(); expect(await readAll(reader)).toEqual(["2"]); expect(await reader.closed).toBeNull(); @@ -85,12 +85,12 @@ test.each([Ietf.ALPN.DRAFT_16, Ietf.ALPN.DRAFT_17, Ietf.ALPN.DRAFT_20])( async (alpn) => { const { video, reader, close } = await session(alpn); try { - video.writeString("0"); + video.writeFrame(textFrame("0")); expect(await reader.readString()).toBe("0"); video.finishAt(4); - video.writeString("1"); - video.writeString("2"); + video.writeFrame(textFrame("1")); + video.writeFrame(textFrame("2")); const ended = performance.now(); video.close(); diff --git a/js/net/src/timed.ts b/js/net/src/timed.ts new file mode 100644 index 00000000000..60e1a38c919 --- /dev/null +++ b/js/net/src/timed.ts @@ -0,0 +1,14 @@ +/** + * A value paired with when it was captured. + * + * @module + */ +import type { Timestamp } from "./time.ts"; + +/** A value, and optionally when it was captured. An absent `at` means untimed, never now. */ +export interface Timed { + /** The value. */ + value: T; + /** When the value was captured, written as its frame's timestamp. Absent for an untimed track. */ + at?: Timestamp; +} diff --git a/js/net/src/track.test.ts b/js/net/src/track.test.ts index 8ef71ad7180..faeec7e24e1 100644 --- a/js/net/src/track.test.ts +++ b/js/net/src/track.test.ts @@ -2,6 +2,7 @@ import { expect, setSystemTime, spyOn, test } from "bun:test"; import { TimestampMismatch, TooFarBehind } from "./error.ts"; import { Producer as GroupProducer, MAX_GROUP_FRAMES } from "./group.ts"; import { hooks } from "./internal.ts"; +import { textFrame } from "./mock.ts"; import { Milli, Timescale, Timestamp } from "./time.ts"; import { infoDefaults, type Subscription, Producer as TrackProducer } from "./track.ts"; @@ -104,7 +105,7 @@ test("a producer never self-closes on zero demand: a publisher keeps serving new expect(producer.closed.peek()).toBeUndefined(); // A later subscriber still works and replays the cache. - producer.writeString("still here"); + producer.writeFrame(textFrame("still here")); const b = producer.subscribe().ordered(); expect(await b.readString()).toBe("still here"); expect(producer.demand().used.peek()).toBe(true); @@ -573,18 +574,18 @@ test("nextGroup abandons the frame helpers' group when it passes it", async () = const track = producer.subscribe({ maxDelay: Milli(5000) }).ordered(); const zero = new GroupProducer(0); - zero.writeString("0.0"); - zero.writeString("0.1"); + zero.writeFrame(textFrame("0.0")); + zero.writeFrame(textFrame("0.1")); zero.close(); producer.writeGroup(zero); const one = new GroupProducer(1); - one.writeString("1.0"); + one.writeFrame(textFrame("1.0")); one.close(); producer.writeGroup(one); const two = new GroupProducer(2); - two.writeString("2.0"); + two.writeFrame(textFrame("2.0")); two.close(); producer.writeGroup(two); @@ -605,18 +606,18 @@ test("ordered frame reads skip a late lower-sequence group", async () => { const track = producer.subscribe({ maxDelay: Milli(5000) }).ordered(); const five = new GroupProducer(5); - five.writeString("five"); + five.writeFrame(textFrame("five")); five.close(); producer.writeGroup(five); expect(await track.readString()).toBe("five"); const three = new GroupProducer(3); - three.writeString("three"); + three.writeFrame(textFrame("three")); three.close(); producer.writeGroup(three); const six = new GroupProducer(6); - six.writeString("six"); + six.writeFrame(textFrame("six")); six.close(); producer.writeGroup(six); @@ -628,8 +629,8 @@ test("zero latency takes the latest group when ages are equal", async () => { try { const producer = new TrackProducer("test").accept({ timescale: Timescale.MILLI, maxAge: Milli(5000) }); const track = producer.subscribe(); - producer.writeString("old"); - producer.writeString("new"); + producer.writeFrame(textFrame("old")); + producer.writeFrame(textFrame("new")); expect((await track.recvGroup())?.sequence).toBe(1); } finally { @@ -891,7 +892,7 @@ test("committing track info wakes a group newly outside the retention window", a test("a handed-out frame cancels its in-flight operation when it expires", async () => { const producer = new TrackProducer("test").accept({ timescale: Timescale.MILLI, maxAge: Milli(5000) }); const track = producer.subscribe(); - producer.writeString("old"); + producer.writeFrame(textFrame("old")); const group = await track.recvGroup(); if (!group) throw new Error("missing group"); @@ -902,7 +903,7 @@ test("a handed-out frame cancels its in-flight operation when it expires", async release = resolve; }); const guarded = hooks.guardGroup(group, () => operation); - producer.writeString("new"); + producer.writeFrame(textFrame("new")); await expect(guarded).rejects.toThrow("max delay budget"); release(); @@ -970,13 +971,13 @@ 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({ timescale: Timescale.MILLI, maxAge: Milli(5000) }); const track = producer.subscribe(); - producer.writeString("old"); + producer.writeFrame(textFrame("old")); const group = await track.recvGroup(); if (!group) throw new Error("missing group"); expect(await group.readString()).toBe("old"); - producer.writeString("new"); + producer.writeFrame(textFrame("new")); expect(await group.readFrame()).toBeUndefined(); expect(group.done).toBe(true); @@ -1033,8 +1034,8 @@ test("retention eviction surfaces as a gap for a handed-out group", async () => 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"); - source.writeString("tail"); + source.writeFrame(textFrame("first")); + source.writeFrame(textFrame("tail")); source.close(); const group = await track.recvGroup(); @@ -1056,8 +1057,8 @@ test("idle expiry reclaims an ended track's held mirror", async () => { 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"); - source.writeString("tail"); + source.writeFrame(textFrame("first")); + source.writeFrame(textFrame("tail")); source.close(); const group = await track.recvGroup(); @@ -1080,7 +1081,7 @@ test("retention reclaims a group the publisher abandoned open", async () => { 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"); + stalled.writeFrame(textFrame("first")); // A successor, so the stalled group is not the live edge the publisher is // still filling. It is never closed: the publisher simply walked away. producer.appendGroup(); @@ -1105,7 +1106,7 @@ test("an idle live edge ages out once a newer group arrives", async () => { 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"); + edge.writeFrame(textFrame("first")); const group = await track.recvGroup(); if (!group) throw new Error("missing group"); @@ -1135,7 +1136,7 @@ test("an abandoned open group ages out with no further write", async () => { try { const track = producer.subscribe({ maxDelay: Milli(30) }); const stalled = producer.appendGroup(); - stalled.writeString("first"); + stalled.writeFrame(textFrame("first")); producer.appendGroup(); const group = await track.recvGroup(); @@ -1155,7 +1156,7 @@ test("publisher maxAge does not change the idle cache deadline", () => { const clock = mockCacheTime(10_000); const producer = new TrackProducer("test").accept({ timescale: Timescale.MILLI, maxAge }); try { - producer.writeString("cached"); + producer.writeFrame(textFrame("cached")); producer.appendGroup(); expect(clock.deadline()).toBe(10_000 + CACHE_WINDOW_MS / 8); } finally { @@ -1171,7 +1172,7 @@ test("retention pruning preserves clean EOF for a drained mirror", async () => { 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"); + source.writeFrame(textFrame("only")); source.close(); const group = await track.recvGroup(); @@ -1196,10 +1197,10 @@ test("system clock changes do not affect the latency budget", async () => { try { const producer = new TrackProducer("test").accept({ timescale: Timescale.MILLI, maxAge: Milli(100) }); const track = producer.subscribe({ maxDelay: Milli(100) }); - producer.writeString("old"); + producer.writeFrame(textFrame("old")); setSystemTime(new Date(20_000)); - producer.writeString("new"); + producer.writeFrame(textFrame("new")); expect((await track.recvGroup())?.sequence).toBe(0); expect((await track.recvGroup())?.sequence).toBe(1); @@ -1218,7 +1219,7 @@ test("frame readiness cancels the losing latency waiter", async () => { for (let i = 0; i < 110; i++) { const pending = group.readFrame(); - source.writeString(`${i}`); + source.writeFrame(textFrame(`${i}`)); expect(new TextDecoder().decode((await pending)?.payload)).toBe(`${i}`); } }); @@ -1434,7 +1435,7 @@ test("writeGroup rejects a duplicate live sequence", async () => { const track = producer.subscribe(); const first = new GroupProducer(7); - first.writeString("first"); + first.writeFrame(textFrame("first")); first.close(); producer.writeGroup(first); @@ -1448,7 +1449,7 @@ test("writeGroup rejects a duplicate live sequence", async () => { aborted.close(new Error("upstream reset")); const retry = new GroupProducer(8); - retry.writeString("retry"); + retry.writeFrame(textFrame("retry")); retry.close(); producer.writeGroup(retry); @@ -1562,7 +1563,7 @@ test("a closed track still delivers a group parked above the cap once the cap is for (let sequence = 0; sequence < 3; sequence++) { const group = new GroupProducer(sequence); - group.writeString(`frame-${sequence}`); + group.writeFrame(textFrame(`frame-${sequence}`)); group.close(); producer.writeGroup(group); } @@ -1627,7 +1628,7 @@ test("readFrame does not livelock when a sole group finishes before the next arr // The next group arrives via a macrotask; if the reader livelocks on microtasks it never runs. setTimeout(() => { const g1 = producer.appendGroup(); - g1.writeString("hello"); + g1.writeFrame(textFrame("hello")); g1.close(); producer.close(); }, 10); @@ -1782,7 +1783,7 @@ for (const ordered of [false, true]) { producer.finishAt(3); const waiting = receive(); const group = new GroupProducer(2); - group.writeString("tail"); + group.writeFrame(textFrame("tail")); producer.writeGroup(group); const received = await waiting; expect(received?.sequence).toBe(2); @@ -1871,7 +1872,7 @@ test("an omitted publisher limit still ages idle groups out", async () => { const producer = new TrackProducer("unlimited").accept({ timescale: Timescale.MILLI }); try { const source = producer.appendGroup(); - source.writeString("old"); + source.writeFrame(textFrame("old")); source.close(); clock.set(10_000 + CACHE_WINDOW_MS - 1_000); producer.appendGroup(); @@ -1896,10 +1897,10 @@ test("a live track does not pin an aborted newest group", () => { const producer = new TrackProducer("test").accept({ timescale: Timescale.MILLI }); try { const good = producer.appendGroup(); - good.writeString("snapshot"); + good.writeFrame(textFrame("snapshot")); good.close(); const reset = producer.appendGroup(); - reset.writeString("partial"); + reset.writeFrame(textFrame("partial")); reset.close(new Error("reset")); clock.set(10_000 + CACHE_WINDOW_MS + CACHE_WINDOW_MS / 8); @@ -1918,7 +1919,7 @@ test("closing a track keeps an idle newest group for subscribers to drain", asyn const producer = new TrackProducer("catalog").accept({ timescale: Timescale.MILLI }); const subscriber = producer.subscribe({ maxDelay: Milli(100_000) }); const snapshot = producer.appendGroup(); - snapshot.writeString("snapshot"); + snapshot.writeFrame(textFrame("snapshot")); snapshot.close(); // Idle well past the window, but protected while the track is live. @@ -1942,7 +1943,7 @@ test("a late subscriber to a closed unlimited track is released once the cache a try { const producer = new TrackProducer("unlimited").accept({ timescale: Timescale.MILLI }); const source = producer.appendGroup(); - source.writeString("last"); + source.writeFrame(textFrame("last")); source.close(); producer.close(); @@ -1981,10 +1982,10 @@ test("an abort keeps finished groups for a slow reader, then reports it", async const ordered = producer.subscribe({ maxDelay: Milli(10_000) }).ordered(); for (let i = 0; i < 2; i++) { const group = producer.appendGroup(); - group.writeString(`g${i}`); + group.writeFrame(textFrame(`g${i}`)); group.close(); } - producer.appendGroup().writeString("open"); + producer.appendGroup().writeFrame(textFrame("open")); const boom = new Error("boom"); producer.close(boom); @@ -2005,7 +2006,7 @@ test("an abort after the declared end settles ends clean", async () => { const ordered = producer.subscribe({ maxDelay: Milli(10_000) }).ordered(); for (let i = 0; i < 2; i++) { const group = producer.appendGroup(); - group.writeString(`g${i}`); + group.writeFrame(textFrame(`g${i}`)); group.close(); } producer.finishAt(2); @@ -2033,7 +2034,7 @@ test("an ended track's buffered groups age out for a stale subscriber", () => { try { const stale = producer.subscribe({ maxDelay: Milli(30) }); const group = producer.appendGroup(); - group.writeString("x"); + group.writeFrame(textFrame("x")); group.close(); producer.close(abort); @@ -2052,7 +2053,7 @@ test("an abort leaves a group already taken readable, then reports the abort", a 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"); + producer.appendGroup().writeFrame(textFrame("held")); const held = [await arrival.recvGroup(), await ordered.nextGroup()]; const boom = new Error("boom"); producer.close(boom); @@ -2199,8 +2200,10 @@ test("accept closes the track when something written before it disagrees", async 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); + // A timestamped frame is refused by an untimed track. + expect(() => producer.writeFrame({ payload: enc.encode("x"), timestamp: Timestamp.fromMillis(1) })).toThrow( + TimestampMismatch, + ); producer.writeFrame({ payload: enc.encode("y") }); // The failed group ends in that error instead of leaving a reader waiting on it. diff --git a/js/net/src/track.ts b/js/net/src/track.ts index fcb950141e4..93f51298678 100644 --- a/js/net/src/track.ts +++ b/js/net/src/track.ts @@ -1039,36 +1039,16 @@ 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(); try { - write(group); + group.writeFrame(frame); } catch (err) { + // Abort the group so no subscriber waits on a group that will never get its frame. 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) { - this.#writeSingle((group) => group.writeString(str)); - } - - /** Appends a JSON value to the track as its own single-frame group. */ - writeJson(json: unknown) { - this.#writeSingle((group) => group.writeJson(json)); - } - - /** Appends a boolean to the track as its own single-frame group. */ - writeBool(bool: boolean) { - this.#writeSingle((group) => group.writeBool(bool)); - } } /** diff --git a/js/net/src/zod.ts b/js/net/src/zod.ts index abca3cd278c..754d98fdcc9 100644 --- a/js/net/src/zod.ts +++ b/js/net/src/zod.ts @@ -1,5 +1,5 @@ /** - * Helpers for reading and writing Zod-validated JSON frames on a track or group. + * Helpers for reading Zod-validated JSON frames from a track or group. * * @module */ @@ -17,9 +17,3 @@ export async function read( if (next === undefined) return undefined; // only treat undefined as EOF, not other falsy values return schema.parse(next); } - -/** 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/catalog.ts b/js/publish/src/catalog.ts index 92ce293740c..cc8ec62dab9 100644 --- a/js/publish/src/catalog.ts +++ b/js/publish/src/catalog.ts @@ -1,6 +1,7 @@ import * as Catalog from "@moq/hang/catalog"; import * as Json from "@moq/json"; import type * as Moq from "@moq/net"; +import { Time } from "@moq/net"; import { Effect } from "@moq/signals"; /** @@ -56,7 +57,8 @@ export class CatalogProducer { this.#pending?.close(); this.#pending = undefined; if (estimate) this.#lastEstimate = performance.now(); - for (const output of this.#outputs) output.update(this.#value); + const at = Time.Timestamp.now(); + for (const output of this.#outputs) output.update({ value: this.#value, at }); } /** @@ -71,7 +73,7 @@ export class CatalogProducer { compression: opts?.compression ? "deflate" : "none", deltaRatio: 0, }); - output.update(this.#value); + output.update({ value: this.#value, at: Time.Timestamp.now() }); this.#outputs.add(output); effect.cleanup(() => { diff --git a/js/room/src/chat.test.ts b/js/room/src/chat.test.ts index aef83ea6263..8c4ea560af8 100644 --- a/js/room/src/chat.test.ts +++ b/js/room/src/chat.test.ts @@ -1,5 +1,5 @@ import { expect, spyOn, test } from "bun:test"; -import { Broadcast } from "@moq/net"; +import { Broadcast, Time } from "@moq/net"; import { HISTORY, info, Publisher, Subscriber, TRACK } from "./chat.ts"; test("chat expires ten-second history and late readers only see retained messages", async () => { @@ -34,7 +34,10 @@ test("chat rejects non-string window records and propagates track failures", asy const track = broadcast.createTrack(TRACK, info()); const subscriber = Subscriber.subscribe(broadcast.consume()); try { - track.writeString('{"offset":0,"records":[42]}'); + track.writeFrame({ + payload: new TextEncoder().encode('{"offset":0,"records":[42]}'), + timestamp: Time.Timestamp.now(), + }); await expect(subscriber.recv()).rejects.toThrow("chat record must be a string"); track.close(new Error("chat aborted")); await expect(subscriber.recv()).rejects.toThrow("chat aborted"); diff --git a/js/room/src/chat.ts b/js/room/src/chat.ts index 33c25679a70..56a0ba8fd88 100644 --- a/js/room/src/chat.ts +++ b/js/room/src/chat.ts @@ -48,7 +48,7 @@ export class Publisher { send(text: string): void { if (!text) return; this.expire(); - this.#producer.push(text); + this.#producer.push({ value: text, at: Time.Timestamp.now() }); this.#expires.update((expires) => [...expires, performance.now() + HISTORY]); } @@ -59,7 +59,7 @@ export class Publisher { let count = 0; while (count < expires.length && expires[count] <= now) count++; if (!count) return; - this.#producer.pop(count); + this.#producer.pop(count, Time.Timestamp.now()); this.#expires.set(expires.slice(count)); } diff --git a/js/room/src/metadata.test.ts b/js/room/src/metadata.test.ts index 47875966a64..3acfe426edf 100644 --- a/js/room/src/metadata.test.ts +++ b/js/room/src/metadata.test.ts @@ -62,8 +62,8 @@ test("metadata clears when entries disappear or broadcast becomes inactive", asy 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 } }); + user.update({ value: { name: "Alice" }, at: Net.Time.Timestamp.now() }); + preview.update({ value: { info: { video: true } }, at: Net.Time.Timestamp.now() }); const consumed = consume({ out: { catalog, active } } as unknown as Watch.Broadcast); try { await flush(); diff --git a/js/room/src/metadata.ts b/js/room/src/metadata.ts index 190f0e52c25..35e3ea170e6 100644 --- a/js/room/src/metadata.ts +++ b/js/room/src/metadata.ts @@ -164,7 +164,7 @@ function serveSnapshot( effect.cleanup(() => producer.finish()); effect.run((effect) => { - producer.update(value(effect)); + producer.update({ value: value(effect), at: Moq.Time.Timestamp.now() }); }); }); } diff --git a/js/watch/src/broadcast.test.ts b/js/watch/src/broadcast.test.ts index f536c93684e..7d727e6cf1a 100644 --- a/js/watch/src/broadcast.test.ts +++ b/js/watch/src/broadcast.test.ts @@ -425,7 +425,9 @@ describe("wildcard renditions", () => { expect(active).toBeUndefined(); const produced = new Moq.Broadcast.Producer(); - produced.createTrack("video", { timescale: Moq.Time.Timescale.MILLI }).writeString("frame"); + produced + .createTrack("video", { timescale: Moq.Time.Timescale.MILLI }) + .writeFrame({ payload: new TextEncoder().encode("frame"), timestamp: Moq.Time.Timestamp.now() }); request?.accept(produced); await settle(); expect(active).toBeDefined(); diff --git a/quest/m1/README.md b/quest/m1/README.md index ffeb39caee1..564e61b86a1 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -42,7 +42,6 @@ were done or not worth their cost. - [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 - [Publishing never invents a timestamp](/quest/m1/publish-timestamp.md) - no Rust or binding publish API fills in a timestamp; an untimed payload goes out untimed -- [JS publishing never invents a timestamp](/quest/m1/js-publish-timestamp.md) - the same in @moq/json, @moq/flate, and @moq/net - [Hard fork](/quest/m1/quic/fork/README.md) - quinn hard-forked in-tree as `moq-quic`, ranked ahead of perf; the rest of the QUIC line follows it - [Cluster routing](/quest/m1/cluster-routing/README.md) - any node routes toward a broadcast's origin over CDN and P2P links alike, with per-origin routes and path-less announces - [Track tail interop](/quest/m1/track-tail-interop.md) - a Rust publisher ending a track with a group in flight is read to its end by the JS subscriber, and the reverse, in `just test interop` diff --git a/quest/m1/js-data-consumer-timestamps.md b/quest/m1/js-data-consumer-timestamps.md index aed3340a669..a5a824b8244 100644 --- a/quest/m1/js-data-consumer-timestamps.md +++ b/quest/m1/js-data-consumer-timestamps.md @@ -13,8 +13,7 @@ Requested by OneTooMany, whose web frontend shows KLV and MAVLink telemetry beside video and today reads raw frames to recover the timestamps. Decided (2026-10-01): `next()` and the async iterator yield `@moq/net`'s -`Timed` (`{ value, at? }`), the type the producers take after -[JS publishing never invents a timestamp](/quest/m1/js-publish-timestamp.md). +`Timed` (`{ value, at? }`), the type the producers take. `at` is the frame's timestamp, absent for an untimed frame. 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: @@ -28,10 +27,6 @@ that falls behind still jumps to the newest group. Update Public API: breaking. Wire: none. -## Required - -- [JS publishing never invents a timestamp](/quest/m1/js-publish-timestamp.md) - adds `Timed` to `@moq/net` - ## Related - [Synced data playback](/quest/m2/watch-data-sync.md) - the js/watch reader built on these timestamps diff --git a/quest/m1/js-publish-timestamp.md b/quest/m1/js-publish-timestamp.md deleted file mode 100644 index a066045a3c2..00000000000 --- a/quest/m1/js-publish-timestamp.md +++ /dev/null @@ -1,46 +0,0 @@ -# [M] JS publishing never invents a timestamp - -## Goal - -`@moq/json`, `@moq/flate`, and `@moq/net` publish APIs never fill in -`Timestamp.now()` for the caller, mirroring -[Publishing never invents a timestamp](/quest/m1/publish-timestamp.md). A -payload published without a timestamp goes out untimed. - -## Plan - -The remaining work is these defaults (checked 2026-10-08): the json and -flate snapshot and stream producers default `at = Timestamp.now()`, the json -window producer always uses now, and js/net's `writeString`, `writeJson`, and -`writeBool` (on the group and track producers) stamp now, as does `zod.write` -through `writeJson`. - -Decided 2026-10-08: delete `writeString`, `writeJson`, and `writeBool` -rather than re-typing them to take a timestamp; `writeFrame` already takes -one. `zod.write` takes the timestamp or goes with them. Their callers -(`js/clock`, `js/net/examples/publish.ts`) write frames with their clock's -now explicitly. - -Decided (2026-10-01): `@moq/net` exports `Timed` -(`{ value: T; at?: Time.Timestamp }`), the Rust name and shape. Each producer -takes a `Timed`; an absent `at` is untimed, never now. The consumers return -the same type in -[JS data consumer timestamps](/quest/m1/js-data-consumer-timestamps.md). -Callers in the repository (js/hang catalog, js/publish, js/room, js/clock) -pass their clock's now explicitly. Update `doc/lib/js/{json,flate,net}.md`. - -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. `@moq/net` already refuses a -mismatched frame, so the group helpers, which still stamp now, only work on a -timed track today. - -Decided (2026-10-07): `@moq/net` has no default timescale. Omitting -`Track.Info.timescale` declares an untimed track, so every timed publisher -names its units, as Rust will once -[An undeclared Rust timescale means untimed](/quest/m1/rust-untimed-default.md) -lands. - -Public API: breaking. Wire: none. diff --git a/quest/m1/publish-timestamp.md b/quest/m1/publish-timestamp.md index 637ce841a59..8db37dd7fcf 100644 --- a/quest/m1/publish-timestamp.md +++ b/quest/m1/publish-timestamp.md @@ -69,5 +69,4 @@ with the untimed implementation quests. ## Related -- [JS publishing never invents a timestamp](/quest/m1/js-publish-timestamp.md) - the same change in the JS packages - [FFI shape](/quest/m1/ffi-shape/README.md) - moves the data producers this changes into `json` and `flate` namespaces in the same merge, so this is ready once #4519 lands rather than waiting on the codec child (2026-10-06 audit) From 468acc973e170044c8b22e777e225d985ef14e6d Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Thu, 8 Oct 2026 23:37:54 -0700 Subject: [PATCH 3/3] fix: migrate the drain harness off writeString, import Time in the json stream example Co-Authored-By: Claude Opus 5.5 --- js/json/README.md | 1 + test/drain/drain.ts | 5 ++++- 2 files changed, 5 insertions(+), 1 deletion(-) diff --git a/js/json/README.md b/js/json/README.md index 5b96a711098..6db2b4de9da 100644 --- a/js/json/README.md +++ b/js/json/README.md @@ -47,6 +47,7 @@ An ordered log of self-contained records, one JSON value per frame, all riding a ```ts import { Stream } from "@moq/json"; +import { Time } from "@moq/net"; const producer = new Stream.Producer({ track }); producer.append({ value: { event: "started" }, at: Time.Timestamp.now() }); diff --git a/test/drain/drain.ts b/test/drain/drain.ts index e4ec44c9eb0..6f0d8d04255 100644 --- a/test/drain/drain.ts +++ b/test/drain/drain.ts @@ -116,7 +116,10 @@ const publisher = new Moq.Connection({ url: new URL(`http://127.0.0.1:${bPort}/` let lastPublished = -1; const ticker = setInterval(() => { const group = track.appendGroup(); - group.writeString(String(group.sequence)); + group.writeFrame({ + payload: new TextEncoder().encode(String(group.sequence)), + timestamp: Moq.Time.Timestamp.now(), + }); group.close(); lastPublished = group.sequence; }, GROUP_INTERVAL_MS);