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
3 changes: 2 additions & 1 deletion doc/lib/js/net.md
Original file line number Diff line number Diff line change
Expand Up @@ -50,7 +50,8 @@ publication.announce();
- **List a broadcast's tracks.** `for await (const event of broadcast.tracks())` reports each track the broadcast lists (`added`, with its `Track.Info`), one `synced`, then `added` and `removed` as tracks come and go, until the broadcast ends; leaving the loop stops listing. Over a session it needs `moq-lite-07-wip`, syncs at once with what this side holds, and the peer's tracks follow as `added`. A track served only on request is never listed. See [discovery](/concept/moq-lite#discovery).
- **One track per name.** Concurrent subscriptions share one request and producer. `createTrack` on a name with a request still queued answers it. The application owns sequence numbers: the broadcast keeps nothing of an ended track, so a track that replaces it, created or requested, starts at 0. A name always means the same content, so the replacement continues past its predecessor's groups by writing its first group with an explicit sequence.
- **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. Omitting it means untimed, as in Rust. Nothing stamps a frame for you: the publisher passes the timestamp, and the `Timed` type (`{ value, at }`) carries one into the `@moq/json` producers.
- **A subscription's `delay` is a `Track.Delay { min, max }`, as in Rust.** Staleness is `delay.max`: it counts from a group's successor, by media time and by wall clock, whichever reaches it first. `delay.min` is the target latency, carried on moq-lite 07; a peer that cannot carry it leaves it `null` (not stated). Passing the old `maxAge` or `maxDelay` key throws a `TypeError` naming `delay.max`. Publisher retention is the separate `Track.Info.maxAge`.
- **A subscription's `delay` is a `Track.Delay { min, max }`, as in Rust.** Staleness is `delay.max`: it counts from a group's successor, by media time and by wall clock, whichever reaches it first. `delay.min` is the target latency, carried on moq-lite 07; a peer that cannot carry it leaves it `null` (not stated). Passing the old `maxAge` or `maxDelay` key throws a `TypeError` naming `delay.max`. The publisher's own staleness bound is the separate `Track.Info.maxAge`, which caps `delay.max` and fetches.
- **The cache keeps an idle group for 30 seconds.** A track evicts a group nothing has written for 30 seconds, matching the Rust cache's default expiry; a live track's newest group is exempt until a newer one arrives, unless it failed. Neither `Track.Info.maxAge` nor `delay.max` changes that window: they only decide which cached groups a reader still receives.
- **Subscription defaults.** `Track.Subscription.default()` returns the default subscription, whose zero `delay.max` skips a superseded group at once; calling `subscribe()` with no options means the same. An omitted `delay` field means the same zero; `max: null` sets no subscriber limit.
- **A subscription asks for `ranges`.** Each [range](/concept/moq-lite#subscriptions) starts and ends at an `absolute` group, one `relative` to the latest, or the group containing a `time` (a `Timestamp`), and a reader reads only its own ranges. A read whose ranges all end finishes once every group in them is handed out, dropped, or skipped, as in Rust. A time anchor needs a timed track and `moq-lite-07-wip` over a session. Passing the old `groups` key throws a `TypeError` naming `ranges`; `withRange` only narrows reads locally.
- **Hidden paths** stay out of discovery unless the announce request opts in. See [hidden broadcasts](/concept/moq-lite#hidden-broadcasts).
Expand Down
21 changes: 10 additions & 11 deletions doc/lib/js/publish.md
Original file line number Diff line number Diff line change
Expand Up @@ -71,10 +71,12 @@ with a warning, since every viewer would refuse it.
## Encoding

Video encodes while enabled, so its recent groups wait in the track's cache for
a late subscription's `delay.max` or a fetch. Audio keeps raw PCM while nobody
listens, then encodes that history ahead of live audio when a subscriber arrives.
Both retain up to `maxAge`; raw audio without a declared retention keeps at most
30 seconds (about 11.5 MB for 48 kHz stereo f32). Capture stays open.
a late subscription's `delay.max` or a fetch. The cache keeps an idle group for
30 seconds whatever `maxAge` says; `maxAge` only bounds how far back a reader
may reach into it. Audio keeps raw PCM while nobody listens, then encodes that
history ahead of live audio when a subscriber arrives. Raw audio keeps up to
`maxAge`, or at most 30 seconds without one (about 11.5 MB for 48 kHz stereo
f32). Capture stays open.

Pass `onDemand: false` to `Publish.Broadcast` to encode audio continuously too.
`onDemand: true` also gates video, which then loses its unsubscribed past.
Expand Down Expand Up @@ -115,20 +117,17 @@ the same content, so a track re-created on the same `net` throws on an append
that would reuse its sequences:

```ts
import { Milli } from "@moq/clock";
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. 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: Milli(86_400_000),
});
// A live track always serves and keeps its newest group, 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 });
effect.cleanup(() => {
track.finish();
track.close();
Expand Down
8 changes: 4 additions & 4 deletions js/net/MIGRATE.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,11 +25,11 @@ A loop that read a bounded range until a timeout now ends on its own; one that w
### Ordered subscriptions wait for owed groups

An ordered reader on a subscribed track now waits at a missing group while the feed may still deliver it, up to `delay.max` by media time or wall clock. Local tracks still skip gaps, and the zero default waits for nothing.
With `delay: { max: null }`, there is no subscriber deadline. Use a finite budget for bounded waiting: a moq-transport SUBSCRIBE signals no gaps, so an unlimited wait can last until the track ends. Publisher retention still bounds the budget.
With `delay: { max: null }`, there is no subscriber deadline. Use a finite budget for bounded waiting: a moq-transport SUBSCRIBE signals no gaps, so an unlimited wait can last until the track ends. The publisher's `Track.Info.maxAge` still bounds the budget.

### `maxDelay: null` sets no subscriber limit ([#7403](https://github.com/moq-dev/moq/pull/7403))

A `Track.Subscription` whose `maxDelay` is `null` reaches back as far as the publisher's `Track.Info.maxAge` keeps, as `None` does in Rust. An omitted or `undefined` `maxDelay` is still zero.
A `Track.Subscription` whose `maxDelay` is `null` reaches back as far as the publisher's `Track.Info.maxAge` allows, as `None` does in Rust. An omitted or `undefined` `maxDelay` is still zero.

### Paths fit moq-transport's 4096-byte namespace ([#6927](https://github.com/moq-dev/moq/pull/6927))

Expand Down Expand Up @@ -247,10 +247,10 @@ A write whose timedness does not match its track throws `Error.TimestampMismatch

### Subscriber staleness is `maxDelay`

`Track.Subscription`'s `maxAge` is `maxDelay`; `maxAge` stays the publisher's retention on `Track.Info`.
`Track.Subscription`'s `maxAge` is `maxDelay`; `maxAge` stays the publisher's staleness bound on `Track.Info`.
A `maxAge` key in subscription options throws a `TypeError`, even when `undefined` or beside `maxDelay`.

### Publisher retention is optional (#4242)
### `Track.Info.maxAge` is optional (#4242)

`Track.Info.maxAge` is optional, absent meaning no publisher limit, and `DEFAULT_MAX_AGE_MS` is gone.
Pass an explicit value such as `Milli(30_000)` where you used the constant.
Expand Down
2 changes: 1 addition & 1 deletion js/net/src/broadcast.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -641,7 +641,7 @@ test("a fetch waits for a group still to come", async () => {
broadcast.close();
});

test("fetch maxDelay tightens publisher retention without changing omission", async () => {
test("fetch maxDelay tightens the publisher's maxAge without changing omission", async () => {
const broadcast = new BroadcastProducer();
const track = broadcast.createTrack("video", { timescale: Timescale.MILLI, maxAge: Milli(2000) });

Expand Down
4 changes: 2 additions & 2 deletions js/net/src/lite/publisher.ts
Original file line number Diff line number Diff line change
Expand Up @@ -129,8 +129,8 @@ function trackInfoMessage(info: track.Info, version: Version): TrackInfoMessage
return new TrackInfoMessage({
priority: info.priority,
refresh: info.refresh,
// Publisher Max Age: the publisher's retention bound, advertised so relays re-serve
// with the same window.
// Publisher Max Age: the publisher's staleness bound, advertised so relays re-serve
// with the same bound.
maxAge: info.maxAge,
// `#serveGroup` emits each frame converted to it.
timescale: info.timescale ?? undefined,
Expand Down
17 changes: 9 additions & 8 deletions js/net/src/track.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -741,7 +741,7 @@ test("subscriber maxAge and maxDelay are refused before defaults or updates take
expect(producer.subscription.peek()).toEqual(original);
}

// Publisher retention keeps its distinct maxAge field.
// The publisher's own staleness bound keeps its distinct maxAge field.
producer.accept({ maxAge: Milli(500) });
track.close();
producer.finish();
Expand Down Expand Up @@ -1537,7 +1537,7 @@ test("the ordered cursor sheds a stale backlog", async () => {
}
});

test("the budget is clamped to the publisher's window", async () => {
test("the budget is clamped to the publisher's maxAge", async () => {
const producer = new TrackProducer("test").accept({ timescale: Timescale.MILLI, maxAge: Milli(1500) });
const track = producer.subscribe({ delay: { max: Milli(60_000) } });

Expand All @@ -1547,8 +1547,8 @@ test("the budget is clamped to the publisher's window", async () => {
producer.writeFrame({ payload: enc.encode(`${timestamp}`), timestamp: Timestamp.fromMillis(timestamp) });
}

// Asking to tolerate a minute cannot reach back further than the publisher keeps a group
// live, the same clamp delivery applies.
// Asking to tolerate a minute cannot reach back past the publisher's maxAge, the same
// clamp delivery applies.
expect((await track.recvGroup())?.sequence).toBe(1);
});

Expand Down Expand Up @@ -1683,7 +1683,7 @@ test("a handed-out group still expires while its first frame is stalled", async
}
});

test("committing track info wakes a group newly outside the retention window", async () => {
test("committing track info wakes a group newly past the publisher's maxAge", async () => {
const producer = new TrackProducer("test");
const track = producer.subscribe({ delay: { max: Milli(10_000) } });
const source = producer.appendGroup();
Expand Down Expand Up @@ -1791,10 +1791,11 @@ test("a drained group finishes cleanly after the live edge advances", async () =
expect(group.done).toBe(true);
});

// A stalled track keeps its newest group and gives up the ones before it by the wall clock:
// A stalled track serves its newest group and skips the ones before it by the wall clock:
// maxAge measures how long ago each group's successor arrived as well as media time, so a
// publisher that stops writing cannot pin its superseded groups.
test("a stalled track keeps only its newest group", () => {
// publisher that stops writing cannot keep its superseded groups deliverable. The cache still
// holds them, since two seconds is well inside its idle window: this is staleness, not eviction.
test("a stalled track serves only its newest group", () => {
const clock = manualTime(10_000);
const producer = new TrackProducer("test").accept({ timescale: Timescale.MILLI, maxAge: Milli(1000) });
try {
Expand Down
5 changes: 3 additions & 2 deletions js/watch/src/retention.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -80,8 +80,9 @@ test("waits on a stable clock leave nothing behind", async () => {
// the effect's teardown. Retention anywhere along it grows with the frame count.
test("a long subscription through the player path leaves nothing behind", async () => {
const broadcast = new Moq.Broadcast.Producer();
// A tiny publisher window, so the track's own replay cache stays flat too.
const track = broadcast.createTrack("audio", { timescale: Time.Timescale.MILLI, maxAge: Milli(1) });
// No maxAge: the track's cache keeps every group here for its fixed 30s idle window whatever
// the track declares, and holds no reactions or listeners while it does.
const track = broadcast.createTrack("audio", { timescale: Time.Timescale.MILLI });
const format = new Container.Legacy.Format("audio");
const producer = new Container.Legacy.Producer(track, format);

Expand Down
1 change: 0 additions & 1 deletion quest/m1/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -156,7 +156,6 @@ per-frame CPU growth since #5926.
- [A step back smaller than the delay keeps the TS export](/quest/m1/ts-small-step-back.md) - audio restarts instead of regressing; video stays within its declared depth
- [A replaced copy's grace wakes its reader](/quest/m1/grace-deadline.md) - the grace arms a deadline, so a clean end is on time
- [moq-boy's status loop stops on an errored track](/quest/m1/moq-boy-status-loop.md) - only schema errors are caught
- [JS tests and docs say what keeps a group cached](/quest/m1/js-cache-window.md) - none assume maxAge is retention
- [release carries the fanout-threads bench](/quest/m1/release-fanout-bench.md) - a bench-only port of session_fanout_threads for the pre-cut pairing
- [Finalize moq-lite-07](/quest/m1/lite07-finalize.md) - when the maintainer cuts it, lite-07 negotiates as `moq-lite-07` and the next release ships it
- [Sockets](/quest/m1/socket/README.md) - a generic dial/accept `Socket` in moq-net, Rust, JS, and Python, with tracks as streams; moq-boy and CARLA move onto it
Expand Down
15 changes: 0 additions & 15 deletions quest/m1/js-cache-window.md

This file was deleted.