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

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 4 additions & 1 deletion demo/web/src/publish.ts
Original file line number Diff line number Diff line change
Expand Up @@ -401,7 +401,10 @@ meta.run((effect) => {
if (!net) return;

// A day-long cache so a viewer joining long after the last edit still replays the value.
const track = net.createTrack(META_TRACK, { maxAge: Net.Time.Milli(86_400_000) });
const track = net.createTrack(META_TRACK, {
timescale: Net.Time.Timescale.MILLI,
maxAge: Net.Time.Milli(86_400_000),
});
effect.cleanup(() => track.close());

const producer = new Json.Snapshot.Producer<unknown>({ track });
Expand Down
3 changes: 2 additions & 1 deletion doc/lib/js/flate.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,8 @@ producer.update(payload);
```

A payload is stamped when written, unless you pass its capture time:
`producer.update(payload, at)`.
`producer.update(payload, at)`. Every frame carries a timestamp, so the track must
declare a timescale, such as `createTrack(name, { timescale: Time.Timescale.MILLI })`.

The codec underneath is exported as `Encoder`/`Decoder`. Create one pair per
group and feed frames in order.
Expand Down
3 changes: 2 additions & 1 deletion doc/lib/js/json.md
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,8 @@ for await (const value of consumer) {
```

A value is stamped when written, unless you pass its capture time:
`producer.update(value, at)`.
`producer.update(value, at)`. Every frame carries a timestamp, so the track must
declare a timescale, such as `createTrack(name, { timescale: Time.Timescale.MILLI })`.

A Stream rides one group, so the whole log shares `@moq/net`'s group budget:
32 MiB of payload and 8192 records. An `append` that might not fit throws
Expand Down
3 changes: 2 additions & 1 deletion doc/lib/js/net.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@ const connection = await Moq.Connection.connect({
});

const broadcast = origin.createBroadcast(Moq.Path.from("chat.room"));
const track = broadcast.createTrack("messages");
const track = broadcast.createTrack("messages", { timescale: Moq.Time.Timescale.MILLI });
const group = track.appendGroup();
group.writeString("hello"); // or writeFrame({ payload, timestamp })
group.close();
Expand All @@ -53,6 +53,7 @@ for (;;) {
- **Bandwidth** (`Bandwidth.Allocator`) divides the connection's send-rate estimate by track priority, max-min fair within a tier. An idle track claims nothing. The receive side is untouched.
- **Discovery** by any pattern scope (`origin.announced(scope)`, such as `room/*/chat`; default everything). A route event's `kind` says whether the route started, updated, or ended; its `prefix` is the covered prefix relative to the origin, and `captures` reports what the scope's wildcards matched when the prefix pins them. The consumer is an async iterable. `origin.broadcasts(scope)` is a live `Getter<ReadonlyMap<Path.Valid, Route>>` of the same covered prefixes for UIs that need the current set. A borrowed `Connection.origin` also exposes `dynamic(prefix, route)` for serving paths on demand.
- **Publisher retention** is optional `Track.Info.maxAge`, measured against media timestamps: omission sets no limit, while zero serves only the live edge. It clamps every subscriber's max delay, and stalled media does not age out merely because wall time passes. Separately, cached groups nobody writes for 30 seconds are reclaimed, except a live track's newest group, which stays replayable until the track closes.
- **Timing** is per track. A timed track declares `Track.Info.timescale` (such as `Time.Timescale.MILLI`); omitting it (or passing `null`, which means the same) declares an untimed track. There is no default, unlike Rust's millisecond default. A frame or datagram carries a `timestamp` exactly when its track has a timescale, and a write that disagrees throws `Error.TimestampMismatch`. Nothing fills in a time on receive: moq-lite before 05, and moq-transport without TIMESCALE (always so on drafts 14-16), deliver untimed tracks. moq-lite 05 and 06 can't declare an untimed track, so it goes out at milliseconds with each frame's send time. An untimed group is never stale, so a subscription without a `groups.start` begins at the latest group.
- **Subscriptions** carry a priority, a `Time.Milli` max delay measured against media timestamps, and optional `groups` bounds. Subscription options use `maxDelay`; supplying the obsolete subscriber `maxAge` key throws a `TypeError` naming its replacement, including on `update()`. Groups arrive out of order and are read frame by frame, with `Error.TooFarBehind` when a reader asks for a frame the group never held and `Error.GroupTooLarge` when a write exceeds the cache budget and aborts the group.
- **Track ends**: `close()` ends a track at its live edge, while `finishAt(n)` declares the exclusive end ahead of it and still accepts the groups below. A finished track stays on its broadcast and serves its cache to late subscribers until `removeTrack`; an aborted one is removed, and subscribing to a track the broadcast does not have rejects with `Error.NotFound` when no on-demand handler is pulling requests, as in Rust. With a pulling handler, an absent track queues an on-demand request. A subscriber reads the end with `final()` or awaits `finished()`. Group and datagram readers end once the live edge reaches the declared boundary, even while missing lower groups wait out the grace. The `closed` signal settles separately once every group below the end has arrived or was dropped; one reset before its header arrived is skipped after the subscription's max delay on moq-lite (one second without one), or after one second on IETF.
- **Datagrams** on moq-lite 05+ and fetch-by-sequence for history. `track.fetchGroup(sequence)` on moq-lite resolves when the publisher sends the first response byte or finishes an empty group. A missing group rejects the fetch with `StreamCode.NotFound`, including every concurrent caller sharing that fetch. `fetchGroup(sequence, { signal })` abandons a pending fetch with the signal's reason; the shared stream is cancelled only once every caller has left. Once resolved, close the group instead.
Expand Down
9 changes: 7 additions & 2 deletions doc/lib/js/publish.md
Original file line number Diff line number Diff line change
Expand Up @@ -115,13 +115,18 @@ can serve its own tracks alongside the media. It is recreated on each

```ts
import * as Json from "@moq/json";
import * as Moq from "@moq/net";

signals.run((effect) => {
const net = effect.get(broadcast.net);
if (!net) return;

// A day-long retention so a late viewer still replays the last value.
const track = net.createTrack("meta.json", { maxAge: 86_400_000 });
// A day-long retention so a late viewer still replays the last value. JSON
// values are stamped when written, so the track declares a timescale.
const track = net.createTrack("meta.json", {
timescale: Moq.Time.Timescale.MILLI,
maxAge: Moq.Time.Milli(86_400_000),
});
effect.cleanup(() => track.close());

const meta = new Json.Snapshot.Producer<Meta>({ track });
Expand Down
2 changes: 1 addition & 1 deletion js/clock/src/main.ts
Original file line number Diff line number Diff line change
Expand Up @@ -84,7 +84,7 @@ async function publish(config: Config) {

console.log("✅ Published broadcast:", config.broadcast);

void publishTrack(broadcast.createTrack(config.track));
void publishTrack(broadcast.createTrack(config.track, { timescale: Moq.Time.Timescale.MILLI }));
await connection.closed;
}

Expand Down
2 changes: 1 addition & 1 deletion js/flate/src/snapshot/snapshot.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -147,5 +147,5 @@ test("a capture timestamp is written as the frame timestamp", async () => {
producer.finish();

const frame = await (await track.subscribe().ordered().nextGroup())?.readFrame();
expect(frame?.timestamp.as(Time.Timescale.MILLI)).toBe(1_234);
expect(frame?.timestamp?.as(Time.Timescale.MILLI)).toBe(1_234);
});
4 changes: 2 additions & 2 deletions js/flate/src/stream/stream.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -194,6 +194,6 @@ test("each record keeps its capture timestamp", async () => {
producer.finish();

const group = await track.subscribe().ordered().nextGroup();
expect((await group?.readFrame())?.timestamp.as(Time.Timescale.MILLI)).toBe(1_000);
expect((await group?.readFrame())?.timestamp.as(Time.Timescale.MILLI)).toBe(2_000);
expect((await group?.readFrame())?.timestamp?.as(Time.Timescale.MILLI)).toBe(1_000);
expect((await group?.readFrame())?.timestamp?.as(Time.Timescale.MILLI)).toBe(2_000);
});
8 changes: 4 additions & 4 deletions js/hang/src/catalog/consumer.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -57,7 +57,7 @@ test("the shared containment check covers every section carrying a broadcast ref

test("watch refuses an oversized catalog update", async () => {
const broadcast = new Moq.Broadcast.Producer();
const track = broadcast.createTrack(TRACK);
const track = broadcast.createTrack(TRACK, { timescale: Moq.Time.Timescale.MILLI });
const producer = new Json.Snapshot.Producer<Root>({ track, deltaRatio: 0 });
const consumer = watch(broadcast.consume())[Symbol.asyncIterator]();
producer.update(catalog(MAX_RENDITIONS + 1));
Expand All @@ -78,7 +78,7 @@ function referencing(broadcast: string): Root {
async function watchRequested(root: Root) {
const origin = new Moq.Origin.Producer();
const broadcast = origin.createBroadcast(Moq.Path.from("room/alice"));
const track = broadcast.createTrack(TRACK);
const track = broadcast.createTrack(TRACK, { timescale: Moq.Time.Timescale.MILLI });
const producer = new Json.Snapshot.Producer<Root>({ track, deltaRatio: 0 });
broadcast.announce();
const request = origin.request(Moq.Path.from("room/alice"));
Expand Down Expand Up @@ -107,7 +107,7 @@ test("watch accepts a sibling reference under the same root and yields it unreso

test("watch on a standalone broadcast refuses any parent reference", async () => {
const broadcast = new Moq.Broadcast.Producer();
const track = broadcast.createTrack(TRACK);
const track = broadcast.createTrack(TRACK, { timescale: Moq.Time.Timescale.MILLI });
const producer = new Json.Snapshot.Producer<Root>({ track, deltaRatio: 0 });
const consumer = watch(broadcast.consume())[Symbol.asyncIterator]();
producer.update(referencing("../bob"));
Expand All @@ -118,7 +118,7 @@ test("watch on a standalone broadcast refuses any parent reference", async () =>

test("watch subscribes and yields typed catalog updates", async () => {
const broadcast = new Moq.Broadcast.Producer();
const track = broadcast.createTrack(TRACK);
const track = broadcast.createTrack(TRACK, { timescale: Moq.Time.Timescale.MILLI });
const producer = new Json.Snapshot.Producer<Root>({ track, deltaRatio: 0 });
const consumer = watch(broadcast.consume())[Symbol.asyncIterator]();
producer.update(catalog(1));
Expand Down
6 changes: 3 additions & 3 deletions js/hang/src/container/consumer.outoforder.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -47,7 +47,7 @@ async function drain(consumer: Consumer): Promise<[number, number | undefined][]
// audio writes into a timestamp-indexed ring and video drops a late frame at render, and the
// subscription's own max delay already bounds how far back one can be.
test("out-of-order groups are delivered rather than dropped", async () => {
const track = new Track.Producer("test").accept({ maxAge: Time.Milli(30_000) });
const track = new Track.Producer("test").accept({ timescale: Time.Timescale.MILLI, maxAge: Time.Milli(30_000) });
const consumer = new Consumer(track.subscribe({ maxDelay: Time.Milli(5000) }), {
format: new LegacyFormat("data"),
maxDelay: 5000 as Time.Milli,
Expand Down Expand Up @@ -77,7 +77,7 @@ test("out-of-order groups are delivered rather than dropped", async () => {
// drained (the decode loop consumes faster than the network delivers). Removing it at that
// instant silently truncates its tail, so removal must wait for the group to finish.
test("a below-cursor group still downloading is not truncated", async () => {
const track = new Track.Producer("test").accept({ maxAge: Time.Milli(30_000) });
const track = new Track.Producer("test").accept({ timescale: Time.Timescale.MILLI, maxAge: Time.Milli(30_000) });
const consumer = new Consumer(track.subscribe({ maxDelay: Time.Milli(5000) }), {
format: new LegacyFormat("data"),
maxDelay: 5000 as Time.Milli,
Expand Down Expand Up @@ -115,7 +115,7 @@ test("a below-cursor group still downloading is not truncated", async () => {
// The floor belongs to the latest group, not to delayed history within max delay.
test("delayed older groups survive a floor established by two newer groups", async () => {
const clock = spyOn(performance, "now").mockReturnValue(200);
const track = new Track.Producer("test").accept({ maxAge: Time.Milli(30_000) });
const track = new Track.Producer("test").accept({ timescale: Time.Timescale.MILLI, maxAge: Time.Milli(30_000) });
const consumer = new Consumer(track.subscribe({ maxDelay: Time.Milli(5000) }), {
format: new LegacyFormat("data"),
maxDelay: Time.Milli(5000),
Expand Down
8 changes: 4 additions & 4 deletions js/hang/src/timeline.test.ts
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
import { expect, test } from "bun:test";
import * as Json from "@moq/json";
import { Broadcast, type Time } from "@moq/net";
import { Broadcast, Time } from "@moq/net";
import { u53 } from "./catalog";
import { Consumer, type Record } from "./timeline.ts";

Expand All @@ -10,7 +10,7 @@ const archive = (timescale: number) => ({ timelines: { video: "video.timeline.z"

test("timeline consumer yields converted push and pop events", async () => {
const broadcast = new Broadcast.Producer();
const track = broadcast.createTrack("video.timeline.z");
const track = broadcast.createTrack("video.timeline.z", { timescale: Time.Timescale.MILLI });
const producer = new Json.Window.Producer<Record>({ 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 } });
Expand All @@ -29,7 +29,7 @@ test("timeline consumer yields converted push and pop events", async () => {

test("timeline consumer floors fractional microseconds without floating point drift", async () => {
const broadcast = new Broadcast.Producer();
const track = broadcast.createTrack("video.timeline.z");
const track = broadcast.createTrack("video.timeline.z", { timescale: Time.Timescale.MILLI });
const producer = new Json.Window.Producer<Record>({ 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 } });
Expand All @@ -52,7 +52,7 @@ test("timeline consumer floors fractional microseconds without floating point dr

test("a record numbered unlike its window index is refused", async () => {
const broadcast = new Broadcast.Producer();
const track = broadcast.createTrack("video.timeline.z");
const track = broadcast.createTrack("video.timeline.z", { timescale: Time.Timescale.MILLI });
const producer = new Json.Window.Producer<Record>({ 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 } });
Expand Down
4 changes: 2 additions & 2 deletions js/json/src/snapshot/snapshot.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -417,6 +417,6 @@ test("a capture timestamp is written on snapshots and deltas alike", async () =>
producer.finish();

const group = await track.subscribe().ordered().nextGroup();
expect((await group?.readFrame())?.timestamp.as(Time.Timescale.MILLI)).toBe(1_000);
expect((await group?.readFrame())?.timestamp.as(Time.Timescale.MILLI)).toBe(2_000);
expect((await group?.readFrame())?.timestamp?.as(Time.Timescale.MILLI)).toBe(1_000);
expect((await group?.readFrame())?.timestamp?.as(Time.Timescale.MILLI)).toBe(2_000);
});
4 changes: 2 additions & 2 deletions js/json/src/stream/stream.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -158,8 +158,8 @@ test("each record keeps its capture timestamp", async () => {
producer.finish();

const group = await track.subscribe().ordered().nextGroup();
expect((await group?.readFrame())?.timestamp.as(Time.Timescale.MILLI)).toBe(1_000);
expect((await group?.readFrame())?.timestamp.as(Time.Timescale.MILLI)).toBe(2_000);
expect((await group?.readFrame())?.timestamp?.as(Time.Timescale.MILLI)).toBe(1_000);
expect((await group?.readFrame())?.timestamp?.as(Time.Timescale.MILLI)).toBe(2_000);
});

// A record past the group budget is refused before anything is written, so the log carries on: the
Expand Down
2 changes: 1 addition & 1 deletion js/moq-boy/src/game.ts
Original file line number Diff line number Diff line change
Expand Up @@ -308,7 +308,7 @@ export class Game {
this.viewerId.set(undefined);
});

const track = viewerBroadcast.createTrack("command");
const track = viewerBroadcast.createTrack("command", { timescale: Moq.Time.Timescale.MILLI });
const producer = new Json.Snapshot.Producer<Record<string, unknown>>({ track });
effect.cleanup(() => producer.finish());
effect.run(this.#runCommandTrack.bind(this, track, producer));
Expand Down
4 changes: 2 additions & 2 deletions js/net/bench/track.ts
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
/** Sweep retained groups and subscribers for one group published through a track and received. */
import { type Consumer as GroupConsumer, Producer as GroupProducer } from "../src/group.ts";
import { Milli, Timestamp } from "../src/time.ts";
import { Milli, Timescale, Timestamp } from "../src/time.ts";
import { Producer, type Subscriber } from "../src/track.ts";

const retainedCounts = [25, 100, 400, 1500];
Expand Down Expand Up @@ -47,7 +47,7 @@ async function measure(
): Promise<{ publish: number; end: number; idle: number }> {
// Held rows stay within the idle window while the media budget keeps their frames usable.
const window = Milli(held > 0 ? 3_600_000 : retained);
const producer = new Producer("bench").accept({ maxAge: window });
const producer = new Producer("bench").accept({ timescale: Timescale.MILLI, maxAge: window });
const subscribers = Array.from({ length: subscriberCount }, () => producer.subscribe({ maxDelay: window }));
let sequence = 0;
// Inserted by sequence, the way the wire hands a subscribed track its groups.
Expand Down
3 changes: 2 additions & 1 deletion js/net/examples/publish.ts
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,8 @@ async function main() {

// Insert the "chat" track up front. A subscriber is served directly from this
// track, no requested() round-trip needed. Mirrors the Rust createTrack/insertTrack.
void publishTrack(broadcast.createTrack("chat"));
// writeString stamps each frame with the current time, so the track declares a timescale.
void publishTrack(broadcast.createTrack("chat", { timescale: Moq.Time.Timescale.MILLI }));
console.log("Published broadcast: my-broadcast");

await connection.closed;
Expand Down
Loading
Loading