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
6 changes: 3 additions & 3 deletions demo/web/src/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -436,9 +436,9 @@ ui.run((effect) => {
effect.spawn(async () => {
try {
for (;;) {
const value = await effect.race(consumer.next());
if (value === undefined) break;
metaSignal.set(value);
const state = await effect.race(consumer.latest());
if (state === undefined) break;
metaSignal.set(state.value);
}
} catch (err) {
console.warn("error reading metadata", err);
Expand Down
10 changes: 6 additions & 4 deletions doc/lib/js/flate.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ description: Opaque MoQ tracks, optionally compressed with group-scoped DEFLATE

Opaque payloads over [`@moq/net`](/lib/js/net) tracks, in two modes:

- **Snapshot**: lossy latest-value, one payload per group.
- **Snapshot**: lossy latest-value, one payload per group. `next()` yields every value in order; `latest()` skips to the newest.
- **Stream**: lossless append-log in a single group.

The bytes are never inspected. Compression is opt-in: `"none"` (the default)
Expand All @@ -26,9 +26,11 @@ producer.update({ value: payload, at: Time.Timestamp.now() });
```

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.
time written as the frame timestamp, and consumers return the same shape.
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 and reads back without
one.

A Stream rides one group, so the whole log shares `@moq/net`'s group budget:
32 MiB of payload and 8192 payloads. An `append` that might not fit throws
Expand Down
23 changes: 20 additions & 3 deletions doc/lib/js/json.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,14 +12,31 @@ are the catalog modes on the [hang](/concept/hang#data-tracks) page. Window is
a third framing for a raw track: both ends opt into it, and a generic catalog
reader will not pick it up.

- **Snapshot**: lossy latest value, with RFC 7396 merge-patch deltas. A delta before any snapshot is an error.
- **Snapshot**: lossy latest value, with RFC 7396 merge-patch deltas. A delta before any snapshot is an error. `next()` yields every state in order; `latest()` skips to the newest.
- **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"`. 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.
the frame timestamp, and the snapshot and stream consumers return the same
shape. Nothing fills in now: a timed track needs `at` on every write, and
an untimed track (no `timescale`) takes none and reads back without one.

```ts
import { Snapshot } from "@moq/json";

// Hold each state back until the video playhead reaches it.
const consumer = new Snapshot.Consumer<Telemetry>({ track });
for await (const { value, at } of consumer) {
schedule(value, at);
}
```

`next()` buffers every state it has not yielded. On a timed track it skips a
group once the subscription's `maxDelay` proves it stale, and the default of
zero keeps only the newest group, so subscribe with a `maxDelay` covering how
far the playhead trails the live edge. An untimed track skips nothing; a reader
that cannot keep up calls `latest()` instead.

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
Expand Down
6 changes: 3 additions & 3 deletions doc/lib/js/watch.md
Original file line number Diff line number Diff line change
Expand Up @@ -103,9 +103,9 @@ const dispose = el.signals.run((effect) => {
const consumer = new Json.Snapshot.Consumer<unknown>({ track });
effect.spawn(async () => {
for (;;) {
const value = await effect.race(consumer.next());
if (value === undefined) break;
console.log("metadata", value);
const state = await effect.race(consumer.latest());
if (state === undefined) break;
console.log("metadata", state.value);
}
});
});
Expand Down
11 changes: 11 additions & 0 deletions doc/setup/upgrade.md
Original file line number Diff line number Diff line change
Expand Up @@ -299,6 +299,17 @@ These land with the next breaking release, not the 2026-09-23 train.
`TrackStream` accept a CMAF rendition's track at that timescale; a track you
create yourself declares it with `track::Info::with_timescale`. Both decoders refuse a `trun` whose
`data_offset` doesn't start at the next sample in the `mdat`.
- **@moq/json and @moq/flate consumers return `Timed` values.** The snapshot
and stream consumers' `next()` and async iterator yield `{ value, at }`,
where `at` is the frame's timestamp and absent on an untimed track; read
`.value` for what they used to return. A snapshot consumer's `next()` now
yields every state in order. Call `latest()` for the old behavior, which
skips to the newest state. A caller that passes the result on as `any` or
`unknown` (logging, `JSON.stringify`, a generic setter) still compiles but
now gets the wrapper and every intermediate state, so search for each
`next()` and `for await` over a snapshot consumer rather than relying on
type errors. On an untimed track nothing marks a group stale, so a `next()`
reader that falls behind replays the whole backlog where it used to skip it.

## Wire

Expand Down
9 changes: 4 additions & 5 deletions js/flate/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@

Opaque byte tracks over MoQ, optionally compressed with group-scoped DEFLATE, in two modes:

- `Snapshot`: **lossy**. One value updated over time; a consumer only gets the most recent one.
- `Snapshot`: **lossy**. One value updated over time; a consumer reads every value it receives (`next()`) or skips to the most recent (`latest()`).
- `Stream`: **lossless**. An ordered append-log of self-contained payloads, nothing superseded.

The bytes are opaque: the tracks frame them onto a [`@moq/net`](../net) track and optionally compress them, and never look inside. For JSON documents reach for [`@moq/json`](../json) instead, which adds RFC 7396 merge-patch deltas on top of the same two modes and codec. Interoperable with the Rust [`moq-flate`](https://crates.io/crates/moq-flate) crate.
Expand All @@ -22,15 +22,14 @@ const thumbnail = new Snapshot.Producer({ track, compression: "deflate" });
thumbnail.update({ value: jpeg, at: Time.Timestamp.now() });

const log = new Stream.Consumer({ track: subscriber, compression: "deflate" });
for (;;) {
const payload = await log.next();
if (payload === undefined) break;
for await (const { value, at } of log) {
console.log(value.byteLength, at);
}
```

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.
Producers take `{ value, at }`, where `at` is the capture time written as the frame timestamp, and consumers return the same shape. Nothing fills in now: a timed track needs `at` on every write, and an untimed track takes none and reads back without one.

## Codec

Expand Down
4 changes: 2 additions & 2 deletions js/flate/src/index.ts
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
/**
* Opaque byte tracks over MoQ, optionally compressed with group-scoped DEFLATE, in two modes:
*
* - {@link Snapshot}: **lossy**. One value updated over time; a consumer only gets the most recent
* one. Older values are superseded and dropped.
* - {@link Snapshot}: **lossy**. One value updated over time; a newer value supersedes the older
* ones, and a consumer can read every value it receives or skip to the most recent.
* - {@link Stream}: **lossless**. An ordered append-log of self-contained payloads, delivered in
* order with nothing superseded. Bounded by the group budget: see {@link Stream} for what happens
* once it is spent.
Expand Down
49 changes: 34 additions & 15 deletions js/flate/src/snapshot/consumer.ts
Original file line number Diff line number Diff line change
@@ -1,15 +1,17 @@
import type { Timed } from "@moq/net";
import * as Moq from "@moq/net";
import { Decoder as Flate } from "../codec.ts";

import { isDeflate } from "../compression.ts";
import type { Config as CodecConfig } from "./producer.ts";

/**
* Consumes an opaque value from a track, yielding the newest one.
* Consumes an opaque value from a track, yielding each with the timestamp of its frame.
*
* Jumps to the newest group and reads the value out of it, so a late joiner starts at the current
* value rather than replaying superseded ones. Interoperable with the Rust
* `moq_flate::snapshot::Consumer`, which collapses the same backlog.
* Two reads: {@link next} yields every value in group order, for a caller that picks the value
* matching a playhead, and {@link latest} jumps to the newest group, for a caller that only wants
* the current value. What {@link latest} skips is gone, so a later {@link next} resumes after
* it. Interoperable with the Rust `moq_flate::snapshot::Consumer`.
*/
export class Consumer {
#track: Moq.Track.Ordered;
Expand All @@ -27,20 +29,37 @@ export class Consumer {
}

/**
* Get the next value, or `undefined` once the track ends.
* Get the next value in group order, or `undefined` once the track ends.
*
* Buffers every value the reader has not reached yet. On a timed track, a group the
* subscription's `maxDelay` proves too old is skipped: the default of zero keeps only the
* newest group, so a playhead reader sets `maxDelay` to how far it trails the live edge. An
* untimed track never proves a group stale, so a reader that falls behind replays the whole
* backlog; use {@link latest} to skip it. A group lost to a gap resyncs from the next one.
*/
next(): Promise<Timed<Uint8Array> | undefined> {
return this.#read(false);
}

/**
* Get the newest value, or `undefined` once the track ends.
*
* Every group is a complete value, so any older group is already superseded. Raising the read
* floor to the newest sequence before each read does two things: it discards a backlog instead
* of decoding every superseded value in turn, and it abandons a group a newer one has
* superseded rather than waiting out its close. A snapshot reader's latency therefore never
* grows with the queue, and never depends on a stale group's FIN arriving.
*
* This consumer owns its subscriber's read cursor, which is what lets it discard the backlog.
* superseded rather than waiting out its close. A reader's latency therefore never grows with
* the queue, and never depends on a stale group's FIN arriving.
*/
async next(): Promise<Uint8Array | undefined> {
latest(): Promise<Timed<Uint8Array> | undefined> {
return this.#read(true);
}

async #read(skip: boolean): Promise<Timed<Uint8Array> | undefined> {
for (;;) {
const latest = this.#track.latest();
if (latest !== undefined) this.#track.setGroups({ start: { included: latest } });
if (skip) {
const latest = this.#track.latest();
if (latest !== undefined) this.#track.setGroups({ start: { included: latest } });
}

let next: Awaited<ReturnType<Moq.Track.Ordered["readFrame"]>>;
try {
Expand All @@ -63,12 +82,12 @@ export class Consumer {
this.#flate = this.#decompress ? new Flate() : undefined;
}

return this.#flate ? this.#flate.frame(next.payload) : next.payload;
return { value: this.#flate ? this.#flate.frame(next.payload) : next.payload, at: next.timestamp };
}
}

/** Iterate over values until the track ends, each the newest at the time it is yielded. */
async *[Symbol.asyncIterator](): AsyncIterator<Uint8Array> {
/** Iterate over every value in group order, as {@link next} yields them, until the track ends. */
async *[Symbol.asyncIterator](): AsyncIterator<Timed<Uint8Array>> {
for (;;) {
const value = await this.next();
if (value === undefined) return;
Expand Down
11 changes: 6 additions & 5 deletions js/flate/src/snapshot/index.ts
Original file line number Diff line number Diff line change
@@ -1,11 +1,12 @@
/**
* Lossy latest-value opaque publishing over MoQ tracks.
*
* One opaque value updated over time, for consumers that only care about the current state (a
* poster image, a serialized state blob). This mode is **lossy** by design: a consumer yields only
* the most recent value. A late joiner (or a consumer that falls behind) jumps straight to the
* newest group, and older groups are dropped entirely. For an ordered log where every payload is
* preserved, use the `Stream` module instead.
* One opaque value updated over time, for consumers that care about the state rather than every
* payload (a poster image, a serialized state blob). This mode is **lossy** by design: a new group
* supersedes the older ones, which are dropped. {@link Consumer.next} yields every value it still
* receives, in group order, each with its frame's timestamp, and {@link Consumer.latest} jumps
* straight to the newest group. For an ordered log where every payload is preserved, use the
* `Stream` module instead.
*
* On the wire each value is one group holding one frame, so a group is self-contained and a
* consumer never needs an older one. With {@link Config.compression} `"deflate"`, that frame is its
Expand Down
86 changes: 67 additions & 19 deletions js/flate/src/snapshot/snapshot.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -8,15 +8,19 @@ const bytes = (...values: number[]) => new Uint8Array(values);
// instead of the transport's live-edge default, which skips every superseded group.
const REPLAY_LATENCY = Time.Milli(30_000);

// Drain every value currently available from a fresh consumer over the (finished) track.
// Drain every value `next()` yields from a fresh consumer over the (finished) track.
async function drain(track: Track.Subscriber, compression: boolean): Promise<Uint8Array[]> {
const consumer = new Consumer({ track, compression: compression ? "deflate" : "none" });
const out: Uint8Array[] = [];
for (;;) {
const value = await consumer.next();
if (value === undefined) break;
out.push(value);
}
for await (const { value } of consumer) out.push(value);
return out;
}

// Drain every value `latest()` yields from a fresh consumer over the (finished) track.
async function drainLatest(track: Track.Subscriber): Promise<Uint8Array[]> {
const consumer = new Consumer({ track });
const out: Uint8Array[] = [];
for (let next = await consumer.latest(); next; next = await consumer.latest()) out.push(next.value);
return out;
}

Expand All @@ -27,9 +31,10 @@ test("one single-frame group per update", async () => {
producer.update({ value: bytes(2) });
producer.finish();

// Two updates => two self-contained groups, so a consumer never needs an older one: a reader
// that arrives after both discards the superseded first group instead of replaying it.
expect(await drain(track.subscribe(), false)).toEqual([bytes(2)]);
// Two updates => two self-contained groups, so a consumer never needs an older one: `next()` reads
// both in order, while `latest()` discards the superseded first group instead of replaying it.
expect(await drain(track.subscribe({ maxDelay: REPLAY_LATENCY }), false)).toEqual([bytes(1), bytes(2)]);
expect(await drainLatest(track.subscribe({ maxDelay: REPLAY_LATENCY }))).toEqual([bytes(2)]);

const subscriber = track.subscribe({ maxDelay: REPLAY_LATENCY }).ordered();
const counts: number[] = [];
Expand All @@ -50,7 +55,7 @@ test("a live consumer sees each update", async () => {

for (let n = 0; n < 3; n++) {
producer.update({ value: bytes(n) });
expect(await consumer.next()).toEqual(bytes(n));
expect((await consumer.next())?.value).toEqual(bytes(n));
}
producer.finish();
});
Expand Down Expand Up @@ -86,41 +91,54 @@ test("a finished track ends the consumer", async () => {
producer.finish();

const consumer = new Consumer({ track: track.subscribe() });
expect(await consumer.next()).toEqual(bytes(7));
expect((await consumer.next())?.value).toEqual(bytes(7));
expect(await consumer.next()).toBeUndefined();
});

test("a backlog collapses to the newest value", async () => {
// A consumer that fell behind (or joined late) must not replay every superseded value: its
// latency would grow with the backlog, and each older group is already superseded by design.
test("latest collapses a backlog to the newest value", async () => {
// A reader that fell behind (or joined late) and only wants the current value must not replay
// every superseded one: its latency would grow with the backlog.
const track = new Track.Producer("test");
const producer = new Producer({ track });
const consumer = new Consumer({ track: track.subscribe() });

for (let n = 0; n < 10; n++) producer.update({ value: bytes(n) });
producer.finish();

expect(await consumer.next()).toEqual(bytes(9));
expect((await consumer.latest())?.value).toEqual(bytes(9));
expect(await consumer.latest()).toBeUndefined();
});

test("next reads a backlog in group order", async () => {
// A reader syncing to a playhead needs every value it can still get, not just the head.
const track = new Track.Producer("test");
const producer = new Producer({ track });
const consumer = new Consumer({ track: track.subscribe({ maxDelay: REPLAY_LATENCY }) });

for (let n = 0; n < 10; n++) producer.update({ value: bytes(n) });
producer.finish();

for (let n = 0; n < 10; n++) expect((await consumer.next())?.value).toEqual(bytes(n));
expect(await consumer.next()).toBeUndefined();
});

test("a newer group preempts an open one", async () => {
test("latest lets a newer group preempt an open one", async () => {
// A group whose close is delayed must not park the reader while a newer value is available.
// Snapshot mode exists to deliver the current value, not to wait out a stale group's FIN, and
// `latest()` exists to deliver the current value, not to wait out a stale group's FIN, and
// groups ride independent QUIC streams so a newer one can land first.
const track = new Track.Producer("test");
const consumer = new Consumer({ track: track.subscribe() });

const stale = track.appendGroup();
stale.writeFrame({ payload: bytes(1), timestamp: Time.Timestamp.now() });
expect(await consumer.next()).toEqual(bytes(1));
expect((await consumer.latest())?.value).toEqual(bytes(1));

// A complete newer value arrives while the previous group is still open.
const fresh = track.appendGroup();
fresh.writeFrame({ payload: bytes(2), timestamp: Time.Timestamp.now() });
fresh.close();

expect(await consumer.next()).toEqual(bytes(2));
expect((await consumer.latest())?.value).toEqual(bytes(2));

stale.close();
track.close();
Expand Down Expand Up @@ -159,3 +177,33 @@ test("a capture timestamp is written as the frame timestamp", async () => {
const frame = await (await track.subscribe().ordered().nextGroup())?.readFrame();
expect(frame?.timestamp?.as(Time.Timescale.MILLI)).toBe(1_234);
});

test("an untimed value reads back untimed", async () => {
const track = new Track.Producer("test").accept({});
const producer = new Producer({ track });
producer.update({ value: bytes(1) });
producer.finish();

expect(await new Consumer({ track: track.subscribe() }).next()).toEqual({ value: bytes(1), at: undefined });
});

test("each value reads back with its frame's timestamp", async () => {
const track = new Track.Producer("test").accept({ timescale: Time.Timescale.MILLI });
const producer = new Producer({ track, compression: "deflate" });
for (let n = 1; n <= 3; n++) producer.update({ value: bytes(n), at: Time.Timestamp.fromMillis(n * 1_000) });
producer.finish();

const subscription = { maxDelay: REPLAY_LATENCY };
const consumer = new Consumer({ track: track.subscribe(subscription), compression: "deflate" });
const values: [number, number | undefined][] = [];
for await (const { value, at } of consumer) values.push([value[0], at?.as(Time.Timescale.MILLI)]);
expect(values).toEqual([
[1, 1_000],
[2, 2_000],
[3, 3_000],
]);

const head = await new Consumer({ track: track.subscribe(subscription), compression: "deflate" }).latest();
expect(head?.value).toEqual(bytes(3));
expect(head?.at?.as(Time.Timescale.MILLI)).toBe(3_000);
});
Loading
Loading