diff --git a/doc/lib/js/net.md b/doc/lib/js/net.md index 307f5bffa71..bd1e8b794e8 100644 --- a/doc/lib/js/net.md +++ b/doc/lib/js/net.md @@ -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). diff --git a/doc/lib/js/publish.md b/doc/lib/js/publish.md index 8273fa2b15f..36d1c08c0e0 100644 --- a/doc/lib/js/publish.md +++ b/doc/lib/js/publish.md @@ -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. @@ -115,7 +117,6 @@ 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"; @@ -123,12 +124,10 @@ 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(); diff --git a/js/net/MIGRATE.md b/js/net/MIGRATE.md index 8346353ad3b..044095604b0 100644 --- a/js/net/MIGRATE.md +++ b/js/net/MIGRATE.md @@ -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)) @@ -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. diff --git a/js/net/src/broadcast.test.ts b/js/net/src/broadcast.test.ts index 4c471872ca3..e225b1d69c2 100644 --- a/js/net/src/broadcast.test.ts +++ b/js/net/src/broadcast.test.ts @@ -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) }); diff --git a/js/net/src/lite/publisher.ts b/js/net/src/lite/publisher.ts index bf59ef19506..e394915d87c 100644 --- a/js/net/src/lite/publisher.ts +++ b/js/net/src/lite/publisher.ts @@ -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, diff --git a/js/net/src/track.test.ts b/js/net/src/track.test.ts index 19a22c67693..22b234270cd 100644 --- a/js/net/src/track.test.ts +++ b/js/net/src/track.test.ts @@ -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(); @@ -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) } }); @@ -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); }); @@ -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(); @@ -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 { diff --git a/js/watch/src/retention.test.ts b/js/watch/src/retention.test.ts index a8416295456..bd09ac1a439 100644 --- a/js/watch/src/retention.test.ts +++ b/js/watch/src/retention.test.ts @@ -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); diff --git a/quest/m1/README.md b/quest/m1/README.md index d8a307f3e3e..d134d60cb85 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -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 diff --git a/quest/m1/js-cache-window.md b/quest/m1/js-cache-window.md deleted file mode 100644 index 2bd36170359..00000000000 --- a/quest/m1/js-cache-window.md +++ /dev/null @@ -1,15 +0,0 @@ -# [XS] JS tests and docs say what keeps a group cached - -## Goal - -No `@moq/net` test or doc assumes a track's `maxAge` controls how long the JS -cache keeps a group. That is the fixed 30 s `CACHE_WINDOW` in -`js/net/src/track.ts`. Each one either uses the window or says why it doesn't. - -## Plan - -Planned 2026-11-01 (maintainer, follow-up planning after the 2026-11-01 /quest-complete run). Found by [moq-dev/moq#7219](https://github.com/moq-dev/moq/pull/7219), whose -eviction test passed with eviction disabled because it assumed `maxAge`. - -- Search the JS tests and `doc/` for `maxAge` used as retention, and fix each. -- Check that each fixed test fails with eviction disabled.