diff --git a/c/moq/MIGRATE.md b/c/moq/MIGRATE.md index 48c82e836c2..668c82a42ce 100644 --- a/c/moq/MIGRATE.md +++ b/c/moq/MIGRATE.md @@ -16,6 +16,10 @@ Audio and video subscribe setup now reports `MOQ_ERROR_UNSUPPORTED_CONFIG` when The hand-written crate never published as moq-c: a libmoq 0.6 user applies these entries before moving to the generated API. +### Authored tracks default to a zero max age ([#7729](https://github.com/moq-dev/moq/pull/7729)) + +A NULL or zeroed `moq_track_info` now advertises a zero max age, serving only the live edge, instead of no publisher limit. `max_age_present` is gone and `max_age_us` always applies; set the new `max_age_unlimited`, which ignores `max_age_us`, where you relied on `max_age_present` false meaning no limit. Zero-initialize the struct (`moq_track_info info = {0};`) or assign every member. In the generated API, an unset `moq_track_info.max_age` is likewise zero, and `max_age_unlimited` sets no limit. + ### JSON writes refuse a NULL timestamp ([#7691](https://github.com/moq-dev/moq/pull/7691)) `moq_publish_json_snapshot_update`, `moq_publish_json_stream_append`, `moq_publish_json_window_push`, and `moq_publish_json_window_pop` fail with `MOQ_ERROR_INVALID_POINTER` on a NULL `timestamp` instead of stamping the broadcast clock. Stamp media and JSON from `moq_publish_catalog_now()`; in the generated API, JSON `update`, `append`, `push`, and `pop` take a required `moq_timestamp` from the media catalog producer's `now`, and the JSON producers refuse a track without a timescale. diff --git a/cpp/moq/MIGRATE.md b/cpp/moq/MIGRATE.md index 07314ea0fd7..edf827e0ebf 100644 --- a/cpp/moq/MIGRATE.md +++ b/cpp/moq/MIGRATE.md @@ -2,6 +2,10 @@ ## Unreleased +### Authored tracks default to a zero max age ([#7729](https://github.com/moq-dev/moq/pull/7729)) + +An unset `moq::TrackInfo::max_age`, and a `std::nullopt` info, now advertise a zero max age, serving only the live edge, instead of no publisher limit. Set the new `max_age_unlimited`, which ignores `max_age`, where you relied on `std::nullopt` meaning no limit. A received track's `info()` sets it when its publisher advertised no limit. + ### Viewer targets are bounded ([#7090](https://github.com/moq-dev/moq/pull/7090)) Viewer ceilings and PROBE target overrides are refused with the new `moq::Error::kOutOfRange` once they would sum above 2^53 - 1 bps, the most a PROBE target carries; nothing changes on a refusal. `Viewers::watch` and `set_target` and `Viewer::update` return a `moq::expected` carrying it. Handle the new variant wherever you match the error exhaustively. Regenerate bindings and rebuild the matching native library together. diff --git a/cpp/moq/test/probe.cpp b/cpp/moq/test/probe.cpp index 706a8984065..75866efd00f 100644 --- a/cpp/moq/test/probe.cpp +++ b/cpp/moq/test/probe.cpp @@ -167,7 +167,7 @@ void audio_roundtrip() CHECK(snapshot.has_value()); moq::AudioDecoderOutput decoded{}; decoded.format = moq::AudioSampleFormat::kF32; - // The track's whole retention: reading starts only after finish, and the budget ages + // The track's whole max age: reading starts only after finish, and the budget ages // groups by wall clock, so a stalled host would otherwise skip the start. decoded.delay = moq::Delay{std::chrono::seconds(0), std::chrono::seconds(30)}; auto consumer = ok(moq::AudioConsumer::subscribe(receiver, "tone", snapshot->audio.at("tone"), decoded).get(), diff --git a/dart/moq/MIGRATE.md b/dart/moq/MIGRATE.md index 3b8b4f43267..d3f8613f4e6 100644 --- a/dart/moq/MIGRATE.md +++ b/dart/moq/MIGRATE.md @@ -4,6 +4,10 @@ How to update your code for each breaking change, newest first. ## Unreleased +### Authored tracks default to a zero max age ([#7729](https://github.com/moq-dev/moq/pull/7729)) + +A null `TrackInfo.maxAge`, the default, and a null info now advertise a zero max age, serving only the live edge, instead of no publisher limit. Pass `maxAgeUnlimited: true`, which ignores `maxAge`, where you relied on null meaning no limit. A received track's `info()` sets it when its publisher advertised no limit. + ### Viewer targets are bounded ([#7090](https://github.com/moq-dev/moq/pull/7090)) Viewer ceilings and PROBE target overrides are refused with the new `OutOfRangeMoqException` once they would sum above 2^53 - 1 bps, the most a PROBE target carries; nothing changes on a refusal. `Viewers.watch` and `setTarget` and `Viewer.update` throw it. Handle the new variant wherever you match the error exhaustively. Regenerate bindings and rebuild the matching native library together. diff --git a/dart/moq/test/moq_test.dart b/dart/moq/test/moq_test.dart index 1124c71e377..e7c53d87877 100644 --- a/dart/moq/test/moq_test.dart +++ b/dart/moq/test/moq_test.dart @@ -67,6 +67,22 @@ void main() { broadcast.close(); }); + test('an omitted max age is zero and the unlimited flag sets none', () { + final broadcast = BroadcastProducer(); + final omitted = broadcast + .publishTrack(name: 'omitted', info: null) + .consume(subscription: null) + .info(); + expect(omitted.maxAge, Duration.zero); + final unlimited = broadcast + .publishTrack(name: 'unlimited', info: TrackInfo(maxAgeUnlimited: true)) + .consume(subscription: null) + .info(); + expect(unlimited.maxAge, isNull); + expect(unlimited.maxAgeUnlimited, isTrue); + broadcast.close(); + }); + test('a default subscription skips superseded groups at once', () { for (final subscription in [defaultSubscription(), Subscription()]) { expect(subscription.delay.min, Duration.zero); @@ -97,7 +113,7 @@ void main() { final broadcast = BroadcastProducer(); final track = broadcast.publishTrack( name: 'backlog', - info: TrackInfo(timescale: 1000000), + info: TrackInfo(maxAgeUnlimited: true, timescale: 1000000), ); for (var ms = 0; ms < 3; ms++) { final group = track.appendGroup(); diff --git a/dart/moq_ffi/lib/src/moq.dart b/dart/moq_ffi/lib/src/moq.dart index 27fe6eac5d0..4a6a4ecb94d 100644 --- a/dart/moq_ffi/lib/src/moq.dart +++ b/dart/moq_ffi/lib/src/moq.dart @@ -3145,12 +3145,14 @@ class FfiConverterMoqPosition { class MoqTrackInfo { final int priority; final Duration? maxAge; + final bool maxAgeUnlimited; final int? refresh; final int? timescale; final bool compress; MoqTrackInfo({ this.priority = 0, this.maxAge = null, + this.maxAgeUnlimited = false, this.refresh = null, this.timescale = null, this.compress = false, @@ -3174,6 +3176,11 @@ class FfiConverterMoqTrackInfo { ); final maxAge = maxAge_lifted.value; new_offset += maxAge_lifted.bytesRead; + final maxAgeUnlimited_lifted = FfiConverterBool.read( + Uint8List.view(buf.buffer, new_offset), + ); + final maxAgeUnlimited = maxAgeUnlimited_lifted.value; + new_offset += maxAgeUnlimited_lifted.bytesRead; final refresh_lifted = FfiConverterOptionalUInt32.read( Uint8List.view(buf.buffer, new_offset), ); @@ -3193,6 +3200,7 @@ class FfiConverterMoqTrackInfo { MoqTrackInfo( priority: priority, maxAge: maxAge, + maxAgeUnlimited: maxAgeUnlimited, refresh: refresh, timescale: timescale, compress: compress, @@ -3205,6 +3213,7 @@ class FfiConverterMoqTrackInfo { final total_length = FfiConverterInt8.allocationSize(value.priority) + FfiConverterOptionalDuration.allocationSize(value.maxAge) + + FfiConverterBool.allocationSize(value.maxAgeUnlimited) + FfiConverterOptionalUInt32.allocationSize(value.refresh) + FfiConverterOptionalUInt64.allocationSize(value.timescale) + FfiConverterBool.allocationSize(value.compress) + @@ -3224,6 +3233,10 @@ class FfiConverterMoqTrackInfo { value.maxAge, Uint8List.view(buf.buffer, new_offset), ); + new_offset += FfiConverterBool.write( + value.maxAgeUnlimited, + Uint8List.view(buf.buffer, new_offset), + ); new_offset += FfiConverterOptionalUInt32.write( value.refresh, Uint8List.view(buf.buffer, new_offset), @@ -3242,6 +3255,7 @@ class FfiConverterMoqTrackInfo { static int allocationSize(MoqTrackInfo value) { return FfiConverterInt8.allocationSize(value.priority) + FfiConverterOptionalDuration.allocationSize(value.maxAge) + + FfiConverterBool.allocationSize(value.maxAgeUnlimited) + FfiConverterOptionalUInt32.allocationSize(value.refresh) + FfiConverterOptionalUInt64.allocationSize(value.timescale) + FfiConverterBool.allocationSize(value.compress) + diff --git a/doc/bin/cli.md b/doc/bin/cli.md index 80f1dcf0b85..3f79d7f5666 100644 --- a/doc/bin/cli.md +++ b/doc/bin/cli.md @@ -504,8 +504,9 @@ See [Authentication](/bin/relay/auth). ## Retention and latency -`import --max-age` (default 30 s) tells relays how long to keep old groups -fetchable, which the [HLS gateway](/bin/hls) depends on. `export fmp4`, `export mp4`, +`import --max-age` (default 30 s) tells relays how long a superseded media group stays +fresh and fetchable, which the [HLS gateway](/bin/hls) depends on. `import archive` +refuses it: a replay advertises no max age, and the archive's retention bounds what it serves. `export fmp4`, `export mp4`, `export h264`, and `export h265` take `--max-delay` (default 500 ms): how far a stalled group may fall behind the live edge before *this* consumer skips it. Raising `--max-age` never delays playback. diff --git a/doc/bin/hls.md b/doc/bin/hls.md index bb9bf7e9e29..74441a1c44c 100644 --- a/doc/bin/hls.md +++ b/doc/bin/hls.md @@ -56,7 +56,7 @@ What that means for you: - **The publisher declares the interval.** Only a broadcast whose catalog carries `media.join.interval` gets playlists. Rust publishers built on `moq-mux` (the CLI, the RTMP, SRT, and WebRTC gateways, and the native bindings) declare it: an encoder that knows its GOP passes it as a hint, and an ingest without one measures each track over its first second or group, whichever is longer, then declares the longest. `@moq/publish` declares its keyframe interval. - **Every rendition shares the grid.** A group spans from its first frame's timestamp to the next group's and belongs to the first grid line it contains, or, containing none, the line it starts after. Segment N therefore starts at the group containing N times the segment length, every rendition numbers its segments alike, and each cuts its boundaries at its own keyframes. A grid line no group starts a segment at, because a GOP ran past it or the content paused, is listed as an `EXT-X-GAP` so the numbering never skips: on a 2 s grid, a GOP from 0 to 7 s is segment 0, segments 1 and 2 are gaps, and the next GOP starts segment 3. Timestamps that go back start a discontinuity on that rendition alone; `EXT-X-PROGRAM-DATE-TIME`, written after every discontinuity when the catalog has a clock, lets players resync. -- **Idle renditions cost nothing**, and a segment is servable for as long as the relay's [cache](/bin/relay/config#cache) retains it. Keep `--window` (the playlist length, default 16 s) within that retention. +- **Idle renditions cost nothing**, and a segment is servable for as long as the relay's [cache](/bin/relay/config#cache) retains it. Keep `--window` (the playlist length, default 16 s) within that retention and within the media's max age (30 s by default), after which a superseded segment's groups are stale. - **Live joins cost the window.** The exporter subscribes 30 s behind the live edge and lists at most 256 segments. One joining partway through a segment lists nothing before the first segment it sees start. - **Segments are timed by the grid.** A segment is listed once a later one starts or the track ends. It starts at its first group's timestamp, or at its line when that group starts after it (as one resuming from a pause does), or a gap at its line, and lasts until the next segment starts, so a segment's bytes never change with a catalog estimate. A GOP longer than the segment is listed at its first line, so its duration understates its media. - **The target duration is twice the segment.** Every media playlist keeps one `EXT-X-TARGETDURATION` while its rendition stays in the catalog, even across a reconfigure: twice the segment length, rounded up to whole seconds (twice the interval for a GOP of a second or more, 2 s for 20 ms audio groups), since the GOP containing a grid line starts at most one interval before it, and a gap ends under two segment lengths after its line. Only a final GOP longer than that is listed past it, against RFC 8216's rule: hls.js plays it, but Apple's `mediastreamvalidator` flags it, so keep keyframe intervals within the declared interval. diff --git a/doc/bin/relay/cluster.md b/doc/bin/relay/cluster.md index 08b24f9e6fa..c0f6fc071f2 100644 --- a/doc/bin/relay/cluster.md +++ b/doc/bin/relay/cluster.md @@ -50,7 +50,7 @@ Failover routes must carry copies of one publisher's broadcast. Independent importers use distinct instances and switch as a restart, even when fed one stream. See [Redundant ingest](/setup/redundancy) to choose between publisher switching, subscriber selection, and several routes to one publisher. -A source whose track differs in any property, such as timescale, retention, +A source whose track differs in any property, such as timescale, max age, publisher priority, compression, or refresh, is refused for that track. A moq-transport link records its draft in the track's properties and carries refresh only as on or off, so a route crossing one does not fail over to or from diff --git a/doc/bin/relay/config.md b/doc/bin/relay/config.md index faf47dde4b0..8457a273ecc 100644 --- a/doc/bin/relay/config.md +++ b/doc/bin/relay/config.md @@ -349,12 +349,14 @@ replacement is up and it carries no subscription or fetch. [cache] capacity = "8GiB" # Target bytes of cached groups and buffered datagrams. "75%" of memory also works. headroom = "2GiB" # Or: keep this much system memory free and grow into the rest. -duration = "30s" # Cap how long a non-latest group is kept, whatever the publisher asked. +duration = "30s" # Reclaim groups idle this long, and cap every track's max age at it. ``` `capacity` is a byte target, repaid as active publishers write. `duration` (30s by default) bounds memory by age, and sweeps on a timer, so a publisher -that stalls but stays connected still has its idle groups reclaimed. The latest +that stalls but stays connected still has its idle groups reclaimed. Set +explicitly, it also caps how long a superseded group stays fresh, whatever max +age the publisher declared; unset, each track keeps its own max age. The latest group of every track, and any group still being read, is kept past `capacity` but sheds its oldest frames instead. Whatever the capacity, a group holds at most its newest 32 MB. A reader of a track's newest group that reaches a shed frame asks diff --git a/doc/concept/archives.md b/doc/concept/archives.md index 65f1d24c249..53a095dacbe 100644 --- a/doc/concept/archives.md +++ b/doc/concept/archives.md @@ -96,7 +96,7 @@ like any other broadcast; it does not look in object storage on a cache miss. Each track starts live at its newest stored sequence and serves older groups from storage when requested by group position. It advertises no max age, so the -source's live retention cannot expire archived history. A growing recording is +source's live max age cannot make archived history stale. A growing recording is periodically listed for new tracks and objects. Once `.end` appears, refreshing stops and tracks end as recorded; without it, including when a recorder stopped early, the archive stays live. Empty or unrecognized prefixes are refused. diff --git a/doc/concept/audio-jitter.md b/doc/concept/audio-jitter.md index edb3a751326..2729ea1c83a 100644 --- a/doc/concept/audio-jitter.md +++ b/doc/concept/audio-jitter.md @@ -445,7 +445,7 @@ the declared number, so the browser decodes at most 500 ms of any target and holds the rest as the encoded frames it actually received. Policy limits sit above the algorithm. A receiver's own configured maximum and -the track's retention window both cap what it may hold, and neither is the +the track's max age both cap what it may hold, and neither is the estimator's business. ## Idle intervals @@ -484,7 +484,7 @@ target = delay ``` An impossible fixed target is refused, not silently adjusted. A negative delay, -or one beyond the track's retention window, is an error at configuration time. +or one beyond the track's max age, is an error at configuration time. Supported or refused, not warned about and continued. In the browser this is the numeric `delay` setting; natively it is diff --git a/doc/concept/identity.md b/doc/concept/identity.md index 15ff9b99a01..024877746f5 100644 --- a/doc/concept/identity.md +++ b/doc/concept/identity.md @@ -232,13 +232,14 @@ Within one stream, recovery is about which groups are still worth having. after a route change within its instance, continues from the first frame it lacks. A fetch asks for one group by sequence, which a relay fills upstream when its cache misses. Both are bound to the instance they resolved. -- **Publisher max age bounds retention; reader max delay bounds interest.** A +- **Publisher max age bounds freshness; reader max delay bounds interest.** A track's `max_age` (`maxAge` in JavaScript, `--max-age` on `moq import`) is the - longest any hop keeps a non-latest group for late joiners, fetches, and - recovery; a relay may evict sooner. A reader's `delay.max` is how long a non-latest group - stays worth delivering to that reader. It can tighten retention, never relax - it. Both age a group from its successor's arrival and never expire the newest - group. Not every wire carries a reader's max delay on every request; see + longest a non-latest group stays fresh at any hop for late joiners, fetches, + and recovery; a relay may cap it lower, and its cache may reclaim the bytes + sooner. A reader's `delay.max` is how long a non-latest group + stays worth delivering to that reader. It can tighten the publisher's bound, + never relax it. Both age a group from its successor's arrival and never make + the newest group stale. Not every wire carries a reader's max delay on every request; see [subscriptions](/concept/moq-lite#subscriptions). - **Arrivals are unordered.** Each group is its own stream, so a lower group can land after a higher one, and is still delivered if the reader's range and diff --git a/doc/concept/moq-lite.md b/doc/concept/moq-lite.md index ff0385a16d0..ad4f65609ed 100644 --- a/doc/concept/moq-lite.md +++ b/doc/concept/moq-lite.md @@ -285,7 +285,7 @@ Each subscription carries the knobs that decide behavior under congestion: | --- | --- | | **Priority** (-128..127, default 0) | Higher-priority tracks get bandwidth first. Audio above video, base layer above enhancement. The publisher's track priority breaks ties between subscriptions at one priority. From a native Rust publisher over QUIC or WebTransport, subscriptions at the same priority and publisher priority split bandwidth evenly by bytes, streams and datagrams alike, however many groups each has queued. A browser publisher and other transports without send groups are not covered. | | **Order** | Which group to send first when several are pending. Newest first for live (the default), oldest first for catch-up. Needs moq-lite 07 or moq-transport; older moq-lite always sends newest first. | -| **Max delay** | How long a non-latest group stays worth delivering before it is skipped. Zero means "live edge only", and raising it is also what asks for history. Unset leaves the publisher's retention window alone to bound it. | +| **Max delay** | How long a non-latest group stays worth delivering before it is skipped. Zero means "live edge only", and raising it is also what asks for history. Unset leaves the publisher's max age alone to bound it. | | **Ranges** | Which groups to ask for: from a group, a number of groups back from the latest, or the group containing a presentation time, optionally up to an end. Each group arrives whole, from its first frame. The default asks for everything max delay allows. Max delay still caps every range. | On moq-lite 05 and later, a publisher explicitly reports groups that will not arrive. @@ -371,12 +371,16 @@ until then too, so a player starting at the latest waits for the answer instead of starting from what the ended feed left. A reader's latest group stays within the groups it limits itself to, and ends once the track does. -The publisher may declare a retention window per track. Omission sets no limit; -zero keeps only the live edge. Relays preserve that declaration, and may still -evict sooner under their own cache ceiling. Media tracks explicitly use 30 -seconds so a segmented egress can still find its segments. Retention ages a -group by the same two clocks as max delay and always keeps the newest group. -A fetch obeys the same window, and may name a tighter max delay of its own. +The publisher may declare a max age per track: how long a superseded group stays +fresh. On the wire, omission sets no limit; zero makes a group stale as soon as +its successor arrives. Relays preserve that declaration, and may still cap it +lower under their own ceiling. The Rust and JS libraries give an authored track +zero, the live edge only, unless its publisher asks for more or for no limit; +media tracks declare 30 seconds, so a segmented egress can still find its +segments. A relay bounds what it keeps with its own cache, not the publisher's +default. Max age ages a group by the +same two clocks as max delay and never makes the newest group stale. A fetch +obeys the same bound, and may name a tighter max delay of its own. IETF carries the same idea as `MAX_CACHE_DURATION`, measured in wall time alone. Put together, a conference might use: diff --git a/doc/lib/js/net.md b/doc/lib/js/net.md index 17d44d9dc42..69f64df188b 100644 --- a/doc/lib/js/net.md +++ b/doc/lib/js/net.md @@ -53,6 +53,7 @@ publication.announce(); - **Serve history on request.** `track.requests()` opens a handle that serves the groups readers miss: ones their ranges name below the newest group written that the cache no longer holds, or never did. Each run of misses arrives as a `Track.Fill` from `await requests.requestedFill()`, shared by every reader missing it. `accept(sequence)` it into the cache and write the group's frames as first published, `dropGroups(start, end)` what the source lacks (sequences are `bigint`), and serve `wanted()` until it is `undefined`: a reader that leaves or narrows stops wanting its groups. `close()` the fill when done; whatever is still wanted is named dropped. A `fetchGroup` of an uncached group asks the handle at once, even for a group not written yet, which a live write then answers; with no handle open it fails with `NotFound`, as in Rust, and a reader's miss is given up. A reader only asks for what its `delay.max` still wants, so a reader at the live edge never asks. This serves lite FETCH, single-group IETF FETCH, and lite-07 ranged subscriptions from the same track, as Rust's `requests()` does. - **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`. The publisher's own staleness bound is the separate `Track.Info.maxAge`, which caps `delay.max` and fetches. +- **Authored tracks default to a zero `maxAge`.** `createTrack` and `accept` take a `Track.InfoInit`: an omitted `maxAge` is zero, so readers get only the live edge; `null` sets no publisher limit, and a number is that bound, as `Info::default()` and `with_max_age(None)` do in Rust. A track whose readers reach back for superseded groups (history, a fetch, a range from an absolute start) sets one explicitly; media takes `@moq/hang`'s 30-second `Container.MAX_AGE`. `maxAge` is how long a superseded group stays fresh, never the newest group, so a track that writes one snapshot stays readable to a late joiner. Received metadata keeps absence as no limit; serve a received `Track.Info` onward with `maxAge: info.maxAge ?? null`. - **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. diff --git a/doc/lib/js/publish.md b/doc/lib/js/publish.md index e6c7229c37d..aeff8755be2 100644 --- a/doc/lib/js/publish.md +++ b/doc/lib/js/publish.md @@ -76,8 +76,11 @@ 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. Disabling an audio encoder keeps what it retained: a +`maxAge`, which for media defaults to 30 seconds (about 11.5 MB for 48 kHz +stereo f32). With `maxAge: null`, which sets no publisher limit on the media, raw +audio still keeps 30 seconds, since raw history needs a bound. The catalog and +HLS record tracks keep `@moq/net`'s zero default, since a viewer needs only +their newest group. Capture stays open. Disabling an audio encoder keeps what it retained: a subscriber still gets that history, and it expires on its own. Players skip a disabled rendition, so that history reaches subscribers that are already held on it or that subscribe directly. The codec stays diff --git a/doc/lib/rs/moq-audio.md b/doc/lib/rs/moq-audio.md index 1b12fa4758f..17fe26bac12 100644 --- a/doc/lib/rs/moq-audio.md +++ b/doc/lib/rs/moq-audio.md @@ -36,7 +36,7 @@ without stalling the mix. Without a subscriber the encoder keeps raw PCM up to the track's `max_age`, then encodes that history before continuing live when -someone subscribes. With no declared retention it keeps at most 30 seconds +someone subscribes. With an unlimited `max_age` it keeps at most 30 seconds (about 11.5 MB for 48 kHz stereo f32). Set `encode::Capture::on_demand` to false to encode continuously instead. Stopping an encoder leaves the shared capture running, and the history it retained stays on the track until it is subscribed or expires; a device failure keeps diff --git a/doc/lib/rs/moq-net.md b/doc/lib/rs/moq-net.md index 0ed50e2dfe7..03b7e13cec8 100644 --- a/doc/lib/rs/moq-net.md +++ b/doc/lib/rs/moq-net.md @@ -21,6 +21,7 @@ What you use it for, beyond what the concept page already describes: - **Request one instance, or follow them all.** `consumer.request(path, None)` resolves the instance serving a path now, and fails `Unroutable` only once discovery has synced with no route for it. `consumer.follow(path, None)` hands out each publisher instance serving a path from `available()`: the first once announced, then each one that takes over or returns after an end, like JS `follow(path)`. A broadcast already resolved stays on the old instance until dropped or its route goes. See [identity and recovery](/concept/identity) to choose between following and holding one instance. - **Discovery follows what you watch.** A client session asks the relay for announcements only under the prefixes its subscribe origin's readers watch, with `announced()`, `request`, or `follow`, stops asking about a prefix 2s after nothing at or beneath it is watched, and asks again on reconnect. A broadcast resolved through a discovered route keeps its path watched until dropped. `request` owns discovery of its path, so no separate watch is needed. A server session, or a client fed into an origin handle marked `with_link(origin::Link::Peer)` or `Link::Upstream`, asks for everything it may, so a relay discovers everything. An HTTP gateway (the moq-hls `Server`, the moq-rtc WHEP router) watches its whole scope while it lives, so the paths its callers name never open a request each. moq-lite-03/04 sessions, whose announcements mark no initial set, still ask for everything. - **One track per name.** Concurrent subscriptions share one request and producer. The application owns sequence numbers: the broadcast keeps nothing of an ended track, so a producer that replaces it starts at 0. A name always means the same content, so the replacement continues past its predecessor's groups with `create_group` at an explicit sequence. Readers of an aborted track resume onto the replacement when they read through an origin request, whose route always names an instance; otherwise their subscription ends with the error. +- **Authored tracks default to a zero `max_age`.** `track::Info::default()` sets `max_age` to `Some(Duration::ZERO)`, the live edge only; a publisher that wants readers to reach history sets a longer bound, or `with_max_age(None)` for no publisher limit. Media tracks from `hang::container::track_info` declare `hang::container::MAX_AGE` (30 seconds). `max_age` is how long a superseded group stays fresh, never the newest group; it frees no bytes, which the cache pool's expiry reclaims. Received metadata keeps absence as no limit, and an origin's `cache_duration` can only cap it lower. - **End content by finishing tracks.** A broadcast has no finished state. When the input ends, finish each track; the broadcast stays announced and keeps serving them until you close it or drop its last producer. How long to keep it up for late readers is yours to decide: `moq_mux::Linger` holds a hang broadcast for a fixed window. - **Demand says whether anyone is watching.** `demand()` on a track, group, or broadcast says whether a subscriber is attached. First-party capture does not wait for it: video encodes while enabled and audio keeps raw PCM to encode when someone listens, so a late subscription's `delay.max` or a FETCH finds the recent past. Demand gates bandwidth reservations, transcode rungs, and on-demand video where a publisher opts in, which saves the encode but leaves nothing from before the first subscriber. Holding a broadcast or track consumer is not demand: a track consumer requests nothing until it queries, subscribes, or fetches, and those count until dropped. A shared fetch stays up until its last reader leaves. Demand rolls up: a frame being read keeps its group wanted, a group a subscription or fetch handed out keeps its track wanted until read to its end, and any wanted track keeps its broadcast wanted. - **Use the model without a runtime.** Disable default features on `moq-net` to use its `poll_*` APIs and origin driver with caller-supplied time. The default `async` feature adds async helpers, `time::run`, and both wire sessions. diff --git a/doc/setup/redundancy.md b/doc/setup/redundancy.md index 83e415b068c..6357ec7d704 100644 --- a/doc/setup/redundancy.md +++ b/doc/setup/redundancy.md @@ -119,7 +119,7 @@ When the serving route fails or another route with the same instance wins, the subscription resumes from the first frame it lacks. This needs an explicit matching instance across every hop (moq-lite 07 on every link), routes whose copies report identical track info (so the same protocol and draft on each), and a surviving route that can still serve -those frames within the broadcast's retention. It preserves broadcast +those frames within the track's max age. It preserves broadcast continuity, but a late recovery can still miss playback deadlines. Losing the only publisher cannot be repaired by adding routes to it. diff --git a/drafts/draft-lcurley-moq-timestamp.md b/drafts/draft-lcurley-moq-timestamp.md index 39fb4f38626..614a4e776cc 100644 --- a/drafts/draft-lcurley-moq-timestamp.md +++ b/drafts/draft-lcurley-moq-timestamp.md @@ -168,7 +168,7 @@ On an update, absence leaves the subscription's budget unchanged; presence repla A publisher receiving MAX_AGE MUST apply the budget as specified in {{age}} and MUST NOT translate it into OBJECT_DELIVERY_TIMEOUT or SUBGROUP_DELIVERY_TIMEOUT. Those timeouts can expire the newest group and do not express this policy. -A relay combining subscribers MUST request at least the most tolerant subscriber's max age upstream, bounded by the publisher's retention policy. +A relay combining subscribers MUST request at least the most tolerant subscriber's max age upstream, bounded by any age limit the publisher declares. One subscriber's shorter budget MUST NOT tighten another subscriber's budget. diff --git a/go/wrapper/MIGRATE.md b/go/wrapper/MIGRATE.md index 08d483234ed..bbe83b57ba9 100644 --- a/go/wrapper/MIGRATE.md +++ b/go/wrapper/MIGRATE.md @@ -4,6 +4,10 @@ How to update your code for each breaking change, newest first. ## Unreleased +### Authored tracks default to a zero max age ([#7729](https://github.com/moq-dev/moq/pull/7729)) + +`TrackInfo.MaxAge` is a `time.Duration` instead of a `*time.Duration`, like `Delay.Max`: the zero value, and a nil `*TrackInfo`, now advertise a zero max age, serving only the live edge, instead of no publisher limit. Assign the duration directly, and set the new `MaxAgeUnlimited`, which ignores `MaxAge`, where you relied on nil meaning no limit. A received track's `Info()` sets it when its publisher advertised no limit. + ### Viewer targets are bounded ([#7090](https://github.com/moq-dev/moq/pull/7090)) Viewer ceilings and PROBE target overrides are refused with the new `ErrOutOfRange` once they would sum above 2^53 - 1 bps, the most a PROBE target carries; nothing changes on a refusal. `Viewers.Watch` returns `(*Viewer, error)`, and `Viewers.SetTarget` and `Viewer.Update` return an `error`. Handle the new variant wherever you match the error exhaustively. Regenerate bindings and rebuild the matching native library together. diff --git a/go/wrapper/moq_test.go b/go/wrapper/moq_test.go index 4ff1c20af46..827e09c258a 100644 --- a/go/wrapper/moq_test.go +++ b/go/wrapper/moq_test.go @@ -570,6 +570,53 @@ func TestInsertDatagramAndLargest(t *testing.T) { } } +// An omitted max age is zero, MaxAgeUnlimited sets no limit and wins over MaxAge, and a +// received info republishes unchanged. +func TestTrackInfoMaxAge(t *testing.T) { + broadcast, err := moq.NewBroadcastProducer() + if err != nil { + t.Fatal(err) + } + two := 2 * time.Second + cases := []struct { + info *moq.TrackInfo + want moq.TrackInfo + }{ + {nil, moq.TrackInfo{}}, + {&moq.TrackInfo{}, moq.TrackInfo{}}, + {&moq.TrackInfo{MaxAge: two}, moq.TrackInfo{MaxAge: two}}, + {&moq.TrackInfo{MaxAgeUnlimited: true}, moq.TrackInfo{MaxAgeUnlimited: true}}, + {&moq.TrackInfo{MaxAge: two, MaxAgeUnlimited: true}, moq.TrackInfo{MaxAgeUnlimited: true}}, + } + info := func(name string, in *moq.TrackInfo) moq.TrackInfo { + track, err := broadcast.PublishTrack(name, in) + if err != nil { + t.Fatal(err) + } + consumer, err := track.Consume(nil) + if err != nil { + t.Fatal(err) + } + return consumer.Info() + } + for i, c := range cases { + got := info(fmt.Sprint(i), c.info) + if got.MaxAge != c.want.MaxAge || got.MaxAgeUnlimited != c.want.MaxAgeUnlimited { + t.Errorf("case %d: Info() = %+v, want %+v", i, got, c.want) + } + again := info(fmt.Sprint("again", i), &got) + if again.MaxAge != got.MaxAge || again.MaxAgeUnlimited != got.MaxAgeUnlimited { + t.Errorf("case %d: republished Info() = %+v, want %+v", i, again, got) + } + } + if _, err := broadcast.PublishTrack("negative", &moq.TrackInfo{MaxAge: -time.Second}); err == nil { + t.Error("a negative max age was accepted") + } + if err := broadcast.Close(); err != nil { + t.Fatal(err) + } +} + func TestBroadcastConsumerClosed(t *testing.T) { ctx, cancel := context.WithTimeout(context.Background(), testTimeout) defer cancel() @@ -867,7 +914,10 @@ func TestAscendingSubscriptionReadsCachedBacklogOldestFirst(t *testing.T) { if err != nil { t.Fatal(err) } - track, err := broadcast.PublishTrack("backlog", timedInfo()) + // No publisher age limit, so the superseded backlog stays readable. + info := timedInfo() + info.MaxAgeUnlimited = true + track, err := broadcast.PublishTrack("backlog", info) if err != nil { t.Fatal(err) } diff --git a/go/wrapper/records.go b/go/wrapper/records.go index 286554ca169..3f34a046f08 100644 --- a/go/wrapper/records.go +++ b/go/wrapper/records.go @@ -142,41 +142,54 @@ func subscriptionFFI(s *Subscription) (*ffi.MoqSubscription, error) { } // TrackInfo holds publisher-side track properties: priority, how long a -// non-latest group is cached (nil for no limit), how many times its first frame -// a group's later bytes may grow before a joining subscriber asks for a new group -// (nil never asks), and the timescale in ticks per second (nil means untimed on -// both publish and receive). Priority is higher first; the zero Priority is the -// midpoint a nil TrackInfo uses. Compress DEFLATEs each group on the wire to peers -// that support it; readers always see the original frames. +// superseded group stays fresh, how many times its first frame a group's later +// bytes may grow before a joining subscriber asks for a new group (nil never +// asks), and the timescale in ticks per second (nil means untimed on both publish +// and receive). Priority is higher first; the zero Priority is the midpoint a nil +// TrackInfo uses. Compress DEFLATEs each group on the wire to peers that support +// it; readers always see the original frames. type TrackInfo struct { - Priority int8 - MaxAge *time.Duration - Refresh *uint32 - Timescale *uint64 - Compress bool + Priority int8 + // MaxAge is how long a superseded group stays fresh. Zero, the default, serves + // only the live edge. + MaxAge time.Duration + // MaxAgeUnlimited ignores MaxAge and sets no publisher limit, leaving only the + // cache to bound how long a superseded group is served. + MaxAgeUnlimited bool + Refresh *uint32 + Timescale *uint64 + Compress bool } func trackInfoFFI(info *TrackInfo) (*ffi.MoqTrackInfo, error) { if info == nil { return nil, nil } - return &ffi.MoqTrackInfo{ - Priority: info.Priority, - MaxAge: info.MaxAge, - Refresh: info.Refresh, - Timescale: info.Timescale, - Compress: info.Compress, - }, bridge.NonNegative(info.MaxAge, "max age") + out := &ffi.MoqTrackInfo{ + Priority: info.Priority, + MaxAgeUnlimited: info.MaxAgeUnlimited, + Refresh: info.Refresh, + Timescale: info.Timescale, + Compress: info.Compress, + } + if !info.MaxAgeUnlimited { + out.MaxAge = &info.MaxAge + } + return out, bridge.NonNegative(out.MaxAge, "max age") } func trackInfoFromFFI(info ffi.MoqTrackInfo) TrackInfo { - return TrackInfo{ - Priority: info.Priority, - MaxAge: info.MaxAge, - Refresh: info.Refresh, - Timescale: info.Timescale, - Compress: info.Compress, + out := TrackInfo{ + Priority: info.Priority, + MaxAgeUnlimited: info.MaxAgeUnlimited, + Refresh: info.Refresh, + Timescale: info.Timescale, + Compress: info.Compress, } + if info.MaxAge != nil && !info.MaxAgeUnlimited { + out.MaxAge = *info.MaxAge + } + return out } // ConnectionStats holds transport metrics for a session (RTT, bandwidth, byte diff --git a/js/crypto/src/e2ee/broadcast.ts b/js/crypto/src/e2ee/broadcast.ts index 5375461eb58..db64a175eb5 100644 --- a/js/crypto/src/e2ee/broadcast.ts +++ b/js/crypto/src/e2ee/broadcast.ts @@ -42,7 +42,7 @@ export class Producer { * produced the name (even on another broadcast), or the net error if the broadcast already * holds it. */ - async createTrack(semantic: string, info: Partial = {}): Promise { + async createTrack(semantic: string, info: NetTrack.InfoInit = {}): Promise { const name = await this.generation.name(semantic); return this.generation.produce(this.#inner.createTrack(name, info), semantic); } diff --git a/js/crypto/src/e2ee/e2ee.test.ts b/js/crypto/src/e2ee/e2ee.test.ts index 01db429f0cc..14f17fd6c36 100644 --- a/js/crypto/src/e2ee/e2ee.test.ts +++ b/js/crypto/src/e2ee/e2ee.test.ts @@ -35,8 +35,10 @@ function credential(): Credential { const ms = (value: number) => Time.Timestamp.fromMillis(value); const text = (value: string) => encoder.encode(value); +// No publisher limit, since the tests read groups a later one has superseded. function netTrack(name: string, timed = true): NetTrack.Producer { - return new Broadcast.Producer().createTrack(name, timed ? { timescale: Time.Timescale.MILLI } : {}); + const timescale = timed ? Time.Timescale.MILLI : undefined; + return new Broadcast.Producer().createTrack(name, { timescale, maxAge: null }); } function subscribe(net: NetTrack.Producer): NetTrack.Subscriber { diff --git a/js/crypto/src/sign/broadcast.ts b/js/crypto/src/sign/broadcast.ts index 07ff923b78b..fecfde5f21d 100644 --- a/js/crypto/src/sign/broadcast.ts +++ b/js/crypto/src/sign/broadcast.ts @@ -40,7 +40,7 @@ export class Producer { } /** Create a track whose frames are signed; throws the net error if the broadcast already holds it. */ - createTrack(name: string, info: Partial = {}): Track.Producer { + createTrack(name: string, info: NetTrack.InfoInit = {}): Track.Producer { const inner = this.#inner.createTrack(name, info); let sequences = this.#sequences.get(name); if (!sequences) { diff --git a/js/hang/MIGRATE.md b/js/hang/MIGRATE.md index 12e0570f176..c1e0d020299 100644 --- a/js/hang/MIGRATE.md +++ b/js/hang/MIGRATE.md @@ -4,6 +4,11 @@ How to update your code for each breaking change, newest first. ## Unreleased +### `Container.trackInfo` takes `maxAge: null` ([#7729](https://github.com/moq-dev/moq/pull/7729)) + +`TrackInfoOptions.maxAge` accepts `null` for no publisher limit, and `trackInfo` returns a `@moq/net` `Track.InfoInit`. An omitted `maxAge` is still 30 seconds for media, now exported as `Container.MAX_AGE`. +Following `@moq/net`, report tracks now advertise a zero max age instead of no limit: a reader gets their newest group, which restates the whole state. + ### The root `clock` is `media.clock`, and the catalog declares a join interval ([#7652](https://github.com/moq-dev/moq/pull/7652)) The catalog root gains an optional `media` section holding what applies to every audio and video track: `clock`, moved from the root, and `join`, whose `interval` is the longest GOP in whole milliseconds. diff --git a/js/hang/api/container.api.md b/js/hang/api/container.api.md index 4d67cc1eb12..8db9aa8394b 100644 --- a/js/hang/api/container.api.md +++ b/js/hang/api/container.api.md @@ -73,6 +73,8 @@ export namespace Legacy { export * as Loc from "@moq/loc"; +export const MAX_AGE: Milli; + export type Read = { frame: ReceivedFrame; group: bigint; @@ -92,11 +94,11 @@ export interface ReceivedFrame extends Frame { } export type TrackInfoOptions = { - maxAge?: Milli; + maxAge?: Milli | null; priority: number; }; export function mergeBufferedRanges(a: BufferedRanges, b: BufferedRanges): BufferedRanges; -export function trackInfo(options: TrackInfoOptions): Partial; +export function trackInfo(options: TrackInfoOptions): Net.Track.InfoInit; ``` diff --git a/js/hang/src/container/index.ts b/js/hang/src/container/index.ts index 14d2edf2cc7..a703433506f 100644 --- a/js/hang/src/container/index.ts +++ b/js/hang/src/container/index.ts @@ -11,5 +11,5 @@ export { Consumer, type ConsumerProps, DEFAULT_MAX_BUFFER, type Read } from "./c export type { Format } from "./format"; /** The legacy varint container. */ export * as Legacy from "./legacy"; -export { type TrackInfoOptions, trackInfo } from "./track"; +export { MAX_AGE, type TrackInfoOptions, trackInfo } from "./track"; export * from "./types"; diff --git a/js/hang/src/container/track.test.ts b/js/hang/src/container/track.test.ts new file mode 100644 index 00000000000..f0523477a4d --- /dev/null +++ b/js/hang/src/container/track.test.ts @@ -0,0 +1,20 @@ +import { expect, test } from "bun:test"; +import { Milli } from "@moq/clock"; +import { Time, Track } from "@moq/net"; +import { MAX_AGE, trackInfo } from "./track"; + +test("trackInfo declares the media max age, null is unlimited, and a value is kept", async () => { + expect(MAX_AGE).toBe(Milli(30_000)); + const omitted = trackInfo({ priority: 1 }); + expect(omitted).toEqual({ timescale: Time.Timescale.MICRO, maxAge: MAX_AGE, priority: 1 }); + expect(trackInfo({ priority: 1, maxAge: undefined }).maxAge).toBe(MAX_AGE); + expect(trackInfo({ priority: 1, maxAge: null }).maxAge).toBeNull(); + expect(trackInfo({ priority: 1, maxAge: Milli(5000) }).maxAge).toBe(Milli(5000)); + + // What a producer accepting each commits. + const committed = async (maxAge?: Milli | null) => + (await new Track.Producer("media").accept(trackInfo({ priority: 1, maxAge })).info()).maxAge; + expect(await committed()).toBe(Milli(30_000)); + expect(await committed(null)).toBeUndefined(); + expect(await committed(Milli(5000))).toBe(Milli(5000)); +}); diff --git a/js/hang/src/container/track.ts b/js/hang/src/container/track.ts index 3a199bca5c8..be03b97e7da 100644 --- a/js/hang/src/container/track.ts +++ b/js/hang/src/container/track.ts @@ -10,28 +10,29 @@ import { Milli } from "@moq/clock"; import { Time, type Track } from "@moq/net"; -// How long a media track asks its publisher (and, through TRACK_INFO, every relay) to keep a -// non-latest group fetchable. Must match `hang::container::MAX_AGE` in -// rs/hang/src/container/frame.rs. -const MAX_AGE_MS = Milli(30_000); +/** + * How long a superseded group of a media track stays fresh: the media publisher's explicit + * choice, which {@link trackInfo} declares unless told otherwise. Mirrors `hang::container::MAX_AGE`. + * + * Media is read as history rather than only followed at the live edge: a segmented egress + * (HLS/DASH) may only advertise segments a fetch can still reach, a standard player starts several + * target durations behind live, and a recorder absorbs reordering. `@moq/net`'s default of zero + * would leave those addressing groups that are already stale. + */ +export const MAX_AGE = Milli(30_000); /** * Track properties for a track carrying media frames, for `Request.accept`. * - * Pins the timescale to microseconds (the timestamps hang's containers stamp), and declares a - * retention long enough for a FETCH-based consumer to reach back over a full playlist window: a - * segmented egress (HLS/DASH) may only advertise segments a fetch can still reach, and a standard - * player starts several target durations behind live. Every media track a publisher accepts should - * use this rather than the bare defaults, which are sized for the catalog and timeline: both are - * read at the live edge, which is retained unconditionally, so neither pays for history it never - * serves. - * - * Options override that retention; see {@link TrackInfoOptions.maxAge}. + * Pins the timescale to microseconds (the timestamps hang's containers stamp), and declares + * {@link MAX_AGE} instead of `@moq/net`'s zero default, so superseded groups stay fresh long enough + * for a fetch to reach back over a full playlist window. Options override that max age; see + * {@link TrackInfoOptions.maxAge}. */ -export function trackInfo(options: TrackInfoOptions): Partial { +export function trackInfo(options: TrackInfoOptions): Track.InfoInit { return { timescale: Time.Timescale.MICRO, - maxAge: options.maxAge ?? MAX_AGE_MS, + maxAge: options.maxAge === undefined ? MAX_AGE : options.maxAge, priority: options.priority, }; } @@ -49,11 +50,13 @@ export type TrackInfoOptions = { priority: number; /** - * How long a relay keeps a non-latest group fetchable, in milliseconds, replacing the - * retention {@link trackInfo} declares by default. + * How long, in milliseconds, a superseded group stays fresh, so a fetch or a subscriber's + * `delay.max` can still reach it; see `Track.Info.maxAge`. Omitted or `undefined` is + * {@link MAX_AGE}, and `null` sets no publisher limit. * - * A RETENTION budget, not a delivery one, so it never makes anyone play further behind live + * A freshness bound, not a delivery budget, so it never makes anyone play further behind live * and lowering it does not reduce latency: it only shortens how far back a fetch can reach. + * It keeps no bytes either; the cache decides how long a group's payload stays held. */ - maxAge?: Milli; + maxAge?: Milli | null; }; diff --git a/js/hang/src/report.ts b/js/hang/src/report.ts index c3839235689..adb23f300b9 100644 --- a/js/hang/src/report.ts +++ b/js/hang/src/report.ts @@ -19,7 +19,8 @@ const REFRESH = 8; /** * One compressed snapshot track, written only while someone subscribes, so an unobserved report - * never leaves the process. + * never leaves the process. It takes `@moq/net`'s zero default max age: a joiner reads only the + * newest group, which starts with a full snapshot. */ export class Writer { /** The report track. */ diff --git a/js/json/src/snapshot/snapshot.test.ts b/js/json/src/snapshot/snapshot.test.ts index 4448b20971a..128fd19419d 100644 --- a/js/json/src/snapshot/snapshot.test.ts +++ b/js/json/src/snapshot/snapshot.test.ts @@ -184,7 +184,7 @@ test("next reads a held group out before a newer snapshot group", async () => { // Reading in order is still bounded: a group the subscription's max delay proves stale is skipped, // as on any ordered track, so a reader that falls behind jumps ahead instead of replaying it. test("next skips the groups the max delay abandons", async () => { - const track = new Track.Producer("test").accept({ timescale: Time.Timescale.MILLI }); + const track = new Track.Producer("test").accept({ timescale: Time.Timescale.MILLI, maxAge: null }); const producer = new Producer({ track, deltas: false }); for (let n = 1; n <= 3; n++) producer.update({ value: { n }, at: Time.Timestamp.fromMillis(n * 1_000) }); producer.finish(); @@ -343,7 +343,7 @@ test("a joiner over the ratio gets a fresh snapshot", async () => { [8, [4]], [1, [4, 1]], ] as const) { - const track = new Track.Producer("test").accept({ refresh }); + const track = new Track.Producer("test").accept({ refresh, maxAge: null }); const producer = new Producer({ track }); fill(producer); @@ -359,7 +359,7 @@ test("a joiner over the ratio gets a fresh snapshot", async () => { }); test("a refresh reuses the newest timestamp", async () => { - const track = new Track.Producer("test").accept({ timescale: Time.Timescale.MILLI, refresh: 1 }); + const track = new Track.Producer("test").accept({ timescale: Time.Timescale.MILLI, refresh: 1, maxAge: null }); const producer = new Producer({ track }); for (let n = 0; n <= 3; n++) producer.update({ value: { n }, at: Time.Timestamp.fromMillis(n * 10) }); @@ -380,7 +380,7 @@ test("a refresh reuses the newest timestamp", async () => { }); test("a refresh after an older update starts at the newest timestamp", async () => { - const track = new Track.Producer("test").accept({ timescale: Time.Timescale.MILLI, refresh: 1 }); + const track = new Track.Producer("test").accept({ timescale: Time.Timescale.MILLI, refresh: 1, maxAge: null }); const producer = new Producer({ track }); // Deltas may carry timestamps older than their group's first frame. for (const [n, ms] of [30, 10, 20, 15].entries()) @@ -409,7 +409,7 @@ test("a refresh after an older update starts at the newest timestamp", async () // update rides as a delta against it. (Mirrors the Rust // `a_refresh_after_a_rejected_update_restates_the_last_written_value`.) test("a refresh after a rejected update restates the last written value", async () => { - const track = new Track.Producer("test").accept({ refresh: 1 }); + const track = new Track.Producer("test").accept({ refresh: 1, maxAge: null }); const producer = new Producer({ track }); fill(producer); @@ -448,7 +448,7 @@ test("no ratio never refreshes", async () => { }); test("a compressed refresh opens a fresh group", async () => { - const track = new Track.Producer("test").accept({ refresh: 0, compress: true }); + const track = new Track.Producer("test").accept({ refresh: 0, compress: true, maxAge: null }); const producer = new Producer({ track }); producer.update({ value: { a: 1, b: 1 } }); producer.update({ value: { a: 1, b: 2 } }); diff --git a/js/json/src/window/window.test.ts b/js/json/src/window/window.test.ts index 68ddf6242c1..39e7c5f5c11 100644 --- a/js/json/src/window/window.test.ts +++ b/js/json/src/window/window.test.ts @@ -234,7 +234,7 @@ test("a joiner over the ratio gets a fresh header", async () => { [2, [3]], [3, [4, 1]], ] as const) { - const track = new Track.Producer("test").accept({ refresh: 1 }); + const track = new Track.Producer("test").accept({ refresh: 1, maxAge: null }); const producer = new Producer({ track }); producer.push({ value: { n: 1000 } }); for (let n = 0; n < pushes; n++) producer.push({ value: { n } }); @@ -249,7 +249,7 @@ test("a joiner over the ratio gets a fresh header", async () => { }); test("a window refresh reuses the newest timestamp", async () => { - const track = new Track.Producer("test").accept({ timescale: Time.Timescale.MILLI, refresh: 0 }); + const track = new Track.Producer("test").accept({ timescale: Time.Timescale.MILLI, refresh: 0, maxAge: null }); const producer = new Producer({ track }); producer.push({ value: { n: 0 }, at: Time.Timestamp.fromMillis(10) }); producer.push({ value: { n: 1 }, at: Time.Timestamp.fromMillis(20) }); @@ -272,7 +272,7 @@ test("a window refresh reuses the newest timestamp", async () => { }); test("a window refresh after an older edit starts at the newest timestamp", async () => { - const track = new Track.Producer("test").accept({ timescale: Time.Timescale.MILLI, refresh: 0 }); + const track = new Track.Producer("test").accept({ timescale: Time.Timescale.MILLI, refresh: 0, maxAge: null }); const producer = new Producer({ track }); producer.push({ value: { n: 0 }, at: Time.Timestamp.fromMillis(30) }); // Ops may carry timestamps older than their group's first frame. diff --git a/js/net/MIGRATE.md b/js/net/MIGRATE.md index e12e417b78f..88f063d8291 100644 --- a/js/net/MIGRATE.md +++ b/js/net/MIGRATE.md @@ -4,6 +4,19 @@ How to update your code for each breaking change, newest first. ## Unreleased +### Authored tracks default to a zero `maxAge` ([#7729](https://github.com/moq-dev/moq/pull/7729)) + +A track created with `Broadcast.Producer.createTrack`, `Track.Request.accept`, or `Track.Producer.accept` takes a `Track.InfoInit`, whose omitted or `undefined` `maxAge` is now zero instead of no publisher limit: a superseded group is stale as soon as its successor arrives, so readers get only the live edge. The newest group never goes stale, so a track that writes one snapshot stays readable to a late joiner. +A track whose readers reach back for superseded groups (a subscription's `delay.max`, a fetch, or a range from an absolute start) passes `maxAge: null` for unlimited history, or a window, when it creates the track; changing it means a new track or broadcast. A relay or cache bounds what it keeps with its own window, not the publisher's default. +Received metadata is unchanged: a decoded `Track.Info` without `maxAge` still means no publisher limit, and `Track.infoDefaults` keeps an absent `maxAge` absent. To serve a received `Track.Info` onward unchanged, pass `{ ...info, maxAge: info.maxAge ?? null }`. + +```ts +// Before: no publisher limit +broadcast.createTrack("history", { timescale: Time.Timescale.MILLI }); +// After: the same, stated explicitly +broadcast.createTrack("history", { timescale: Time.Timescale.MILLI, maxAge: null }); +``` + ### Past group ranges work over moq-transport ([#7793](https://github.com/moq-dev/moq/pull/7793)) `track.Consumer.fetchGroup()` and subscriptions to past group ranges now use standalone FETCH on drafts 18, 20, and 22. No API migration is needed. First-party publishers serve one group per FETCH; multi-group ranges require a publisher that serves them. diff --git a/js/net/api/index.api.md b/js/net/api/index.api.md index 68203040da6..a6214d43948 100644 --- a/js/net/api/index.api.md +++ b/js/net/api/index.api.md @@ -106,7 +106,7 @@ export namespace Broadcast { close(): void; get closed(): Signals.GetPromise; consume(): Broadcast.Consumer; - createTrack(name: string, info?: Partial): Track.Producer; + createTrack(name: string, info?: Track.InfoInit): Track.Producer; removeTrack(name: string): void; track(name: string): Track.Consumer; } @@ -674,6 +674,9 @@ export namespace Track { refresh?: number; timescale?: Time.Timescale | null; } + export interface InfoInit extends Partial> { + maxAge?: Milli | null; + } export type Order = "ascending" | "descending"; export class Ordered { close(abort?: Error): void; @@ -703,7 +706,7 @@ export namespace Track { export class Producer { constructor(name: string); abort(error: Error): void; - accept(info?: Partial): this; + accept(info?: Track.InfoInit): this; appendDatagram(timestamp: Time.Timestamp | undefined, payload: Uint8Array): bigint; appendGroup(): Group.Producer; close(): void; @@ -727,7 +730,7 @@ export namespace Track { start?: Track.Anchor; } export class Request { - accept(info?: Partial): Track.Producer; + accept(info?: Track.InfoInit): Track.Producer; demand(): Track.Demand; readonly name: string; get priority(): number; diff --git a/js/net/bench/drift.ts b/js/net/bench/drift.ts index ca022b410cd..65dd33ea94e 100644 --- a/js/net/bench/drift.ts +++ b/js/net/bench/drift.ts @@ -13,7 +13,8 @@ export async function run(): Promise { const offsets = [0, 80, 40]; try { // The same reordered-PTS verdict runs here in Chromium before timing any work. - const check = new Track.Producer("reordered").accept({ timescale: Time.Timescale.MILLI }); + // No publisher limit, so the reader's own 80 ms budget alone judges the reordered tail. + const check = new Track.Producer("reordered").accept({ timescale: Time.Timescale.MILLI, maxAge: null }); const reader = check.subscribe({ delay: { max: Milli(80) } }); try { for (const timestamps of [[0], [100], [150, 200, 160]]) { @@ -39,7 +40,10 @@ export async function run(): Promise { ? Time.Timestamp.fromMicros(ms * 1000) : Time.Timestamp.fromMillis(ms); const tracks = Array.from({ length: publishers }, (_, i) => - new Track.Producer(`p${i}`).accept(mode !== 0 ? { timescale: Time.Timescale.MILLI } : {}), + // No publisher limit: the retained history is what the readers drift over. + new Track.Producer(`p${i}`).accept( + mode !== 0 ? { timescale: Time.Timescale.MILLI, maxAge: null } : { maxAge: null }, + ), ); const sources: Group.Producer[] = []; const consumers: Group.Consumer[] = []; diff --git a/js/net/bench/replay.ts b/js/net/bench/replay.ts index acff8cdcc16..558862700e1 100644 --- a/js/net/bench/replay.ts +++ b/js/net/bench/replay.ts @@ -90,7 +90,8 @@ async function shape( const installed = clock.install(); const total = kind === "join" ? groups : groups + APPENDS; const sequences = arrivals(total, order); - const track = new Track.Producer(kind).accept(); + // No publisher limit: joins and appends replay superseded groups. + const track = new Track.Producer(kind).accept({ maxAge: null }); const readers: Track.Subscriber[] = []; try { if (kind === "append") for (let i = 0; i < subscribers; i++) readers.push(track.subscribe(SUBSCRIPTION)); diff --git a/js/net/src/broadcast.test.ts b/js/net/src/broadcast.test.ts index 9522bf4f73c..bf6adef6fe5 100644 --- a/js/net/src/broadcast.test.ts +++ b/js/net/src/broadcast.test.ts @@ -438,7 +438,7 @@ test("subscribe serves a statically inserted track without a request", async () test("two subscribers to one inserted track each get a full copy", async () => { const broadcast = new BroadcastProducer(); - const producer = broadcast.createTrack("video", { timescale: Timescale.MILLI }); + const producer = broadcast.createTrack("video", { timescale: Timescale.MILLI, maxAge: null }); const a = broadcast .track("video") @@ -475,7 +475,7 @@ test("a late subscriber replays the cached window", async () => { test("a read throws Evicted at a shed front, then resyncs to the next group", async () => { const broadcast = new BroadcastProducer(); - const producer = broadcast.createTrack("video", { timescale: Timescale.MILLI }); + const producer = broadcast.createTrack("video", { timescale: Timescale.MILLI, maxAge: null }); const sub = broadcast .track("video") .subscribe({ delay: { max: Milli(5000) } }) diff --git a/js/net/src/broadcast.ts b/js/net/src/broadcast.ts index c45a2a6ba25..8962412ccbf 100644 --- a/js/net/src/broadcast.ts +++ b/js/net/src/broadcast.ts @@ -362,9 +362,10 @@ export class Producer { * from the returned producer. A request a handler has already taken stays a duplicate. * An append on the track throws if it would reuse a sequence an earlier track of the name * wrote in this broadcast, so a replacement writes its first group explicitly. Throws if an - * open track or a live request already holds the name. + * open track or a live request already holds the name. `info` resolves as + * {@link track.Producer.accept} does, so an omitted `maxAge` is zero, the live edge only. */ - createTrack(name: string, info: Partial = {}): track.Producer { + createTrack(name: string, info: track.InfoInit = {}): track.Producer { if (this.#state.closed.peek() !== undefined) { throw new Error("broadcast is closed"); } @@ -376,7 +377,7 @@ export class Producer { const lookups = this.#state.lookups.get(producer); if (lookups) lookups.opened = false; this.#state.requests.delete(name); - adopt(this.#state, producer, track.infoDefaults(info)); + adopt(this.#state, producer, track.authoredInfo(info)); return producer; } @@ -388,7 +389,7 @@ export class Producer { } const producer = new track.Producer(name).accept(info); - adopt(this.#state, producer, track.infoDefaults(info)); + adopt(this.#state, producer, track.authoredInfo(info)); return producer; } diff --git a/js/net/src/fill.test.ts b/js/net/src/fill.test.ts index d1b17886121..a69f70a546e 100644 --- a/js/net/src/fill.test.ts +++ b/js/net/src/fill.test.ts @@ -16,6 +16,9 @@ import { wireOf } from "./wire.ts"; const enc = new TextEncoder(); const dec = new TextDecoder(); +// Every track here states no publisher max age: a fill serves history, which the default zero +// max age would leave stale. + // The archive an in-memory responder serves: each group's frames, by sequence. type Archive = Map; @@ -65,7 +68,7 @@ async function drain(reader: { recvGroup(): Promise } // A track whose first write is group `first`, so every group below it was never cached here. function resumed(first: bigint): { broadcast: BroadcastProducer; track: Producer } { const broadcast = new BroadcastProducer(); - const track = broadcast.createTrack("video"); + const track = broadcast.createTrack("video", { maxAge: null }); const group = track.createGroup(first); group.writeFrame({ payload: enc.encode(`live ${first}`) }); group.finish(); @@ -335,7 +338,7 @@ test("fill: a fill names the most urgent priority and loosest budget among its r test("fill: a group arriving live answers the fill", async () => { const broadcast = new BroadcastProducer(); - const track = broadcast.createTrack("video"); + const track = broadcast.createTrack("video", { maxAge: null }); const requests = track.requests(); const late = track.createGroup(3n); late.finish(); @@ -452,7 +455,7 @@ test("fill: a bounded reader keeps waiting on a fresh fill once an older one goe const installed = clock.install(); try { const broadcast = new BroadcastProducer(); - const track = broadcast.createTrack("video"); + const track = broadcast.createTrack("video", { maxAge: null }); const write = (sequence: bigint) => { const group = track.createGroup(sequence); group.writeFrame({ payload: enc.encode(`live ${sequence}`) }); @@ -646,7 +649,7 @@ test("fill: a reader parked on a miss asks once a handler opens", async () => { test("fill: a sequence the track's datagram took is never asked, even once a reader read it", async () => { const broadcast = new BroadcastProducer(); - const track = broadcast.createTrack("video"); + const track = broadcast.createTrack("video", { maxAge: null }); // Subscribed first: a datagram is not replayed to a later reader. const reader = track.subscribe(history); track.insertDatagram(2n, undefined, enc.encode("datagram 2")); @@ -717,7 +720,7 @@ test("fill: a cache-miss fetch of a dynamic track serves the one track the broad const fetching = wireOf(broadcast).fetchGroup("video", 1n); const request = await pulled; if (!request) throw new Error("no track request"); - const track = request.accept(); + const track = request.accept({ maxAge: null }); const requests = track.requests(); const group = track.createGroup(4n); group.finish(); @@ -753,7 +756,7 @@ async function session(alpn: string) { const publication = origin.createBroadcast(Path.from("archive")); publication.announce(); const broadcast = publication.broadcast; - const track = broadcast.createTrack("video", { timescale: Timescale.MILLI }); + const track = broadcast.createTrack("video", { timescale: Timescale.MILLI, maxAge: null }); // Groups 0 to 2 were published before this producer existed. const live = track.createGroup(3n); live.writeFrame({ payload: enc.encode("live 3"), timestamp: Timestamp.fromMillis(3000) }); diff --git a/js/net/src/fill.ts b/js/net/src/fill.ts index 3a329599436..8f2ef577977 100644 --- a/js/net/src/fill.ts +++ b/js/net/src/fill.ts @@ -518,7 +518,7 @@ export class Fill { /** * Insert group `sequence` into the track's cache, handing it to the readers waiting on it, * and return the producer to write its frames into. `info` commits the track's {@link Info} - * if it has none yet. Throws a `RangeError` outside the fill, and an error if the group was + * if it has none yet, as received metadata: an absent `maxAge` sets no publisher limit. Throws a `RangeError` outside the fill, and an error if the group was * already answered or cached, or the track is closed. */ accept(sequence: bigint, info?: Partial): GroupProducer { diff --git a/js/net/src/goaway-requests.test.ts b/js/net/src/goaway-requests.test.ts index b781fe6c4b4..8de6f9da638 100644 --- a/js/net/src/goaway-requests.test.ts +++ b/js/net/src/goaway-requests.test.ts @@ -117,7 +117,8 @@ async function handover(kind: "lite" | "ietf"): Promise { for (;;) { const req = await wireOf(broadcast).requested(); if (!req) break; - const track = req.accept({ timescale: Timescale.MILLI }); + // The draining session fetches the superseded group 0 below. + const track = req.accept({ timescale: Timescale.MILLI, maxAge: null }); 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")); diff --git a/js/net/src/ietf/fetch.test.ts b/js/net/src/ietf/fetch.test.ts index bac5040319c..fec9cb5754e 100644 --- a/js/net/src/ietf/fetch.test.ts +++ b/js/net/src/ietf/fetch.test.ts @@ -41,7 +41,9 @@ const INVALID_RANGE = 0x11; const INVALID_JOINING_REQUEST_ID = 0x32; /** A publisher serving the `room` broadcast, with its `video` track and the client's uni streams. */ -function serve(version: IetfVersion, grant?: Signal, priority?: number) { +// `maxAge` is the track's publisher max age: omitted is the authored zero, and a test that fills +// superseded history passes `null`, since the publisher fills only groups still fresh. +function serve(version: IetfVersion, grant?: Signal, priority?: number, maxAge?: Milli | null) { const pair = createMockTransportPair(ALPNS[version]); const origin = new OriginProducer(); const pub = new Publisher({ @@ -53,7 +55,7 @@ function serve(version: IetfVersion, grant?: Signal, priority }); const publication = origin.createBroadcast(Path.from("room")); publication.announce(); - const track = publication.broadcast.createTrack("video", { timescale: Timescale.MILLI, priority }); + const track = publication.broadcast.createTrack("video", { timescale: Timescale.MILLI, priority, maxAge }); const uni = pair.client.incomingUnidirectionalStreams.getReader() as ReadableStreamDefaultReader< ReadableStream >; @@ -432,7 +434,7 @@ test("a FETCH fills never-cached and evicted history, then reuses the cache", as for (const version of VERSIONS) { for (const evicted of [false, true]) { using clock = manual(); - using fx = serve(version); + using fx = serve(version, undefined, undefined, null); if (evicted) { writeGroup(fx.track, 1n, ["1-0", "1-1", "1-2"]); await clock.advance(ms(CACHE_EXPIRY * 2)); @@ -527,7 +529,7 @@ test("a FETCH preserves relayed metadata and cached groups without upstream FETC test("a FETCH refused by its history responder sends no FETCH_OK", async () => { for (const version of VERSIONS) { - using fx = serve(version); + using fx = serve(version, undefined, undefined, null); writeGroup(fx.track, 3n, ["live"]); using requests = fx.track.requests(); const responding = (async () => { @@ -545,7 +547,7 @@ test("a cancelled or unauthorized FETCH withdraws its unanswered history fill", for (const version of VERSIONS) { for (const revoke of [false, true]) { const grant = new Signal(undefined); - using fx = serve(version, grant); + using fx = serve(version, grant, undefined, null); writeGroup(fx.track, 3n, ["live"]); using requests = fx.track.requests(); const requested = requests.requestedFill(); @@ -722,7 +724,8 @@ test("draft-18: a joining FETCH serves the head its subscription starts after", new FetchOk({ endOfTrack: false, endLocation: at(5, 3), - properties: { timescale: Timescale.MILLI, priority: 127, groupOrder: 0x2 }, + // The zero authored default max age, advertised as MAX_CACHE_DURATION. + properties: { timescale: Timescale.MILLI, priority: 127, groupOrder: 0x2, maxCacheDuration: 0n }, }), ); expect(head.requestId).toBe(FETCH_ID); diff --git a/js/net/src/ietf/publisher.test.ts b/js/net/src/ietf/publisher.test.ts index a4d14dac0d9..71bdabef1b2 100644 --- a/js/net/src/ietf/publisher.test.ts +++ b/js/net/src/ietf/publisher.test.ts @@ -2369,7 +2369,7 @@ async function readFill( test("draft-22: an absolute filter trims the range it serves", async () => { using clock = manual(); const fx = fixture(); - const track = fx.broadcast.createTrack("video", { timescale: Timescale.MILLI }); + const track = fx.broadcast.createTrack("video", { timescale: Timescale.MILLI, maxAge: null }); for (let i = 0; i < 4; i++) writeGroup(track, 3); const { client } = await runSubscribe( @@ -3553,7 +3553,7 @@ test("unsupported REQUEST_UPDATE is refused and ends with UPDATE_FAILED", async test("a SUBSCRIBE pauses without demand and resumes as a new subscriber", async () => { for (const startPaused of [false, true]) { const fx = fixture(V22); - const track = fx.broadcast.createTrack("video", { timescale: Timescale.MILLI }); + const track = fx.broadcast.createTrack("video", { timescale: Timescale.MILLI, maxAge: null }); const write = (text: string) => { const group = track.appendGroup(); group.writeFrame({ payload: new TextEncoder().encode(text), timestamp: Timestamp.now() }); @@ -3874,7 +3874,7 @@ test.each([0, Number.MAX_SAFE_INTEGER + 2])( test("draft-22: a range update replaces the live subscription bounds", async () => { const fx = fixture(); - const track = fx.broadcast.createTrack("video", { timescale: Timescale.MILLI }); + const track = fx.broadcast.createTrack("video", { timescale: Timescale.MILLI, maxAge: null }); const { client } = await runSubscribe( fx, new Subscribe({ diff --git a/js/net/src/ietf/subscriber.ts b/js/net/src/ietf/subscriber.ts index 14a9dc6f2bb..8b2652f68ab 100644 --- a/js/net/src/ietf/subscriber.ts +++ b/js/net/src/ietf/subscriber.ts @@ -1064,7 +1064,8 @@ export class Subscriber { const staged = hooks.stageRequest(request, { timescale: ok.properties.timescale, priority: fromWire(ok.properties.priority ?? DEFAULT_WIRE), - maxAge: cache === undefined ? undefined : Milli(Number(cache)), + // No MAX_CACHE_DURATION sets no publisher limit, not the authored default. + maxAge: cache === undefined ? null : Milli(Number(cache)), ietf: this.#session.version, }); producer = staged.producer; @@ -1592,7 +1593,8 @@ export class Subscriber { // No TIMESCALE means no timeline, and the track must not claim one when served onward. timescale: ok.properties.timescale, priority: fromWire(ok.properties.priority ?? DEFAULT_WIRE), - maxAge: maxCacheDuration === undefined ? undefined : Milli(Number(maxCacheDuration)), + // No MAX_CACHE_DURATION sets no publisher limit, not the authored default. + maxAge: maxCacheDuration === undefined ? null : Milli(Number(maxCacheDuration)), // A moq-transport peer may stamp arrival times, and nothing on the wire says it didn't. ietf: version, }); diff --git a/js/net/src/integration.test.ts b/js/net/src/integration.test.ts index 281d522de18..5e96b0dea34 100644 --- a/js/net/src/integration.test.ts +++ b/js/net/src/integration.test.ts @@ -349,7 +349,7 @@ test("integration: lite applies initial and updated group bounds", async () => { ]); const broadcast = publish(origin, Path.from("test")); - const producer = broadcast.createTrack("video", { timescale: Timescale.MILLI }); + const producer = broadcast.createTrack("video", { timescale: Timescale.MILLI, maxAge: null }); for (let sequence = 0n; sequence < GROUP_COUNT; sequence++) producer.appendGroup().finish(); const remote = wireOf(client).consume(Path.from("test")); @@ -470,7 +470,7 @@ test("integration: lite-07 serves sparse and relative ranges", async () => { ]); const broadcast = publish(origin, Path.from("test")); - const producer = broadcast.createTrack("video", { timescale: Timescale.MILLI }); + const producer = broadcast.createTrack("video", { timescale: Timescale.MILLI, maxAge: null }); for (let sequence = 0; sequence < 10; sequence++) producer.appendGroup().finish(); const remote = wireOf(client).consume(Path.from("test")); @@ -513,7 +513,7 @@ test("integration: lite-07 keeps a covered bounded subscription open", async () ]); const broadcast = publish(origin, Path.from("test")); - const producer = broadcast.createTrack("video", { timescale: Timescale.MILLI }); + const producer = broadcast.createTrack("video", { timescale: Timescale.MILLI, maxAge: null }); for (const sequence of [0n, 1n, 2n, 4n, 5n]) producer.createGroup(sequence).finish(); const remote = wireOf(client).consume(Path.from("test")); @@ -565,7 +565,7 @@ test("integration: lite-07 serves a time range", async () => { ]); const broadcast = publish(origin, Path.from("test")); - const producer = broadcast.createTrack("video", { timescale: Timescale.MICRO }); + const producer = broadcast.createTrack("video", { timescale: Timescale.MICRO, maxAge: null }); for (let sequence = 0; sequence < 10; sequence++) { const group = producer.appendGroup(); group.writeFrame(textFrame(`${sequence}`, Timestamp.fromMillis(sequence * 1000))); @@ -1164,7 +1164,7 @@ test("integration: lite draft-07 fetches a cached group", async () => { ]); const broadcast = publish(origin, Path.from("test")); - const producer = broadcast.createTrack("video", { timescale: Timescale.MILLI }); + const producer = broadcast.createTrack("video", { timescale: Timescale.MILLI, maxAge: null }); const group0 = producer.appendGroup(); group0.writeFrame({ payload: enc.encode("alpha"), timestamp: Timestamp.fromMillis(10) }); @@ -1407,6 +1407,51 @@ test("integration: lite draft-07 track info follows a republished broadcast", as server.abort(); }); +// An authored track omitting maxAge advertises the zero default, an explicit null advertises no +// limit, which a consumer decodes as absence, and a number goes out as itself. Before lite-05 +// nothing is carried, and a received track without one has no publisher limit. +test.each([Lite.ALPN_03, Lite.ALPN_05, Lite.ALPN_07_WIP, Ietf.ALPN.DRAFT_22])( + "integration: %s carries the authored max age default, null, and a value", + async (alpn) => { + const pair = createMockTransportPair(alpn); + const origin = new OriginProducer(); + const [client, server] = await Promise.all([ + connect(url, { transport: pair.client }), + accept(pair.server, url, { publish: origin.consume() }), + ]); + + const path = Path.from("test"); + const broadcast = publish(origin, path); + const tracks = { + omitted: broadcast.createTrack("omitted", { timescale: Timescale.MILLI }), + unlimited: broadcast.createTrack("unlimited", { timescale: Timescale.MILLI, maxAge: null }), + explicit: broadcast.createTrack("explicit", { timescale: Timescale.MILLI, maxAge: Milli(5000) }), + }; + expect((await tracks.omitted.info()).maxAge).toBe(Milli.zero); + expect((await tracks.unlimited.info()).maxAge).toBeUndefined(); + + const remote = wireOf(client).consume(path); + const info = async (name: string) => { + // moq-transport answers info through a subscription, so hold one open. + const sub = remote.track(name).subscribe(); + try { + return await withTimeout(sub.info(), Nano.fromMilli(Milli(5_000)), `${name} info`); + } finally { + sub.close(); + } + }; + const carried = alpn !== Lite.ALPN_03; + expect((await info("omitted")).maxAge).toBe(carried ? Milli.zero : undefined); + expect((await info("unlimited")).maxAge).toBeUndefined(); + expect((await info("explicit")).maxAge).toBe(carried ? Milli(5000) : undefined); + + broadcast.close(); + remote.close(); + client.abort(); + server.abort(); + }, +); + // FETCH reads the same cache to decide the timescale it serves frames in, so a stale entry // quantizes the successor's timestamps to the predecessor's resolution. test("integration: lite draft-07 fetch uses the republished track's timescale", async () => { @@ -1454,7 +1499,8 @@ test("integration: ietf fetches a past group of a finished track", async () => { const origin = new OriginProducer(); const publication = origin.createBroadcast(Path.from("test")); publication.announce(); - const published = publication.broadcast.createTrack("video", { timescale: Timescale.MILLI }); + // No publisher limit, so the superseded group stays fresh to fetch, and no MAX_CACHE_DURATION. + const published = publication.broadcast.createTrack("video", { timescale: Timescale.MILLI, maxAge: null }); for (let sequence = 0; sequence < 3; sequence++) { const group = published.appendGroup(); group.writeFrame({ @@ -1476,6 +1522,8 @@ test("integration: ietf fetches a past group of a finished track", async () => { expect(frame?.timestamp).toEqual(new Timestamp(1000, Timescale.MILLI)); expect(await group.readFrame()).toBeUndefined(); group.close(); + // The FETCH-only copy keeps the absent MAX_CACHE_DURATION as no limit, not the authored zero. + expect((await remote.track("video").info()).maxAge).toBeUndefined(); remote.close(); client.abort(); server.abort(); diff --git a/js/net/src/internal.ts b/js/net/src/internal.ts index f3a4526ad2c..bc994677a7d 100644 --- a/js/net/src/internal.ts +++ b/js/net/src/internal.ts @@ -16,7 +16,18 @@ import { isAnonymous, type Route } from "./hop.ts"; import type * as Instance from "./instance.ts"; import * as Path from "./path.ts"; import type { Timestamp } from "./time.ts"; -import type { Delay, Demand, Groups, Info, Position, Producer, Request, Subscriber, Subscription } from "./track.ts"; +import type { + Delay, + Demand, + Groups, + Info, + InfoInit, + Position, + Producer, + Request, + Subscriber, + Subscription, +} from "./track.ts"; import { max, min } from "./util/sequence.ts"; import * as Varint from "./varint.ts"; import type { Window } from "./window.ts"; @@ -495,7 +506,7 @@ export const hooks: { * Take a request's producer without resolving its subscribers, so content written before * {@link StagedTrack.commit} is there when the first reader looks; assigned by `track.ts`. */ - stageRequest: (request: Request, info: Partial) => StagedTrack; + stageRequest: (request: Request, info: InfoInit) => StagedTrack; /** The newest frame a producer's cache holds, read without subscribing; assigned by `track.ts`. */ cachedLargest: (producer: Producer) => Position | undefined; /** The publisher priority from a demanded track's committed {@link Info}; assigned by `track.ts`. */ diff --git a/js/net/src/lite/fetch.ts b/js/net/src/lite/fetch.ts index fb31a2ace68..cd22ff23bcf 100644 --- a/js/net/src/lite/fetch.ts +++ b/js/net/src/lite/fetch.ts @@ -23,7 +23,7 @@ export class Fetch { instance?: Instance.Valid; track: string; priority: number; - /** Reader freshness budget. Lite-07+ only; omission uses publisher retention alone. */ + /** Reader freshness budget. Lite-07+ only; omission leaves the publisher's max age as the only bound. */ maxDelay?: Milli; group: bigint; diff --git a/js/net/src/lite/publisher.test.ts b/js/net/src/lite/publisher.test.ts index caeb08eb484..9dd2a350cf1 100644 --- a/js/net/src/lite/publisher.test.ts +++ b/js/net/src/lite/publisher.test.ts @@ -272,7 +272,11 @@ async function groupSendOrders(options: { const publisher = new Publisher(pair.server, version, randomHop(), origin.consume()); const broadcast = publish(origin, Path.from("test")); - const track = broadcast.createTrack("video", { timescale: Timescale.MILLI, priority: options.publisher }); + const track = broadcast.createTrack("video", { + timescale: Timescale.MILLI, + priority: options.publisher, + maxAge: null, + }); const client = await Stream.open(pair.client, { version }); const server = await Stream.accept(pair.server, version); @@ -475,7 +479,7 @@ test("lite draft-05: many concurrent groups share one subscription listener", as const publisher = new Publisher(pair.server, Version.DRAFT_05, randomHop(), origin.consume()); const broadcast = publish(origin, Path.from("test")); - const track = broadcast.createTrack("video", { timescale: Timescale.MILLI }); + const track = broadcast.createTrack("video", { timescale: Timescale.MILLI, maxAge: null }); const client = await Stream.open(pair.client, { version: Version.DRAFT_05 }); const server = await Stream.accept(pair.server, Version.DRAFT_05); @@ -727,7 +731,8 @@ async function servedSubscription( } else { broadcast = publish(origin, Path.from("test")); } - const info = { timescale: Timescale.MILLI, maxAge: options.maxAge }; + // Unset is no publisher limit: these fixtures serve superseded groups. + const info = { timescale: Timescale.MILLI, maxAge: options.maxAge ?? null }; let track = options.pending ? undefined : broadcast.createTrack("video", info); for (const sequence of options.prefill ?? []) { if (!track) throw new Error("a pending track holds nothing to prefill"); @@ -2081,7 +2086,7 @@ test("blocked DROP responses stop opening later groups", async () => { const origin = new OriginProducer(); const publisher = new Publisher(pair.server, Version.DRAFT_07, randomHop(), origin.consume()); const broadcast = publish(origin, Path.from("test")); - const track = broadcast.createTrack("video", { timescale: Timescale.MILLI }); + const track = broadcast.createTrack("video", { timescale: Timescale.MILLI, maxAge: null }); const client = await Stream.open(pair.client, { version: Version.DRAFT_07 }); const server = await Stream.accept(pair.server, Version.DRAFT_07); if (!server) throw new Error("missing subscribe stream"); diff --git a/js/net/src/lite/subscriber.test.ts b/js/net/src/lite/subscriber.test.ts index 839354147c8..98d57de162d 100644 --- a/js/net/src/lite/subscriber.test.ts +++ b/js/net/src/lite/subscriber.test.ts @@ -1299,7 +1299,7 @@ test("a lite subscribe whose SUBSCRIBE write stalls past the deadline closes its }); // On lite-05 and later a SUBSCRIBE goes out beside its TRACK, before the TRACK_INFO, and accepting -// the info sends no SUBSCRIBE_UPDATE even when the publisher keeps groups for less than the +// the info sends no SUBSCRIBE_UPDATE even when the publisher keeps groups fresh for less than the // subscriber waits. test.each([Version.DRAFT_05, Version.DRAFT_06, Version.DRAFT_07])( "lite %s: a subscribe goes out with its track", diff --git a/js/net/src/lite/subscriber.ts b/js/net/src/lite/subscriber.ts index 15658cc6f19..74fabdc0a5c 100644 --- a/js/net/src/lite/subscriber.ts +++ b/js/net/src/lite/subscriber.ts @@ -1301,7 +1301,8 @@ export class Subscriber { if (!hasTrackStream(this.version)) { // Older drafts negotiate nothing per-track: verbatim frames with no timeline. const framing = { compress: false, timescale: 0, scale: undefined }; - const entry = this.#register(id, msg, ranges, request.accept(), framing, state); + // Nor a max age: no publisher limit, not the authored default. + const entry = this.#register(id, msg, ranges, request.accept({ maxAge: null }), framing, state); const stream = await this.#sendSubscribe(state, msg, deadline); // The first response MUST be a SUBSCRIBE_OK (older drafts only). const resp = await decodeSubscribeResponse(stream.reader, this.version); @@ -1345,7 +1346,8 @@ export class Subscriber { // accept it again. state.cancel.signal.throwIfAborted(); const model = this.#toModelInfo(answered.info); - const producer = request.accept(model); + // A TRACK_INFO without a max age sets no publisher limit, not the authored default. + const producer = request.accept({ ...model, maxAge: model.maxAge ?? null }); const framing = { compress: answered.info.compress, timescale: answered.info.timescale ?? 0, @@ -1399,7 +1401,7 @@ export class Subscriber { ...framing, // The effective max delay is the stopgap grace: the wrong clock (it bounds // presentation-time drift), but it is how long the subscriber was willing to wait - // for a late group anyway, and no longer than the publisher keeps one. + // for a late group anyway, and no longer than the publisher keeps one fresh. tail: new Tail({ grace: () => hooks.tailGrace(producer), }), diff --git a/js/net/src/lite/track.test.ts b/js/net/src/lite/track.test.ts index 62d14358343..c35c728589f 100644 --- a/js/net/src/lite/track.test.ts +++ b/js/net/src/lite/track.test.ts @@ -4,7 +4,7 @@ import { ProtocolViolation } from "../error.ts"; import * as Path from "../path.ts"; import { Reader, Writer } from "../stream.ts"; import { Timescale } from "../time.ts"; -import { infoDefaults } from "../track.ts"; +import { authoredInfo, infoDefaults } from "../track.ts"; import { Track, TrackInfo } from "./track.ts"; import { Version } from "./version.ts"; @@ -49,11 +49,12 @@ test("TrackInfo round-trips on draft-05", async () => { }); test("TrackInfo for Rust's default Info matches cross-language wire bytes", async () => { - // The default track is untimed, which lite-05 declares as milliseconds. - const model = infoDefaults(); + // The default authored track is untimed, which lite-05 declares as milliseconds, and + // advertises the default zero max age. + const model = authoredInfo(); const info = new TrackInfo({ ...model, timescale: model.timescale ?? undefined }); expect(await bytes((w) => info.encode(w, Version.DRAFT_05), Version.DRAFT_05)).toEqual( - new Uint8Array([0x0c, 0x80, 0x00, 0xc0, 0x1f, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0x43, 0xe8]), + new Uint8Array([0x05, 0x80, 0x00, 0x00, 0x43, 0xe8]), ); }); diff --git a/js/net/src/lite/version.ts b/js/net/src/lite/version.ts index 688c9956a2c..f18b3e0c7e1 100644 --- a/js/net/src/lite/version.ts +++ b/js/net/src/lite/version.ts @@ -309,7 +309,7 @@ export function hasRanges(version: Version): boolean { } /** Whether FETCH carries the subscriber's optional max delay. Added in lite-07; an earlier - * fetch is bounded by the publisher's retention alone. */ + * fetch is bounded by the publisher's max age alone. */ export function hasFetchMaxDelay(version: Version): boolean { // Explicitly list older versions so future versions keep the lite-07+ behavior. switch (version) { diff --git a/js/net/src/lite/widened_max_age.test.ts b/js/net/src/lite/widened_max_age.test.ts index d1f41fda63a..6bc779b4cb9 100644 --- a/js/net/src/lite/widened_max_age.test.ts +++ b/js/net/src/lite/widened_max_age.test.ts @@ -31,7 +31,7 @@ test("a widened maxDelay re-offers what the publisher skipped below the start", const publication = origin.createBroadcast(Path.from("room")); publication.announce(); const broadcast = publication.broadcast; - const producer = broadcast.createTrack("video", { timescale: Timescale.MILLI }); + const producer = broadcast.createTrack("video", { timescale: Timescale.MILLI, maxAge: null }); // One group per second, so a budget picks how far back a reader reaches. for (let sequence = 0; sequence < 10; sequence++) { const group = producer.appendGroup(); diff --git a/js/net/src/order.test.ts b/js/net/src/order.test.ts index ea3ba400207..c8442c43db0 100644 --- a/js/net/src/order.test.ts +++ b/js/net/src/order.test.ts @@ -122,7 +122,7 @@ async function backlog(protocol: string, order: Order, update?: Order) { const broadcastPublication = origin.createBroadcast(Path.from("test")); const broadcast = broadcastPublication.broadcast; broadcastPublication.announce(); - const video = broadcast.createTrack("video", { timescale: Timescale.MILLI }); + const video = broadcast.createTrack("video", { timescale: Timescale.MILLI, maxAge: null }); const groups = [0, 1, 2].map(() => writeGroup(video)); const remote = wireOf(client).consume(Path.from("test")); @@ -176,7 +176,7 @@ test.each(["ascending", "descending"] as const)("ietf serves GROUP_ORDER %s", as const broadcastPublication = origin.createBroadcast(Path.from("test")); const broadcast = broadcastPublication.broadcast; broadcastPublication.announce(); - const video = broadcast.createTrack("video", { timescale: Timescale.MILLI }); + const video = broadcast.createTrack("video", { timescale: Timescale.MILLI, maxAge: null }); const remote = wireOf(client).consume(Path.from("test")); const subscriber = remote.track("video").subscribe({ delay: { max: MAX_DELAY }, order }); @@ -244,7 +244,7 @@ test("ietf keeps a closing group stream ranked until it settles", async () => { const broadcastPublication = origin.createBroadcast(Path.from("test")); const broadcast = broadcastPublication.broadcast; broadcastPublication.announce(); - const video = broadcast.createTrack("video", { timescale: Timescale.MILLI }); + const video = broadcast.createTrack("video", { timescale: Timescale.MILLI, maxAge: null }); const remote = wireOf(client).consume(Path.from("test")); const subscriber = remote.track("video").subscribe({ delay: { max: MAX_DELAY }, order: "descending" }); @@ -285,7 +285,7 @@ test("a shared track aggregates descending and serves each subscriber in its own const broadcastPublication = origin.createBroadcast(Path.from("test")); const broadcast = broadcastPublication.broadcast; broadcastPublication.announce(); - const video = broadcast.createTrack("video", { timescale: Timescale.MILLI }); + const video = broadcast.createTrack("video", { timescale: Timescale.MILLI, maxAge: null }); const ascendingRemote = wireOf(ascending.client).consume(Path.from("test")); const ascendingTrack = ascendingRemote.track("video").subscribe({ delay: { max: MAX_DELAY }, order: "ascending" }); diff --git a/js/net/src/parked-expiry.test.ts b/js/net/src/parked-expiry.test.ts index 448dce3f1ad..4888591407c 100644 --- a/js/net/src/parked-expiry.test.ts +++ b/js/net/src/parked-expiry.test.ts @@ -33,7 +33,8 @@ for (const protocol of protocols) { const broadcastPublication = origin.createBroadcast(Path.from("parked")); const broadcast = broadcastPublication.broadcast; broadcastPublication.announce(); - const track = broadcast.createTrack("video", { timescale: Timescale.MILLI }); + // No publisher limit, so the cache eviction rather than a stale verdict ends a long budget. + const track = broadcast.createTrack("video", { timescale: Timescale.MILLI, maxAge: null }); const write = (sequence: bigint) => { const group = track.createGroup(sequence); group.writeFrame({ payload: new Uint8Array([1]), timestamp: Timestamp.fromMillis(0) }); diff --git a/js/net/src/resume.model.test.ts b/js/net/src/resume.model.test.ts index f4e56b67cd4..b40633d5c17 100644 --- a/js/net/src/resume.model.test.ts +++ b/js/net/src/resume.model.test.ts @@ -455,7 +455,7 @@ class Model { }); const serving = wireOf(this.origin).receive(PATH, route); const broadcast = new BroadcastProducer(); - const producer = broadcast.createTrack("video", { timescale: Timescale.MILLI }); + const producer = broadcast.createTrack("video", { timescale: Timescale.MILLI, maxAge: null }); void (async () => { for await (const request of serving.requested()) { request.serve(Upstream.of(broadcast, (sequence, local) => this.fill(instance, slot, sequence, local))); diff --git a/js/net/src/resume.test.ts b/js/net/src/resume.test.ts index 6b23ae0951e..494ebdb95ec 100644 --- a/js/net/src/resume.test.ts +++ b/js/net/src/resume.test.ts @@ -46,9 +46,12 @@ function serve(origin: Producer, source: BroadcastProducer, cost: bigint) { return () => handle.close(); } -/** A copy of the logical track: every route's copy holds the same groups under the same sequences. */ +/** + * A copy of the logical track: every route's copy holds the same groups under the same sequences. + * Resumed readers backfill superseded groups, so it sets no publisher limit. + */ function copy(source: BroadcastProducer) { - const producer = source.createTrack("seq"); + const producer = source.createTrack("seq", { maxAge: null }); return { producer, write(sequence: bigint, frames = 1, close = true) { @@ -485,13 +488,13 @@ test("a lagging same-instance replica resumes from one publisher's bytes exactly const originalPublication = publisher.createBroadcast(path); const original = originalPublication.broadcast; originalPublication.announce({ instance: INSTANCE }); - const source = original.createTrack("seq"); + const source = original.createTrack("seq", { maxAge: null }); const origin = new Producer(); // Both replicas forward this one source. Only the incumbent pauses mid-group. function replica(lagging: boolean) { const broadcast = new BroadcastProducer(); - const output = broadcast.createTrack("seq"); + const output = broadcast.createTrack("seq", { maxAge: null }); const input = source.subscribe({ delay: { max: Milli(60_000) } }); const release = Promise.withResolvers(); let stopped = false; @@ -740,7 +743,7 @@ for (const [name, before, after] of [ // `unchecked` records how a copy arrived (lite-05/06), so it splices beside a lite-07 copy. test("a replacement differing only in unchecked takes over", async () => { const { a, b, swap, active, close } = await setup(); - const old = a.createTrack("seq", { unchecked: true }); + const old = a.createTrack("seq", { unchecked: true, maxAge: null }); const tb = copy(b); const sub = active.track("seq").subscribe(); await sub.info(); @@ -2144,7 +2147,7 @@ test("a fetch still out on the old route moves to the new one", async () => { const a = new BroadcastProducer(); const b = new BroadcastProducer(); // a has the track but not group 5 yet, so its fetch waits on a's request handler. - const pending = a.createTrack("seq").requests(); + const pending = a.createTrack("seq", { maxAge: null }).requests(); const tb = copy(b); tb.write(5n); front.serve(a.consume()); diff --git a/js/net/src/tail.test.ts b/js/net/src/tail.test.ts index 5b7fa87b252..b7dde35ea7a 100644 --- a/js/net/src/tail.test.ts +++ b/js/net/src/tail.test.ts @@ -29,7 +29,7 @@ async function session(protocol: string) { const broadcastPublication = origin.createBroadcast(Path.from("test")); const broadcast = broadcastPublication.broadcast; broadcastPublication.announce(); - const video = broadcast.createTrack("video", { timescale: Timescale.MILLI }); + const video = broadcast.createTrack("video", { timescale: Timescale.MILLI, maxAge: null }); const remote = wireOf(client).consume(Path.from("test")); const reader = remote .track("video") diff --git a/js/net/src/track.test.ts b/js/net/src/track.test.ts index abad37e2ff9..4ee9915c6b7 100644 --- a/js/net/src/track.test.ts +++ b/js/net/src/track.test.ts @@ -9,7 +9,7 @@ import { Version as IetfVersion } from "./ietf/version.ts"; import { hooks } from "./internal.ts"; import { textFrame } from "./mock.ts"; import { Timescale, Timestamp } from "./time.ts"; -import { infoDefaults, rescale, Subscription, Producer as TrackProducer } from "./track.ts"; +import { authoredInfo, infoDefaults, rescale, Subscription, Producer as TrackProducer } from "./track.ts"; import { unwanted } from "./util/demand.ts"; const enc = new TextEncoder(); @@ -59,9 +59,10 @@ function manualTime(initial: number) { }; } -// A session-fed copy owes holes; an in-process producer does not. +// A session-fed copy owes holes; an in-process producer does not. Received without a max age, +// it has no publisher limit, as a decoded TRACK_INFO without one does. function receivedTrack(info: Parameters[0] = {}) { - const producer = new TrackProducer("test").accept(info); + const producer = new TrackProducer("test").accept({ maxAge: null, ...info }); hooks.receiveTrack(producer); return producer; } @@ -840,6 +841,54 @@ test("infoDefaults re-validates timescale and the safe maxAge bound", () => { expect(() => infoDefaults({ maxAge: Milli(Number.MAX_SAFE_INTEGER + 1) })).toThrow(RangeError); }); +test("an authored track defaults to a zero max age, null is unlimited, and decoded absence stays unlimited", async () => { + expect((await new TrackProducer("omitted").accept().info()).maxAge).toBe(Milli.zero); + expect((await new TrackProducer("undefined").accept({ maxAge: undefined }).info()).maxAge).toBe(Milli.zero); + expect((await new TrackProducer("unlimited").accept({ maxAge: null }).info()).maxAge).toBeUndefined(); + expect((await new TrackProducer("explicit").accept({ maxAge: Milli(5000) }).info()).maxAge).toBe(Milli(5000)); + expect(authoredInfo({ maxAge: null }).maxAge).toBeUndefined(); + // Decoded metadata has no authored default: absence is no publisher limit. + expect(infoDefaults({}).maxAge).toBeUndefined(); + expect(infoDefaults({ maxAge: undefined }).maxAge).toBeUndefined(); +}); + +// The catalog relies on this: a track that publishes one snapshot and never changes it stays +// readable to a viewer joining long after, despite the zero default max age, since only a +// superseded group goes stale and the live edge is exempt from the payload cache window. +test("a sole snapshot stays readable to a late joiner at the zero default max age", async () => { + const clock = manualTime(10_000); + const producer = new TrackProducer("catalog").accept({ timescale: Timescale.MILLI, compress: true }); + try { + expect((await producer.info()).maxAge).toBe(Milli.zero); + const group = producer.appendGroup(); + group.writeFrame(textFrame("snapshot", Timestamp.fromMillis(0))); + group.finish(); + + // Well past the payload cache window. + await clock.advance(10_000 + 10 * CACHE_WINDOW_MS); + for (const delay of [undefined, { max: null }] as const) { + const late = producer.subscribe(delay ? { delay } : undefined); + const joined = late.tryRecvGroup(); + if (!joined) throw new Error("the sole snapshot was not served"); + expect(joined.sequence).toBe(0n); + expect(await joined.readString()).toBe("snapshot"); + late.close(); + } + + // A declared end keeps the track open, so its former edge is still exempt. + producer.finish(); + await clock.advance(10_000 + 20 * CACHE_WINDOW_MS); + const late = producer.subscribe(); + const joined = late.tryRecvGroup(); + if (!joined) throw new Error("the finished snapshot was not served"); + expect(await joined.readString()).toBe("snapshot"); + late.close(); + } finally { + producer.close(); + clock.installed.close(); + } +}); + test("multiple subscriber options aggregate like Rust", async () => { const producer = new TrackProducer("test"); const bounded = producer.subscribe({ @@ -1039,7 +1088,7 @@ test("a copy over a wire without ranges refuses a relative anchor it cannot carr test("a time range reads the groups containing its times, settling its end as groups start", () => { const producer = new TrackProducer("test"); - producer.accept({ timescale: Timescale.MILLI }); + producer.accept({ timescale: Timescale.MILLI, maxAge: null }); const start = (sequence: bigint, millis: number) => { const group = producer.createGroup(sequence); group.writeFrame(textFrame(`${sequence}`, Timestamp.fromMillis(millis))); @@ -1090,7 +1139,7 @@ test("a datagram is judged against a time range by its own timestamp", () => { test("a time start waits on groups below a reached end that have yet to start", () => { for (const order of ["ascending", "descending"] as const) { const producer = new TrackProducer("test"); - producer.accept({ timescale: Timescale.MILLI }); + producer.accept({ timescale: Timescale.MILLI, maxAge: null }); const groups = [0n, 1n, 2n].map((sequence) => producer.createGroup(sequence)); producer.finishAt({ group: 3n, frame: 0 }); const subscription = { delay: { max: null }, order, ranges: [{ start: { time: Timestamp.fromMillis(1500) } }] }; @@ -1184,7 +1233,7 @@ test("the producer aggregate is not clamped to the track's maxAge", () => { expect(producer.subscription.peek()).toEqual(before); expect(producer.subscription.peek()?.delay?.max).toBe(Milli(10_000)); expect(track.subscription.peek()?.delay?.max).toBe(Milli(10_000)); - // A late group is waited for no longer than the publisher keeps it. + // A late group is waited for no longer than the publisher keeps it fresh. expect(hooks.tailGrace(producer)).toBe(Milli(2_000)); }); @@ -1228,7 +1277,7 @@ test("nextGroup returns buffered groups in sequence", async () => { test.each([false, true])("a reordered tail keeps the group PTS drift verdict (B-frame: %s)", async (reordered) => { const clock = manualTime(0); try { - const producer = new TrackProducer("test").accept({ timescale: Timescale.MILLI }); + const producer = new TrackProducer("test").accept({ timescale: Timescale.MILLI, maxAge: null }); const subscriber = producer.subscribe({ delay: { max: Milli(80) } }); for (const ms of [0, 100]) { const group = producer.appendGroup(); @@ -1469,7 +1518,7 @@ test("an omitted delay is the default zero, and a null max sets no limit", async expect((await bare.recvGroup())?.sequence).toBe(2n); expect(producer.subscription.peek()?.delay?.max).toBe(Milli.zero); - // An explicit null leaves the publisher's retention as the only bound. + // An explicit null leaves the publisher's max age as the only bound. const unlimited = producer.subscribe({ delay: { max: null } }); for (const sequence of [0n, 1n, 2n]) expect((await unlimited.recvGroup())?.sequence).toBe(sequence); expect(producer.subscription.peek()?.delay?.max).toBe(Milli(Number.MAX_SAFE_INTEGER)); @@ -1772,7 +1821,7 @@ test("a frame still being written is judged against the budget", async () => { // group it read whole abandons the stream once the budget gives up on the group. test("a fully read group still reports its expiry", async () => { const clock = manualTime(10_000); - const producer = new TrackProducer("test").accept({ timescale: Timescale.MILLI }); + const producer = new TrackProducer("test").accept({ timescale: Timescale.MILLI, maxAge: null }); try { const track = producer.subscribe({ delay: { max: Milli(1000) } }); const source = producer.appendGroup(); @@ -1846,7 +1895,7 @@ test("a stalled track serves only its newest group", () => { // clock still does. test("frozen timestamps still age out by wall clock", () => { const clock = manualTime(10_000); - const producer = new TrackProducer("test").accept({ timescale: Timescale.MILLI }); + const producer = new TrackProducer("test").accept({ timescale: Timescale.MILLI, maxAge: null }); const frame = () => producer.writeFrame({ payload: enc.encode("x"), timestamp: Timestamp.fromMillis(0) }); try { frame(); @@ -1872,7 +1921,7 @@ test("frozen timestamps still age out by wall clock", () => { // clock can. test("a startup burst ages out by media time", () => { const clock = manualTime(10_000); - const producer = new TrackProducer("test").accept({ timescale: Timescale.MILLI }); + const producer = new TrackProducer("test").accept({ timescale: Timescale.MILLI, maxAge: null }); try { for (let second = 0; second < 5; second++) { producer.writeFrame({ payload: enc.encode("x"), timestamp: Timestamp.fromMillis(second * 1000) }); @@ -1892,7 +1941,7 @@ test("a startup burst ages out by media time", () => { test("a parked read wakes at its wall deadline", async () => { for (const timescale of [undefined, Timescale.MILLI]) { const clock = manualTime(10_000); - const producer = new TrackProducer("test").accept({ timescale }); + const producer = new TrackProducer("test").accept({ timescale, maxAge: null }); try { const track = producer.subscribe({ delay: { max: Milli(1000) } }); const held = producer.appendGroup(); @@ -1929,7 +1978,7 @@ test("a parked read wakes at its wall deadline", async () => { // a failure: the held group is still judged by that successor's arrival, not the next one's. test("an evicted successor with unread frames still starts the wall clock", async () => { const clock = manualTime(10_000); - const producer = new TrackProducer("test").accept({ timescale: Timescale.MILLI }); + const producer = new TrackProducer("test").accept({ timescale: Timescale.MILLI, maxAge: null }); try { const budget = 2 * CACHE_WINDOW_MS; const track = producer.subscribe({ delay: { max: Milli(budget) } }); @@ -1971,7 +2020,7 @@ test("an evicted successor with unread frames still starts the wall clock", asyn // guard looks again, rather than convicting by the failed one's arrival. test("a failed successor hands the wall clock on after the cache evicts it", async () => { const clock = manualTime(10_000); - const producer = new TrackProducer("test").accept({ timescale: Timescale.MILLI }); + const producer = new TrackProducer("test").accept({ timescale: Timescale.MILLI, maxAge: null }); try { const budget = 2 * CACHE_WINDOW_MS; const track = producer.subscribe({ delay: { max: Milli(budget) } }); @@ -2018,7 +2067,7 @@ test("a failed successor hands the wall clock on after the cache evicts it", asy test("a run of empty groups ages out by wall clock", () => { const RUN = 1000; const clock = manualTime(10_000); - const producer = new TrackProducer("test").accept({ timescale: Timescale.MILLI }); + const producer = new TrackProducer("test").accept({ timescale: Timescale.MILLI, maxAge: null }); try { const track = producer.subscribe({ delay: { max: Milli(1000) } }); producer.writeFrame({ payload: enc.encode("x"), timestamp: Timestamp.fromMillis(0) }); @@ -2170,7 +2219,7 @@ test("an idle live edge ages out once a newer group arrives", async () => { test("an abandoned open group ages out with no further write", async () => { const clock = manualTime(10_000); - const producer = new TrackProducer("test").accept({ timescale: Timescale.MILLI }); + const producer = new TrackProducer("test").accept({ timescale: Timescale.MILLI, maxAge: null }); try { // A budget past the cache window, so the eviction rather than the budget ends it. const track = producer.subscribe({ delay: { max: Milli(2 * CACHE_WINDOW_MS) } }); @@ -3029,7 +3078,7 @@ test("largest stays ended when the bounds widen", async () => { // A reader that starts at the largest group while it is still empty is at the live edge: it // gets that group, which ends with nothing, then the next one. test("a live-edge reader starts on an empty largest group", async () => { - const producer = new TrackProducer("test").accept({ timescale: Timescale.MILLI }); + const producer = new TrackProducer("test").accept({ timescale: Timescale.MILLI, maxAge: null }); const first = producer.appendGroup(); first.writeFrame({ payload: enc.encode("a"), timestamp: Timestamp.now() }); first.finish(); @@ -3295,11 +3344,11 @@ test("finished rejects when the track aborts or closes without an end", async () expect(await reader.finished()).toEqual({ group: 1n, frame: 0 }); }); -// Rust applies the pool's idle expiry with `max_age: None` too: omitting the publisher -// limit only removes the media-time clamp, never the wall-clock bound on memory. -test("an omitted publisher limit still ages idle groups out", async () => { +// Rust applies the pool's idle expiry with `max_age: None` too: no publisher limit only +// removes the media-time clamp, never the wall-clock bound on memory. +test("no publisher limit still ages idle groups out", async () => { const clock = manualTime(10_000); - const producer = new TrackProducer("unlimited").accept({ timescale: Timescale.MILLI }); + const producer = new TrackProducer("unlimited").accept({ timescale: Timescale.MILLI, maxAge: null }); try { const source = producer.appendGroup(); source.writeFrame(textFrame("old")); @@ -3594,7 +3643,7 @@ function drain(track: { tryRecvGroup(): GroupConsumer | undefined }): bigint[] { /** An untimed track holding `count` single-frame groups. */ function untimedTrack(count: number): TrackProducer { - const producer = new TrackProducer("test").accept({}); + const producer = new TrackProducer("test").accept({ maxAge: null }); for (let i = 0; i < count; i++) producer.writeFrame({ payload: enc.encode(`${i}`) }); return producer; } @@ -3655,7 +3704,7 @@ test("unknown track metadata keeps presentation-time expiry until accepted", () // No wall time passes. Until metadata is accepted, buffered timestamps still // prove that the two oldest groups are outside this reader's media budget. expect(drain(producer.subscribe({ delay: { max: Milli(500) } }))).toEqual([2n, 3n]); - producer.accept({ timescale: Timescale.MILLI }); + producer.accept({ timescale: Timescale.MILLI, maxAge: null }); expect(drain(producer.subscribe({ delay: { max: Milli(500) } }))).toEqual([2n, 3n]); } finally { producer.finish(); @@ -3669,7 +3718,7 @@ test("unknown track metadata keeps presentation-time expiry until accepted", () // successor arrived a full budget ago. test("an untimed subscriber starts at the oldest fresh group", () => { const clock = manualTime(10_000); - const producer = new TrackProducer("test").accept({}); + const producer = new TrackProducer("test").accept({ maxAge: null }); try { // Group N's successor arrives N + 1 seconds in. for (let i = 0; i < 5; i++) { @@ -3715,7 +3764,7 @@ 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 producer = new TrackProducer("test").accept({ maxAge: null }); const subscriber = producer.subscribe({ delay: { max: Milli(60_000) } }); // A timestamped frame is refused by an untimed track. expect(() => producer.writeFrame({ payload: enc.encode("x"), timestamp: Timestamp.fromMillis(1) })).toThrow( @@ -3784,7 +3833,7 @@ test("a group ended by a cancel or cache policy is a hole, not a drop", async () }); test("an upstream drop ends a group still arriving with its error", async () => { - const producer = new TrackProducer("video").accept({}); + const producer = new TrackProducer("video").accept({ maxAge: null }); const reader = producer.subscribe({ delay: { max: Milli(60_000) } }); const arriving = producer.createGroup(3n); arriving.writeFrame({ payload: enc.encode("3") }); @@ -4194,7 +4243,7 @@ test("an untimed track takes groups in any order", () => { }); test("replay and backlogs deliver sparse out-of-order arrivals ascending without sorting", () => { - const producer = new TrackProducer("test").accept({}); + const producer = new TrackProducer("test").accept({ maxAge: null }); const all = { ranges: [{ start: { absolute: 0n } }], delay: { max: null } }; const write = (sequence: bigint) => { const group = producer.createGroup(sequence); @@ -4498,7 +4547,7 @@ for (const abort of [false, true]) { // A widened budget re-offers the cached groups the reader skipped as stale, and never one it // already handed out. test("a widened maxDelay re-offers what it skipped as stale", () => { - const producer = new TrackProducer("test").accept({ timescale: Timescale.MILLI }); + const producer = new TrackProducer("test").accept({ timescale: Timescale.MILLI, maxAge: null }); const subscriber = producer.subscribe({ delay: { max: Milli(1500) } }); stampGroup(producer, 0n, 0); expect(drainGroups(subscriber)).toEqual([0n]); @@ -4521,7 +4570,7 @@ test("a widened maxDelay re-offers what it skipped as stale", () => { // A read already parked when the budget widens wakes for the re-offer. test("a widened maxDelay wakes a parked read", async () => { - const producer = new TrackProducer("test").accept({ timescale: Timescale.MILLI }); + const producer = new TrackProducer("test").accept({ timescale: Timescale.MILLI, maxAge: null }); const subscriber = producer.subscribe({ delay: { max: Milli(1500) } }); stampGroup(producer, 0n, 0); expect(drainGroups(subscriber)).toEqual([0n]); @@ -4574,7 +4623,7 @@ test("an evicted stale skip lets the delivered gaps fold", () => { // A re-offer never hands out a group below a floor raised in the same update. test("a widened maxDelay re-offers nothing below a raised floor", () => { - const producer = new TrackProducer("test").accept({ timescale: Timescale.MILLI }); + const producer = new TrackProducer("test").accept({ timescale: Timescale.MILLI, maxAge: null }); const subscriber = producer.subscribe({ delay: { max: Milli(1500) } }); stampGroup(producer, 0n, 0); expect(drainGroups(subscriber)).toEqual([0n]); @@ -4597,7 +4646,7 @@ test("a widened maxDelay re-offers nothing below a raised floor", () => { // its group, so the reader never gets both the group and its drop. for (const reported of [false, true]) { test(`a widened maxDelay re-offers a stale group after its drop was ${reported ? "reported" : "pending"}`, () => { - const producer = new TrackProducer("test").accept({ timescale: Timescale.MILLI }); + const producer = new TrackProducer("test").accept({ timescale: Timescale.MILLI, maxAge: null }); const subscriber = producer.subscribe({ delay: { max: Milli(1500) } }); expect(hooks.tryDrop(subscriber)).toBeUndefined(); stampGroup(producer, 0n, 0); @@ -4627,7 +4676,7 @@ for (const reported of [false, true]) { // A widening that covers only the newer of two skipped groups hands it out without folding the // older one into the delivered floor: a further widening still re-offers it. test("a partial maxDelay widening keeps the older skip owed", () => { - const producer = new TrackProducer("test").accept({ timescale: Timescale.MILLI }); + const producer = new TrackProducer("test").accept({ timescale: Timescale.MILLI, maxAge: null }); const subscriber = producer.subscribe({ delay: { max: Milli(1500) } }); stampGroup(producer, 0n, 0); expect(drainGroups(subscriber)).toEqual([0n]); @@ -4699,7 +4748,7 @@ test("reading a shed frame head requests refresh", async () => { // An end declared with an error keeps the history below it: a reader gets every group, then the // error, even one arriving after the producer closed. test("an errored end keeps its history", async () => { - const producer = new TrackProducer("test").accept({ timescale: Timescale.MILLI }); + const producer = new TrackProducer("test").accept({ timescale: Timescale.MILLI, maxAge: null }); for (const sequence of [0n, 1n]) { const group = producer.createGroup(sequence); group.writeFrame(textFrame("a", Timestamp.fromMillis(Number(sequence)))); diff --git a/js/net/src/track.ts b/js/net/src/track.ts index ac1237ceaa2..e2b051eafdc 100644 --- a/js/net/src/track.ts +++ b/js/net/src/track.ts @@ -134,7 +134,7 @@ export interface Position { /** * A track's immutable publisher properties, fixed for the lifetime of the track. * - * A producer declares these once (via {@link Request.accept} or + * A producer declares these once from an {@link InfoInit} (via {@link Request.accept} or * {@link Producer.accept}); a consumer awaits them via {@link Subscriber.info} * (resolved from the wire TRACK_INFO on lite-05+). They map 1:1 onto TRACK_INFO. */ @@ -157,10 +157,13 @@ export interface Info { * stale once either clock reaches the budget: the wall-clock time since its successor * arrived at this hop, or how far its successor's first timestamp trails the live edge. * The newest group is never stale, and an untimed track is judged by the wall clock alone. - * Reported in TRACK_INFO (Lite05+) so relays re-serve with the same bound. Omission sets - * no publisher limit; zero serves only the live edge. This clamps each subscriber budget. - * Rounded up to a whole millisecond by {@link infoDefaults}, which refuses a negative - * or non-finite value and a result past `Number.MAX_SAFE_INTEGER`. + * Reported in TRACK_INFO (Lite05+) so relays re-serve with the same bound. Absence sets + * no publisher limit, as on a track received without one; zero serves only the live edge. + * This clamps each subscriber budget. An authored track gets zero unless its + * {@link InfoInit.maxAge} asks for more. A freshness bound, not retention: a hop's cache + * bounds the bytes it keeps with its own window. Rounded up to a whole millisecond by + * {@link infoDefaults}, which refuses a negative or non-finite value and a result past + * `Number.MAX_SAFE_INTEGER`. */ maxAge?: Milli; /** Tie-break priority between subscriptions of equal subscriber priority (`-128..=127`, higher first). Defaults to `0`. */ @@ -183,6 +186,31 @@ export interface Info { unchecked?: boolean; } +/** + * What an author supplies to create a track: any {@link Info} field, each defaulting as + * {@link infoDefaults} does, except {@link maxAge}. + * + * Received metadata is an {@link Info}, whose absent `maxAge` means no publisher limit. To serve + * one onward unchanged, pass `{ ...info, maxAge: info.maxAge ?? null }`. + */ +export interface InfoInit extends Partial> { + /** + * The publisher max age; see {@link Info.maxAge}. Omitted or `undefined` is zero, so readers + * get only the live edge; `null` sets no publisher limit (the wire omits it), and a number + * is that bound. A track whose readers reach back for superseded groups sets it explicitly. + */ + maxAge?: Milli | null; +} + +/** + * Resolve an author's {@link InfoInit} into the {@link Info} a producer commits. + * @internal + */ +export function authoredInfo(init: InfoInit = {}): Info { + const { maxAge, ...rest } = init; + return infoDefaults({ ...rest, maxAge: maxAge === undefined ? Milli.zero : (maxAge ?? undefined) }); +} + export { rescale }; // Normalize a duration for the wire, which carries it as an unsigned varint. @@ -209,7 +237,11 @@ function priorityValue(value: number): number { return value; } -/** Fill in any unset {@link Info} fields with their defaults. */ +/** + * Fill in any unset {@link Info} fields with their defaults, as for received metadata: an absent + * `maxAge` stays absent, meaning no publisher limit. An authored track resolves its + * {@link InfoInit} at {@link Producer.accept} instead, where an omitted `maxAge` is zero. + */ export function infoDefaults(info: Partial = {}): Info { if (info.compress !== undefined && typeof info.compress !== "boolean") throw new TypeError("compress must be a boolean"); @@ -484,14 +516,14 @@ export class Request { } /** - * Accept the request, committing the track's immutable {@link Info}. Throws, rejecting the - * request, if `info` is invalid. + * Accept the request, committing the track's immutable {@link Info}, resolved as + * {@link Producer.accept} does. Throws, rejecting the request, if `info` is invalid. */ - accept(info: Partial = {}): Producer { + accept(info: InfoInit = {}): Producer { return this.#stage(info).commit(); } - #stage(info: Partial): StagedTrack { + #stage(info: InfoInit): StagedTrack { this.#pending.delete(this); const producer = this.#producer; return { @@ -520,7 +552,7 @@ export interface FetchGroupOptions { /** Delivery priority for the fetch stream. Defaults to `0`. */ priority?: number; - /** Maximum age behind the live edge this caller accepts. Omission uses publisher retention alone. */ + /** Maximum age behind the live edge this caller accepts. Omission leaves the publisher's {@link Info.maxAge} as the only bound. */ maxDelay?: Milli; /** @@ -559,7 +591,8 @@ export class Consumer { * {@link Delay.max} is what asks for data: delivery skips everything in range that the budget * convicts. Without options this is {@link Subscription.default}, whose budget of zero * delivers only the latest group; a larger one reaches back over what it can still use, and - * `delay: { max: null }` reaches back as far as the publisher retains. + * `delay: { max: null }` reaches back over every group the publisher's {@link Info.maxAge} still + * considers fresh. */ subscribe(options?: Subscription): Subscriber { return this.#broadcast.subscribe(this.name, options); @@ -946,7 +979,10 @@ export class Producer { this.#fills = new FillState({ name, accept: (sequence, info) => { - if (info !== undefined && this.#state.info.peek() === undefined) this.accept(info); + // A fill's info is the publisher's metadata, whose absent maxAge means no publisher + // limit, not an authored track's zero. + if (info !== undefined && this.#state.info.peek() === undefined) + this.accept({ ...info, maxAge: info.maxAge ?? null }); return this.#createGroup(sequence, 0); }, drop: (start, end, error) => this.#drop(start, end, error), @@ -1162,10 +1198,13 @@ export class Producer { return this.#state.update; } - /** Commit the immutable publisher properties, resolving {@link info}. Returns `this`. */ - accept(info: Partial = {}): this { + /** + * Commit the immutable publisher properties, resolving {@link info}. An omitted `maxAge` is + * zero, the live edge only; see {@link InfoInit.maxAge}. Returns `this`. + */ + accept(info: InfoInit = {}): this { if (this.#state.closed.peek() !== undefined) return this; - const resolved = infoDefaults(info); + const resolved = authoredInfo(info); // Anything written before accept() must match too. A mismatch closes the track, so // nothing waiting on info() hangs on a half-bound cache. try { @@ -1212,7 +1251,8 @@ export class Producer { * {@link Delay.max} is what asks for data: delivery skips everything in range that the budget * convicts. Without options this is {@link Subscription.default}, whose budget of zero * delivers only the latest group; a larger one reaches back over what it can still use, and - * `delay: { max: null }` reaches back as far as the publisher retains. + * `delay: { max: null }` reaches back over every group the publisher's {@link Info.maxAge} still + * considers fresh. */ subscribe(options: Subscription = Subscription.default()): Subscriber { const sink = new TrackState(options); @@ -1854,7 +1894,7 @@ export class Producer { } // The grace the session's tail uses, from the max delay the track's subscribers ask for, - // bounded by how long the publisher keeps a group. The demand asked upstream is not. + // bounded by how long the publisher keeps a superseded group fresh. The demand asked upstream is not. #grace(): Milli { const update = this.#state.update.peek(); const maxDelay = update ? maxDelayOf(update) : Milli.zero; @@ -2102,7 +2142,7 @@ export class Subscriber { // and end. A group inside it is read only if the window contains it too. #cursor = new Signal<{ start: bigint; end?: bigint }>({ start: 0n }); // A FETCH's own budget in place of the subscription's; unlike SUBSCRIBE's zero - // default, an omitted one is unbounded, leaving publisher retention alone. + // default, an omitted one is unbounded, leaving the publisher's maxAge as the only bound. #fetchBudget?: number; // Which cursor owns this subscription. Both cursors draw from one buffer, so the // first group read commits the track to arrival order and {@link ordered} commits @@ -2167,10 +2207,10 @@ export class Subscriber { const update = this.#state.update.peek(); const requested = this.#fetchBudget ?? (update ? maxDelayOf(update) : 0); - const retained = info?.maxAge; + const fresh = info?.maxAge; return { - budget: retained === undefined ? requested : Math.min(requested, retained), - bounded: retained !== undefined && requested >= retained, + budget: fresh === undefined ? requested : Math.min(requested, fresh), + bounded: fresh !== undefined && requested >= fresh, presentation, end, }; diff --git a/js/publish/MIGRATE.md b/js/publish/MIGRATE.md index 2392c69ddd8..781cafe6847 100644 --- a/js/publish/MIGRATE.md +++ b/js/publish/MIGRATE.md @@ -4,6 +4,12 @@ How to update your code for each breaking change, newest first. ## Unreleased +### `maxAge: null` is unlimited, and the catalog takes the zero default ([#7729](https://github.com/moq-dev/moq/pull/7729)) + +`Broadcast`'s `maxAge` input accepts `null` for no publisher limit on its media tracks; omitted is still 30 seconds (`Container.MAX_AGE` from `@moq/hang`). With `null`, on-demand audio keeps 30 seconds of raw PCM, since raw history needs a finite bound. +The catalog track now advertises `@moq/net`'s zero default instead of `Number.MAX_SAFE_INTEGER`, as Rust's catalog does. A late viewer still reads an unchanged catalog, since only a superseded group goes stale. +Tracks an application creates on `broadcast.net` follow `@moq/net` and default to a zero max age; pass `maxAge: null` (or a window) where readers reach back for history. + ### The catalog declares `media.join.interval` and moves `clock` to `media.clock` ([#7652](https://github.com/moq-dev/moq/pull/7652)) `Broadcast.catalog` advertises the page's wall-clock mapping as `media.clock` instead of the root `clock`; read `catalog.media?.clock` in a `mutate` callback. diff --git a/js/publish/api/index.api.md b/js/publish/api/index.api.md index 9c63dd9a9b3..9ecb9d909da 100644 --- a/js/publish/api/index.api.md +++ b/js/publish/api/index.api.md @@ -138,7 +138,7 @@ export type BroadcastInput = { echo: Signals.Getter; enabled: Signals.Getter; flip: Signals.Getter; - maxAge: Signals.Getter; + maxAge: Signals.Getter; name: Signals.Getter; onDemand: Signals.Getter; origin: Signals.Getter; diff --git a/js/publish/src/audio/encoder.ts b/js/publish/src/audio/encoder.ts index ec80da8fbea..a031b9ba8a7 100644 --- a/js/publish/src/audio/encoder.ts +++ b/js/publish/src/audio/encoder.ts @@ -439,9 +439,9 @@ export class Encoder { const resolved = effect.get(this.#config); if (!format || fatal || !resolved) return; - const maxAge = - effect.get(broadcast.in.maxAge) ?? Container.trackInfo({ priority: Catalog.PRIORITY.audio }).maxAge; - this.#encode(broadcast.order, format, Micro.fromMilli(maxAge ?? Milli(30_000)), effect); + // Raw history needs a finite bound, so an unlimited max age keeps the media default's worth. + const maxAge = effect.get(broadcast.in.maxAge) ?? Container.MAX_AGE; + this.#encode(broadcast.order, format, Micro.fromMilli(maxAge), effect); }); // A network track change ends the epoch; subscriber changes keep the same producer. diff --git a/js/publish/src/broadcast.test.ts b/js/publish/src/broadcast.test.ts index c8e745bd34c..440098b4f99 100644 --- a/js/publish/src/broadcast.test.ts +++ b/js/publish/src/broadcast.test.ts @@ -2,6 +2,7 @@ import { expect, test } from "bun:test"; import { Manual, Milli, Nano } from "@moq/clock"; import { Stats } from "@moq/hang"; import * as Catalog from "@moq/hang/catalog"; +import * as Container from "@moq/hang/container"; import * as Json from "@moq/json"; import { Origin, Path, Track } from "@moq/net"; import { Effect, Signal } from "@moq/signals"; @@ -400,7 +401,7 @@ test("replacing a closed rendition track keeps the broadcast and publishes a fre }); test("changing maxAge publishes a new network broadcast", async () => { - const maxAge = new Signal(Milli(1000)); + const maxAge = new Signal(Milli(1000)); const broadcast = new Broadcast({ enabled: true, origin: new Origin.Producer(), @@ -419,6 +420,22 @@ test("changing maxAge publishes a new network broadcast", async () => { expect(after).not.toBe(before); expect((await after?.track("video").info())?.maxAge).toBe(Milli(2000)); + // Omitted is the media max age, and null is no publisher limit. + maxAge.set(undefined); + await settle(); + expect((await broadcast.net.peek()?.track("video").info())?.maxAge).toBe(Container.MAX_AGE); + maxAge.set(null); + await settle(); + expect((await broadcast.net.peek()?.track("video").info())?.maxAge).toBeUndefined(); + + broadcast.close(); +}); + +test("the catalog track takes the zero default max age", async () => { + const broadcast = new Broadcast({ enabled: true, origin: new Origin.Producer(), name: Path.from("test.hang") }); + await settle(); + const info = await broadcast.net.peek()?.track(Broadcast.CATALOG_TRACK).info(); + expect(info?.maxAge).toBe(Milli.zero); broadcast.close(); }); diff --git a/js/publish/src/broadcast.ts b/js/publish/src/broadcast.ts index d2395eb3146..75007db23e1 100644 --- a/js/publish/src/broadcast.ts +++ b/js/publish/src/broadcast.ts @@ -49,16 +49,17 @@ export type BroadcastInput = { rotation: Getter; /** - * How long relays keep a non-latest group of this broadcast's media tracks fetchable, in - * milliseconds. Declared on every media track we accept; see {@link Container.trackInfo}, - * whose default (`undefined` here) is sized so a segmented egress (HLS/DASH) can serve a - * full playlist window. + * How long, in milliseconds, a superseded group of this broadcast's media tracks stays fresh, + * so a fetch can still reach it. Declared on every media track we accept; see + * {@link Container.trackInfo}. Omitted (`undefined`) is `Container.MAX_AGE`, 30 seconds, + * sized so a segmented egress (HLS/DASH) can serve a full playlist window; `null` sets no + * publisher limit. The catalog and HLS record tracks keep `@moq/net`'s zero default. * - * A retention budget, not a delivery one, so lowering it does not reduce latency: it only - * shortens how far back a fetch can reach. A track's retention is fixed when it is created, + * A freshness bound, not a delivery budget, so lowering it does not reduce latency: it only + * shortens how far back a fetch can reach. A track's max age is fixed when it is created, * so changing this publishes a new network broadcast. */ - maxAge: Getter; + maxAge: Getter; /** * Whether to publish a stats track and name it in the catalog's `stats` section. Defaults to @@ -84,7 +85,8 @@ export type BroadcastInput = { /** * Override when renditions encode. Omitted: audio retains raw PCM until subscribed, while * video encodes continuously. False encodes both continuously; true gates video too, losing - * its past. Unless false, audio keeps raw history up to `maxAge`. Capture stays open. + * its past. Unless false, audio keeps raw history up to `maxAge`, or 30 seconds when it is + * `null`. Capture stays open. */ onDemand: Getter; }; @@ -491,13 +493,13 @@ export class Broadcast { // is whatever the catalog holds at announce time. if (!serving) { serving = true; - // A catalog may publish once and stay unchanged for the broadcast's whole life. Keep that - // sole closed snapshot replayable so a viewer arriving after the ordinary media retention - // window can still bootstrap. + // The zero default max age, as Rust's catalog track takes: a viewer needs only the newest + // snapshot. A catalog may publish once and stay unchanged for the broadcast's whole life, + // and a viewer arriving long after still bootstraps from it: max age only stales a + // superseded group, and the cache never ages out an open track's newest group. const track = broadcast.createTrack(Broadcast.CATALOG_TRACK, { // Each catalog snapshot is stamped when written. timescale: Moq.Time.Timescale.MILLI, - maxAge: Milli(Number.MAX_SAFE_INTEGER), priority: Catalog.PRIORITY.catalog, // Catalog JSON is small and repetitive. compress: true, diff --git a/js/watch/src/audio/decoder.test.ts b/js/watch/src/audio/decoder.test.ts index 43d10f911ad..1c6060d407f 100644 --- a/js/watch/src/audio/decoder.test.ts +++ b/js/watch/src/audio/decoder.test.ts @@ -1077,7 +1077,7 @@ async function livePlayback(burst: number) { const sync = new Sync({ delay: new Signal("auto") }); // Published before the decoder subscribes, since a broadcast with no request handler refuses // an unknown track. - let track = producer.createTrack("audio", { timescale: Moq.Time.Timescale.MILLI }); + let track = producer.createTrack("audio", { timescale: Moq.Time.Timescale.MILLI, maxAge: Container.MAX_AGE }); const decoder = new Decoder({ source, sync }); const samples = (48_000 * FRAME) / 1000; @@ -1111,7 +1111,7 @@ async function livePlayback(burst: number) { rename(name: string, patch: Record = {}) { track.finish(); track.close(); - track = producer.createTrack(name, { timescale: Moq.Time.Timescale.MILLI }); + track = producer.createTrack(name, { timescale: Moq.Time.Timescale.MILLI, maxAge: Container.MAX_AGE }); sequence = 0n; catalog.set({ audio: { renditions: { [name]: Catalog.AudioConfigSchema.parse({ ...audio, ...patch }) } } }); }, @@ -1119,7 +1119,7 @@ async function livePlayback(burst: number) { move(path: string) { media.peek().close(); producer = new Moq.Origin.Producer().createBroadcast(Moq.Path.from(path)).broadcast; - track = producer.createTrack("audio", { timescale: Moq.Time.Timescale.MILLI }); + track = producer.createTrack("audio", { timescale: Moq.Time.Timescale.MILLI, maxAge: Container.MAX_AGE }); sequence = 0n; media.set(producer.consume()); }, diff --git a/js/watch/src/retention.test.ts b/js/watch/src/retention.test.ts index bd09ac1a439..1a0b823030e 100644 --- a/js/watch/src/retention.test.ts +++ b/js/watch/src/retention.test.ts @@ -80,8 +80,8 @@ 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(); - // 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. + // The track's cache keeps every group here for its fixed 30s idle window whatever maxAge 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/js/watch/src/video/decoder.test.ts b/js/watch/src/video/decoder.test.ts index 67a4857dc24..fa400a5cacf 100644 --- a/js/watch/src/video/decoder.test.ts +++ b/js/watch/src/video/decoder.test.ts @@ -376,7 +376,9 @@ async function guardedPlayback( const enabled = new Signal(true); // Published before the decoder subscribes, since a broadcast with no request handler refuses // an unknown track. - const track = live ? mediaProducer.createTrack("video", { timescale: Moq.Time.Timescale.MILLI }) : undefined; + const track = live + ? mediaProducer.createTrack("video", { timescale: Moq.Time.Timescale.MILLI, maxAge: Container.MAX_AGE }) + : undefined; const decoder = new Decoder({ source, sync, enabled }); await microtasks(); return { @@ -435,7 +437,7 @@ async function guardedPlayback( ? new Moq.Origin.Producer().createBroadcast(Moq.Path.from(path)).broadcast : new Moq.Broadcast.Producer(); const track = live - ? mediaProducer.createTrack("video", { timescale: Moq.Time.Timescale.MILLI }) + ? mediaProducer.createTrack("video", { timescale: Moq.Time.Timescale.MILLI, maxAge: Container.MAX_AGE }) : undefined; media.set(mediaProducer.consume()); return track; @@ -1124,7 +1126,12 @@ it("a renamed video track keeps the delay, so audio neither skips nor goes silen (playback.track as Moq.Track.Producer).finish(); (playback.track as Moq.Track.Producer).close(); playback.switchRendition("video/1"); - video.replace(playback.producer.createTrack("video/1", { timescale: Moq.Time.Timescale.MILLI })); + video.replace( + playback.producer.createTrack("video/1", { + timescale: Moq.Time.Timescale.MILLI, + maxAge: Container.MAX_AGE, + }), + ); await run(20_000, 26_000); // The replacement read the new track and showed it. diff --git a/kt/moq/MIGRATE.md b/kt/moq/MIGRATE.md index 1085c33056d..da10ad84e8b 100644 --- a/kt/moq/MIGRATE.md +++ b/kt/moq/MIGRATE.md @@ -4,6 +4,10 @@ How to update your code for each breaking change, newest first. ## Unreleased +### Authored tracks default to a zero max age ([#7729](https://github.com/moq-dev/moq/pull/7729)) + +A null `TrackInfo.maxAge`, the default, and a null info now advertise a zero max age, serving only the live edge, instead of no publisher limit. Pass `maxAgeUnlimited = true`, which ignores `maxAge`, where you relied on null meaning no limit. A received track's `info()` sets it when its publisher advertised no limit. + ### Viewer targets are bounded ([#7090](https://github.com/moq-dev/moq/pull/7090)) Viewer ceilings and PROBE target overrides are refused with the new `MoqException.OutOfRange` once they would sum above 2^53 - 1 bps, the most a PROBE target carries; nothing changes on a refusal. `Viewers.watch` and `setTarget` and `Viewer.update` throw it. Handle the new variant wherever you match the error exhaustively. Regenerate bindings and rebuild the matching native library together. diff --git a/kt/moq/src/jvmAndAndroidTest/kotlin/dev/moq/SmokeTest.kt b/kt/moq/src/jvmAndAndroidTest/kotlin/dev/moq/SmokeTest.kt index 31b6c21613a..0c2a7a794c4 100644 --- a/kt/moq/src/jvmAndAndroidTest/kotlin/dev/moq/SmokeTest.kt +++ b/kt/moq/src/jvmAndAndroidTest/kotlin/dev/moq/SmokeTest.kt @@ -316,7 +316,11 @@ class SmokeTest { @Test fun `an ascending subscription reads a cached backlog oldest first`() = runTest { BroadcastProducer().use { broadcast -> - val track = broadcast.publishTrack("backlog", TrackInfo(timescale = 1_000_000uL)) + val track = + broadcast.publishTrack( + "backlog", + TrackInfo(maxAgeUnlimited = true, timescale = 1_000_000uL), + ) for (ms in 0uL until 3uL) { val group = track.appendGroup() group.writeFrame( @@ -374,6 +378,21 @@ class SmokeTest { } } + @Test + fun `an omitted max age is zero and the unlimited flag sets none`() { + BroadcastProducer().use { broadcast -> + val omitted = broadcast.publishTrack("omitted", null).consume(null).info() + assertEquals(java.time.Duration.ZERO, omitted.maxAge) + val unlimited = + broadcast + .publishTrack("unlimited", TrackInfo(maxAgeUnlimited = true)) + .consume(null) + .info() + assertNull(unlimited.maxAge) + assertTrue(unlimited.maxAgeUnlimited) + } + } + @Test fun `catalog handle closes with its broadcast`() { val broadcast = BroadcastProducer() diff --git a/py/moq-rs/MIGRATE.md b/py/moq-rs/MIGRATE.md index 27249eeaf44..d3442f2e577 100644 --- a/py/moq-rs/MIGRATE.md +++ b/py/moq-rs/MIGRATE.md @@ -4,6 +4,10 @@ How to update your code for each breaking change, newest first. ## Unreleased +### Authored tracks default to a zero max age ([#7729](https://github.com/moq-dev/moq/pull/7729)) + +`TrackInfo.max_age` defaults to `timedelta(0)`, like `Delay.max`, so a bare `TrackInfo()` and an omitted one now advertise a zero max age, serving only the live edge, instead of no publisher limit. `None` still means no limit: pass `max_age=None` where you relied on the default. + ### Viewer targets are bounded ([#7090](https://github.com/moq-dev/moq/pull/7090)) Viewer ceilings and PROBE target overrides are refused with the new `moq.Error.OutOfRange` once they would sum above 2^53 - 1 bps, the most a PROBE target carries; nothing changes on a refusal. `Viewers.watch` and `set_target` and `Viewer.update` raise it. Handle the new variant wherever you match the error exhaustively. Regenerate bindings and rebuild the matching native library together. diff --git a/py/moq-rs/moq/_records.py b/py/moq-rs/moq/_records.py index 2f51ecfd577..526c991a7dc 100644 --- a/py/moq-rs/moq/_records.py +++ b/py/moq-rs/moq/_records.py @@ -280,17 +280,18 @@ class TrackInfo: """Publisher-side track properties, mirroring moq-net's ``track::Info``. ``priority`` is in ``-128..=127``, higher first, and defaults to 0, the midpoint. It breaks - ties between subscriptions of equal subscriber priority. ``max_age`` is how long the - publisher caches a non-latest group, ``None`` for no limit. ``refresh`` is how many - times its first frame a group's later bytes may grow before a joining subscriber - asks for a new group, ``None`` to never ask. ``timescale`` is ticks per second: + ties between subscriptions of equal subscriber priority. ``max_age`` is how long a + superseded group stays fresh: the default zero serves only the live edge, and + ``None`` sets no publisher limit, leaving only the cache to bound it. ``refresh`` is + how many times its first frame a group's later bytes may grow before a joining + subscriber asks for a new group, ``None`` to never ask. ``timescale`` is ticks per second: ``None`` means the track is untimed, on both publish and receive. ``compress`` DEFLATEs each group on the wire to peers that support it; readers always see the original frames. """ priority: int = 0 - max_age: timedelta | None = None + max_age: timedelta | None = timedelta(0) refresh: int | None = None timescale: int | None = None compress: bool = False @@ -299,6 +300,7 @@ def _ffi(self) -> MoqTrackInfo: return MoqTrackInfo( priority=self.priority, max_age=self.max_age, + max_age_unlimited=self.max_age is None, refresh=self.refresh, timescale=self.timescale, compress=self.compress, @@ -308,7 +310,7 @@ def _ffi(self) -> MoqTrackInfo: def _from_ffi(info: MoqTrackInfo) -> TrackInfo: return TrackInfo( priority=info.priority, - max_age=info.max_age, + max_age=None if info.max_age_unlimited else (info.max_age or timedelta(0)), refresh=info.refresh, timescale=info.timescale, compress=info.compress, diff --git a/py/moq-rs/tests/test_local.py b/py/moq-rs/tests/test_local.py index 770d8e0ede1..7c42bb89c8f 100644 --- a/py/moq-rs/tests/test_local.py +++ b/py/moq-rs/tests/test_local.py @@ -485,6 +485,23 @@ def test_track_info_keeps_native_default_priority(): assert moq.TrackInfo(timescale=90_000)._ffi().priority == native +def test_track_info_max_age(): + """An omitted max age is zero, ``None`` sets no limit, and a received info republishes unchanged.""" + broadcast = moq.BroadcastProducer() + cases = [ + (None, timedelta(0)), + (moq.TrackInfo(), timedelta(0)), + (moq.TrackInfo(max_age=timedelta(seconds=2)), timedelta(seconds=2)), + (moq.TrackInfo(max_age=None), None), + ] + for i, (info, max_age) in enumerate(cases): + got = broadcast.publish_track(f"t{i}", info).consume().info() + assert got.max_age == max_age + again = broadcast.publish_track(f"again{i}", got).consume().info() + assert again.max_age == max_age + broadcast.close() + + def test_default_subscription_skips_superseded_groups_at_once(): """A bare record carries moq-net's zero delay too; only an explicit None leaves a bound unset.""" assert moq.Subscription.default() == moq.Subscription() @@ -1028,7 +1045,7 @@ async def test_raw_publish_consume(): async def test_raw_multiple_frames(): origin = moq.OriginProducer() broadcast = create_announced(origin, "robot/io") - raw = broadcast.publish_track("commands") + raw = broadcast.publish_track("commands", moq.TrackInfo(max_age=None)) consumer = origin.consume() @@ -1059,7 +1076,7 @@ async def test_raw_multiple_frames(): async def test_raw_producer_consume_direct(): """Consume a raw track directly from the producer, no origin/broadcast plumbing.""" broadcast = moq.BroadcastProducer() - track = broadcast.publish_track("direct") + track = broadcast.publish_track("direct", moq.TrackInfo(max_age=None)) consumer = track.consume(moq.Subscription(delay=moq.Delay(max=timedelta(seconds=1)), ranges=FROM_GROUP_0)) track.write_frame(b"hello") @@ -1078,7 +1095,7 @@ async def test_raw_producer_consume_direct(): async def test_ascending_subscription_reads_a_cached_backlog_oldest_first(): """An ascending subscription reaching back over a cached backlog reads it oldest first.""" broadcast = moq.BroadcastProducer() - track = broadcast.publish_track("backlog", moq.TrackInfo(timescale=1_000_000)) + track = broadcast.publish_track("backlog", moq.TrackInfo(max_age=None, timescale=1_000_000)) for ms in range(3): group = track.append_group() group.write_frame(b"x", moq.Timestamp(ms, 1_000)) @@ -1102,7 +1119,7 @@ async def test_ascending_subscription_reads_a_cached_backlog_oldest_first(): async def test_time_anchor_starts_at_the_group_containing_it(): """A time anchor takes a wrapper Timestamp and starts at the group containing that time.""" broadcast = moq.BroadcastProducer() - track = broadcast.publish_track("timed", moq.TrackInfo(timescale=1_000)) + track = broadcast.publish_track("timed", moq.TrackInfo(max_age=None, timescale=1_000)) for second in range(3): group = track.append_group() group.write_frame(b"x", moq.Timestamp(second, 1)) @@ -1157,7 +1174,7 @@ async def test_raw_group_sequence(): """Consumer sees the same sequence numbers the producer assigned.""" origin = moq.OriginProducer() broadcast = create_announced(origin, "track/seq") - raw = broadcast.publish_track("seq", moq.TrackInfo(timescale=1_000_000)) + raw = broadcast.publish_track("seq", moq.TrackInfo(max_age=None, timescale=1_000_000)) consumer = origin.consume() @@ -1194,7 +1211,7 @@ async def test_default_iteration_is_sequence_order(): """ origin = moq.OriginProducer() broadcast = create_announced(origin, "track/ordering") - raw = broadcast.publish_track("ordering") + raw = broadcast.publish_track("ordering", moq.TrackInfo(max_age=None)) subscription = moq.Subscription(delay=moq.Delay(max=timedelta(seconds=1)), ranges=FROM_GROUP_0) seq_consumer = raw.consume(subscription) @@ -1344,7 +1361,7 @@ async def test_raw_multi_frame_group(): async def test_read_frame_one_per_group(): """read_frame() returns the first frame of each successive group.""" broadcast = moq.BroadcastProducer() - track = broadcast.publish_track("status") + track = broadcast.publish_track("status", moq.TrackInfo(max_age=None)) consumer = track.consume(moq.Subscription(delay=moq.Delay(max=timedelta(seconds=1)), ranges=FROM_GROUP_0)) track.write_frame(b"ready") @@ -1388,7 +1405,7 @@ async def test_raw_read_frame_preserves_timestamp(): async def test_read_frame_skips_remaining_frames_in_group(): """read_frame() only returns the first frame of a multi-frame group.""" broadcast = moq.BroadcastProducer() - track = broadcast.publish_track("mixed") + track = broadcast.publish_track("mixed", moq.TrackInfo(max_age=None)) consumer = track.consume(moq.Subscription(delay=moq.Delay(max=timedelta(seconds=1)), ranges=FROM_GROUP_0)) group = track.append_group() diff --git a/py/moq-rs/tests/test_testing_clock.py b/py/moq-rs/tests/test_testing_clock.py index e06bb6e3392..a0b3e23f5a4 100644 --- a/py/moq-rs/tests/test_testing_clock.py +++ b/py/moq-rs/tests/test_testing_clock.py @@ -25,7 +25,7 @@ def test_a_pending_timer_waits_for_advance() -> None: async def main(): # The origin's driver runs the timers that judge a group stale. origin = moq.OriginProducer() - track = origin.create_broadcast("clock").broadcast.publish_track("track") + track = origin.create_broadcast("clock").broadcast.publish_track("track", moq.TrackInfo(max_age=None)) from_group_0 = [moq.Range(start=moq.Anchor.ABSOLUTE(group=0))] consumer = track.consume(moq.Subscription(delay=moq.Delay(max=timedelta(seconds=1)), ranges=from_group_0)) diff --git a/quest/m1/README.md b/quest/m1/README.md index 0d270e56699..9136e7589c9 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -176,7 +176,6 @@ their end report, so an embedder's drain alert pages on real cuts. - [Calibrate the paired nightly benchmarks](/quest/m1/bench-ci.md) - A/A and deliberately slowed Nightly runs set the paired comparison's threshold, so its regression alerts can be trusted - [Unbounded groups](/quest/m1/unbounded-groups/README.md) - groups and frames lose their size caps; a group keeps a 32 MB tail, and readers behind it replay through paced flights or refresh - [Poll-first async](/quest/m1/poll-first/README.md) - library crates compile no coroutines by default: async wrappers are generated from `poll_*` and gated behind an `async` feature -- [Authored tracks default to a 30 s max-age](/quest/m1/max-age-defaults.md) - raw and media tracks advertise 30 s unless their author chooses otherwise, with explicit unlimited in every binding - [HLS export lists a same-codec reconfigure's first group under the new init](/quest/m1/hls-reinit-same-codec.md) - the hand-over pick, whichever of the catalog and the records arrives first, after the catalog `hls` removal is planned - [Ordered reads can skip owed holes, and snapshot latest() does](/quest/m1/ordered-owed-holes.md) - moq-net's `Ordered` gains a read that skips past an owed hole to the newest buffered group, while keeping the reader's bounds - [The relay reports native sessions it force-closes at the drain deadline](/quest/m1/relay-drain-cuts.md) - the drain's public outcome and live tally separate sessions cut while open from sessions only finishing their end report, so an embedder's drain alert pages on real cuts diff --git a/quest/m1/max-age-defaults.md b/quest/m1/max-age-defaults.md deleted file mode 100644 index e58ab86f732..00000000000 --- a/quest/m1/max-age-defaults.md +++ /dev/null @@ -1,91 +0,0 @@ -# [L] Authored tracks default to a 30 s max-age, with explicit unlimited - -## Goal - -A newly authored track, raw or media, advertises a 30 s publisher max-age unless its author chooses otherwise, in Rust, JS, FFI, C, and every hand-written binding. Unlimited stays expressible explicitly in each of them. Received metadata keeps its absence semantics, the relay keeps its unset (no) local age ceiling, and no wire value or wire absence changes meaning. - -## Plan - -Decided 2026-10-30 (maintainer): audit before deciding whether max-age should default to 0 instead of unlimited, following the subscriber max-delay decision in [moq-dev/moq#7403](https://github.com/moq-dev/moq/pull/7403). The audit landed in [moq-dev/moq#7567](https://github.com/moq-dev/moq/pull/7567), and the maintainer settled its three proposals: - -- Decided 2026-11-01 (maintainer): ✅ **30 s for both raw and media authored retention**, over 0 raw with 30 s media, or keeping raw unlimited. Thirty seconds reuses the existing media policy and exceeds the recorder's default 10 s reorder allowance without making live viewers wait; zero would drop superseded-group overlap and past fetch. -- Decided 2026-11-01 (maintainer): ✅ **the relay keeps its current unset ceiling**, over defaulting relay `duration` to 30 s with an operator opt-out. A finite relay ceiling would restrict explicit long-DVR and archive publishers too; the existing 30 s idle expiry is a different policy and stays as is. -- Decided 2026-11-01 (maintainer): ✅ **the authoring API applies the default at construction, with an explicit unlimited and unchanged decoded metadata**, over a new default/unlimited/finite retention type across every authoring API. Changing `Info::default` / `infoDefaults` alone is ruled out: it would silently give incoming tracks 30 s and break explicit unlimited through the current conversions. - -The audit below is the implementation's map of every surface; the Implementation section at the end is the work. - -### Audit scope and overlapping work - -Audited 2026-11-01 at [c95a9b1201](https://github.com/moq-dev/moq/commit/c95a9b1201), after pulling `origin/main`. Source links below pin that revision. Defaults are construction policy; received metadata and subscriber parameters have separate absence semantics. - -Before claiming, checked ready state with `quest unblocked` and searched open PRs; `quest start` accepted the claim. Related open work does not choose defaults: - -- [moq-dev/moq#7446](https://github.com/moq-dev/moq/pull/7446): cache debt reclamation under pressure. -- [moq-dev/moq#7219](https://github.com/moq-dev/moq/pull/7219) and [moq-dev/moq#7516](https://github.com/moq-dev/moq/pull/7516): JS cache-aging test and cache insertion performance. -- [moq-dev/moq#7545](https://github.com/moq-dev/moq/pull/7545): bounded reads and cached backfill; [moq-dev/moq#7310](https://github.com/moq-dev/moq/pull/7310): archive time lookup. -- [moq-dev/moq#7518](https://github.com/moq-dev/moq/pull/7518): unresolved Rust/JS container backlog-start policy. This audit does not promise identical playback start or settle that policy. -- [moq-dev/moq#7522](https://github.com/moq-dev/moq/pull/7522): cached receive-buffer accounting. - -### Current defaults - -Publisher max-age is a freshness bound on **superseded groups**. A group expires when either its successor's arrival is old enough at this hop or the successor's first timestamp trails the live edge enough. Untimed tracks use the wall clock today; once [time-addressing](/quest/m1/time-addressing/model.md) lands, a scale-less track counts max-age in bare key units instead (decided 2026-11-03). The newest group is exempt. Byte reclamation has a separate cache policy. See [rs/moq-net/src/model/track.rs:120](https://github.com/moq-dev/moq/blob/c95a9b1201/rs/moq-net/src/model/track.rs#L120) and [js/net/src/track.ts:137](https://github.com/moq-dev/moq/blob/c95a9b1201/js/net/src/track.ts#L137). - -| Surface | Current default and meaning | Source | -| --- | --- | --- | -| Rust raw tracks | `track::Info::default().max_age = None`; no publisher limit. `with_max_age(None)` explicitly requests that meaning. Producers use the supplied info, not an independent finite default. | [rs/moq-net/src/model/track.rs:210](https://github.com/moq-dev/moq/blob/c95a9b1201/rs/moq-net/src/model/track.rs#L210) | -| Rust local origin ceiling | `cache_duration = Duration::MAX`. Effective retention is the minimum of the publisher limit and local ceiling; metadata stays unchanged. | [rs/moq-net/src/model/origin.rs:164](https://github.com/moq-dev/moq/blob/c95a9b1201/rs/moq-net/src/model/origin.rs#L164); [rs/moq-net/src/model/track.rs:1351](https://github.com/moq-dev/moq/blob/c95a9b1201/rs/moq-net/src/model/track.rs#L1351) | -| Bare Rust pool | `cache::Config::default()` and `Pool::default()` have no byte target or idle expiry. Standalone callers must drive `Pool::poll` if they enable expiry. | [rs/moq-net/src/model/cache.rs:90](https://github.com/moq-dev/moq/blob/c95a9b1201/rs/moq-net/src/model/cache.rs#L90); [rs/moq-net/src/model/cache.rs:140](https://github.com/moq-dev/moq/blob/c95a9b1201/rs/moq-net/src/model/cache.rs#L140) | -| Rust origins and standalone broadcasts | Construct a pool with **30 s idle expiry**, no byte target, and no retention ceiling. Origin drivers collect it; standalone use must arrange collection. | [rs/moq-net/src/model/origin.rs:164](https://github.com/moq-dev/moq/blob/c95a9b1201/rs/moq-net/src/model/origin.rs#L164); [rs/moq-net/src/model/broadcast.rs:74](https://github.com/moq-dev/moq/blob/c95a9b1201/rs/moq-net/src/model/broadcast.rs#L74); [rs/moq-net/src/model/cache.rs:23](https://github.com/moq-dev/moq/blob/c95a9b1201/rs/moq-net/src/model/cache.rs#L23) | -| Relay pool and ceiling | Unset `capacity` and `headroom`: no byte target. Unset `duration`: **30 s idle LRU expiry**, **no local age ceiling**. Explicit `duration` sets both expiry and ceiling. The configured pool is shared across origins. | [rs/moq-relay/src/cache.rs:26](https://github.com/moq-dev/moq/blob/c95a9b1201/rs/moq-relay/src/cache.rs#L26); [rs/moq-relay/src/cache.rs:105](https://github.com/moq-dev/moq/blob/c95a9b1201/rs/moq-relay/src/cache.rs#L105); [rs/moq-relay/src/cluster.rs:1247](https://github.com/moq-dev/moq/blob/c95a9b1201/rs/moq-relay/src/cluster.rs#L1247) | -| Rust idle track copies | `IDLE_LINGER = 30 s` retains an unread track and its cached state for returning readers/fetches, without an upstream subscription. This is not publisher freshness. | [rs/moq-net/src/model/track.rs:86](https://github.com/moq-dev/moq/blob/c95a9b1201/rs/moq-net/src/model/track.rs#L86) | -| JS raw tracks | `Info.maxAge` omitted/`undefined` means no publisher limit; `infoDefaults` preserves absence. `null` is not a supported unlimited publisher value. | [js/net/src/track.ts:147](https://github.com/moq-dev/moq/blob/c95a9b1201/js/net/src/track.ts#L147); [js/net/src/track.ts:193](https://github.com/moq-dev/moq/blob/c95a9b1201/js/net/src/track.ts#L193) | -| JS payload cache | `CACHE_WINDOW = 30 s`, independent of publisher maxAge. Writes refresh expiry; reads do not. The live edge is exempt, but a closed track's former edge ages too. Pruning is sliced and timer-driven, so reclamation is not an exact 30 s deadline. No shared byte-capacity pool here. | [js/net/src/track.ts:61](https://github.com/moq-dev/moq/blob/c95a9b1201/js/net/src/track.ts#L61); [js/net/src/track.ts:1262](https://github.com/moq-dev/moq/blob/c95a9b1201/js/net/src/track.ts#L1262) | -| Rust media producers | `hang::container::MAX_AGE = 30 s`; `track_info` explicitly sets it. `moq_mux::catalog::Config.max_age = None` means **inherit hang's 30 s**, not unlimited; `with_max_age(None)` also inherits. | [rs/hang/src/container/mod.rs:1](https://github.com/moq-dev/moq/blob/c95a9b1201/rs/hang/src/container/mod.rs#L1); [rs/hang/src/container/frame.rs:40](https://github.com/moq-dev/moq/blob/c95a9b1201/rs/hang/src/container/frame.rs#L40); [rs/moq-mux/src/catalog/producer.rs:430](https://github.com/moq-dev/moq/blob/c95a9b1201/rs/moq-mux/src/catalog/producer.rs#L430); [rs/moq-mux/src/catalog/producer.rs:473](https://github.com/moq-dev/moq/blob/c95a9b1201/rs/moq-mux/src/catalog/producer.rs#L473) | -| Rust catalog, MSF catalog, HLS record tracks | Inherit raw `Info` retention, currently unlimited. These represent snapshots/windows at the live edge; media overrides do not apply. | [rs/hang/src/catalog/root.rs:250](https://github.com/moq-dev/moq/blob/c95a9b1201/rs/hang/src/catalog/root.rs#L250); [rs/moq-mux/src/catalog/producer.rs:528](https://github.com/moq-dev/moq/blob/c95a9b1201/rs/moq-mux/src/catalog/producer.rs#L528); [rs/moq-mux/src/hls.rs:383](https://github.com/moq-dev/moq/blob/c95a9b1201/rs/moq-mux/src/hls.rs#L383) | -| JS media producers | `Container.trackInfo({maxAge: undefined})` substitutes **30,000 ms**, used by `publish.Broadcast`. A finite override is fixed per network broadcast; changing it creates a new broadcast. There is currently no explicit unlimited option through this helper. | [js/hang/src/container/track.ts:16](https://github.com/moq-dev/moq/blob/c95a9b1201/js/hang/src/container/track.ts#L16); [js/publish/src/broadcast.ts:53](https://github.com/moq-dev/moq/blob/c95a9b1201/js/publish/src/broadcast.ts#L53); [js/publish/src/broadcast.ts:447](https://github.com/moq-dev/moq/blob/c95a9b1201/js/publish/src/broadcast.ts#L447) | -| JS catalog and room metadata | Browser catalog explicitly uses `Number.MAX_SAFE_INTEGER` ms (a very large finite value); room snapshots use **86,400,000 ms / one day**. Neither overrides the separate payload cache. | [js/publish/src/broadcast.ts:398](https://github.com/moq-dev/moq/blob/c95a9b1201/js/publish/src/broadcast.ts#L398); [js/room/src/metadata.ts:156](https://github.com/moq-dev/moq/blob/c95a9b1201/js/room/src/metadata.ts#L156) | -| On-demand audio history | Rust uses the track's max-age, falling back to hang's **30 s** if unlimited; JS uses broadcast/helper maxAge, with **30 s** fallback. Raw capture history is separate from encoded group retention. | [rs/moq-audio/src/encode/producer.rs:195](https://github.com/moq-dev/moq/blob/c95a9b1201/rs/moq-audio/src/encode/producer.rs#L195); [js/publish/src/audio/encoder.ts:413](https://github.com/moq-dev/moq/blob/c95a9b1201/js/publish/src/audio/encoder.ts#L413) | -| CLI and ingest gateways | `--max-age` unset and RTMP/SRT/RTC retention overrides `None` inherit the mux/hang media default, **30 s**. They do not make ingested media unlimited. | [rs/moq-cli/src/args.rs:798](https://github.com/moq-dev/moq/blob/c95a9b1201/rs/moq-cli/src/args.rs#L798); [rs/moq-rtmp/src/dial.rs:177](https://github.com/moq-dev/moq/blob/c95a9b1201/rs/moq-rtmp/src/dial.rs#L177); [rs/moq-rtmp/src/dial.rs:341](https://github.com/moq-dev/moq/blob/c95a9b1201/rs/moq-rtmp/src/dial.rs#L341); [rs/moq-srt/src/dial.rs:84](https://github.com/moq-dev/moq/blob/c95a9b1201/rs/moq-srt/src/dial.rs#L84); [rs/moq-srt/src/dial.rs:174](https://github.com/moq-dev/moq/blob/c95a9b1201/rs/moq-srt/src/dial.rs#L174); [rs/moq-rtc/src/server/mod.rs:146](https://github.com/moq-dev/moq/blob/c95a9b1201/rs/moq-rtc/src/server/mod.rs#L146); [rs/moq-rtc/src/server/whip.rs:164](https://github.com/moq-dev/moq/blob/c95a9b1201/rs/moq-rtc/src/server/whip.rs#L164) | -| GStreamer opaque data | Explicit **5 s** publisher age for `application/octet-stream`; codec media goes through its importer/catalog. | [rs/moq-gst/src/sink/pad.rs:465](https://github.com/moq-dev/moq/blob/c95a9b1201/rs/moq-gst/src/sink/pad.rs#L465) | -| UniFFI raw tracks | `MoqTrackInfo.max_age` defaults to `None`; absent info also uses raw defaults. Conversion currently sets age **only for Some**. Omitted and explicit null both mean unlimited today. Media uses the mux catalog policy. | [rs/moq-ffi/src/producer.rs:31](https://github.com/moq-dev/moq/blob/c95a9b1201/rs/moq-ffi/src/producer.rs#L31); [rs/moq-ffi/src/producer.rs:58](https://github.com/moq-dev/moq/blob/c95a9b1201/rs/moq-ffi/src/producer.rs#L58); [rs/moq-ffi/src/producer.rs:80](https://github.com/moq-dev/moq/blob/c95a9b1201/rs/moq-ffi/src/producer.rs#L80) | -| UniFFI origin cache | No capacity unless configured; Rust origin's **30 s idle expiry** is preserved when adding a capacity. | [rs/moq-ffi/src/origin.rs:331](https://github.com/moq-dev/moq/blob/c95a9b1201/rs/moq-ffi/src/origin.rs#L331) | -| C raw tracks / Python wrapper | C zero-initialized `max_age_present = false` means unlimited; when true, microseconds are used, including zero. Python `TrackInfo.max_age = None` also means unlimited. | [rs/moq-c/src/api.rs:637](https://github.com/moq-dev/moq/blob/c95a9b1201/rs/moq-c/src/api.rs#L637); [rs/moq-c/src/api.rs:664](https://github.com/moq-dev/moq/blob/c95a9b1201/rs/moq-c/src/api.rs#L664); [py/moq-rs/moq/_records.py:171](https://github.com/moq-dev/moq/blob/c95a9b1201/py/moq-rs/moq/_records.py#L171) | -| Archive recording and DVR | Recorder defaults: no DVR pruning (`dvr = None`, intentional durable archive), **10 s** missing-group max-delay, **2 s** object duration, **4 s** flush. Effective missing-group wait is also capped by source max-age. A DVR explicitly supplies `window` and `grace`; neither has a default. | [rs/moq-archive/src/producer/mod.rs:53](https://github.com/moq-dev/moq/blob/c95a9b1201/rs/moq-archive/src/producer/mod.rs#L53); [rs/moq-archive/src/producer/mod.rs:108](https://github.com/moq-dev/moq/blob/c95a9b1201/rs/moq-archive/src/producer/mod.rs#L108); [rs/moq-archive/src/producer/track.rs:450](https://github.com/moq-dev/moq/blob/c95a9b1201/rs/moq-archive/src/producer/track.rs#L450) | -| Archive playback cache and age | Republished info explicitly clears publisher max-age; stored history is governed by the store/DVR retention. Decoded archive objects have a separate **64 MiB** cache; the growing archive listing refresh interval defaults to **1 s**. | [rs/moq-archive/src/consumer/track.rs:299](https://github.com/moq-dev/moq/blob/c95a9b1201/rs/moq-archive/src/consumer/track.rs#L299); [rs/moq-archive/src/consumer/mod.rs:48](https://github.com/moq-dev/moq/blob/c95a9b1201/rs/moq-archive/src/consumer/mod.rs#L48) | -| Ended publisher availability | `moq_mux::Linger::DEFAULT = 30 s` keeps a cleanly ended broadcast and its producers up. Separate from group freshness and pool expiry. | [rs/moq-mux/src/linger.rs:31](https://github.com/moq-dev/moq/blob/c95a9b1201/rs/moq-mux/src/linger.rs#L31) | - -Cache capacity is a converging target, not a hard memory limit. Live edges remain protected; active reads can keep Rust idle-LRU entries fresh (JS uses write activity); an unbounded byte target plus a time window does not bound bytes, group count, publisher count, or an arbitrarily large newest group. Finite max-age alone is not a hostile-peer resource bound. See [rs/moq-net/src/model/cache.rs:125](https://github.com/moq-dev/moq/blob/c95a9b1201/rs/moq-net/src/model/cache.rs#L125). - -### Subscriber and wire absence are separate - -- Rust subscriptions default to `max_delay = Some(0)`; JS omitted subscriber `maxDelay` means 0. Explicit Rust `None` / JS `null` uses publisher retention alone. Changing publisher retention is not another latency-default change. See [rs/moq-net/src/model/subscription.rs:23](https://github.com/moq-dev/moq/blob/c95a9b1201/rs/moq-net/src/model/subscription.rs#L23) and [js/net/src/track.ts:233](https://github.com/moq-dev/moq/blob/c95a9b1201/js/net/src/track.ts#L233). -- A direct fetch has its own options, defaulting to no *subscriber* cap. It still obeys publisher/local retention: Rust `Fetching::poll` clamps the budget and returns `Error::Old` before serving stale data. A more tolerant subscriber cannot recover history expired by publisher policy. See [rs/moq-net/src/model/group.rs:4112](https://github.com/moq-dev/moq/blob/c95a9b1201/rs/moq-net/src/model/group.rs#L4112) and [rs/moq-net/src/model/track.rs:5531](https://github.com/moq-dev/moq/blob/c95a9b1201/rs/moq-net/src/model/track.rs#L5531). -- For an IETF SUBSCRIBE with absent MAX_AGE, Rust's `serving_subscription` sets `max_delay = None`; JS uses its largest safe integer budget. This means no additional subscriber restriction, **not guaranteed unlimited storage**. Explicit MAX_AGE overrides this. See [rs/moq-net/src/ietf/publisher.rs:30](https://github.com/moq-dev/moq/blob/c95a9b1201/rs/moq-net/src/ietf/publisher.rs#L30), [rs/moq-net/src/ietf/publisher.rs:1932](https://github.com/moq-dev/moq/blob/c95a9b1201/rs/moq-net/src/ietf/publisher.rs#L1932), and [js/net/src/ietf/publisher.ts:504](https://github.com/moq-dev/moq/blob/c95a9b1201/js/net/src/ietf/publisher.ts#L504). -- The checkout's Timestamp extension says SUBSCRIBE absence preserves publisher delivery policy and update absence preserves the current budget; zero expires superseded groups, never the newest. This is extension semantics, not a base-IETF default of zero: [drafts/draft-lcurley-moq-timestamp.md:142](https://github.com/moq-dev/moq/blob/c95a9b1201/drafts/draft-lcurley-moq-timestamp.md#L142). The published [timestamp-01](https://www.ietf.org/archive/id/draft-lcurley-moq-timestamp-01.html) predates this MAX_AGE section; do not cite that revision as specifying it. -- Base [moq-transport-22 section 10.3](https://www.ietf.org/archive/id/draft-ietf-moq-transport-22.html#section-10.3) defines a different property, MAX_CACHE_DURATION: absence allows caching until implementation constraints evict objects. Its present-value rule measures age from receipt of each object, unlike this model's superseded-group freshness. The implementation maps publisher age to that property ([rs/moq-net/src/ietf/properties.rs:89](https://github.com/moq-dev/moq/blob/c95a9b1201/rs/moq-net/src/ietf/properties.rs#L89)). That pre-existing distinction is not resolved by the authored default. No wire omission is reinterpreted by this quest. - -### Concrete consequences - -For a live feed with successive groups A then B, **zero publisher age makes A stale as soon as B supersedes it**, even if A's payload remains allocated until cache reclamation. A late join can still read the newest retained B from its start, including its keyframe or snapshot. Zero does not inherently break every late join. It removes overlap for catch-up, switching/warmup that needs A, and direct fetching of A once superseded. Even with zero, the newest group can be large or old in absolute time. - -With **30 s publisher age**, a reader can request superseded groups within the age window, provided they remain cached or can be filled. That does not delay a default live reader, whose own budget is still zero. The window is measured at group reach, not an exact 30 s of first-frame history, and idle expiry, byte pressure, upstream availability, track lifetime, and decoder needs can shorten useful history. This is eligibility, not a guaranteed DVR service level. - -HLS/DASH needs past media for listed segments and players starting several target durations behind live. Zero media retention makes those segment fetches fail once their media groups are superseded. A finite value must cover the advertised playlist and fetch/reorder needs; 30 s is the existing media policy, not a proof that every possible playlist configuration fits. The HLS record track is different: its newest group restates its window. - -DVR and archive need two policies: enough live overlap to record reordered groups without gaps, and durable storage retention to seek later. Zero source age can lose superseded content before recording or eliminate reorder tolerance; it does not erase bytes already stored. Thirty seconds is not a long DVR. Archive replay deliberately advertises no publisher limit, so historical reads remain possible while the store retains them; a relay's local ceiling may still restrict them. Keep this intentional exception explicit. - -### Implementation - -One shared 30 s constant serves raw and media; `hang::container::MAX_AGE` reuses it rather than keeping a second value. The default applies where an author builds a track, never where a peer's metadata is decoded. - -- **Rust raw:** an authored `track::Info` gets `max_age: Some(30 s)` unless the author sets it; explicit `None` stays unlimited. Every decode and republish path (lite, IETF, archive playback) states the received value explicitly, so wire absence still yields `None`; audit `..Default::default()` in those paths before changing any default. -- **Rust media:** follows decision 3, so mux `Config.max_age` and `with_max_age` stop meaning "inherit": omitted is 30 s, `None` is unlimited, and a value is that value. This changes the meaning of today's `with_max_age(None)`, so the PR is breaking and says so. CLI `--max-age` unset and the RTMP/SRT/RTC overrides stay at 30 s. -- **Catalog, MSF catalog, and HLS record tracks** inherit the raw default and become 30 s. Their newest group bootstraps a join, so this is harmless; switching them to zero is not part of this quest. -- **Explicit policies stay:** GStreamer's 5 s opaque data, the JS catalog's `Number.MAX_SAFE_INTEGER`, room snapshots' one day, and archive playback's explicit no-limit republish. -- **JS:** split authoring options from decoded `Info`. At producer construction an omitted or `undefined` `maxAge` is 30,000 ms, `null` is unlimited (matching [moq-dev/moq#7403](https://github.com/moq-dev/moq/pull/7403)'s `null` max-delay), and a number is that policy. `infoDefaults` and decoded `Info` keep absence as no publisher limit. `@moq/hang`'s `trackInfo` and `@moq/publish` gain the same `null`. -- **UniFFI and bindings:** fix the conversions that would otherwise inherit the new Rust default for explicit unlimited: UniFFI's `if let Some` in `rs/moq-ffi/src/producer.rs` and C's `if max_age_present` in `rs/moq-c/src/api.rs`. Where omission and unlimited can't be told apart (a UniFFI record default, a Go nil, a zeroed C struct), omitted means 30 s and an explicit unlimited flag carries unlimited, following the pattern the bindings' subscription `Delay` sets for max-delay: Go's `moq.Delay.MaxUnlimited` and moq-c's `moq_delay.max_unlimited`. Python, Swift, Kotlin, Go, Dart, and C++ wrappers expose the same three cases. -- **Relay:** no change. Unset `duration` keeps no local age ceiling and its 30 s idle expiry; byte budgets and cache expiry are untouched. -- **Migration:** raw publishers relying on unlimited history must request unlimited, or a longer window, at construction, before publishing a new track or broadcast identity. Readers asking for history still set a sufficient max-delay and range. The PR title carries `!`, its Impact bullet says how to migrate, migration notes go under `## Unreleased`, and the Rust, JS, binding, and user docs change together. -- **Tests:** cover authored omission versus explicit unlimited in each binding, decoded absence staying unlimited, timed and untimed supersession at 30 s, a late join to an unchanged newest snapshot, a direct fetch of a superseded group inside and past the window, media segment fetch, and archive replay. Use mocked time and the existing harnesses, and run all-language interop for the API and FFI scope. Re-check the overlapping PRs listed above rather than duplicating their fixes. - -Public API: breaking in Rust, JS, and every binding (the authored default, and mux `with_max_age(None)`). Wire: none; only authored advertisements change. diff --git a/quest/m2/interop-shutdown-warnings.md b/quest/m2/interop-shutdown-warnings.md index c19b84c3ea5..f09a1b68eb7 100644 --- a/quest/m2/interop-shutdown-warnings.md +++ b/quest/m2/interop-shutdown-warnings.md @@ -17,8 +17,8 @@ Decided 2026-11-03 (maintainer, /quest-plan of the follow-ups from (around lines 1138–1152) warns "publisher '$lang' was still running 10 s after it was stopped; killing it". #7701 saw it for Rust. The comment near `interop.sh:1077` says a finished import stays up for its linger - (max-age), so a longer default max-age, such as - [the 30 s default](/quest/m1/max-age-defaults.md), may outlast the 10 s. + (max-age), so an explicit max-age, such as media's 30 s, may outlast the + 10 s. Decide whether a stop should end the linger, or the harness should wait for it. - Unfinished producer: `track::Producer dropped without finish() or diff --git a/rs/hang/MIGRATE.md b/rs/hang/MIGRATE.md index f83c2ffc365..1eb2d5aaca1 100644 --- a/rs/hang/MIGRATE.md +++ b/rs/hang/MIGRATE.md @@ -4,6 +4,11 @@ How to update your code for each breaking change, newest first. ## Unreleased +### The catalog track advertises a zero max age ([#7729](https://github.com/moq-dev/moq/pull/7729)) + +`Catalog::default_track_info` takes moq-net's new zero default, so the catalog track advertises the live edge only where it advertised no limit. A late joiner still reads the newest snapshot, which never goes stale. +`container::track_info` still declares `container::MAX_AGE` (30 s) on media tracks. + ### Compression moves to the track `catalog::Compression`, the `compression` field on `JsonConfig` and `BinaryConfig`, `Catalog::COMPRESSED_NAME`, and `catalog::Consumer::compressed` are gone. diff --git a/rs/hang/src/catalog/root.rs b/rs/hang/src/catalog/root.rs index adcc3e90d8b..bfb92b0caa7 100644 --- a/rs/hang/src/catalog/root.rs +++ b/rs/hang/src/catalog/root.rs @@ -251,8 +251,8 @@ impl Catalog<()> { /// [`create_track`](moq_net::broadcast::Producer::create_track) at /// [`DEFAULT_NAME`](Self::DEFAULT_NAME). /// - /// Keeps the bare `moq_net` retention rather than the media one: the catalog is - /// snapshot mode, so the useful value is the live edge, which is always kept. + /// Keeps moq-net's default zero max age rather than the media one: the catalog is + /// snapshot mode, so a join reads the newest snapshot, which never goes stale. /// Timed in milliseconds, so snapshots share the broadcast clock with media, and /// [`compress`](moq_net::track::Info::compress)ed, since catalog JSON is small and repetitive. pub fn default_track_info() -> moq_net::track::Info { diff --git a/rs/hang/src/container/frame.rs b/rs/hang/src/container/frame.rs index 00edd06c572..de38a111dc5 100644 --- a/rs/hang/src/container/frame.rs +++ b/rs/hang/src/container/frame.rs @@ -23,10 +23,10 @@ pub const TIMESCALE: Timescale = Timescale::MICRO; /// [`with_timescale`](moq_net::track::Info::with_timescale) for a container that carries the /// source's own scale instead (CMAF and Matroska both do). /// -/// Also declares a retention long enough for a segmented egress to serve a full playlist window, -/// which is why every media track should start here rather than at `Info::default()`. It is a -/// retention budget and a CEILING on what a subscriber may ask to wait for, so it never makes -/// anyone play further behind live: a subscriber's own +/// Also declares [`MAX_AGE`], long enough for a segmented egress to serve a full playlist window, +/// which is why every media track should start here rather than at `Info::default()`, whose max +/// age is zero. It bounds how long a superseded group stays fresh and caps what a subscriber may +/// ask to wait for, so it never makes anyone play further behind live: a subscriber's own /// [`Delay::max`](moq_net::track::Delay::max) defaults to /// [`std::time::Duration::ZERO`](std::time::Duration::ZERO) (skip the moment a newer group arrives). /// @@ -152,15 +152,13 @@ mod test { } #[test] - fn media_tracks_declare_their_retention() { + fn media_tracks_declare_their_max_age() { // A media track is read as history (a segmented egress FETCHes segments a playlist - // advertised), so it declares a finite retention window. - assert_eq!(track_info(crate::catalog::PRIORITY.video).max_age, Some(MAX_AGE)); - - // Retimescaling for a container that carries the source's own scale keeps it, since that - // is the shape that would otherwise reach for `Info::default()` and lose the retention. + // advertised), so it declares a finite max age, kept through a retimescale. + let max_age = Some(MAX_AGE); + assert_eq!(track_info(crate::catalog::PRIORITY.video).max_age, max_age); let at = track_info(crate::catalog::PRIORITY.video).with_timescale(Timescale::MILLI); assert_eq!(at.timescale, Some(Timescale::MILLI)); - assert_eq!(at.max_age, Some(MAX_AGE)); + assert_eq!(at.max_age, max_age); } } diff --git a/rs/hang/src/container/mod.rs b/rs/hang/src/container/mod.rs index ce5d6ffe252..fd35a08ab79 100644 --- a/rs/hang/src/container/mod.rs +++ b/rs/hang/src/container/mod.rs @@ -1,15 +1,15 @@ -/// How long a media track asks its publisher (and, through `track_info`, every relay) to keep a -/// non-latest group fetchable. +/// How long a superseded group of a media track stays fresh: the media publisher's explicit +/// choice, which [`track_info`] declares on every media track. /// -/// Media is the one thing on a broadcast that is read as HISTORY rather than followed at the live -/// edge: a segmented egress (HLS/DASH) may only advertise segments a FETCH can still reach, and a -/// standard player starts several target durations behind live. `moq_net`'s conservative default -/// is sized for a live-edge follower and leaves such a player addressing groups that are already -/// gone. +/// Media is the one thing on a broadcast that is read as history rather than followed at the live +/// edge: a segmented egress (HLS/DASH) may only advertise segments a FETCH can still reach, a +/// standard player starts several target durations behind live, and a recorder absorbs +/// reordering. moq-net's default of zero suits a live-edge follower and would leave those +/// addressing groups that are already stale. /// -/// Declared per track rather than by raising that default, so the tracks that do NOT index history -/// keep the cheap default: the catalog is snapshot mode and an HLS record track restates its window -/// in each new group, so in both the useful value is the live edge, which is retained unconditionally. +/// Declared per track rather than as moq-net's default, so the tracks that do not index history +/// keep the live edge alone: the catalog is snapshot mode and an HLS record track restates its +/// window in each new group, and their newest group never goes stale. pub const MAX_AGE: std::time::Duration = std::time::Duration::from_secs(30); mod frame; diff --git a/rs/moq-archive/src/consumer/tests.rs b/rs/moq-archive/src/consumer/tests.rs index 49f37859cb1..4e36096eedf 100644 --- a/rs/moq-archive/src/consumer/tests.rs +++ b/rs/moq-archive/src/consumer/tests.rs @@ -595,7 +595,10 @@ async fn markers_end_a_followed_archive() { async fn a_re_added_track_replays_both_runs() { let store = Store::new(Mock::memory(), "rec"); let source = broadcast::Info::new().produce(); - let info = track::Info::default().with_timescale(Timescale::MILLI); + // Each run is written before the recorder reads it, so superseded groups must stay fresh. + let info = track::Info::default() + .with_timescale(Timescale::MILLI) + .with_max_age(None); let config = crate::producer::Config::default().with_flush(Duration::from_secs(1)); let recording = tokio::spawn(crate::Producer::new(store.clone(), source.consume(), config).run()); diff --git a/rs/moq-archive/src/producer/backends.rs b/rs/moq-archive/src/producer/backends.rs index 06eeb2b0934..53842193eea 100644 --- a/rs/moq-archive/src/producer/backends.rs +++ b/rs/moq-archive/src/producer/backends.rs @@ -29,10 +29,16 @@ fn config() -> Config { } /// A source with `groups` one-second video groups, and the chat's groups as `(sequence, frames)`. +/// Both are published before the recorder reads them, so neither sets a publisher max age. fn source(groups: u64, chat: &[(u64, &[&str])]) -> (broadcast::Producer, [track::Producer; 2]) { let source = broadcast::Info::new().produce(); let video = source - .create_track(VIDEO, track::Info::default().with_timescale(Timescale::MILLI)) + .create_track( + VIDEO, + track::Info::default() + .with_timescale(Timescale::MILLI) + .with_max_age(None), + ) .unwrap(); for sequence in 0..groups { let mut group = video.create_group(group::Info { sequence }).unwrap(); @@ -42,7 +48,9 @@ fn source(groups: u64, chat: &[(u64, &[&str])]) -> (broadcast::Producer, [track: } group.finish().unwrap(); } - let text = source.create_track(CHAT, track::Info::default()).unwrap(); + let text = source + .create_track(CHAT, track::Info::default().with_max_age(None)) + .unwrap(); for (sequence, frames) in chat { let mut group = text.create_group(group::Info { sequence: *sequence }).unwrap(); for frame in *frames { diff --git a/rs/moq-archive/src/producer/ordered.rs b/rs/moq-archive/src/producer/ordered.rs index a58a5735d19..efc880a55a8 100644 --- a/rs/moq-archive/src/producer/ordered.rs +++ b/rs/moq-archive/src/producer/ordered.rs @@ -154,6 +154,14 @@ mod tests { const MAX_DELAY: Duration = Duration::from_secs(10); + /// A source track with no publisher max age, so a superseded group still reaches the reader + /// and only [`MAX_DELAY`] decides how long a gap is waited for. + fn source(broadcast: &broadcast::Producer) -> track::Producer { + broadcast + .create_track("t", track::Info::default().with_max_age(None)) + .unwrap() + } + fn group(track: &track::Producer, sequence: u64) { let mut group = track.create_group(group::Info { sequence }).unwrap(); group.write_frame(None, "x").unwrap(); @@ -187,7 +195,7 @@ mod tests { #[tokio::test(start_paused = true)] async fn only_a_missing_sequence_waits_the_max_delay() { let broadcast = broadcast::Info::new().produce(); - let track = broadcast.create_track("t", track::Info::default()).unwrap(); + let track = source(&broadcast); let mut ordered = ordered(&broadcast, None).await; group(&track, 0); @@ -216,7 +224,7 @@ mod tests { #[tokio::test(start_paused = true)] async fn lower_arrivals_never_extend_a_gap() { let broadcast = broadcast::Info::new().produce(); - let track = broadcast.create_track("t", track::Info::default()).unwrap(); + let track = source(&broadcast); let mut ordered = ordered(&broadcast, Some(0)).await; group(&track, 10); @@ -233,7 +241,7 @@ mod tests { #[tokio::test(start_paused = true)] async fn handed_out_arrivals_are_dropped() { let broadcast = broadcast::Info::new().produce(); - let track = broadcast.create_track("t", track::Info::default()).unwrap(); + let track = source(&broadcast); let mut ordered = ordered(&broadcast, None).await; for sequence in 0..100 { group(&track, sequence); diff --git a/rs/moq-archive/src/producer/tests.rs b/rs/moq-archive/src/producer/tests.rs index 6353719c33e..55c75a6b85e 100644 --- a/rs/moq-archive/src/producer/tests.rs +++ b/rs/moq-archive/src/producer/tests.rs @@ -31,8 +31,12 @@ fn spawn(store: &Store, broadcast: &broadcast::Producer, config: Config) - tokio::spawn(Producer::new(store.clone(), broadcast.consume(), config).run()) } +/// A millisecond source track with no publisher max age, so the recorder reaches superseded +/// groups and only its own max delay bounds the wait for a missing one. fn timed() -> track::Info { - track::Info::default().with_timescale(Timescale::MILLI) + track::Info::default() + .with_timescale(Timescale::MILLI) + .with_max_age(None) } fn ms(ms: u64) -> Timestamp { diff --git a/rs/moq-audio/src/decode/consumer.rs b/rs/moq-audio/src/decode/consumer.rs index 764576e8429..ab92b59dc07 100644 --- a/rs/moq-audio/src/decode/consumer.rs +++ b/rs/moq-audio/src/decode/consumer.rs @@ -82,7 +82,7 @@ pub struct Options { /// [`Delay::min`] is the playout delay: the jitter buffer a player holds ahead of the /// playhead, reported by [`Consumer::delay`], and where a cold join starts. With /// [`estimate`](Self::estimate) it is a floor under the measured delay instead. A `min` - /// beyond the track's retention is refused. [`Delay::max`] is how far a group may fall + /// beyond the track's max age is refused. [`Delay::max`] is how far a group may fall /// behind the live edge before the subscription skips it; it adds no buffering. pub delay: Delay, /// Measure the playout delay from arrival timing, never below [`Delay::min`] (default: @@ -227,20 +227,20 @@ impl Consumer { subscriber = subscriber.with_range(live_edge.group..); } let track = subscriber; - let retention = track.info().max_age; + let max_age = track.info().max_age; let max_delay = options .delay .max .unwrap_or(Duration::MAX) - .min(retention.unwrap_or(Duration::MAX)); - // Holding more than the publisher keeps would wait on media it has already - // discarded, so the caller asked for something impossible. + .min(max_age.unwrap_or(Duration::MAX)); + // Holding longer than the publisher's max age would wait on groups that go stale + // before they play, so the caller asked for something impossible. let delay = options.delay.min.unwrap_or_default(); - if let Some(retention) = retention - && delay > retention + if let Some(max_age) = max_age + && delay > max_age { return Err(Error::Unsupported(format!( - "playout delay {delay:?} exceeds the track's retention of {retention:?}" + "playout delay {delay:?} exceeds the track's max age of {max_age:?}" ))); } // The catalog says how the track is framed, and it is not always the legacy @@ -291,7 +291,7 @@ impl Consumer { &self.options } - /// The effective skip budget after clamping to retention, excluding decoder warmup. + /// The effective skip budget after clamping to the track's max age, excluding decoder warmup. pub fn max_delay(&self) -> std::time::Duration { self.max_delay } @@ -2326,7 +2326,7 @@ mod tests { } #[tokio::test] - async fn a_delay_beyond_retention_is_refused() { + async fn a_delay_beyond_max_age_is_refused() { let broadcast = moq_net::broadcast::Info::new().produce(); let info = hang::container::track_info(hang::catalog::PRIORITY.audio) .with_max_age(std::time::Duration::from_millis(100)); @@ -2355,7 +2355,7 @@ mod tests { } #[tokio::test] - async fn max_delay_is_clamped_to_publisher_retention() { + async fn max_delay_is_clamped_to_publisher_max_age() { let broadcast = moq_net::broadcast::Info::new().produce(); let info = hang::container::track_info(hang::catalog::PRIORITY.audio) .with_max_age(std::time::Duration::from_millis(100)); diff --git a/rs/moq-audio/src/encode/capture.rs b/rs/moq-audio/src/encode/capture.rs index 404585a8f62..ea1e24004a0 100644 --- a/rs/moq-audio/src/encode/capture.rs +++ b/rs/moq-audio/src/encode/capture.rs @@ -95,7 +95,7 @@ pub struct Capture { /// Encode only while subscribed, retaining raw audio up to the track's `max_age`. /// /// On by default. Capture stays open, and a subscriber encodes the retained past before - /// continuing live. Tracks without `max_age` keep 30 seconds, matching hang's media retention. + /// continuing live. Tracks with an unlimited `max_age` keep 30 seconds, the default media max age. /// Set false to encode continuously instead. pub on_demand: bool, } diff --git a/rs/moq-audio/src/encode/producer.rs b/rs/moq-audio/src/encode/producer.rs index ddc0438e163..d49c6ccb120 100644 --- a/rs/moq-audio/src/encode/producer.rs +++ b/rs/moq-audio/src/encode/producer.rs @@ -134,7 +134,7 @@ impl Reserved { let track = match &options.track { // The catalog's info carries the microsecond timescale audio hang frames stamp, so // Lite05 subscribers know what scale to expect and the model layer accepts - // Frame::timestamp on append, plus whatever retention the broadcast declared. + // Frame::timestamp on append, plus whatever max age the catalog declared. Some(name) => broadcast.create_track(name.clone(), catalog.track_info(hang::catalog::PRIORITY.audio))?, // Mirrors the video side, which derives a unique name from the codec // rather than making every caller invent one. @@ -199,13 +199,13 @@ impl Reserved { /// Spend the reservation on a registered encoder, publishing through the track. fn encode(self, registered: Registered) -> Producer { - let retention = self.track.track().info().max_age.unwrap_or(hang::container::MAX_AGE); + let history = self.track.track().info().max_age.unwrap_or(hang::container::MAX_AGE); let bitrate = registered.encoder.bitrate(); self.track.report_bitrate(bitrate); Producer { backlog: Backlog::new( - retention, + history, registered.encoder.frame_size(), registered.encoder.codec_rate(), ), @@ -885,7 +885,7 @@ mod tests { } /// Replay catches up behind the live edge another track already reached; advertising that as - /// delay would buffer playback by the retention for the rest of the broadcast. + /// delay would buffer playback by the replayed history for the rest of the broadcast. #[tokio::test(start_paused = true)] async fn replayed_history_raises_no_catalog_delay() { let mut broadcast = moq_net::broadcast::Info::new().produce(); diff --git a/rs/moq-bench/src/connection.rs b/rs/moq-bench/src/connection.rs index 05409c94558..0fa2d0993fb 100644 --- a/rs/moq-bench/src/connection.rs +++ b/rs/moq-bench/src/connection.rs @@ -135,7 +135,9 @@ pub async fn run(ctx: Connection) { }; let track = match broadcast.create_track( TRACK, - moq_net::track::Info::default().with_timescale(moq_net::Timescale::MILLI), + moq_net::track::Info::default() + .with_timescale(moq_net::Timescale::MILLI) + .with_max_age(None), ) { Ok(track) => track, Err(err) => { @@ -800,9 +802,12 @@ mod tests { } } - /// A millisecond track: the frames written here carry timestamps. + /// A millisecond track with no publisher max age, for tests that write timestamps and + /// rely on the subscription's own delay rather than the authored zero default. fn timed() -> moq_net::track::Info { - moq_net::track::Info::default().with_timescale(moq_net::Timescale::MILLI) + moq_net::track::Info::default() + .with_timescale(moq_net::Timescale::MILLI) + .with_max_age(None) } async fn wait_for(counter: &AtomicU64, value: u64) { diff --git a/rs/moq-c/MIGRATE.md b/rs/moq-c/MIGRATE.md index b75c742e14a..eb6820f63d3 100644 --- a/rs/moq-c/MIGRATE.md +++ b/rs/moq-c/MIGRATE.md @@ -4,6 +4,12 @@ How to update your code for each breaking change, newest first. ## Unreleased +### Authored tracks default to a zero max age ([#7729](https://github.com/moq-dev/moq/pull/7729)) + +A NULL or zeroed `moq_track_info` now advertises a zero max age, serving only the live edge, instead of no publisher limit. +`max_age_present` is gone and `max_age_us` always applies: drop the assignment where you set it to true, and set the new `max_age_unlimited`, which ignores `max_age_us`, where you relied on it being false for no limit. +Recompile against the new header, since an old binary's `max_age_present` byte now reads as `max_age_unlimited`, and zero-initialize the struct (`moq_track_info info = {0};`) or assign every member, since an indeterminate member is undefined behavior. + ### Datagrams are a track of their own A raw track's datagrams travel on a separate datagram track of the same name, so the C ABI is unchanged but some results differ: diff --git a/rs/moq-c/README.md b/rs/moq-c/README.md index 377774df99f..445f6e51427 100644 --- a/rs/moq-c/README.md +++ b/rs/moq-c/README.md @@ -157,6 +157,13 @@ track's timescale, a microsecond one unless `moq_track_info.timescale` sets another, and `moq_consume_track_frame` points `moq_frame.timestamp` at the timestamp read, valid until the frame is freed, or NULL on an untimed track. +A zeroed `moq_track_info`, like a NULL one, advertises a zero max age, how long +a superseded group stays fresh, so only the live edge is served. Set +`max_age_us` for a longer age, or `max_age_unlimited` for no publisher limit, +which ignores `max_age_us`. Zero-initialize the struct +(`moq_track_info info = {0};`) before assigning members, so every flag starts +false. + JSON window pushes and pops accept an optional `const moq_timestamp *timestamp`, like snapshot updates and stream appends. It is when the edit occurred, converted to the track's milliseconds; pass NULL to stamp the broadcast clock. diff --git a/rs/moq-c/src/api.rs b/rs/moq-c/src/api.rs index 9b5a9767c38..4267530d2d3 100644 --- a/rs/moq-c/src/api.rs +++ b/rs/moq-c/src/api.rs @@ -642,19 +642,21 @@ pub struct moq_datagram { /// Publisher-side raw track properties. /// -/// A null [moq_publish_track] `info` pointer uses the moq-net defaults, and so does a -/// zero-initialized struct. +/// A null [moq_publish_track] `info` pointer uses the moq-net defaults, including a zero max +/// age, and so does a zero-initialized struct. #[repr(C)] pub struct moq_track_info { /// Priority, used to break ties between subscriptions of equal subscriber priority. /// Higher is more urgent; the default 0 is the midpoint. pub priority: i8, - /// Maximum age of a non-latest group before the publisher evicts it, in microseconds. - /// The publisher-side half of `moq_subscription.delay.max_us`. + /// How long a superseded group stays fresh, in microseconds. Zero, the default, serves only + /// the live edge. The publisher-side half of `moq_subscription.delay.max_us`. Ignored when + /// `max_age_unlimited` is set. pub max_age_us: u64, - /// Whether `max_age_us` is set. When false, the publisher imposes no age limit. - pub max_age_present: bool, + /// No publisher age limit, leaving only the cache to bound how long a superseded group is + /// served. + pub max_age_unlimited: bool, /// Per-frame timescale in ticks per second. pub timescale: u64, @@ -679,10 +681,8 @@ impl TryFrom<&moq_track_info> for moq_net::track::Info { // Raw tracks default to a microsecond timescale; an explicit one below overrides it. let mut out = moq_net::track::Info::default() .with_timescale(moq_net::Timescale::MICRO) - .with_priority(info.priority); - if info.max_age_present { - out = out.with_max_age(std::time::Duration::from_micros(info.max_age_us)); - } + .with_priority(info.priority) + .with_max_age((!info.max_age_unlimited).then(|| std::time::Duration::from_micros(info.max_age_us))); if info.timescale_present { out = out.with_timescale(moq_net::Timescale::new(info.timescale)?); } diff --git a/rs/moq-c/src/test.rs b/rs/moq-c/src/test.rs index 788cd996a4d..f5106d36cbd 100644 --- a/rs/moq-c/src/test.rs +++ b/rs/moq-c/src/test.rs @@ -1732,7 +1732,7 @@ fn publish_track_invalid_broadcast() { let info = moq_track_info { priority: 1, max_age_us: 0, - max_age_present: false, + max_age_unlimited: false, timescale: 0, timescale_present: false, refresh: 0, @@ -1767,7 +1767,7 @@ fn publish_track_with_info_rejects_invalid_timescale() { let info = moq_track_info { priority: 0, max_age_us: 0, - max_age_present: false, + max_age_unlimited: false, timescale: 0, timescale_present: true, refresh: 0, @@ -1779,6 +1779,41 @@ fn publish_track_with_info_rejects_invalid_timescale() { assert_eq!(moq_publish_close(broadcast), 0); } +/// A zeroed struct serves only the live edge, and the unlimited flag wins over a stated age, +/// like `moq_delay.max_unlimited`. +#[test] +fn track_info_max_age() { + let zeroed = || moq_track_info { + priority: 0, + max_age_us: 0, + max_age_unlimited: false, + timescale: 0, + timescale_present: false, + refresh: 0, + refresh_present: false, + compress: false, + }; + let max_age = |info: moq_track_info| moq_net::track::Info::try_from(&info).unwrap().max_age; + + assert_eq!(max_age(zeroed()), Some(Duration::ZERO)); + let stated = moq_track_info { + max_age_us: 5_000_000, + ..zeroed() + }; + assert_eq!(max_age(stated), Some(Duration::from_secs(5))); + let unlimited = moq_track_info { + max_age_unlimited: true, + ..zeroed() + }; + assert_eq!(max_age(unlimited), None); + let both = moq_track_info { + max_age_us: 5_000_000, + max_age_unlimited: true, + ..zeroed() + }; + assert_eq!(max_age(both), None); +} + /// Raw frames, datagrams, and JSON values read back exactly the timestamp written: a 90 kHz /// tick that microseconds cannot express, a present zero, and untimed. The C API only creates /// timed tracks, so the tracks and the JSON producer come from moq-net. @@ -2288,7 +2323,7 @@ fn raw_track_subscription_options_and_update() { let info = moq_track_info { priority: 3, max_age_us: 1_000_000, - max_age_present: true, + max_age_unlimited: false, timescale: 1_000_000, timescale_present: true, refresh: 0, @@ -2423,7 +2458,7 @@ fn raw_track_time_anchor() { let info = moq_track_info { priority: 3, max_age_us: 1_000_000, - max_age_present: true, + max_age_unlimited: false, timescale: 1_000_000, timescale_present: true, refresh: 0, @@ -3367,7 +3402,7 @@ fn publish_finish_serves_finished_tracks_until_closed() { let info = moq_track_info { priority: 0, max_age_us: 0, - max_age_present: false, + max_age_unlimited: false, timescale: 0, timescale_present: false, refresh: 0, @@ -4115,7 +4150,7 @@ fn track_demand_reports_the_wanted_group() { let info = moq_track_info { priority: 0, max_age_us: 0, - max_age_present: false, + max_age_unlimited: false, timescale: 0, timescale_present: false, refresh: 0, @@ -4523,8 +4558,18 @@ fn a_group_request_nobody_reads_is_withdrawn() { let origin = id(moq_origin_create()); let broadcast = publish_broadcast(origin, b"track-dynamic-narrowed"); let name = b"data"; - let track = - id(unsafe { moq_publish_track(broadcast, name.as_ptr() as *const c_char, name.len(), std::ptr::null()) }); + // No publisher age limit, so the requested groups behind the live one stay fresh. + let info = moq_track_info { + priority: 0, + max_age_us: 0, + max_age_unlimited: true, + timescale: 0, + timescale_present: false, + refresh: 0, + refresh_present: false, + compress: false, + }; + let track = id(unsafe { moq_publish_track(broadcast, name.as_ptr() as *const c_char, name.len(), &info) }); let group_cb = Callback::new(); let dynamic = id(unsafe { moq_publish_track_requests(track, Some(channel_callback), group_cb.ptr) }); diff --git a/rs/moq-cli/src/archive.rs b/rs/moq-cli/src/archive.rs index 3d42ec99e6f..4012c556d4e 100644 --- a/rs/moq-cli/src/archive.rs +++ b/rs/moq-cli/src/archive.rs @@ -412,7 +412,11 @@ mod tests { let url = Url::from_directory_path(dir.path()).unwrap(); let source = moq_net::broadcast::Info::new().produce(); - let info = track::Info::default().with_timescale(Timescale::MILLI); + // Both groups are written before the recorder reads them, so the superseded one must + // stay fresh. + let info = track::Info::default() + .with_timescale(Timescale::MILLI) + .with_max_age(None); let video = source.create_track("video", info).unwrap(); for sequence in 0..2 { let mut group = video.create_group(group::Info { sequence }).unwrap(); diff --git a/rs/moq-cli/src/args.rs b/rs/moq-cli/src/args.rs index cacc8f64c5a..8677c5e9330 100644 --- a/rs/moq-cli/src/args.rs +++ b/rs/moq-cli/src/args.rs @@ -790,15 +790,15 @@ pub struct Import { #[usage(long = "name", hide = true)] name: Option, - /// How long relays keep a non-latest group of the published media tracks fetchable, - /// e.g. "30s" or "5s". Defaults to hang's 30s. + /// How long a superseded group of the published media tracks stays fresh, e.g. "30s" or + /// "5s". Defaults to 30s. /// - /// A RETENTION budget, not a delivery one: it never makes a subscriber play further behind + /// A freshness bound, not a delivery one: it never makes a subscriber play further behind /// live, it caps how far back a FETCH can still reach (and how long a subscriber may ask to /// wait for a late group). The default suits a segmented egress (HLS/DASH), which may only - /// advertise segments that are still fetchable; lower it when nothing reads history and the - /// memory matters. Media tracks only -- the catalog and HLS records are read at the live - /// edge, which is retained unconditionally. + /// advertise segments that are still fetchable; lower it when nothing reads history. Media + /// tracks only -- the catalog and HLS records keep moq-net's zero default, since they are read at the + /// live edge, which never goes stale. #[usage(long)] pub max_age: Option, @@ -2551,10 +2551,10 @@ mod tests { assert!(err.to_string().contains("--latency-max -> --delay"), "{}", err); } - /// A publisher's retention is `--max-age` on `import`; a subscriber's staleness budget is + /// A publisher's freshness bound is `--max-age` on `import`; a subscriber's staleness budget is /// `--max-delay` for immediate exports and `--delay` for buffered exports. #[test] - fn export_staleness_is_max_delay_and_import_retention_is_max_age() { + fn export_staleness_is_max_delay_and_import_freshness_is_max_age() { let export = |args: &[&str]| { let mut argv = vec!["moq", "export", "--broadcast", "b"]; argv.extend_from_slice(args); diff --git a/rs/moq-cli/src/fetch.rs b/rs/moq-cli/src/fetch.rs index 4c8b8398b8d..1ef750a79e5 100644 --- a/rs/moq-cli/src/fetch.rs +++ b/rs/moq-cli/src/fetch.rs @@ -166,9 +166,12 @@ mod tests { use super::*; use crate::args::{Command, Invocation}; - /// A millisecond track: the frames written here carry timestamps. + /// A millisecond track: the frames written here carry timestamps. It sets no publisher max + /// age, so a fetch still reaches its superseded groups. fn timed() -> moq_net::track::Info { - moq_net::track::Info::default().with_timescale(moq_net::Timescale::MILLI) + moq_net::track::Info::default() + .with_timescale(moq_net::Timescale::MILLI) + .with_max_age(None) } /// The frames of each finished group on the `data` track. diff --git a/rs/moq-cli/src/hls.rs b/rs/moq-cli/src/hls.rs index e8e212eb1a6..e4c1a40b785 100644 --- a/rs/moq-cli/src/hls.rs +++ b/rs/moq-cli/src/hls.rs @@ -50,8 +50,8 @@ pub struct ExportArgs { pub tls: Tls, /// Minimum media listed in each rendition's playlist window, at most 256 segments. - /// Keep it within the relay's group-cache retention, since segments are fetched from - /// there on request. + /// Keep it within the media's max age and the relay's group-cache retention, since + /// segments are fetched from there on request. #[usage(long, default = "16s")] pub window: moq_tokio::cli::Duration, diff --git a/rs/moq-cli/src/hls/record.rs b/rs/moq-cli/src/hls/record.rs index 2891a0d4f87..9e8f3b57e89 100644 --- a/rs/moq-cli/src/hls/record.rs +++ b/rs/moq-cli/src/hls/record.rs @@ -623,7 +623,10 @@ mod tests { let video = names .iter() .map(|name| { - let info = moq_net::track::Info::default().with_timescale(moq_net::Timescale::MILLI); + // Media's max age, so a segment stays fetchable once its successor starts. + let info = moq_net::track::Info::default() + .with_timescale(moq_net::Timescale::MILLI) + .with_max_age(hang::container::MAX_AGE); let track = broadcast.create_track(*name, info).unwrap(); let container = moq_mux::catalog::hang::Container::Legacy(moq_mux::container::Kind::Video); reserved.video(track, container, config_of(320)).unwrap() diff --git a/rs/moq-cli/src/main.rs b/rs/moq-cli/src/main.rs index 8e466f525a5..a2efb6f0a20 100644 --- a/rs/moq-cli/src/main.rs +++ b/rs/moq-cli/src/main.rs @@ -754,7 +754,7 @@ fn spawn_import( reject_listener_cors(&rtc.cors, "import rtc")?; } - let max_age = import.max_age.map(Into::into); + let max_age = Some(import.max_age.map_or(hang::container::MAX_AGE, Into::into)); let linger = import.linger.map_or(moq_mux::Linger::DEFAULT, Into::into); // The MoQ side every gateway publishes into, minted per source since each takes it // by value onto its own task. @@ -830,8 +830,11 @@ fn spawn_import( } } ImportSource::Archive(args) => { - // A replay serves the retention the recording was made with. - anyhow::ensure!(max_age.is_none(), "`--max-age` does not apply to `import archive`"); + // A replay advertises no max age: the archive's retention bounds what it serves. + anyhow::ensure!( + import.max_age.is_none(), + "`--max-age` does not apply to `import archive`" + ); tasks.spawn(archive::import(origin.clone(), name, args, instance)); } #[cfg(feature = "capture")] diff --git a/rs/moq-cli/src/moq.rs b/rs/moq-cli/src/moq.rs index 4d9ec745f2b..55b7c505b96 100644 --- a/rs/moq-cli/src/moq.rs +++ b/rs/moq-cli/src/moq.rs @@ -7,7 +7,7 @@ use hang::moq_net; /// The MoQ side of an import: where a gateway publishes, under what name, the -/// retention it declares on the media tracks it mints, how long a clean end stays +/// max age it declares on the media tracks it mints, how long a clean end stays /// up, and the connection allocator those tracks claim on. /// /// They travel together rather than as loose arguments per entry point. @@ -19,8 +19,8 @@ pub struct ImportTarget { /// The broadcast name to publish under. pub name: String, - /// How long relays keep a non-latest group of the published media tracks fetchable - /// (`--max-age`), or `None` for the publisher's own default. + /// How long a superseded group of the published media tracks stays fresh + /// (`--max-age`, else hang's 30 s media max age), or `None` for no publisher limit. pub max_age: Option, /// How long a cleanly ended broadcast stays up (`--linger`). diff --git a/rs/moq-cli/tests/integration/instances.rs b/rs/moq-cli/tests/integration/instances.rs index f8614c35060..c7e9fc16410 100644 --- a/rs/moq-cli/tests/integration/instances.rs +++ b/rs/moq-cli/tests/integration/instances.rs @@ -74,10 +74,13 @@ fn publish(origin: &origin::Producer, instance: &Instance, tag: &str) -> Publish let route = origin::Route::default().with_instance(instance.clone(), 0); let broadcast = origin.publish("live/catalog.hang", route.clone()).unwrap(); let sibling = origin.publish("live/media", route).unwrap(); + // Media's max age, so its superseded groups stay fetchable. let media = sibling .create_track( "audio", - track::Info::default().with_timescale(moq_net::Timescale::MILLI), + track::Info::default() + .with_timescale(moq_net::Timescale::MILLI) + .with_max_age(hang::container::MAX_AGE), ) .unwrap(); write(&media, &format!("{tag}:0")); diff --git a/rs/moq-crypto/benches/protect.rs b/rs/moq-crypto/benches/protect.rs index 5a1f7ed8334..170395d2471 100644 --- a/rs/moq-crypto/benches/protect.rs +++ b/rs/moq-crypto/benches/protect.rs @@ -32,7 +32,7 @@ fn bench_protect(c: &mut Criterion) { let mut group = c.benchmark_group("protect"); group.throughput(Throughput::Bytes(grouped.len() as u64)); group.bench_function("grouped_1k", |b| { - // Advancing timestamps plus a zero max age keep only the newest group cached. + // Advancing timestamps plus a zero max age leave only the newest group fresh. let info = moq_net::track::Info::default() .with_timescale(moq_net::Timescale::MILLI) .with_max_age(Duration::ZERO); diff --git a/rs/moq-crypto/benches/sign.rs b/rs/moq-crypto/benches/sign.rs index fad191fd460..f05dac9fe24 100644 --- a/rs/moq-crypto/benches/sign.rs +++ b/rs/moq-crypto/benches/sign.rs @@ -10,7 +10,7 @@ use criterion::{Criterion, Throughput, criterion_group, criterion_main}; use moq_crypto::sign::{SecretKey, broadcast}; fn produce(key: &SecretKey) -> (moq_crypto::sign::track::Producer, moq_net::broadcast::Producer) { - // A zero max age keeps only the newest group cached. + // A zero max age leaves only the newest group fresh. let info = moq_net::track::Info::default().with_max_age(Duration::ZERO); let inner = moq_net::broadcast::Info::new().produce(); let path = moq_net::Path::new("bench").unwrap(); diff --git a/rs/moq-crypto/src/e2ee/tests.rs b/rs/moq-crypto/src/e2ee/tests.rs index 02bd7ab1576..e93da945948 100644 --- a/rs/moq-crypto/src/e2ee/tests.rs +++ b/rs/moq-crypto/src/e2ee/tests.rs @@ -346,10 +346,11 @@ fn subscribe_all() -> moq_net::track::Subscription { .with_delay(moq_net::track::Delay::default().with_max(Duration::from_secs(60))) } +/// A track whose superseded groups stay fresh, so [`subscribe_all`] reads every group. fn net_track(name: &Name) -> moq_net::track::Producer { moq_net::broadcast::Info::new() .produce() - .create_track(name.as_str(), timed()) + .create_track(name.as_str(), timed().with_max_age(None)) .unwrap() } diff --git a/rs/moq-ffi/MIGRATE.md b/rs/moq-ffi/MIGRATE.md index 5260084c9d4..d4f56763db0 100644 --- a/rs/moq-ffi/MIGRATE.md +++ b/rs/moq-ffi/MIGRATE.md @@ -5,6 +5,11 @@ These are the UniFFI names; each language wrapper has its own `MIGRATE.md` in it ## Unreleased +### Authored tracks default to a zero max age ([#7729](https://github.com/moq-dev/moq/pull/7729)) + +A null `MoqTrackInfo.max_age`, and a null `MoqTrackInfo`, now advertise a zero max age, serving only the live edge, instead of no publisher limit. Set the new `max_age_unlimited`, which ignores `max_age`, where you relied on null meaning no limit. +A received track's `info()` sets `max_age_unlimited` when its publisher advertised no limit, so the record republishes unchanged. + ### Viewer targets are bounded ([#7090](https://github.com/moq-dev/moq/pull/7090)) Viewer ceilings and PROBE target overrides are refused with the new `MoqError::OutOfRange` once they would sum above 2^53 - 1 bps, the most a PROBE target carries; nothing changes on a refusal. `MoqViewers::watch` and `set_target` and `MoqViewer::update` return a `Result`. Handle the new variant wherever you match the error exhaustively. Regenerate bindings and rebuild the matching native library together. diff --git a/rs/moq-ffi/src/audio.rs b/rs/moq-ffi/src/audio.rs index dc867e1d910..8e2e56d1cd0 100644 --- a/rs/moq-ffi/src/audio.rs +++ b/rs/moq-ffi/src/audio.rs @@ -169,7 +169,7 @@ pub struct MoqAudioDecoderOutput { /// jitter buffer to hold ahead of the playhead, reported by /// [`MoqAudioConsumer::delay`], and where a cold join starts; with /// [`estimate`](Self::estimate) it floors the measured delay instead. A `min` - /// beyond the track's retention is refused. `max` is the congestion-control + /// beyond the track's max age is refused. `max` is the congestion-control /// knob of [`MoqSubscription::delay`](crate::consumer::MoqSubscription::delay): /// a stalled group more than this far behind a newer one is skipped, with no /// buffering added. `None` keeps the moq-mux default of zero for both. diff --git a/rs/moq-ffi/src/bench.rs b/rs/moq-ffi/src/bench.rs index 549f9e213db..26063e83970 100644 --- a/rs/moq-ffi/src/bench.rs +++ b/rs/moq-ffi/src/bench.rs @@ -248,6 +248,7 @@ async fn rust_ffi() { let timed = MoqTrackInfo { priority: 0, max_age: None, + max_age_unlimited: false, refresh: None, timescale: Some(1_000_000), compress: false, diff --git a/rs/moq-ffi/src/consumer.rs b/rs/moq-ffi/src/consumer.rs index ef266870504..422ccce97cd 100644 --- a/rs/moq-ffi/src/consumer.rs +++ b/rs/moq-ffi/src/consumer.rs @@ -186,7 +186,7 @@ pub struct MoqFetchGroupOptions { /// The default 0 is the midpoint. #[uniffi(default = 0)] pub priority: i8, - /// Maximum age behind the live edge; null uses publisher retention alone. + /// Maximum age behind the live edge; null uses the publisher's max age alone. #[uniffi(default = None)] pub max_delay: Option, } diff --git a/rs/moq-ffi/src/producer.rs b/rs/moq-ffi/src/producer.rs index 4228694b7fe..452e4536a6a 100644 --- a/rs/moq-ffi/src/producer.rs +++ b/rs/moq-ffi/src/producer.rs @@ -32,18 +32,23 @@ impl From for MoqPosition { /// Publisher-side track properties, mirroring [`moq_net::track::Info`]. /// /// Construct with the fields you care about; the rest use raw-track defaults -/// (priority 0, no publisher age limit, untimed). +/// (priority 0, a zero max age, untimed). #[derive(Clone, uniffi::Record)] pub struct MoqTrackInfo { /// Priority, used only to break ties between subscriptions of equal subscriber priority. /// Higher is more urgent; the default 0 is the midpoint. #[uniffi(default = 0)] pub priority: i8, - /// Maximum age of a non-latest group before the publisher evicts it. Null imposes no - /// publisher age limit. This is the publisher-side half of - /// [`MoqDelay::max`](crate::consumer::MoqDelay::max). + /// How long a superseded group stays fresh, or null for the default, zero: only the live + /// edge is served. The publisher-side half of + /// [`MoqDelay::max`](crate::consumer::MoqDelay::max). Ignored when `max_age_unlimited` is + /// set. Uniffi can't default a duration, hence null rather than zero. #[uniffi(default = None)] pub max_age: Option, + /// Set no publisher age limit, ignoring `max_age` and leaving only the cache to bound how + /// long a superseded group is served. A received track that advertised none reports this. + #[uniffi(default = false)] + pub max_age_unlimited: bool, /// How many times its first frame a group's later bytes may grow before a joining /// subscriber asks for a new group, or null to never ask. See /// [`MoqTrackDemand::wanted`](crate::demand::MoqTrackDemand::wanted). @@ -65,7 +70,9 @@ impl TryFrom for moq_net::track::Info { let mut out = moq_net::track::Info::default() .with_priority(info.priority) .with_refresh(info.refresh); - if let Some(max_age) = info.max_age { + if info.max_age_unlimited { + out = out.with_max_age(None); + } else if let Some(max_age) = info.max_age { out = out.with_max_age(max_age); } if let Some(ticks) = info.timescale { @@ -96,6 +103,7 @@ impl From<&moq_net::track::Info> for MoqTrackInfo { Self { priority: info.priority, max_age: info.max_age.map(crate::ffi::duration), + max_age_unlimited: info.max_age.is_none(), refresh: info.refresh, timescale: info.timescale.map(|timescale| timescale.as_u64()), compress: info.compress, @@ -1061,28 +1069,36 @@ mod metadata_tests { } #[test] - fn optional_retention_survives_binding_conversion() { - for max_age in [ - None, - Some(std::time::Duration::ZERO), - Some(std::time::Duration::from_secs(30)), + fn max_age_survives_binding_conversion() { + let info = |max_age, max_age_unlimited| MoqTrackInfo { + priority: 0, + max_age, + max_age_unlimited, + refresh: None, + timescale: None, + compress: false, + }; + let zero = Some(std::time::Duration::ZERO); + let five = Some(std::time::Duration::from_secs(5)); + assert_eq!(raw_track_info(None).unwrap().max_age, zero); + for (max_age, unlimited, want) in [ + (None, false, zero), + (five, false, five), + (None, true, None), + // The flag wins over a stated age. + (five, true, None), ] { - let info = MoqTrackInfo { - priority: 0, - max_age, - refresh: None, - timescale: None, - compress: false, - }; - let model = moq_net::track::Info::try_from(info).unwrap(); - assert_eq!(model.max_age, max_age); - assert_eq!(MoqTrackInfo::from(&model).max_age, max_age); + let model = moq_net::track::Info::try_from(info(max_age, unlimited)).unwrap(); + assert_eq!(model.max_age, want); + // A received record republishes unchanged. + let back = MoqTrackInfo::from(&model); + assert_eq!(moq_net::track::Info::try_from(back).unwrap().max_age, want); } } /// C and C++ abort on a duration past `i64::MAX` nanoseconds, so a peer's longer age saturates. #[test] - fn oversized_retention_saturates_for_the_bindings() { + fn oversized_max_age_saturates_for_the_bindings() { let model = moq_net::track::Info::default().with_max_age(std::time::Duration::MAX); let max_age = MoqTrackInfo::from(&model).max_age.unwrap(); assert_eq!(max_age, std::time::Duration::from_nanos(i64::MAX as u64)); diff --git a/rs/moq-ffi/src/test.rs b/rs/moq-ffi/src/test.rs index d523344453b..e8b89539f06 100644 --- a/rs/moq-ffi/src/test.rs +++ b/rs/moq-ffi/src/test.rs @@ -46,12 +46,21 @@ fn timed_info() -> MoqTrackInfo { MoqTrackInfo { priority: 0, max_age: None, + max_age_unlimited: false, refresh: None, timescale: Some(1_000_000), compress: false, } } +/// [`timed_info`] with no publisher age limit, for a test that reads superseded groups. +fn unlimited_info() -> MoqTrackInfo { + MoqTrackInfo { + max_age_unlimited: true, + ..timed_info() + } +} + const TIMEOUT: Duration = Duration::from_secs(10); /// Wait until the FFI runtime has polled work spawned ahead of this call. @@ -810,7 +819,7 @@ async fn audio_raw_publish_from_many_threads() { "tone".into(), snapshot.audio["tone"].clone(), MoqAudioDecoderOutput { - // The track's whole retention: reading starts only after finish, and the budget + // The track's whole max age: reading starts only after finish, and the budget // ages groups by wall clock, so a stalled host would otherwise skip the start. delay: Some(MoqDelay { min: Some(Duration::ZERO), @@ -1252,6 +1261,7 @@ async fn raw_track_datagram_roundtrip() { Some(MoqTrackInfo { priority: 0, max_age: None, + max_age_unlimited: false, refresh: None, timescale: Some(1_000_000), compress: false, @@ -1285,6 +1295,7 @@ async fn raw_track_info_reports_publisher_properties() { let info = MoqTrackInfo { priority: 7, max_age: Some(Duration::from_millis(2_500)), + max_age_unlimited: false, refresh: Some(2), timescale: Some(90_000), compress: true, @@ -1295,6 +1306,7 @@ async fn raw_track_info_reports_publisher_properties() { let got = consumer.info(); assert_eq!(got.priority, 7); assert_eq!(got.max_age, Some(Duration::from_millis(2_500))); + assert!(!got.max_age_unlimited); assert_eq!(got.refresh, Some(2)); assert_eq!(got.timescale, Some(90_000)); assert!(got.compress); @@ -1369,6 +1381,7 @@ async fn data_writes_preserve_the_callers_timestamp() { Some(MoqTrackInfo { priority: 0, max_age: None, + max_age_unlimited: false, refresh: None, timescale: Some(timestamp.scale), compress: false, @@ -1472,6 +1485,7 @@ async fn json_snapshot_roundtrip() { let info = MoqTrackInfo { priority: 0, max_age: None, + max_age_unlimited: false, timescale: Some(1_000_000), refresh: None, compress: true, @@ -1545,6 +1559,7 @@ async fn json_snapshot_refreshes_for_a_joiner() { Some(MoqTrackInfo { priority: 127, max_age: None, + max_age_unlimited: false, refresh: Some(1), timescale: Some(1_000_000), compress: false, @@ -1772,6 +1787,7 @@ async fn json_window_refreshes_a_bounded_checkpoint_for_a_joiner() { Some(MoqTrackInfo { priority: 127, max_age: None, + max_age_unlimited: false, refresh: Some(1), timescale: Some(1_000_000), compress: false, @@ -4453,7 +4469,7 @@ async fn video_decode_start() { rendition.clone(), MoqVideoDecoderOutput { start, - // The track's whole retention, so a slow host does not skip the first group. + // The track's whole max age, so a slow host does not skip the first group. delay: Some(MoqDelay { min: Some(Duration::ZERO), max: Some(Duration::from_secs(30)), @@ -8770,7 +8786,9 @@ async fn shutdown_times_out_on_an_unfinished_track() { #[tokio::test] async fn ascending_subscription_reads_a_cached_backlog_oldest_first() { let broadcast = MoqBroadcastProducer::new().unwrap(); - let track = broadcast.publish_track("events".into(), Some(timed_info())).unwrap(); + let track = broadcast + .publish_track("events".into(), Some(unlimited_info())) + .unwrap(); for timestamp_us in [0, 1_000, 2_000] { let group = track.append_group().unwrap(); group @@ -8982,7 +9000,9 @@ async fn auth_tokens_join_and_leave_the_union() { #[tokio::test] async fn time_anchors_start_at_the_containing_group() { let broadcast = MoqBroadcastProducer::new().unwrap(); - let track = broadcast.publish_track("events".into(), Some(timed_info())).unwrap(); + let track = broadcast + .publish_track("events".into(), Some(unlimited_info())) + .unwrap(); for timestamp_us in [0, 1_000, 2_000] { let group = track.append_group().unwrap(); group @@ -9213,7 +9233,9 @@ fn raw_group_read_frame_cancelled_unfreed_does_not_block_the_next() { #[tokio::test] async fn raw_read_frame_moves_on_when_next_group_takes_its_group() { let broadcast = MoqBroadcastProducer::new().unwrap(); - let track = broadcast.publish_track("events".into(), Some(timed_info())).unwrap(); + let track = broadcast + .publish_track("events".into(), Some(unlimited_info())) + .unwrap(); let consumer = track .consume(Some(MoqSubscription { delay: MoqDelay { @@ -9324,7 +9346,9 @@ async fn raw_next_group_wakes_read_frame_after_unlocking() { async fn raw_track_concurrent_reads_take_every_group_once() { const GROUPS: u64 = 200; let broadcast = MoqBroadcastProducer::new().unwrap(); - let track = broadcast.publish_track("events".into(), Some(timed_info())).unwrap(); + let track = broadcast + .publish_track("events".into(), Some(unlimited_info())) + .unwrap(); // No age limit, so a group nobody has read yet is never skipped for a newer one. let consumer = track .consume(Some(MoqSubscription { @@ -9554,6 +9578,7 @@ async fn audio_subscribe_configuration_boundary() { Some(MoqTrackInfo { priority: 0, max_age: Some(Duration::from_millis(10)), + max_age_unlimited: false, refresh: None, timescale: None, compress: false, diff --git a/rs/moq-gst/src/sink/pad.rs b/rs/moq-gst/src/sink/pad.rs index 69c137250ef..806abe8e5d5 100644 --- a/rs/moq-gst/src/sink/pad.rs +++ b/rs/moq-gst/src/sink/pad.rs @@ -471,7 +471,7 @@ impl Pad { let request = broadcast .reserve_track(name.clone()) .with_context(|| format!("cannot reserve track {name}"))?; - // Raw data keeps a short explicit window for subscribers that buffer its samples. + // Raw data declares a short explicit max age for subscribers that buffer its samples. let info = moq_net::track::Info::default() .with_timescale(moq_net::Timescale::MICRO) .with_max_age(std::time::Duration::from_secs(5)); @@ -2059,10 +2059,10 @@ mod tests { assert!(frame.is_some()); } - // The opaque track declares microseconds so the PTS maps 1:1, and keeps moq-net's retention: the - // media helper raises it to 30s for a segmented egress reading history, which a data track never is. + // The opaque track declares microseconds so the PTS maps 1:1, and a short explicit max age: the + // media helper uses 30s for a segmented egress reading history, which a data track never is. #[tokio::test] - async fn an_opaque_track_declares_micros_and_a_retention_window() { + async fn an_opaque_track_declares_micros_and_a_short_max_age() { gst::init().unwrap(); let (broadcast, catalog) = producers(); let mut pad = Pad::new(); @@ -2083,7 +2083,7 @@ mod tests { assert_eq!( subscriber.info().max_age, Some(std::time::Duration::from_secs(5)), - "an opaque track declares a short retention window" + "an opaque track declares a short max age" ); } diff --git a/rs/moq-hls/src/export/archive_tests.rs b/rs/moq-hls/src/export/archive_tests.rs index 739549482f6..fac89851afe 100644 --- a/rs/moq-hls/src/export/archive_tests.rs +++ b/rs/moq-hls/src/export/archive_tests.rs @@ -120,10 +120,12 @@ impl Recording { let mut sources = HashMap::new(); for name in ["360p", "1080p", "audio"] { - // Legacy media is stamped in microseconds. + // Legacy media is stamped in microseconds. It is published in bursts, so it sets no + // publisher max age and the recorder stores every superseded group. let media = track::Info::default() .with_timescale(Timescale::new(1_000_000).unwrap()) - .with_priority(1); + .with_priority(1) + .with_max_age(None); let media = broadcast.create_track(name, media).unwrap(); sources.insert(name.to_string(), Source { media }); } diff --git a/rs/moq-hls/src/export/mod.rs b/rs/moq-hls/src/export/mod.rs index e517d855c70..843fc5dfaf3 100644 --- a/rs/moq-hls/src/export/mod.rs +++ b/rs/moq-hls/src/export/mod.rs @@ -77,8 +77,8 @@ const CATALOG_RETRY_MAX: Duration = Duration::from_secs(5); pub struct Config { /// Minimum duration of media listed in each rendition's playlist window. Older segments are /// evicted once the remaining ones still cover this span. Past 256 segments they are evicted - /// however short they are. Keep it within the relay's group-cache retention, since segments - /// are fetched from there on request. It also caps segment `Cache-Control: max-age`. + /// however short they are. Keep it within the media's max age and the relay's group-cache + /// retention, since segments are fetched from there on request. It also caps segment `Cache-Control: max-age`. /// /// A durable archive gets the same window: a live playlist stays bounded however much its store /// retains. @@ -500,8 +500,12 @@ async fn watch_catalog(source: moq_mux::Source, renditions: renditions::Producer #[cfg(test)] mod tests { /// A millisecond track: the frames written here carry timestamps. + /// A millisecond track with no publisher max age, so a test's playlist window may span more + /// media than the default max age keeps fresh. fn timed() -> moq_net::track::Info { - moq_net::track::Info::default().with_timescale(moq_net::Timescale::MILLI) + moq_net::track::Info::default() + .with_timescale(moq_net::Timescale::MILLI) + .with_max_age(None) } /// Build an origin producer, spawning its driver on the ambient runtime. diff --git a/rs/moq-hls/src/server/routes.rs b/rs/moq-hls/src/server/routes.rs index ac9953a6d30..54524e9450b 100644 --- a/rs/moq-hls/src/server/routes.rs +++ b/rs/moq-hls/src/server/routes.rs @@ -218,9 +218,12 @@ fn server_error(err: crate::Error) -> Response { mod tests { use super::*; - /// A millisecond track: the frames written here carry timestamps. + /// A millisecond track: the frames written here carry timestamps. It sets no publisher max + /// age, so the segments a playlist lists stay fetchable once superseded. fn timed() -> moq_net::track::Info { - moq_net::track::Info::default().with_timescale(moq_net::Timescale::MILLI) + moq_net::track::Info::default() + .with_timescale(moq_net::Timescale::MILLI) + .with_max_age(None) } const TIMEOUT: Duration = Duration::from_secs(10); diff --git a/rs/moq-hls/tests/integration/support.rs b/rs/moq-hls/tests/integration/support.rs index 9953114e38b..403ca66aa3e 100644 --- a/rs/moq-hls/tests/integration/support.rs +++ b/rs/moq-hls/tests/integration/support.rs @@ -146,9 +146,12 @@ pub fn catalog_config() -> moq_mux::catalog::Config { moq_mux::catalog::Config::default().with_catalog(catalog) } -/// A millisecond track: the frames written here carry timestamps. +/// A millisecond track: the frames written here carry timestamps. It sets no publisher max +/// age, so the segments a playlist lists stay fetchable once superseded. pub fn timed() -> moq_net::track::Info { - moq_net::track::Info::default().with_timescale(moq_net::Timescale::MILLI) + moq_net::track::Info::default() + .with_timescale(moq_net::Timescale::MILLI) + .with_max_age(None) } /// A 320x240 VP8 rendition, whose init its catalog config alone describes. diff --git a/rs/moq-json/src/snapshot/consumer.rs b/rs/moq-json/src/snapshot/consumer.rs index d8f974dec2a..0c01471c93d 100644 --- a/rs/moq-json/src/snapshot/consumer.rs +++ b/rs/moq-json/src/snapshot/consumer.rs @@ -178,9 +178,11 @@ mod timestamps { fn exact_timestamps_survive_reads() { for compress in [false, true] { let scale = moq_net::Timescale::new(90_000).unwrap(); + // Every state is read, superseded groups included, so they must stay fresh. let info = moq_net::track::Info::default() .with_timescale(scale) - .with_compress(compress); + .with_compress(compress) + .with_max_age(None); let track = moq_net::broadcast::Info::new() .produce() .create_track("data", info) diff --git a/rs/moq-json/src/stream/mod.rs b/rs/moq-json/src/stream/mod.rs index ef98b0d434f..ce6e399a493 100644 --- a/rs/moq-json/src/stream/mod.rs +++ b/rs/moq-json/src/stream/mod.rs @@ -370,11 +370,12 @@ mod test { fn a_second_group_is_reported_while_the_first_is_open() { let track = moq_net::broadcast::Info::new() .produce() - .create_track("test", timed()) + .create_track("test", timed().with_max_age(None)) .unwrap(); // Ask for a replay window, so the first group is delivered rather than skipped by the - // subscriber's default max delay budget once a newer group exists. + // subscriber's default max delay budget once a newer group exists. The track keeps it + // fresh with an unlimited max age. let subscription = moq_net::track::Subscription::default() .with_delay(moq_net::track::Delay::default().with_max(std::time::Duration::from_secs(30))); let subscriber = track.subscribe(subscription); diff --git a/rs/moq-json/src/window/mod.rs b/rs/moq-json/src/window/mod.rs index 2116aecab48..71a4b0897c3 100644 --- a/rs/moq-json/src/window/mod.rs +++ b/rs/moq-json/src/window/mod.rs @@ -965,9 +965,10 @@ mod test { #[test] fn cut_finishes_the_group_and_the_next_edit_restates() { + // The superseded first group is inspected too, so it must stay fresh. let track = moq_net::broadcast::Info::new() .produce() - .create_track("test", moq_net::track::Info::default()) + .create_track("test", moq_net::track::Info::default().with_max_age(None)) .unwrap(); let replay = moq_net::track::Subscription::default() .with_delay(moq_net::track::Delay::default().with_max(std::time::Duration::from_secs(30))); diff --git a/rs/moq-mux/MIGRATE.md b/rs/moq-mux/MIGRATE.md index fa580fcf187..090dd32c02e 100644 --- a/rs/moq-mux/MIGRATE.md +++ b/rs/moq-mux/MIGRATE.md @@ -4,6 +4,23 @@ How to adopt new APIs and update for breaking changes, newest first. ## Unreleased +### `catalog::Config::with_max_age(None)` is unlimited ([#7729](https://github.com/moq-dev/moq/pull/7729)) + +`Config::with_max_age` no longer treats `None` as "keep hang's default": an unset `Config` mints media tracks with `hang::container::MAX_AGE` (30 s), as before, `None` sets no publisher limit, and a value is that value. +Callers that passed an optional override straight through call `with_max_age` only when it is set. + +```rust +// Before +Config::default().with_max_age(override_or_none); +// After +let mut config = Config::default(); +if let Some(max_age) = override_or_none { + config = config.with_max_age(max_age); +} +``` + +The catalog and HLS record tracks take moq-net's new zero default instead of no limit; their newest group restates them. + ### Shared playout timing Native players can use `timeline::Producer` and its read-only `Consumer` instead diff --git a/rs/moq-mux/src/catalog/producer.rs b/rs/moq-mux/src/catalog/producer.rs index d9d1e665898..be235d269cd 100644 --- a/rs/moq-mux/src/catalog/producer.rs +++ b/rs/moq-mux/src/catalog/producer.rs @@ -354,10 +354,9 @@ pub struct Producer { /// Every media track's join interval, declared once as `media.join.interval`. intervals: super::interval::Intervals, - /// Retention override for the media tracks minted under this catalog, or `None` to keep - /// hang's default. Fixed at construction, so every clone and every - /// [`Reserved`](super::Reserved) mints tracks under one policy. See - /// [`Config::with_max_age`]. + /// The max age of the media tracks minted under this catalog, or `None` for no publisher + /// limit. Fixed at construction, so every clone and every [`Reserved`](super::Reserved) + /// mints tracks under one policy. See [`Config::with_max_age`]. max_age: Option, /// Connection allocator passthrough tracks claim their peak-hold bitrate on. /// See [`Config::with_bandwidth`]. @@ -403,7 +402,7 @@ impl Default for Config<()> { fn default() -> Self { Self { catalog: Catalog::default(), - max_age: None, + max_age: Some(hang::container::MAX_AGE), bandwidth: moq_net::bandwidth::Allocator::unlimited(), clock: None, } @@ -439,17 +438,18 @@ impl Config { self } - /// Override how long the media tracks minted under this catalog keep a non-latest group - /// fetchable, replacing hang's default. `None` keeps it. + /// Set how long a superseded group of the media tracks minted under this catalog stays + /// fresh, or `None` for no publisher limit. Defaults to + /// [`MAX_AGE`](hang::container::MAX_AGE). /// /// That default suits a segmented egress (HLS/DASH), which may only advertise segments a - /// FETCH can still reach. Lower it when nothing reads history and the memory matters; - /// raise it for a deeper seek window. It is a RETENTION budget, not a delivery one, so it - /// never makes a subscriber play further behind live -- it caps what one may ask to wait - /// for, and a subscriber's own budget still defaults to zero. + /// FETCH can still reach. Lower it when nothing reads history; raise it for a deeper seek + /// window. It is a freshness bound, not a delivery one, so it never makes a subscriber play + /// further behind live -- it caps what one may ask to wait for, and a subscriber's own + /// budget still defaults to zero. /// - /// Applies to the media tracks the catalog mints. The catalog tracks keep moq-net's default: - /// they are read at the live edge, which is retained unconditionally. + /// Applies to the media tracks the catalog mints. The catalog tracks keep moq-net's zero + /// default: they are read at the live edge, which never goes stale. pub fn with_max_age(mut self, max_age: impl Into>) -> Self { self.max_age = max_age.into(); self @@ -528,18 +528,14 @@ impl Producer { }) } - /// Track properties for a media track under this catalog: hang's media defaults, plus any - /// [`Config::with_max_age`] override. + /// Track properties for a media track under this catalog: hang's media defaults, with the + /// [`Config::with_max_age`] policy. /// /// `priority` should come from [`PRIORITY`](hang::catalog::PRIORITY) for the kind of media /// the track carries. Chain [`with_timescale`](moq_net::track::Info::with_timescale) for a /// container that carries the source's own scale (CMAF and Matroska both do). pub fn track_info(&self, priority: i8) -> moq_net::track::Info { - let info = hang::container::track_info(priority); - match self.max_age { - Some(max_age) => info.with_max_age(max_age), - None => info, - } + hang::container::track_info(priority).with_max_age(self.max_age) } /// Resolve a timestamp, synthesizing one from the broadcast's shared @@ -1713,17 +1709,22 @@ mod test { } #[test] - fn media_tracks_inherit_the_catalogs_declared_retention() { + fn media_tracks_take_the_catalogs_max_age() { let mut broadcast = moq_net::broadcast::Info::new().produce(); - // Unset, a catalog mints hang's media defaults, sized so a segmented egress can serve a - // full playlist window. Raw tracks impose no publisher age limit. + // Unset, a catalog mints hang's media max age, sized so a segmented egress can serve a + // full playlist window. let catalog = Producer::new(&mut broadcast, Config::default()).unwrap(); assert_eq!( catalog.track_info(hang::catalog::PRIORITY.video).max_age, - hang::container::track_info(hang::catalog::PRIORITY.video).max_age + Some(hang::container::MAX_AGE) ); + // `None` is an explicit unlimited, not a request for the default. + let mut broadcast = moq_net::broadcast::Info::new().produce(); + let catalog = Producer::new(&mut broadcast, Config::default().with_max_age(None)).unwrap(); + assert_eq!(catalog.track_info(hang::catalog::PRIORITY.video).max_age, None); + // An override reaches every media track this catalog mints, and does NOT disturb the // timescale hang pins (or survive a retimescale for a source-scale container). let mut broadcast = moq_net::broadcast::Info::new().produce(); diff --git a/rs/moq-mux/src/catalog/tracks.rs b/rs/moq-mux/src/catalog/tracks.rs index b0fbf73ae8b..06c9d4d3341 100644 --- a/rs/moq-mux/src/catalog/tracks.rs +++ b/rs/moq-mux/src/catalog/tracks.rs @@ -452,7 +452,7 @@ impl Reserved { self } - /// Track properties for a media track under this catalog, carrying any retention it declares. + /// Track properties for a media track under this catalog, carrying any max age it declares. /// See [`Producer::track_info`](super::Producer::track_info). pub fn track_info(&self, priority: i8) -> moq_net::track::Info { self.timebase.catalog.track_info(priority) diff --git a/rs/moq-mux/src/container/consumer.rs b/rs/moq-mux/src/container/consumer.rs index 27c845a3e76..da4be0b5188 100644 --- a/rs/moq-mux/src/container/consumer.rs +++ b/rs/moq-mux/src/container/consumer.rs @@ -277,7 +277,7 @@ impl Consumer { /// Create a Consumer wrapping the given moq-lite consumer, decoding `format`. /// /// The ordering window inherits the subscriber's current max delay budget, clamped - /// to the track's retention window. Put that budget on the + /// to the track's max age. Put that budget on the /// [`moq_net::track::Subscription`] before awaiting the subscription, so the /// publisher preserves the same replay window. pub fn new(track: moq_net::track::Subscriber, format: F) -> Self { @@ -285,9 +285,9 @@ impl Consumer { // Delivery starts at the subscription floor; without one it starts wherever // the publisher does, adopted from the first arrivals (see poll_read). Either // way the age budget is the one rule that catches the cursor up to the live - // edge from there. The budget is clamped to the track's retention window, - // since history the publisher no longer keeps can't be waited for and would - // otherwise stall the catch-up by the excess. + // edge from there. The budget is clamped to the track's max age, since a group + // the publisher already marks stale can't be waited for and would otherwise + // stall the catch-up by the excess. let start = track.floor(); let max_delay = subscription .delay @@ -357,8 +357,8 @@ impl Consumer { /// A subscription that names a start already waits for it, and a live start takes the newest /// group. pub fn with_warmup(mut self, warmup: std::time::Duration) -> Self { - // Carve the warmup out of what was asked for, then clamp to retention as `new` does, so a - // budget the track can keep is not cut by the clamp too. + // Carve the warmup out of what was asked for, then clamp to max age as `new` does, so a + // budget within the track's max age is not cut by the clamp too. if let Some(track) = &self.track { let requested = track.subscription().delay.max.unwrap_or(std::time::Duration::MAX); self.max_delay = requested @@ -1117,7 +1117,7 @@ impl Consumer { /// Set the [`Delay`], mid-stream or before the first read. /// - /// [`Delay::max`] is clamped to the track's retention window like [`new`](Self::new). The + /// [`Delay::max`] is clamped to the track's max age like [`new`](Self::new). The /// subscription keeps the requested delay verbatim, its max plus any /// [`with_warmup`](Self::with_warmup). An unstated [`Delay::min`] reads as zero here, and moves /// only a start still to come. A min past the max starts at the max, since the publisher serves @@ -1480,9 +1480,12 @@ mod tests { use bytes::Bytes; - /// A millisecond track: the frames written here carry timestamps. + /// A millisecond track: the frames written here carry timestamps. It sets no publisher max + /// age, so the test's delay budget alone decides which superseded groups are read. fn timed() -> moq_net::track::Info { - moq_net::track::Info::default().with_timescale(moq_net::Timescale::MILLI) + moq_net::track::Info::default() + .with_timescale(moq_net::Timescale::MILLI) + .with_max_age(None) } /// Mint a standalone track for tests via a throwaway broadcast, since tracks are @@ -1601,8 +1604,8 @@ mod tests { } /// Wrap `track` so only the container consumer performs age skips. The - /// transport gets the media track's full retention window and hands over every - /// retained group; what the container does with them is what the test measures. + /// transport gets the media track's full max age and hands over every + /// fresh group; what the container does with them is what the test measures. /// /// Both layers enforce the same budget, and normally should: the transport skipping /// a group the consumer was going to skip anyway just saves the bandwidth. These @@ -3541,10 +3544,10 @@ mod tests { assert_eq!(frame.timestamp, ts(4_400_000)); } - /// The warmup is carved out of the requested budget before the retention clamp, so a max delay - /// the track can keep stays whole. + /// The warmup is carved out of the requested budget before the max age clamp, so a max delay + /// within the track's max age stays whole. #[tokio::test] - async fn the_warmup_is_carved_before_the_retention_clamp() { + async fn the_warmup_is_carved_before_the_max_age_clamp() { let mut info = hang::container::track_info(hang::catalog::PRIORITY.audio); info.max_age = Some(Duration::from_secs(1)); let mut track = track_producer("test", info); @@ -4730,7 +4733,7 @@ mod tests { assert_eq!(frames.len(), 1); } - /// A finished group aborted afterwards (aged out of the track's max age window) + /// A finished group aborted afterwards (idle past the cache pool's expiry window) /// keeps serving the frames it still holds: an abort only matters where a frame is /// missing, so a reader that stopped short of the end drains the rest and moves on /// to the next buffered group instead of ending the track. diff --git a/rs/moq-mux/src/container/flv/export_test.rs b/rs/moq-mux/src/container/flv/export_test.rs index 020b1f64dd2..886fc7c8c54 100644 --- a/rs/moq-mux/src/container/flv/export_test.rs +++ b/rs/moq-mux/src/container/flv/export_test.rs @@ -10,9 +10,12 @@ use hang::catalog::{AudioCodec, VideoCodec}; use super::{Export, Import}; -/// A millisecond track: the frames written here carry timestamps. +/// A millisecond media track: the frames written here carry timestamps. It declares media's +/// max age, so an exporter started after publishing still reads the superseded groups. fn timed() -> moq_net::track::Info { - moq_net::track::Info::default().with_timescale(moq_net::Timescale::MILLI) + moq_net::track::Info::default() + .with_timescale(moq_net::Timescale::MILLI) + .with_max_age(hang::container::MAX_AGE) } /// Open an FLV export on the hang catalog of `source`. @@ -26,8 +29,8 @@ async fn open_export(source: crate::Source) -> Export /// A drift budget no test timeline comes close to, so the exporter reads every group. /// -/// The media track's full retention window, so an exporter started after publishing -/// can still read every retained group. These tests write or import a whole broadcast +/// The media track's full max age, so an exporter started after publishing +/// can still read every fresh group. These tests write or import a whole broadcast /// and only then export it, which the /// exporter's default [`Duration::ZERO`] collapses to the /// live edge: completeness has to be asked for, exactly as a real recorder does. diff --git a/rs/moq-mux/src/container/fmp4/export_test.rs b/rs/moq-mux/src/container/fmp4/export_test.rs index 9c4d26571f6..02b42f6dae7 100644 --- a/rs/moq-mux/src/container/fmp4/export_test.rs +++ b/rs/moq-mux/src/container/fmp4/export_test.rs @@ -12,8 +12,8 @@ fn timed() -> moq_net::track::Info { moq_net::track::Info::default().with_timescale(moq_net::Timescale::MILLI) } -/// The media track's full retention window, so an exporter started after publishing -/// can still read every retained group. These tests write or import a whole broadcast +/// The media track's full max age, so an exporter started after publishing +/// can still read every fresh group. These tests write or import a whole broadcast /// and only then export it, which the /// exporter's default [`std::time::Duration::ZERO`](std::time::Duration::ZERO) collapses to the /// live edge: completeness has to be asked for, exactly as a real recorder does. diff --git a/rs/moq-mux/src/container/fmp4/import_test.rs b/rs/moq-mux/src/container/fmp4/import_test.rs index 8c6b64913ad..e5de0c89f42 100644 --- a/rs/moq-mux/src/container/fmp4/import_test.rs +++ b/rs/moq-mux/src/container/fmp4/import_test.rs @@ -4,8 +4,8 @@ use mp4_atom::{Atom, Decode, Encode}; /// A drift budget no test timeline comes close to, so every group is read. /// -/// The media track's full retention window, so a reader started after publishing can -/// still read every retained group. These tests write every group up front, which the +/// The media track's full max age, so a reader started after publishing can +/// still read every fresh group. These tests write every group up front, which the /// default [`std::time::Duration::ZERO`](std::time::Duration::ZERO) budget collapses to the live /// edge: completeness has to be asked for. const RECORDING_MAX_DELAY: std::time::Duration = std::time::Duration::from_secs(30); diff --git a/rs/moq-mux/src/container/mkv/export_test.rs b/rs/moq-mux/src/container/mkv/export_test.rs index ada094e8118..72db47bf4c7 100644 --- a/rs/moq-mux/src/container/mkv/export_test.rs +++ b/rs/moq-mux/src/container/mkv/export_test.rs @@ -15,8 +15,8 @@ use crate::container::test_util::{IDR, Live, PPS, SPS, raw_frame, video_frame}; /// A drift budget no test timeline comes close to, so the exporter reads every group. /// -/// The media track's full retention window, so an exporter started after publishing -/// can still read every retained group. These tests import a whole file and only then +/// The media track's full max age, so an exporter started after publishing +/// can still read every fresh group. These tests import a whole file and only then /// export it, which the exporter's default /// [`std::time::Duration::ZERO`](std::time::Duration::ZERO) collapses to the live edge: /// completeness has to be asked for, exactly as a real recorder does. diff --git a/rs/moq-mux/src/container/producer.rs b/rs/moq-mux/src/container/producer.rs index d9d6a9d4699..6d823fa1ab2 100644 --- a/rs/moq-mux/src/container/producer.rs +++ b/rs/moq-mux/src/container/producer.rs @@ -1016,8 +1016,8 @@ mod tests { .with_delay(moq_net::track::Delay::default().with_max(RECORDING_MAX_DELAY)) } - /// The media track's full retention window, so readers started after publishing - /// can still consume every retained group. + /// The media track's full max age, so readers started after publishing + /// can still consume every fresh group. const RECORDING_MAX_DELAY: std::time::Duration = std::time::Duration::from_secs(30); fn frame(timestamp_us: u64, keyframe: bool) -> Frame { @@ -1401,7 +1401,7 @@ mod tests { /// continuity from adjacent sequences. #[tokio::test] async fn discontinuity_publishes_an_empty_group() { - // The resumed clock jumps forty minutes, so both the retention window and the + // The resumed clock jumps forty minutes, so both the max age and the // drift budget have to cover it or the pre-discontinuity group reads as ancient. let discontinuity_max_age = std::time::Duration::from_secs(41 * 60); let info = hang::container::track_info(hang::catalog::PRIORITY.audio).with_max_age(discontinuity_max_age); diff --git a/rs/moq-mux/src/container/ts/export.rs b/rs/moq-mux/src/container/ts/export.rs index b969a6161b8..ec4b9102bf4 100644 --- a/rs/moq-mux/src/container/ts/export.rs +++ b/rs/moq-mux/src/container/ts/export.rs @@ -1288,10 +1288,11 @@ struct SiTrack { dirty: bool, /// Media timestamp of the last emission ([`Export::mux`]). last_emit: Option, - /// The same budget the media sources use. SI carries table snapshots at a low - /// rate, so the real-time default would take only the newest group and drop - /// the revisions between: an SI track needs the export's replay window as much - /// as the media it describes. + /// The same budget the media sources use, asked of the SI track's publisher, and + /// capped by that publisher's max age. A snapshot table needs only its newest group, + /// which never goes stale. A clock table (TDT/TOT) needs every revision to stay on + /// the subscription until media reaches its stamped slot ([`Self::advance`]), so the + /// TS importer's SI tracks declare their catalog's media max age ([`super::si::track_info`]). max_age: Duration, } diff --git a/rs/moq-mux/src/container/ts/export_test.rs b/rs/moq-mux/src/container/ts/export_test.rs index 7bbd011a3a2..f48d87260e7 100644 --- a/rs/moq-mux/src/container/ts/export_test.rs +++ b/rs/moq-mux/src/container/ts/export_test.rs @@ -84,8 +84,8 @@ fn length_prefixed(nals: &[&[u8]]) -> Bytes { /// paused time) or the stream ends. /// A drift budget no test timeline comes close to, so the exporter reads every group. /// -/// The media track's full retention window, so an exporter started after publishing -/// can still read every retained group. These tests write a whole broadcast up front +/// The media track's full max age, so an exporter started after publishing +/// can still read every fresh group. These tests write a whole broadcast up front /// and only then export it, which the /// exporter's default [`Duration::ZERO`] collapses to the /// live edge: completeness has to be asked for, exactly as a real recorder does. @@ -3241,39 +3241,24 @@ fn make_long_section(table_id: u8, ext: u16, version: u8, number: u8, last: u8, s } -/// Read an SI snapshot track from the start: every group, as its frames' payloads. +/// The newest snapshot group of an SI track: its sequence, and its frames' payloads. /// -/// Starting at group 0 only asks the publisher to send from there; the default -/// [`Duration::ZERO`] budget then skips every group the live edge has -/// already passed, which is all of them once the importer has finished. A budget -/// wider than the test's wall-clock span (every cut lands within microseconds) is -/// what actually delivers the history, so a count of groups counts cuts. -async fn read_si_groups(consumer: &moq_net::broadcast::Consumer, name: &str) -> Vec> { - let mut track = consumer - .track(name) - .unwrap() - .subscribe( - moq_net::track::Subscription::default() - .with_range(0..) - .with_delay(moq_net::track::Delay::default().with_max(Duration::from_secs(5))), - ) - .await - .unwrap(); - let mut groups = Vec::new(); - while let Some(mut group) = track.recv_group().await.unwrap() { - let mut frames = Vec::new(); - while let Some(frame) = kio::wait(|waiter| group.poll_read_frame(waiter)).await.unwrap() { - frames.push(frame.payload); - } - groups.push(frames); +/// An SI track keeps the default zero max age: a superseded snapshot is stale at once, so only +/// the newest is served. Its groups are appended from sequence 0, so the sequence counts the +/// cuts before it, and a test checks an earlier revision's snapshot right after cutting it. +async fn newest_si_group(consumer: &moq_net::broadcast::Consumer, name: &str) -> (u64, Vec) { + let mut track = consumer.track(name).unwrap().subscribe(None).await.unwrap(); + let mut group = track.recv_group().await.unwrap().expect("a snapshot group"); + let mut frames = Vec::new(); + while let Some(frame) = kio::wait(|waiter| group.poll_read_frame(waiter)).await.unwrap() { + frames.push(frame.payload); } - groups + (group.sequence, frames) } /// The newest snapshot of an SI track, reduced to its sections. async fn read_si_sections(consumer: &moq_net::broadcast::Consumer, name: &str) -> Vec { - let groups = read_si_groups(consumer, name).await; - let frames = groups.last().expect("at least one snapshot group"); + let (_, frames) = newest_si_group(consumer, name).await; frames .iter() .flat_map(crate::container::ts::si::split_sections) @@ -3426,14 +3411,13 @@ async fn service_layer_survives_roundtrip() { Some(Duration::from_secs(10)), "the DVB NIT interval was filled in" ); - let nit_groups = read_si_groups(&consumer, &nit_entry.track).await; + let (nit_sequence, nit_frames) = newest_si_group(&consumer, &nit_entry.track).await; assert_eq!( - nit_groups.len(), - 1, + nit_sequence, 0, "the repeated NIT committed once; a repetition cuts no group" ); assert_eq!( - nit_groups[0], + nit_frames, vec![Bytes::from(nit.clone())], "the NIT snapshot is the section, byte-for-byte" ); @@ -4571,21 +4555,23 @@ async fn torn_transition_is_never_published() { let mut input = si_packet(0x0011, &sdt(5, 0, 0xaa)); input.extend_from_slice(&si_packet_cc(0x0011, &sdt(5, 1, 0xab), 1)); rig.import.decode(&BytesMut::from(&input[..])).unwrap(); + let si = rig.catalog.snapshot().ext.mpegts.si.clone(); + let track = &si[&0x0011][&0x42].track; + // A superseded snapshot is stale at once, so each batch's newest is read before the next. + let mut snapshots = vec![newest_si_group(&rig.consumer, track).await]; // Version 6 arrives torn across two batches; the intermediate state (section 0 // at v6, section 1 still v5) must never hit the track. rig.import .decode(&BytesMut::from(&si_packet_cc(0x0011, &sdt(6, 0, 0xba), 2)[..])) .unwrap(); + snapshots.push(newest_si_group(&rig.consumer, track).await); rig.import .decode(&BytesMut::from(&si_packet_cc(0x0011, &sdt(6, 1, 0xbb), 3)[..])) .unwrap(); rig.import.finish().unwrap(); + snapshots.push(newest_si_group(&rig.consumer, track).await); - let si = rig.catalog.snapshot().ext.mpegts.si.clone(); - let track = &si[&0x0011][&0x42].track; - let groups = read_si_groups(&rig.consumer, track).await; - assert!(!groups.is_empty(), "at least one snapshot group"); - for (i, frames) in groups.iter().enumerate() { + for (sequence, frames) in &snapshots { let versions: Vec = frames .iter() .flat_map(crate::container::ts::si::split_sections) @@ -4593,7 +4579,7 @@ async fn torn_transition_is_never_published() { .collect(); assert!( versions.windows(2).all(|w| w[0] == w[1]), - "group {i} mixes versions: {versions:?}" + "group {sequence} mixes versions: {versions:?}" ); } assert_eq!( @@ -4827,20 +4813,24 @@ async fn an_sdt_revision_dropping_the_service_retires_it() { .map(|tables| tables[&0x42].track.clone()) }; + // A superseded snapshot is stale at once, so each revision's is read before the next. let track = revise(0, &[(1, b"One"), (2, b"Two")]).expect("the SDT is advertised"); + let mut groups = vec![newest_si_group(&consumer, &track).await]; assert_eq!(revise(1, &[(2, b"Two")]), None, "the revision retired the SDT entry"); + groups.push(newest_si_group(&consumer, &track).await); assert_eq!( revise(2, &[(1, b"One"), (2, b"Two")]), Some(track.clone()), "listed again, on the same track" ); capture.finish(Timestamp::ZERO).unwrap(); + groups.push(newest_si_group(&consumer, &track).await); - let groups = read_si_groups(&consumer, &track).await; - assert_eq!(groups.len(), 3, "one snapshot per revision"); - assert_sdt_lists_only(&groups[0][0], 0, 1, b"One"); - assert!(groups[1].is_empty(), "the retiring snapshot carries no SDT"); - assert_sdt_lists_only(&groups[2][0], 2, 1, b"One"); + let sequences: Vec = groups.iter().map(|(sequence, _)| *sequence).collect(); + assert_eq!(sequences, [0, 1, 2], "one snapshot per revision"); + assert_sdt_lists_only(&groups[0].1[0], 0, 1, b"One"); + assert!(groups[1].1.is_empty(), "the retiring snapshot carries no SDT"); + assert_sdt_lists_only(&groups[2].1[0], 2, 1, b"One"); } /// A corrupted SDT actual is not rebuilt under a fresh, valid CRC: the section is @@ -4874,6 +4864,8 @@ async fn a_corrupt_sdt_keeps_the_last_good_snapshot() { }; let track = feed(sdt_actual(0, 0, 0, &[(1, b"One")])).expect("the SDT is advertised"); + // A superseded snapshot is stale at once, so the first is read before the next revision. + let first = newest_si_group(&consumer, &track).await; // One unflagged bit flip turns the service name "One" into "Nne" under the source CRC. let mut corrupt = sdt_actual(1, 0, 0, &[(1, b"One")]); let name = corrupt.len() - 4 - 3; @@ -4881,11 +4873,11 @@ async fn a_corrupt_sdt_keeps_the_last_good_snapshot() { assert_eq!(feed(corrupt), Some(track.clone()), "the corrupt revision kept the SDT"); assert_eq!(feed(sdt_actual(2, 0, 0, &[(1, b"Uno")])), Some(track.clone())); capture.finish(Timestamp::ZERO).unwrap(); + let last = newest_si_group(&consumer, &track).await; - let groups = read_si_groups(&consumer, &track).await; - assert_eq!(groups.len(), 2, "no snapshot for the corrupt revision"); - assert_sdt_lists_only(&groups[0][0], 0, 1, b"One"); - assert_sdt_lists_only(&groups[1][0], 2, 1, b"Uno"); + assert_eq!((first.0, last.0), (0, 1), "no snapshot for the corrupt revision"); + assert_sdt_lists_only(&first.1[0], 0, 1, b"One"); + assert_sdt_lists_only(&last.1[0], 2, 1, b"Uno"); } /// A multi-section SDT revision with the selected service's section corrupt does not @@ -4919,6 +4911,8 @@ async fn a_partial_sdt_revision_keeps_the_last_good_snapshot() { feed(sdt_actual(0, 0, 1, &[(1, b"One")])); let track = feed(sdt_actual(0, 1, 1, &[(2, b"Two")])).expect("the SDT is advertised"); + // A superseded snapshot is stale at once, so the first is read before the next revision. + let first = newest_si_group(&consumer, &track).await; let mut corrupt = sdt_actual(1, 0, 1, &[(1, b"One")]); let name = corrupt.len() - 4 - 3; corrupt[name] ^= 0x01; @@ -4931,11 +4925,11 @@ async fn a_partial_sdt_revision_keeps_the_last_good_snapshot() { ); assert_eq!(feed(sdt_actual(1, 0, 1, &[(1, b"Uno")])), Some(track.clone())); capture.finish(Timestamp::ZERO).unwrap(); + let last = newest_si_group(&consumer, &track).await; - let groups = read_si_groups(&consumer, &track).await; - assert_eq!(groups.len(), 2, "no snapshot for the partial revision"); - assert_sdt_lists_only(&groups[0][0], 0, 1, b"One"); - assert_sdt_lists_only(&groups[1][0], 1, 1, b"Uno"); + assert_eq!((first.0, last.0), (0, 1), "no snapshot for the partial revision"); + assert_sdt_lists_only(&first.1[0], 0, 1, b"One"); + assert_sdt_lists_only(&last.1[0], 1, 1, b"Uno"); } /// A selection filters EIT schedule actual (0x50..=0x5F) by service, as it does @@ -5100,8 +5094,8 @@ async fn tdt_round_trips_as_latest_value() { vec![Bytes::from(tick(2))], "the newest snapshot is the latest tick alone" ); - let groups = read_si_groups(&rig.consumer, &entry.track).await; - assert_eq!(groups.len(), 2, "one group per tick, no accumulation"); + let (sequence, _) = newest_si_group(&rig.consumer, &entry.track).await; + assert_eq!(sequence, 1, "one group per tick, no accumulation"); } /// Build a well-formed short-form section (syntax indicator clear): header + body, @@ -5155,8 +5149,8 @@ async fn short_form_repetition_cuts_no_group() { rig.import.finish().unwrap(); let si = rig.catalog.snapshot().ext.mpegts.si.clone(); - let groups = read_si_groups(&rig.consumer, &si[&0x0014][&0x70].track).await; - assert_eq!(groups.len(), 1, "a repetition cut no further group"); + let (sequence, _) = newest_si_group(&rig.consumer, &si[&0x0014][&0x70].track).await; + assert_eq!(sequence, 0, "a repetition cut no further group"); } /// SI never gates output: an advertised entry whose track resolves but never diff --git a/rs/moq-mux/src/container/ts/import.rs b/rs/moq-mux/src/container/ts/import.rs index 68b4e8a3639..f12c34b4398 100644 --- a/rs/moq-mux/src/container/ts/import.rs +++ b/rs/moq-mux/src/container/ts/import.rs @@ -3914,7 +3914,7 @@ impl AacStream { let mut config = aac::config(&asc)?; config.container = self.container.clone(); // Consume the reservation held since the PMT: this resolves the gated rendition, - // and carries the catalog's declared media retention onto the track. + // and carries the catalog's declared media max age onto the track. let reserved = self.reserved.take().unwrap_or_else(|| self.timebase.reserve()); let track = self .broadcast @@ -4476,7 +4476,7 @@ impl LegacyStream { container: self.container.clone(), }; // Consume the reservation held since the PMT: this resolves the gated rendition, - // and carries the catalog's declared media retention onto the track. A track + // and carries the catalog's declared media max age onto the track. A track // after a format change reserves anew on the same timebase. let reserved = self.reserved.take().unwrap_or_else(|| self.timebase.reserve()); let track = self.broadcast.unique_track( @@ -4684,8 +4684,8 @@ pub(super) mod test { /// A drift budget no test timeline comes close to, so the reader sees every group. /// - /// The media track's full retention window, so a reader started after importing can - /// still read every retained group. These tests import a whole file first, which the default + /// The media track's full max age, so a reader started after importing can + /// still read every fresh group. These tests import a whole file first, which the default /// [`Duration::ZERO`] budget collapses to the live /// edge: completeness has to be asked for. const RECORDING_MAX_AGE: std::time::Duration = Duration::from_secs(30); @@ -8271,7 +8271,7 @@ pub(super) mod test { import.decode(mp2_pes(pid, 0, 90_000, [0xAA, 0xBB]).as_slice()).unwrap(); } // The encoder restarts: the clock declares the break and the media resumes 20 s - // ahead. Under the track's 30 s retention window, so a subscribe still reaches + // ahead. Within the track's 30 s max age, so a subscribe still reaches // back to the first frame; the exported-clock tests cover the 30 s leap itself. import.decode(clock_break_packet(PCR_PID).as_slice()).unwrap(); for pid in [PCR_PID, PEER_PID] { @@ -9867,7 +9867,7 @@ pub(super) mod test { let at = mux.out.len() - 188; mux.out[at..].copy_from_slice(&video_pes(VIDEO, 7, 90_000 + 7 * FRAME, None, &last)); mux.out.extend_from_slice(&clock_break_packet(VIDEO)); - // Inside the track's 30 s retention, so the reader still reaches the first pass. + // Inside the track's 30 s max age, so the reader still reaches the first pass. mux.gops(VIDEO, 20 * 90_000, 2); let frames = video_frames(&mux.out).await; assert_eq!(frames.len(), 16); diff --git a/rs/moq-mux/src/container/ts/import_test.rs b/rs/moq-mux/src/container/ts/import_test.rs index 8b5566b99e0..818e02dd488 100644 --- a/rs/moq-mux/src/container/ts/import_test.rs +++ b/rs/moq-mux/src/container/ts/import_test.rs @@ -7,8 +7,8 @@ use bytes::BytesMut; /// A drift budget no test timeline comes close to, so the reader sees every group. /// -/// The media track's full retention window, so a reader started after importing can -/// still read every retained group. These tests import a whole file first, which the default +/// The media track's full max age, so a reader started after importing can +/// still read every fresh group. These tests import a whole file first, which the default /// [`std::time::Duration::ZERO`](std::time::Duration::ZERO) budget collapses to the live edge: /// completeness has to be asked for. const RECORDING_MAX_AGE: std::time::Duration = std::time::Duration::from_secs(30); diff --git a/rs/moq-mux/src/container/ts/si.rs b/rs/moq-mux/src/container/ts/si.rs index a1c3295c8fc..73a653856ba 100644 --- a/rs/moq-mux/src/container/ts/si.rs +++ b/rs/moq-mux/src/container/ts/si.rs @@ -40,6 +40,22 @@ use super::mux_rate::{MAX_INTERVAL, PCR_WRAP}; use super::passthrough::PCR_HZ; use super::psi::{self, CRC}; +/// Track properties for an SI table track, given `max_age`: the max age its catalog mints +/// media with ([`Config::with_max_age`](crate::catalog::Config::with_max_age)), `None` for +/// no publisher limit. +/// +/// Declares that media max age rather than moq-net's zero default: the TS export reads a +/// clock table (TDT/TOT) in order under its delay, and holds each revision until media +/// reaches its stamped slot, leaving the next revisions on the subscription meanwhile. At +/// zero, a revision superseded before the export reads it would be stale at once and +/// skipped. SI describes the media it travels with, so it stays fresh as long as that +/// media does. +pub(crate) fn track_info(max_age: Option) -> moq_net::track::Info { + moq_net::track::Info::default() + .with_timescale(moq_net::Timescale::MILLI) + .with_max_age(max_age) +} + const SDT_PID: u16 = 0x0011; const SDT_ACTUAL: u8 = 0x42; const EIT_PID: u16 = 0x0012; @@ -401,6 +417,7 @@ impl Entry { fn cut( &mut self, broadcast: &moq_net::broadcast::Producer, + max_age: Option, (pid, table_id): (u16, u8), pts: Timestamp, now: Instant, @@ -421,7 +438,7 @@ impl Entry { // Deterministic, greppable name; fall back to a unique suffix on the // (pathological) collision with an existing track. None => { - let info = moq_net::track::Info::default().with_timescale(moq_net::Timescale::MILLI); + let info = track_info(max_age); self.track.insert( match broadcast.create_track(format!("{pid:#06x}-{table_id:#04x}.si"), info.clone()) { Ok(track) => track, @@ -629,6 +646,8 @@ impl Capture { /// overrides the debounce, for end of stream. pub fn flush(&mut self, pts: Timestamp, force: bool) -> anyhow::Result<()> { let now = kio::clock::now(); + // The max age this catalog mints media with, which its SI shares. + let max_age = self.catalog.track_info(hang::catalog::PRIORITY.catalog).max_age; for (key, entry) in self.entries.iter_mut() { entry.expire(self.now); if !entry.dirty { @@ -640,7 +659,7 @@ impl Capture { { continue; } - entry.cut(&self.broadcast, *key, pts, now)?; + entry.cut(&self.broadcast, max_age, *key, pts, now)?; } if self.entries.values().any(|e| e.advertised != e.populated) { @@ -774,6 +793,37 @@ mod tests { use super::*; use crate::container::ts::fixture::{Flags, Mux}; + /// The TS export reads a clock table in order under its delay and holds each revision + /// until media reaches its stamped slot, so a revision superseded before the export reads + /// it has to stay on the subscription for that budget. The SI track's max age caps the + /// budget: at moq-net's zero default the superseded revision would be skipped at once. + #[test] + fn a_superseded_si_revision_stays_readable_within_the_export_budget() { + for (info, expected) in [ + (track_info(Some(hang::container::MAX_AGE)), vec![0, 1]), + (track_info(Some(Duration::ZERO)), vec![1]), + ] { + let broadcast = moq_net::broadcast::Info::new().produce(); + let mut track = broadcast.create_track("0x0014-0x70.si", info).unwrap(); + for revision in 0..2u64 { + track + .write_frame(Timestamp::from_millis(revision * 100).unwrap(), vec![revision as u8]) + .unwrap(); + } + // As the export subscribes: in order, with the CLI's default 500 ms delay. + let delay = moq_net::track::Delay::default().with_max(Duration::from_millis(500)); + let mut reader = track + .subscribe(moq_net::track::Subscription::default().with_delay(delay)) + .ordered(); + let waiter = kio::Waiter::noop(); + let mut read = Vec::new(); + while let std::task::Poll::Ready(Ok(Some(group))) = reader.poll_next_group(&waiter) { + read.push(group.sequence); + } + assert_eq!(read, expected); + } + } + #[kio::test] async fn program_clock_places_and_retires_si_without_media_pts() { let mut broadcast = moq_net::broadcast::Info::new().produce(); @@ -1058,6 +1108,35 @@ mod tests { } } + /// An SI track takes the max age its catalog mints media with: the default, a configured + /// window, or an explicit no limit. + #[kio::test] + async fn si_tracks_share_the_catalogs_media_max_age() { + for (config, expected) in [ + (crate::catalog::Config::default(), Some(hang::container::MAX_AGE)), + ( + crate::catalog::Config::default().with_max_age(Duration::from_secs(120)), + Some(Duration::from_secs(120)), + ), + (crate::catalog::Config::default().with_max_age(None), None), + ] { + let mut broadcast = moq_net::broadcast::Info::new().produce(); + let consumer = broadcast.consume(); + let catalog = crate::catalog::Producer::new( + &mut broadcast, + config.with_catalog(crate::catalog::hang::Catalog::::default()), + ) + .unwrap(); + let mut capture = Capture::new(broadcast, catalog); + let input = Input::new(&mut capture); + input.section(&mut capture, 0x14, Bytes::from(vec![0x70, 0x70, 5, 0, 0, 0, 0, 0])); + capture.flush(Timestamp::ZERO, true).unwrap(); + let track = capture.entries[&(0x14, 0x70)].track.as_ref().expect("the TDT track"); + assert_eq!(track.info().max_age, expected); + drop(consumer); + } + } + #[kio::test] async fn short_form_repetitions_replace_their_deadline_and_latest_value() { let (mut capture, _) = capture(); diff --git a/rs/moq-mux/src/import/mod.rs b/rs/moq-mux/src/import/mod.rs index 5ec803c8436..4a0d49e6a7c 100644 --- a/rs/moq-mux/src/import/mod.rs +++ b/rs/moq-mux/src/import/mod.rs @@ -15,7 +15,7 @@ //! catalog rendition through their container producer. //! //! A single-codec importer takes a track the caller mints, typically -//! `broadcast.unique_track(suffix, catalog.track_info())`, so the retention the catalog +//! `broadcast.unique_track(suffix, catalog.track_info())`, so the max age the catalog //! declares reaches the track. mod container; diff --git a/rs/moq-mux/src/linger.rs b/rs/moq-mux/src/linger.rs index 9f7b99a5759..ce8ee43b173 100644 --- a/rs/moq-mux/src/linger.rs +++ b/rs/moq-mux/src/linger.rs @@ -81,10 +81,12 @@ mod tests { const PATH: &str = "live"; - /// A broadcast at [`PATH`] whose one track, `video`, has three finished groups. + /// A broadcast at [`PATH`] whose one track, `video`, has three finished groups. It declares + /// media's max age, so its superseded groups stay fetchable as long as the default linger. fn finished(origin: &moq_net::origin::Producer) -> (moq_net::broadcast::Producer, moq_net::track::Producer) { let broadcast = origin.publish(PATH, moq_net::origin::Route::default()).unwrap(); - let track = broadcast.create_track("video", None).unwrap(); + let info = moq_net::track::Info::default().with_max_age(hang::container::MAX_AGE); + let track = broadcast.create_track("video", info).unwrap(); for _ in 0..3 { let mut group = track.append_group().unwrap(); group.write_frame(None, bytes::Bytes::from_static(b"frame")).unwrap(); diff --git a/rs/moq-net-tests/tests/integration/restart.rs b/rs/moq-net-tests/tests/integration/restart.rs index e28531445b0..39ac6dcdd4b 100644 --- a/rs/moq-net-tests/tests/integration/restart.rs +++ b/rs/moq-net-tests/tests/integration/restart.rs @@ -16,7 +16,9 @@ use support::harness::{MockConnectOptions, MockPair, connect_mock}; /// A millisecond track: the frames written here carry timestamps. fn timed() -> moq_net::track::Info { - moq_net::track::Info::default().with_timescale(moq_net::Timescale::MILLI) + moq_net::track::Info::default() + .with_timescale(moq_net::Timescale::MILLI) + .with_max_age(None) } const TEST_TIMEOUT: Duration = Duration::from_secs(60); diff --git a/rs/moq-net/MIGRATE.md b/rs/moq-net/MIGRATE.md index 85a6caf0965..508423d1c49 100644 --- a/rs/moq-net/MIGRATE.md +++ b/rs/moq-net/MIGRATE.md @@ -4,6 +4,21 @@ How to update your code for each breaking change, newest first. ## Unreleased +### Authored tracks default to a zero max age ([#7729](https://github.com/moq-dev/moq/pull/7729)) + +`track::Info::default()` sets `max_age` to `Some(Duration::ZERO)` instead of `None`: a superseded group is stale as soon as its successor arrives, so readers get only the live edge; the newest group never goes stale. +A track that relied on unlimited history requests it explicitly before it is created, with `with_max_age(None)`, or sets a window, such as `hang::container::MAX_AGE` for media. +A relay or cache bounds what it keeps with its own pool, not the publisher's default. +Readers asking for history still set a sufficient `Delay::max` and range. +Received metadata is unchanged: a track that arrives without a max age keeps `None`, and the wire is unchanged. + +```rust +// Before: no publisher limit +track::Info::default(); +// After: the same, stated explicitly +track::Info::default().with_max_age(None); +``` + ### A zero `Allocator::set_target` leaves the peer's PROBE target ([#7090](https://github.com/moq-dev/moq/pull/7090)) A session with a sender now probes to the larger of its allocator's target and the PROBE target its peer sends, so `Allocator::set_target(Some(Rate::ZERO))` stops probing for this side's reservations only. A peer that advertises a target still raises the probe; a reservation's `Consumer::probed` stays `false`, since nothing probes for it. diff --git a/rs/moq-net/benches/backing.rs b/rs/moq-net/benches/backing.rs index fbde04be899..0a065339395 100644 --- a/rs/moq-net/benches/backing.rs +++ b/rs/moq-net/benches/backing.rs @@ -281,7 +281,9 @@ impl Cache { let broadcast = info.produce(); let tracks = (0..media.tracks) .map(|index| { - let info = track::Info::default().with_timescale(Timescale::MILLI); + let info = track::Info::default() + .with_max_age(None) + .with_timescale(Timescale::MILLI); broadcast.create_track(format!("{index}").as_str(), info).unwrap() }) .collect(); diff --git a/rs/moq-net/benches/bandwidth.rs b/rs/moq-net/benches/bandwidth.rs index 7440f750bf0..eefec953067 100644 --- a/rs/moq-net/benches/bandwidth.rs +++ b/rs/moq-net/benches/bandwidth.rs @@ -41,7 +41,9 @@ fn table(count: usize) -> (Allocator, broadcast::Producer, Vec, let mut tracks = Vec::with_capacity(count); let mut reservations = Vec::with_capacity(count); for i in 0..count { - let track = broadcast.create_track(format!("t{i}"), None).unwrap(); + let track = broadcast + .create_track(format!("t{i}"), moq_net::track::Info::default().with_max_age(None)) + .unwrap(); reservations.push(allocator.reserve(&track.demand(), Rate::from_kbps(1_000))); tracks.push(track); } @@ -283,7 +285,7 @@ impl Connection { let slots = (0..shape.reservations) .map(|index| { let priority = priority(shape, index); - let info = track::Info::default().with_priority(priority); + let info = track::Info::default().with_max_age(None).with_priority(priority); let track = broadcast.create_track(format!("t{index}"), info).unwrap(); let subscriber = (!shape.idle || index % 2 == 0).then(|| track.subscribe(None)); let max = ceiling(index); diff --git a/rs/moq-net/benches/demand.rs b/rs/moq-net/benches/demand.rs index 05920509849..f39a21e0076 100644 --- a/rs/moq-net/benches/demand.rs +++ b/rs/moq-net/benches/demand.rs @@ -58,7 +58,11 @@ fn bench_edge(c: &mut Criterion) { group.bench_function(id, |b| { let producer = broadcast::Info::new().produce(); let _tracks: Vec<_> = (0..tracks) - .map(|i| producer.create_track(format!("t{i}"), None).unwrap()) + .map(|i| { + producer + .create_track(format!("t{i}"), moq_net::track::Info::default().with_max_age(None)) + .unwrap() + }) .collect(); let consumer = producer.consume(); let waiter = kio::Waiter::noop(); @@ -89,9 +93,19 @@ fn bench_churn(c: &mut Criterion) { let producer = broadcast::Info::new().produce(); let _demands: Vec<_> = (0..handles).map(|_| producer.demand()).collect(); let _tracks: Vec<_> = (0..tracks) - .map(|i| producer.create_track(format!("t{i}"), None).unwrap()) + .map(|i| { + producer + .create_track(format!("t{i}"), moq_net::track::Info::default().with_max_age(None)) + .unwrap() + }) .collect(); - b.iter(|| drop(producer.create_track("churn", None).unwrap())); + b.iter(|| { + drop( + producer + .create_track("churn", moq_net::track::Info::default().with_max_age(None)) + .unwrap(), + ) + }); }); } group.finish(); @@ -103,7 +117,11 @@ fn bench_lookup(c: &mut Criterion) { let id = BenchmarkId::from_parameter(format!("{tracks}t_{readers}r")); let producer = broadcast::Info::new().produce(); let _tracks: Vec<_> = (0..tracks) - .map(|i| producer.create_track(format!("t{i}"), None).unwrap()) + .map(|i| { + producer + .create_track(format!("t{i}"), moq_net::track::Info::default().with_max_age(None)) + .unwrap() + }) .collect(); let consumer = producer.consume(); let _readers: Vec<_> = (0..readers) diff --git a/rs/moq-net/benches/group.rs b/rs/moq-net/benches/group.rs index d99a8b0c07b..368a682e39a 100644 --- a/rs/moq-net/benches/group.rs +++ b/rs/moq-net/benches/group.rs @@ -56,7 +56,9 @@ use moq_net::{Timestamp, broadcast, frame, group, track}; /// A millisecond track: the frames written here carry timestamps. fn timed() -> track::Info { - track::Info::default().with_timescale(moq_net::Timescale::MILLI) + track::Info::default() + .with_max_age(None) + .with_timescale(moq_net::Timescale::MILLI) } /// A small, fixed payload shared across every frame. Cloning a `Bytes` is a @@ -70,7 +72,7 @@ const PAYLOAD: usize = 64; const COUNTS: [usize; 7] = [4, 5, 32, 33, 512, 2_048, 8_192]; /// Cached group counts to sweep for the track-level delivery benchmarks. A track -/// publishing one group per frame at the default 5s retention sits in the hundreds, +/// publishing one group per frame inside the default 30s cache expiry sits in the hundreds, /// so the top end is deliberately past anything realistic: a per-delivery scan over /// the cache shows up as a slope here, while a seek stays flat. const DEPTHS: [usize; 3] = [64, 512, 4_096]; @@ -641,7 +643,9 @@ fn contended( readers: usize, ) { let broadcast = broadcast::Producer::new(broadcast::Info::default()); - let track = broadcast.create_track("bench", track::Info::default()).unwrap(); + let track = broadcast + .create_track("bench", track::Info::default().with_max_age(None)) + .unwrap(); let mut group = track.append_group().unwrap(); // The group readers move to once theirs ends. let next = Arc::new(Mutex::new(group.consume())); @@ -750,7 +754,9 @@ fn bench_streaming(c: &mut Criterion) { /// One [`bench_streaming`] case. fn streaming(b: &mut criterion::Bencher, chunk: &Bytes, arrivals: usize, threads: usize, readers: usize) { let broadcast = broadcast::Producer::new(broadcast::Info::default()); - let track = broadcast.create_track("bench", track::Info::default()).unwrap(); + let track = broadcast + .create_track("bench", track::Info::default().with_max_age(None)) + .unwrap(); let info = frame::Info { size: (arrivals * chunk.len()) as u64, timestamp: None, diff --git a/rs/moq-net/benches/memory.rs b/rs/moq-net/benches/memory.rs index ab5f261b2b9..d6bea4918ee 100644 --- a/rs/moq-net/benches/memory.rs +++ b/rs/moq-net/benches/memory.rs @@ -148,7 +148,9 @@ impl Link { ); let broadcast = publisher.create_broadcast("bench").unwrap(); - let info = track::Info::default().with_timescale(moq_net::Timescale::MILLI); + let info = track::Info::default() + .with_max_age(None) + .with_timescale(moq_net::Timescale::MILLI); let tracks: Vec<_> = (0..streams) .map(|index| broadcast.create_track(format!("{index}"), info.clone()).unwrap()) .collect(); diff --git a/rs/moq-net/benches/origin.rs b/rs/moq-net/benches/origin.rs index 31a74aa5ed5..3ad61f8c0f8 100644 --- a/rs/moq-net/benches/origin.rs +++ b/rs/moq-net/benches/origin.rs @@ -56,7 +56,9 @@ use support::harness::{MockConnectOptions, MockPair, connect_mock}; /// A millisecond track: the frames written here carry timestamps. fn timed() -> track::Info { - track::Info::default().with_timescale(moq_net::Timescale::MILLI) + track::Info::default() + .with_max_age(None) + .with_timescale(moq_net::Timescale::MILLI) } /// `(publishers, subscribers)` shapes for the fan-out benchmarks. @@ -1404,7 +1406,11 @@ fn bench_parked(c: &mut Criterion) { runtime.spawn(moq_net::time::run(driver)); let broadcast = producer.publish("room/live", origin::Route::default()).unwrap(); let sources: Vec<_> = (0..tracks) - .map(|i| broadcast.create_track(format!("{i}"), None).unwrap()) + .map(|i| { + broadcast + .create_track(format!("{i}"), moq_net::track::Info::default().with_max_age(None)) + .unwrap() + }) .collect(); let _writers: Vec<_> = sources.iter().map(|source| source.append_group().unwrap()).collect(); let (subscriptions, mut groups) = runtime.block_on(async { diff --git a/rs/moq-net/benches/ranges.rs b/rs/moq-net/benches/ranges.rs index 28392ab8189..3bdf6f57144 100644 --- a/rs/moq-net/benches/ranges.rs +++ b/rs/moq-net/benches/ranges.rs @@ -42,7 +42,9 @@ const BUDGET: Duration = Duration::from_secs(3600); const LIVE: u64 = 1 << 32; fn timed() -> track::Info { - track::Info::default().with_timescale(moq_net::Timescale::MILLI) + track::Info::default() + .with_max_age(None) + .with_timescale(moq_net::Timescale::MILLI) } fn millis(millis: u64) -> Timestamp { diff --git a/rs/moq-net/benches/refresh.rs b/rs/moq-net/benches/refresh.rs index 502dfd8320b..f39ad727710 100644 --- a/rs/moq-net/benches/refresh.rs +++ b/rs/moq-net/benches/refresh.rs @@ -33,7 +33,7 @@ fn join(c: &mut Criterion) { for tracks in TRACKS { for subscribers in SUBSCRIBERS { let broadcast = broadcast::Info::default().produce(); - let info = track::Info::default().with_refresh(1); + let info = track::Info::default().with_max_age(None).with_refresh(1); let producers: Vec<_> = (0..tracks) .map(|i| broadcast.create_track(format!("bench{i}"), info.clone()).unwrap()) .collect(); diff --git a/rs/moq-net/benches/session/mod.rs b/rs/moq-net/benches/session/mod.rs index ba877773589..61744ecb853 100644 --- a/rs/moq-net/benches/session/mod.rs +++ b/rs/moq-net/benches/session/mod.rs @@ -96,7 +96,9 @@ use moq_net::{Hop, Timestamp, Version, broadcast, cache, datagram, group, origin /// A millisecond track: the frames written here carry timestamps. fn timed() -> track::Info { - track::Info::default().with_timescale(moq_net::Timescale::MILLI) + track::Info::default() + .with_max_age(None) + .with_timescale(moq_net::Timescale::MILLI) } /// The lite draft production negotiates, the next one (opt-in), and the newest @@ -1667,10 +1669,18 @@ impl ChurnRoom { let held: Vec<_> = (0..shape.held).map(|i| format!("held{i}")).collect(); let tracks: Vec<_> = held .iter() - .map(|name| published.create_track(name.as_str(), None).unwrap()) + .map(|name| { + published + .create_track(name.as_str(), moq_net::track::Info::default().with_max_age(None)) + .unwrap() + }) .collect(); let churn: Vec<_> = (0..shape.sessions) - .map(|i| published.create_track(format!("churn{i}"), None).unwrap()) + .map(|i| { + published + .create_track(format!("churn{i}"), moq_net::track::Info::default().with_max_age(None)) + .unwrap() + }) .collect(); let mut viewers = Vec::new(); diff --git a/rs/moq-net/benches/tail.rs b/rs/moq-net/benches/tail.rs index 26d18a56e25..7e9db2780dd 100644 --- a/rs/moq-net/benches/tail.rs +++ b/rs/moq-net/benches/tail.rs @@ -32,7 +32,9 @@ impl Held { let mut readers = Vec::with_capacity(tracks); let tracks = (0..tracks) .map(|i| { - let mut track = broadcast.create_track(format!("bench{i}"), None).unwrap(); + let mut track = broadcast + .create_track(format!("bench{i}"), moq_net::track::Info::default().with_max_age(None)) + .unwrap(); // A budget wide enough that no cached group is skipped as stale. let mut reader = track.subscribe( track::Subscription::default() diff --git a/rs/moq-net/benches/track.rs b/rs/moq-net/benches/track.rs index c9daf63bf15..2beef556a53 100644 --- a/rs/moq-net/benches/track.rs +++ b/rs/moq-net/benches/track.rs @@ -134,7 +134,9 @@ use moq_net::{Error, Timestamp, broadcast, cache, group, track}; /// A millisecond track: the frames written here carry timestamps. fn timed() -> track::Info { - track::Info::default().with_timescale(moq_net::Timescale::MILLI) + track::Info::default() + .with_max_age(None) + .with_timescale(moq_net::Timescale::MILLI) } /// Fanout sizes spanning a direct viewer, a small room, and a large room. @@ -311,7 +313,9 @@ struct AbortedScan { impl AbortedScan { fn new(aborted: usize) -> Self { let broadcast = broadcast::Info::default().produce(); - let track = broadcast.create_track("bench", None).unwrap(); + let track = broadcast + .create_track("bench", moq_net::track::Info::default().with_max_age(None)) + .unwrap(); let mut stale = Vec::with_capacity(aborted); for _ in 0..aborted { @@ -391,7 +395,9 @@ impl Churn { /// `peak` more viewers join and leave first, and the aggregate poll sees them go. fn new(steady: usize, peak: usize) -> Self { let broadcast = broadcast::Info::default().produce(); - let mut track = broadcast.create_track("bench", None).unwrap(); + let mut track = broadcast + .create_track("bench", moq_net::track::Info::default().with_max_age(None)) + .unwrap(); let steady = (0..steady).map(|_| track.subscribe(None)).collect(); let peak: Vec<_> = (0..peak).map(|_| track.subscribe(None)).collect(); let waiter = kio::Waiter::noop(); @@ -437,7 +443,9 @@ impl Aged { let mut reads = Vec::with_capacity(tracks); let tracks = (0..tracks) .map(|i| { - let track = broadcast.create_track(format!("bench{i}"), None).unwrap(); + let track = broadcast + .create_track(format!("bench{i}"), moq_net::track::Info::default().with_max_age(None)) + .unwrap(); let mut sub = track.subscribe( track::Subscription::default().with_delay(track::Delay::default().with_max(AGED_BUDGET)), ); @@ -1018,7 +1026,9 @@ fn bench_subscription_ranges(c: &mut Criterion) { for span in SPAN { for ranges in RANGES { let broadcast = broadcast::Info::default().produce(); - let track = broadcast.create_track("bench", None).unwrap(); + let track = broadcast + .create_track("bench", moq_net::track::Info::default().with_max_age(None)) + .unwrap(); // A gap between neighbors keeps every range distinct in the union. let viewers: Vec<_> = (0..ranges) .map(|i| { @@ -1043,7 +1053,9 @@ fn bench_range_serving(c: &mut Criterion) { for span in SERVED_SPAN { for ranges in SERVED_RANGES { let broadcast = broadcast::Info::default().produce(); - let track = broadcast.create_track("bench", None).unwrap(); + let track = broadcast + .create_track("bench", moq_net::track::Info::default().with_max_age(None)) + .unwrap(); // A gap between neighbors keeps every range distinct, and its group cached. for _ in 0..ranges * (span + 1) { let mut group = track.append_group().unwrap(); @@ -1241,7 +1253,10 @@ impl Sparse { fn bench_sparse_read(c: &mut Criterion) { let mut group = c.benchmark_group("track_sparse_read"); group.throughput(Throughput::Elements(2)); - for (name, info) in [("untimed", track::Info::default()), ("timed", timed())] { + for (name, info) in [ + ("untimed", track::Info::default().with_max_age(None)), + ("timed", timed()), + ] { for gaps in [16u64, 256, 4096] { group.bench_function(BenchmarkId::new(name, gaps), |b| { b.iter_custom(|iterations| { @@ -1260,7 +1275,10 @@ fn bench_sparse_read(c: &mut Criterion) { fn bench_sparse_poll(c: &mut Criterion) { let mut group = c.benchmark_group("track_sparse_poll"); - for (name, info) in [("untimed", track::Info::default()), ("timed", timed())] { + for (name, info) in [ + ("untimed", track::Info::default().with_max_age(None)), + ("timed", timed()), + ] { for gaps in [16u64, 256, 4096] { group.bench_function(BenchmarkId::new(name, gaps), |b| { b.iter_custom(|iterations| { @@ -1355,7 +1373,7 @@ struct Expiring { impl Expiring { fn new(gaps: u64) -> Self { - let mut sparse = Sparse::new(track::Info::default(), 0); + let mut sparse = Sparse::new(track::Info::default().with_max_age(None), 0); sparse .sub .update( @@ -1600,7 +1618,9 @@ fn bench_range_widening(c: &mut Criterion) { for cached in WIDENING_CACHED { bench.bench_function(BenchmarkId::new(format!("{readers}r"), cached), |b| { let broadcast = broadcast::Info::default().produce(); - let track = broadcast.create_track("bench", None).unwrap(); + let track = broadcast + .create_track("bench", moq_net::track::Info::default().with_max_age(None)) + .unwrap(); for _ in 0..cached { let mut group = track.append_group().unwrap(); group.write_frame(None, Bytes::from_static(b"x")).unwrap(); diff --git a/rs/moq-net/benches/tracks.rs b/rs/moq-net/benches/tracks.rs index 5ccb8ebf5c1..a8cfd1f959d 100644 --- a/rs/moq-net/benches/tracks.rs +++ b/rs/moq-net/benches/tracks.rs @@ -55,9 +55,11 @@ fn table(listings: usize, tracks: usize, broadcasts: usize) -> Table { for _ in 0..broadcasts { let broadcast = broadcast::Info::new().produce(); for i in 0..tracks { - table - ._tracks - .push(broadcast.create_track(format!("t{i}"), None).unwrap()); + table._tracks.push( + broadcast + .create_track(format!("t{i}"), moq_net::track::Info::default().with_max_age(None)) + .unwrap(), + ); } let consumer = broadcast.consume(); let mut readers: Vec = (0..listings).map(|_| consumer.tracks().unwrap()).collect(); @@ -79,13 +81,17 @@ fn bench_change(c: &mut Criterion) { let broadcast = table.broadcasts[0].clone(); let readers = &mut table.listings[0]; b.iter(|| { - let track = broadcast.create_track("new", None).unwrap(); + let track = broadcast + .create_track("new", moq_net::track::Info::default().with_max_age(None)) + .unwrap(); drop(track); for reader in readers.iter_mut() { // The unread add and removal cancel; read the next pair as it lands. assert_eq!(drain(reader), 0); } - let track = broadcast.create_track("new", None).unwrap(); + let track = broadcast + .create_track("new", moq_net::track::Info::default().with_max_age(None)) + .unwrap(); for reader in readers.iter_mut() { assert_eq!(drain(reader), 1); } diff --git a/rs/moq-net/benches/viewers.rs b/rs/moq-net/benches/viewers.rs index e20ebd01a68..2902b382b4e 100644 --- a/rs/moq-net/benches/viewers.rs +++ b/rs/moq-net/benches/viewers.rs @@ -18,7 +18,9 @@ use moq_net::{Hop, Timestamp, kio, origin}; /// A millisecond track: the frames written here carry timestamps. fn timed() -> moq_net::track::Info { - moq_net::track::Info::default().with_timescale(moq_net::Timescale::MILLI) + moq_net::track::Info::default() + .with_max_age(None) + .with_timescale(moq_net::Timescale::MILLI) } /// `(viewers, broadcasts)` shapes: viewers spread round-robin over the broadcasts. diff --git a/rs/moq-net/src/error.rs b/rs/moq-net/src/error.rs index ca72e858301..2c602f7984a 100644 --- a/rs/moq-net/src/error.rs +++ b/rs/moq-net/src/error.rs @@ -499,7 +499,7 @@ pub enum Error { /// (see [`cache::Pool`](crate::cache::Pool)), or by the transport when incomplete /// messages spent its receive window. Also a read of a frame the group shed from its /// front, past its live tail or under that debt. Unlike [`Self::Old`], the group was - /// still within the publisher's window; it can be re-fetched. + /// still fresh under the publisher's max age; it can be re-fetched. #[error("evicted")] Evicted, diff --git a/rs/moq-net/src/ietf/fetch.rs b/rs/moq-net/src/ietf/fetch.rs index b8d8080d85c..354808f8071 100644 --- a/rs/moq-net/src/ietf/fetch.rs +++ b/rs/moq-net/src/ietf/fetch.rs @@ -938,7 +938,7 @@ mod cache_duration_tests { use std::time::Duration; /// FETCH_OK carries MAX_CACHE_DURATION where SUBSCRIBE_OK does, so a track fetched with no - /// subscription still learns its retention window. + /// subscription still learns its max age. #[test] fn max_cache_duration_is_read_in_each_drafts_field() { for version in [Version::Draft18, Version::Draft20, Version::Draft22] { diff --git a/rs/moq-net/src/ietf/properties.rs b/rs/moq-net/src/ietf/properties.rs index c0f3ca51404..838f6cc68c1 100644 --- a/rs/moq-net/src/ietf/properties.rs +++ b/rs/moq-net/src/ietf/properties.rs @@ -52,7 +52,7 @@ const IMMUTABLE: u64 = 0x0b; /// The Track Properties block carried at the end of SUBSCRIBE_OK, PUBLISH, and FETCH_OK. #[derive(Default, Clone, Debug, PartialEq, Eq)] pub struct Properties { - /// The publisher's cache window; omission leaves retention unconstrained. + /// The publisher's max age; omission sets no publisher limit. pub max_cache_duration: Option, /// The track's Timescale, which declares the units of every object Timestamp on it. diff --git a/rs/moq-net/src/ietf/publisher.rs b/rs/moq-net/src/ietf/publisher.rs index 6d21a3fea5b..ad28790111e 100644 --- a/rs/moq-net/src/ietf/publisher.rs +++ b/rs/moq-net/src/ietf/publisher.rs @@ -27,11 +27,11 @@ use crate::{ use super::{Message, Version, cluster, error::request, peer, request_update}; -/// Preserve retained groups when the subscriber supplies no age budget. +/// Leave only the publisher's max age when the subscriber supplies no age budget. fn serving_subscription(subscriber_priority: u8) -> Subscription { Subscription { priority: super::priority::from_wire(subscriber_priority), - // No Max Age is the publisher's retention alone, whatever it turns out to be, and + // No Max Age leaves the publisher's max age alone, whatever it turns out to be, and // moq-transport has no field for a minimum. delay: crate::track::Delay { min: None, max: None }, // SUBSCRIBE_OK names the live edge, which a relay learns only from its upstream's @@ -7071,10 +7071,10 @@ mod subscribe_cursor_test { use super::*; use crate::lite::test_transport::{Log, SinkSession}; - /// A group retention gives up on while a FETCH reads it is refused as too old, rather + /// A group that goes stale while a FETCH reads it is refused as too old, rather /// than answered with the prefix read so far. #[kio::test] - async fn a_fetch_past_retention_is_refused_not_truncated() { + async fn a_fetch_past_max_age_is_refused_not_truncated() { let track = track::Producer::new( std::sync::Arc::new(crate::broadcast::Info::default()), "video", @@ -15628,7 +15628,8 @@ mod tests { slot } - /// An absent max age preserves everything the producer still retains. + /// An absent subscriber Max Age serves every cached group the publisher's max age still + /// leaves fresh. #[test] fn serving_subscription_keeps_retained_backlog() { let producer = track::Producer::new( @@ -15647,7 +15648,7 @@ mod tests { let subscription = serving_subscription(128); assert_eq!( subscription.delay.max, None, - "no Max Age is the publisher's retention alone" + "no Max Age leaves the publisher's max age alone" ); let mut subscriber = producer.subscribe(subscription); for sequence in [0, 1] { diff --git a/rs/moq-net/src/ietf/subscriber.rs b/rs/moq-net/src/ietf/subscriber.rs index 3d1432c1b3b..036acdc4865 100644 --- a/rs/moq-net/src/ietf/subscriber.rs +++ b/rs/moq-net/src/ietf/subscriber.rs @@ -6465,6 +6465,24 @@ mod tests { use super::*; + /// A publisher that sends no MAX_CACHE_DURATION sets no publisher limit, never the zero an + /// authored track defaults to; one that sends it keeps that value. + #[test] + fn a_received_track_keeps_its_max_cache_duration() { + for version in [Version::Draft18, Version::Draft20, Version::Draft22] { + let absent = accepted_info(&ietf::Properties::default(), version); + assert_eq!(absent.max_age, None, "{version}"); + let present = accepted_info( + &ietf::Properties { + max_cache_duration: Some(std::time::Duration::from_secs(7)), + ..Default::default() + }, + version, + ); + assert_eq!(present.max_age, Some(std::time::Duration::from_secs(7)), "{version}"); + } + } + /// What keeps a SUBSCRIBE_NAMESPACE open until the peer ends it, while the first lives. fn live() -> (kio::Producer<()>, kio::Consumer<()>) { let live = kio::Producer::new(()); @@ -15231,7 +15249,7 @@ mod stitch_tests { let track = track::Producer::new( std::sync::Arc::new(crate::broadcast::Info::default()), "video", - track::Info::default().with_timescale(None), + track::Info::default().with_timescale(None).with_max_age(None), ); Self { diff --git a/rs/moq-net/src/lite/fetch.rs b/rs/moq-net/src/lite/fetch.rs index b52cf825afc..0b5475adcf5 100644 --- a/rs/moq-net/src/lite/fetch.rs +++ b/rs/moq-net/src/lite/fetch.rs @@ -18,7 +18,7 @@ pub struct Fetch<'a> { pub instance: Option, pub track: Cow<'a, str>, pub priority: i8, - /// Reader freshness budget. Lite07+ only; omission uses publisher retention alone. + /// Reader freshness budget. Lite07+ only; omission uses the publisher's max age alone. pub max_delay: Option, pub group: u64, /// Index of the first frame to return; 0 is the start of the group. Lite06+ only. diff --git a/rs/moq-net/src/lite/publisher.rs b/rs/moq-net/src/lite/publisher.rs index a175559e2bc..6d3d12fb213 100644 --- a/rs/moq-net/src/lite/publisher.rs +++ b/rs/moq-net/src/lite/publisher.rs @@ -4085,7 +4085,7 @@ fn final_sequence(end: track::Position) -> u64 { /// Groups are served in arrival order (`poll_recv_group`), not sequence order: on a relay, a /// burst can be ingested micro-reordered by the upstream leg, and a sequence cursor would then /// permanently skip the older group even though it is cached and in demand. Staleness is -/// governed by the max age window (cache expiry), not arrival raciness. +/// governed by max age and the subscriber's max delay, not arrival raciness. /// /// Without `groups` the cursor hands out none, leaving them in the cache, so it never reports /// [`Recv::Finished`] either. diff --git a/rs/moq-net/src/lite/subscriber.rs b/rs/moq-net/src/lite/subscriber.rs index 688df73ad00..ccbcb4c7345 100644 --- a/rs/moq-net/src/lite/subscriber.rs +++ b/rs/moq-net/src/lite/subscriber.rs @@ -2885,7 +2885,7 @@ mod tests { /// A pre-lite-05 relay's track, untimed, with a fetch of `sequence` queued on it. fn feed_fetch(sequence: u64) -> (track::Producer, kio::Pending, track::Fill) { - let info = track::Info::default().with_timescale(None); + let info = track::Info::default().with_timescale(None).with_max_age(None); let track = track::Producer::new(std::sync::Arc::new(crate::broadcast::Info::default()), "video", info); let dynamic = track.requests(); let fetching = track.consume().fetch_group(sequence, None); @@ -3104,7 +3104,7 @@ mod tests { fn feed_batch( sequences: impl IntoIterator, ) -> (track::Producer, Vec>, Vec) { - let info = track::Info::default().with_timescale(None); + let info = track::Info::default().with_timescale(None).with_max_age(None); let track = track::Producer::new(Arc::new(crate::broadcast::Info::default()), "video", info); let dynamic = track.requests(); let mut callers = Vec::new(); @@ -3276,7 +3276,7 @@ mod tests { let clock = crate::time::Deadlines::new(start); let tail = kio::Producer::new(Tail::default()); let sub = feed_sub(&tail).await; - let info = track::Info::default().with_timescale(None); + let info = track::Info::default().with_timescale(None).with_max_age(None); let mut track = track::Producer::new(Arc::new(crate::broadcast::Info::default()), "video", info); let dynamic = track.requests(); let mut reader = track.subscribe( @@ -5479,7 +5479,9 @@ mod tests { let track = crate::track::Producer::new( Arc::new(crate::broadcast::Info::default()), "video", - crate::track::Info::default().with_timescale(Timescale::MILLI), + crate::track::Info::default() + .with_timescale(Timescale::MILLI) + .with_max_age(None), ); // Every group, oldest first, however late. let every = Subscription::default() @@ -9059,9 +9061,9 @@ impl TrackServeRun { _working: serve.subscriber.session.work().start(), } } else { - // Older wires declare no publisher retention limit, and no timeline: their - // frames arrive untimed. - let info = track::Info::default().with_timescale(None); + // Older wires declare no publisher max age, and no timeline: their frames + // arrive untimed. + let info = track::Info::default().with_timescale(None).with_max_age(None); TrackRunState::Serve(ServeLoop::new(&serve, request, info)) }; let gate = serve.gate(); @@ -9440,8 +9442,8 @@ impl TrackInfoFetch { } })?; - // Publisher Max Age rides on the wire, so the local retention - // window matches what the upstream advertises (relays re-serve with + // Publisher Max Age rides on the wire, so the local freshness + // bound matches what the upstream advertises (relays re-serve with // the same bound). `broadcast` is left at its default here; // `track::Request::accept` stamps the track's real broadcast. let mut info: track::Info = track::Info::from(info); diff --git a/rs/moq-net/src/lite/track.rs b/rs/moq-net/src/lite/track.rs index 63770eb4bd4..4d25d389fed 100644 --- a/rs/moq-net/src/lite/track.rs +++ b/rs/moq-net/src/lite/track.rs @@ -326,20 +326,30 @@ mod test { assert_eq!(got.timescale, Some(Timescale::MICRO)); } + /// A TRACK_INFO without a max age is a track with no publisher limit, never the zero an + /// authored track defaults to. + #[test] + fn a_received_track_without_a_max_age_has_no_limit() { + for version in [Version::Lite05, Version::Lite06, Version::Lite07] { + let sent = TrackInfo { + max_age: None, + ..info_sample() + }; + let info = crate::track::Info::from(info_roundtrip(version, &sent)); + assert_eq!(info.max_age, None, "{version}"); + } + } + #[test] fn track_info_defaults_match_cross_language_wire_bytes() { - // The default track is untimed, which lite-05 declares as milliseconds. + // The default authored track is untimed, which lite-05 declares as milliseconds, and + // advertises the default zero max age. let info = TrackInfo::serve(&crate::track::Info::default(), Version::Lite05); let mut buf = Vec::new(); info.encode(&mut Encoder::new(&mut buf, Version::Lite05.into()), Version::Lite05) .unwrap(); - assert_eq!( - buf, - [ - 0x0c, 0x80, 0x00, 0xc0, 0x1f, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0x43, 0xe8 - ] - ); + assert_eq!(buf, [0x05, 0x80, 0x00, 0x00, 0x43, 0xe8]); } #[test] diff --git a/rs/moq-net/src/lite/version.rs b/rs/moq-net/src/lite/version.rs index b7b83323b7b..4732ac9958d 100644 --- a/rs/moq-net/src/lite/version.rs +++ b/rs/moq-net/src/lite/version.rs @@ -202,7 +202,7 @@ impl Version { } /// Whether FETCH carries the subscriber's optional max delay. Added in lite-07; an - /// earlier fetch is bounded by the publisher's retention alone. + /// earlier fetch is bounded by the publisher's max age alone. pub(crate) fn has_fetch_max_delay(self) -> bool { !matches!( self, diff --git a/rs/moq-net/src/model/broadcast.rs b/rs/moq-net/src/model/broadcast.rs index 27f2f1999d8..a6345ce9c13 100644 --- a/rs/moq-net/src/model/broadcast.rs +++ b/rs/moq-net/src/model/broadcast.rs @@ -41,7 +41,7 @@ pub struct Info { /// The cache pool this broadcast's tracks and groups inherit. pub pool: cache::Pool, - /// Ceiling on each track's media-timestamp retention window. + /// Local ceiling on each track's max age: how long a superseded group stays fresh here. pub cache_duration: std::time::Duration, /// The path this broadcast is named by, which relative references in a catalog it diff --git a/rs/moq-net/src/model/group.rs b/rs/moq-net/src/model/group.rs index 00196edf3f6..f5bfff14221 100644 --- a/rs/moq-net/src/model/group.rs +++ b/rs/moq-net/src/model/group.rs @@ -1136,7 +1136,7 @@ impl GroupState { /// Resolve the group's terminal state for a reader positioned at `index`. /// /// A finished group is still aborted once its frames are released to free memory - /// (aged out of the track's max age window, or evicted by the cache pool). A reader + /// (idle past the cache pool's expiry window, or evicted under its byte target). A reader /// that already consumed every frame is missing nothing, so it gets the clean end of /// group; one that fell short sees the abort rather than a silently truncated stream. fn poll_terminal(&self, index: usize) -> Poll> { @@ -4320,7 +4320,7 @@ pub struct Fetch { /// Maximum age behind the live edge this caller accepts. /// - /// `None` applies only the publisher's retention bound. An explicit value can + /// `None` applies only the publisher's max age. An explicit value can /// tighten, but never relax, that bound. pub max_delay: Option, @@ -5475,7 +5475,7 @@ mod test { } /// A finished group is still aborted once its frames are released to free memory (the - /// track's max age window, or the cache pool). A reader that already drained every frame + /// cache pool's expiry window or byte target). A reader that already drained every frame /// is missing nothing, so it must see the clean end of group rather than the abort. #[test] #[cfg(feature = "async")] diff --git a/rs/moq-net/src/model/origin.rs b/rs/moq-net/src/model/origin.rs index 7b1a6a9181f..af40f4365d3 100644 --- a/rs/moq-net/src/model/origin.rs +++ b/rs/moq-net/src/model/origin.rs @@ -122,9 +122,9 @@ pub struct Config { /// one policy. pub pool: cache::Pool, - /// Ceiling on each track's media-timestamp retention window under this origin. - /// This caps the local retention and delivery budget without changing the - /// publisher's [`max_age`](track::Info::max_age) metadata. Wall-clock + /// Local ceiling on each track's max age under this origin. + /// This caps how long a superseded group stays fresh here, and the delivery budget, + /// without changing the publisher's [`max_age`](track::Info::max_age) metadata. Wall-clock /// reclamation of idle content is separate: [`Self::pool`]'s /// [`expiry`](cache::Pool::expiry) window. [`Duration::MAX`] (the default) /// imposes no ceiling, leaving each track's own window in force. @@ -2057,7 +2057,7 @@ pub struct Producer { // mint their remote broadcasts with it). Unbounded by default. pool: cache::Pool, - // Retention ceiling inherited by broadcasts created under this origin (see + // Max age ceiling inherited by broadcasts created under this origin (see // [`Config::cache_duration`]). `Duration::MAX` (no ceiling) by default. cache_duration: Duration, @@ -14517,8 +14517,8 @@ mod tests { let mut stalled = track.append_group().unwrap(); stalled.write_frame(crate::Timestamp::ZERO, b"x".as_slice()).unwrap(); // A successor, so the stalled group is not the protected live edge. Its - // timestamp is inside the retention budget, so subscription expiry keeps the - // stalled group: only reclamation can bound it. + // timestamp is inside the max age, so the stalled group stays fresh and + // subscription expiry never skips it: only reclamation can bound it. let _successor = track.append_group().unwrap(); let mut reading = stalled.consume(); diff --git a/rs/moq-net/src/model/resume.rs b/rs/moq-net/src/model/resume.rs index 3e95f815a15..666b212bb27 100644 --- a/rs/moq-net/src/model/resume.rs +++ b/rs/moq-net/src/model/resume.rs @@ -1919,7 +1919,7 @@ pub(super) struct Recover { /// The reader it was handed out to, followed onto each new route; `None` for a fetch. reader: Option>>, /// A fetch's own age budget, asked of each route and judged while waiting on one. - /// `None` leaves the publisher's retention alone; unused for a reader. + /// `None` leaves the publisher's max age alone; unused for a reader. max_delay: Option, /// The route, watched for [`Self::wants`]: every read of the group that parks asks it /// whether the route moved past [`Self::generation`]. Moving that generation any other @@ -2206,7 +2206,7 @@ impl Recover { } /// The budget for a late group: the reader's current one, or a fetch's own, which is - /// unbounded when it named none so that only the publisher's retention applies. + /// unbounded when it named none so that only the publisher's max age applies. pub(super) fn poll_budget(&self, waiter: &kio::Waiter) -> Option { let Some(reader) = &self.reader else { return Some(self.max_delay.unwrap_or(std::time::Duration::MAX)); @@ -5396,18 +5396,14 @@ mod test { #[kio::test] #[cfg(feature = "async")] async fn an_untimed_group_no_route_continues_is_given_up_by_wall_clock() { - let untimed = || { - track::Producer::new( - Arc::new(broadcast::Info::default()), - "video", - crate::track::Info::default(), - ) - }; + // No publisher max age, so only the subscription's budget gives the group up. + let info = || crate::track::Info::default().with_max_age(None); + let untimed = || track::Producer::new(Arc::new(broadcast::Info::default()), "video", info()); for warm in [false, true] { let routes = Producer::new(); let logical = track::Request::new(Arc::new(broadcast::Info::default()), "video") .routes(routes.consume()) - .accept(crate::track::Info::default()); + .accept(info()); let a = untimed(); routes.serve(a.consume()); let mut sub = subscribe(&logical, Duration::from_secs(1)); diff --git a/rs/moq-net/src/model/track.rs b/rs/moq-net/src/model/track.rs index b592110afc9..e198ac52c3e 100644 --- a/rs/moq-net/src/model/track.rs +++ b/rs/moq-net/src/model/track.rs @@ -118,13 +118,18 @@ pub struct Info { /// by the wall clock alone, and a peer whose timestamps stop advancing cannot pin a /// superseded group. /// - /// A retention bound rather than a delivery one, the inverse of an HTTP + /// A freshness bound on what may still be served, the inverse of an HTTP /// `Cache-Control: max-age`. [`Delay::max`] is clamped to this, since a - /// group can't be waited for longer than it's kept around. Reported in TRACK_INFO so - /// relays re-serve with the same window. `None` (the default) sets no limit; - /// the origin cache ceiling and pool still apply. `Some(Duration::ZERO)` keeps the live edge. - /// Stale groups are skipped by readers; reclaiming their bytes is the cache pool's - /// [`expiry`](crate::cache::Pool::expiry) window. + /// group can't be waited for once it is stale. Reported in TRACK_INFO so + /// relays re-serve with the same bound. + /// + /// An authored track defaults to `Some(Duration::ZERO)`: a superseded group is stale at once, + /// so only the live edge is served, and a publisher that wants a reader to reach history sets a + /// longer age, or `None`, explicitly. `None` sets no publisher limit: requested with + /// `with_max_age(None)`, and kept by a track received without one (an older moq-lite, or + /// moq-transport without MAX_CACHE_DURATION). A hop's cache still bounds what it keeps with + /// its own pool and ceiling. Stale groups are skipped by readers; reclaiming their bytes is + /// the cache pool's [`expiry`](crate::cache::Pool::expiry) window. /// /// This is the `Publisher Max Age` on the wire, the publisher-side half of the /// budget [`Delay::max`] sets for a subscriber. @@ -200,11 +205,13 @@ impl PartialEq for Info { impl Eq for Info {} +/// An authored track's defaults: untimed, a zero [`max_age`](Info::max_age) (the live edge only), +/// priority 0, uncompressed, never asking for a refresh. impl Default for Info { fn default() -> Self { Self { timescale: None, - max_age: None, + max_age: Some(Duration::ZERO), priority: DEFAULT_PRIORITY, compress: false, refresh: None, @@ -225,7 +232,8 @@ impl Info { self } - /// Set how old a non-latest group may get before eviction, returning `self` for chaining. + /// Set how long a superseded group stays fresh, or `None` for no publisher limit, + /// returning `self` for chaining. See [`max_age`](Self::max_age). pub fn with_max_age(mut self, max_age: impl Into>) -> Self { self.max_age = max_age.into(); self @@ -275,9 +283,10 @@ impl Info { #[cfg(test)] impl Info { - /// A millisecond track, for tests that write timestamps. + /// A millisecond track with no publisher max age, for tests that write timestamps: a test + /// of staleness sets its max age explicitly. pub(crate) fn timed() -> Self { - Self::default().with_timescale(Timescale::MILLI) + Self::default().with_timescale(Timescale::MILLI).with_max_age(None) } } @@ -1386,8 +1395,9 @@ impl TrackState { self.lookup.get(&sequence)?.copies().find(|group| group.covers(frames)) } - /// The local retention bound, or `None` when unknown or unlimited: how long a reader - /// may wait for a late group, without changing the publisher's metadata. + /// The local freshness bound, or `None` when unknown or unlimited: the publisher's max + /// age under the local ceiling, how long a reader may wait for a late group, without + /// changing the publisher's metadata. fn max_age_bound(&self) -> Option { let published = self.info.as_ref()?.max_age; match published { @@ -1803,8 +1813,8 @@ impl TrackState { /// Expire groups idle past the pool's wall-clock LRU window, never the latest. /// /// The window is the pool's [`expiry`](cache::Pool::expiry), not the track's - /// [`max_age`](Info::max_age): retention is a media-timestamp promise, while this - /// is the cache's own guard against unread content pinning RAM, shared by every + /// [`max_age`](Info::max_age): max age only bounds how long a superseded group stays + /// fresh and frees nothing, while this is the cache's own guard against unread content pinning RAM, shared by every /// track in the pool. /// /// One bounded, rotating scan over the eviction order, which holds every cached @@ -3018,9 +3028,11 @@ impl TrackState { // Adopt the supplied info only if the track hasn't been accepted yet. Groups // created here charge the same account as any other, so backfill written - // before the track is accepted settles its debt like the rest. + // before the track is accepted settles its debt like the rest. Without one, the + // provisional info claims no publisher max age, not an authored track's zero: the + // publisher's real bound is unknown until its metadata arrives. if self.info.is_none() { - self.install(info.unwrap_or_default()); + self.install(info.unwrap_or_else(|| Info::default().with_max_age(None))); } let info = self.info.clone().unwrap(); @@ -4184,8 +4196,8 @@ fn snapshot_subscription(subs: &kio::Lock, bound: Option>, info: impl Into>) -> Producer { + let info = info.into().unwrap_or_else(|| Info::default().with_max_age(None)); Producer::new(Arc::new(broadcast::Info::default()), name, info) } @@ -9361,7 +9375,7 @@ mod test { #[test] fn a_missing_group_uses_the_subscription_grace() { - let producer = track_producer("test", Info::default()); + let producer = track_producer("test", None); let budget = Duration::from_millis(50); let _sub = producer.subscribe(Subscription::default().with_delay(Delay::default().with_max(budget))); let feed = producer.consume(); @@ -9545,7 +9559,7 @@ mod test { /// it gets that group, which ends with nothing, then the next one. #[test] fn a_live_edge_reader_starts_on_an_empty_largest_group() { - let producer = track_producer("test", Info::default()); + let producer = track_producer("test", None); let noop = kio::Waiter::noop(); let mut first = producer.append_group().unwrap(); first.write_frame(None, &b"a"[..]).unwrap(); @@ -9726,7 +9740,7 @@ mod test { /// aggregate. #[test] fn a_range_reads_only_its_groups() { - let producer = track_producer("test", Info::default()); + let producer = track_producer("test", None); let _groups: Vec<_> = (3..8) .map(|sequence| { let mut group = framed(&producer, sequence, 8); @@ -9981,7 +9995,7 @@ mod test { /// A relay copy holding groups 0 to 3 from an ended feed, idle until its route answers. fn idle_copy() -> Producer { - let mut producer = track_producer("test", Info::default()); + let mut producer = track_producer("test", None); for sequence in 0..4 { framed(&producer, sequence, 1).finish().unwrap(); } @@ -10225,7 +10239,7 @@ mod test { } } - /// A group whose frames outlive `max_age` is aged out when the next group starts, but + /// A group whose frames outlive the pool's LRU window is aged out when the next group starts, but /// a subscriber that already drained it must still see the clean end of group. Otherwise a /// track with long groups (a per-minute rollup, say) fails its readers at every boundary. #[kio::test] @@ -10751,7 +10765,7 @@ mod test { #[kio::test] #[cfg(feature = "async")] async fn a_parked_read_wakes_at_its_wall_deadline() { - for (info, primed) in [Info::default(), Info::timed()] + for (info, primed) in [Info::default().with_max_age(None), Info::timed()] .into_iter() .flat_map(|info| [(info.clone(), true), (info, false)]) { @@ -10801,7 +10815,7 @@ mod test { #[kio::test] #[cfg(feature = "async")] async fn a_frameless_successor_ages_its_predecessor() { - for info in [Info::default(), Info::timed()] { + for info in [Info::default().with_max_age(None), Info::timed()] { let producer = track_producer("test", info.clone()); let at = info.timescale.map(|_| Timestamp::ZERO); elapse(&producer, Duration::ZERO); @@ -11045,8 +11059,8 @@ mod test { assert_eq!(producer.subscription().unwrap().delay.max, Some(Duration::ZERO)); } - /// Mint a track under an origin whose retention ceiling is `cap`, so the - /// local delivery budget is capped without rewriting the publisher's window. + /// Mint a track under an origin whose max age ceiling is `cap`, so the + /// local delivery budget is capped without rewriting the publisher's max age. fn track_producer_capped(name: impl Into>, info: Info, cap: Duration) -> Producer { Producer::new( Arc::new(broadcast::Info { @@ -11058,8 +11072,26 @@ mod test { ) } + /// A fill that lands before the track's metadata installs provisional info with no + /// publisher max age: the real bound is unknown, and an authored track's zero would + /// refuse history an unlimited publisher still serves. + #[test] + fn a_fill_before_metadata_claims_no_max_age() { + let state = TrackState::spawn(Arc::new(broadcast::Info::default())); + let _group = state + .write() + .ok() + .unwrap() + .insert_group_request(0, group::Bounds::default(), None) + .unwrap(); + let state = state.read(); + assert_eq!(state.info.as_ref().unwrap().max_age, None); + assert_eq!(state.max_age_bound(), None); + } + #[test] fn optional_age_keeps_publisher_metadata_and_local_policy_separate() { + assert_eq!(Info::default().max_age, Some(Duration::ZERO)); assert_eq!(Info::timed().max_age, None); for age in [None, Some(Duration::ZERO), Some(Duration::from_secs(30))] { let producer = track_producer_capped("optional", Info::timed().with_max_age(age), Duration::from_secs(1)); @@ -11277,7 +11309,7 @@ mod test { #[test] #[cfg(feature = "async")] fn an_unjudgeable_gap_does_not_hide_a_fresh_ordered_gap() { - let mut producer = track_producer("test", Info::default()); + let mut producer = track_producer("test", None); producer.received(); for sequence in [0, 4] { framed(&producer, sequence, 1).finish().unwrap(); @@ -11361,7 +11393,7 @@ mod test { #[test] #[cfg(feature = "async")] fn a_floor_raised_under_an_asked_fill_keeps_its_fresh_suffix() { - let mut producer = track_producer("test", Info::default()); + let mut producer = track_producer("test", Info::default().with_max_age(None)); let requests = producer.requests(); producer.received(); for sequence in 0..3 { @@ -11416,7 +11448,7 @@ mod test { #[test] #[cfg(feature = "async")] fn the_cache_below_the_floor_is_unread_only_to_unlimited_reads() { - let mut producer = track_producer("test", Info::default()); + let mut producer = track_producer("test", Info::default().with_max_age(None)); producer.received(); for sequence in 0..3 { framed(&producer, sequence, 1).finish().unwrap(); @@ -11469,7 +11501,7 @@ mod test { fn a_resumed_history_read_accounts_for_cached_and_refused_groups() { for ordered in [false, true] { for bounded in [false, true] { - let mut producer = track_producer("test", Info::default()); + let mut producer = track_producer("test", Info::default().with_max_age(None)); let requests = producer.requests(); producer.received(); framed(&producer, 0, 1).finish().unwrap(); @@ -12658,6 +12690,47 @@ mod test { assert_eq!(drain(&mut subscriber), vec![1, 2]); } + /// An authored track's default zero max age serves only the live edge: a superseded group is + /// stale at once, even to a reader with no budget of its own, while the newest group, a + /// snapshot a late joiner bootstraps from, never goes stale. A longer history is the + /// publisher's explicit choice. + #[test] + #[cfg(feature = "async")] + fn the_default_max_age_serves_only_the_live_edge() { + let history = || Subscription::default().with_delay(Delay::default().with_max(None)); + + // Timed: a successor at the same instant already supersedes. + let mut timed = track_producer("timed", Info::default().with_timescale(Timescale::MILLI)); + append_at(&mut timed, 0); + append_at(&mut timed, 0); + assert_eq!(drain(&mut timed.subscribe(history())), vec![1]); + + // Untimed: the wall clock agrees, and an hour on the unchanged newest group still + // bootstraps a late joiner. + let mut untimed = track_producer("untimed", Info::default()); + append_untimed(&mut untimed); + append_untimed(&mut untimed); + assert_eq!(drain(&mut untimed.subscribe(history())), vec![1]); + elapse(&untimed, Duration::from_secs(3600)); + assert_eq!(drain(&mut untimed.subscribe(None)), vec![1]); + assert_eq!(drain(&mut untimed.subscribe(history())), vec![1]); + + // An explicit age keeps superseded groups fresh that long; explicit `None` keeps them all. + let mut explicit = track_producer( + "explicit", + Info::default() + .with_timescale(Timescale::MILLI) + .with_max_age(Duration::from_secs(30)), + ); + let mut unlimited = track_producer("unlimited", Info::timed()); + for millis in [0, 1_000, 31_000] { + append_at(&mut explicit, millis); + append_at(&mut unlimited, millis); + } + assert_eq!(drain(&mut explicit.subscribe(history())), vec![1, 2]); + assert_eq!(drain(&mut unlimited.subscribe(history())), vec![0, 1, 2]); + } + #[test] #[cfg(feature = "async")] fn an_explicit_start_gets_no_exemption_from_the_budget() { @@ -17296,7 +17369,7 @@ mod test { #[cfg(feature = "async")] async fn answered_heads_go_out_in_the_subscription_order() { for (order, expected) in [(Order::Ascending, [0, 1]), (Order::Descending, [1, 0])] { - let producer = track_producer("test", Info::default()); + let producer = track_producer("test", None); let dynamic = producer.requests(); for sequence in 0..2 { let mut live = producer.create_group(group::Info { sequence }).unwrap(); @@ -17338,7 +17411,7 @@ mod test { #[kio::test] #[cfg(feature = "async")] async fn a_head_answered_outside_the_ranges_is_not_handed_out() { - let producer = track_producer("test", Info::default()); + let producer = track_producer("test", None); let dynamic = producer.requests(); let mut live = producer.create_group(group::Info { sequence: 0 }).unwrap(); @@ -17368,7 +17441,7 @@ mod test { #[kio::test] #[cfg(feature = "async")] async fn a_bounded_read_gives_up_a_group_whose_head_is_refused() { - let producer = track_producer("test", Info::default()); + let producer = track_producer("test", None); let dynamic = producer.requests(); let mut live = producer.create_group(group::Info { sequence: 0 }).unwrap(); @@ -19327,7 +19400,7 @@ mod test { group.write_frame(None, &b"x"[..]).unwrap(); group.finish().unwrap(); }; - let mut producer = track_producer("test", Info::default()); + let mut producer = track_producer("test", None); producer.fills_from_start(); let dynamic = producer.requests(); let mut subscriber = producer.subscribe(replay().with_range(0..)); @@ -20128,7 +20201,7 @@ mod test { #[test] #[cfg(feature = "async")] fn history_below_a_resumed_live_floor_is_refilled_after_a_live_arrival() { - let mut producer = track_producer("test", Info::default()); + let mut producer = track_producer("test", None); let dynamic = producer.requests(); producer.received(); for sequence in 0..5 { diff --git a/rs/moq-net/src/model/track/miss.rs b/rs/moq-net/src/model/track/miss.rs index 3575e5ebcbd..7efe9a9c444 100644 --- a/rs/moq-net/src/model/track/miss.rs +++ b/rs/moq-net/src/model/track/miss.rs @@ -1843,7 +1843,9 @@ mod tests { #[kio::test] async fn a_grace_change_with_nothing_deferred_times_the_next_gap() { let broadcast = crate::broadcast::Info::default().produce(); - let track = broadcast.create_track("grace", crate::track::Info::default()).unwrap(); + let track = broadcast + .create_track("grace", crate::track::Info::default().with_max_age(None)) + .unwrap(); let budget = Duration::from_secs(5); let _reader = track.subscribe(Subscription::default().with_delay(Delay::default().with_max(budget))); for sequence in 0..3 { @@ -2204,7 +2206,9 @@ mod tests { } let broadcast = crate::broadcast::Info::default().produce(); - let mut track = broadcast.create_track("fills", crate::track::Info::default()).unwrap(); + let mut track = broadcast + .create_track("fills", crate::track::Info::default().with_max_age(None)) + .unwrap(); let requests = track.requests(); track.start_at(8).unwrap(); track @@ -2277,7 +2281,9 @@ mod tests { } let broadcast = crate::broadcast::Info::default().produce(); - let mut track = broadcast.create_track("fills", crate::track::Info::default()).unwrap(); + let mut track = broadcast + .create_track("fills", crate::track::Info::default().with_max_age(None)) + .unwrap(); let requests = track.requests(); track.start_at(8).unwrap(); track diff --git a/rs/moq-net/tests/integration/errored_end.rs b/rs/moq-net/tests/integration/errored_end.rs index 1f80e822cc3..dbed5db770e 100644 --- a/rs/moq-net/tests/integration/errored_end.rs +++ b/rs/moq-net/tests/integration/errored_end.rs @@ -79,7 +79,9 @@ async fn an_errored_end_keeps_its_history_across_a_hop() { let version: Version = name.parse().unwrap(); let publisher = produce_origin(1); let broadcast = publisher.create_broadcast("bcast").unwrap(); - let info = moq_net::track::Info::default().with_timescale(moq_net::Timescale::MILLI); + let info = moq_net::track::Info::default() + .with_timescale(moq_net::Timescale::MILLI) + .with_max_age(None); let mut track = broadcast.create_track("video", info).unwrap(); broadcast.announce(Default::default()).unwrap(); for _ in 0..GROUPS { diff --git a/rs/moq-net/tests/integration/fetch_only.rs b/rs/moq-net/tests/integration/fetch_only.rs index 59399a0d070..a3678a5e52f 100644 --- a/rs/moq-net/tests/integration/fetch_only.rs +++ b/rs/moq-net/tests/integration/fetch_only.rs @@ -15,9 +15,12 @@ use std::time::Duration; use moq_net::{Hop, Timestamp, Version}; use support::harness::{MockConnectOptions, connect_mock}; -/// A millisecond track: the frames written here carry timestamps. +/// A millisecond track with no publisher max age: the frames written here carry timestamps, +/// and an unlimited read here reaches every cached group. fn timed() -> moq_net::track::Info { - moq_net::track::Info::default().with_timescale(moq_net::Timescale::MILLI) + moq_net::track::Info::default() + .with_timescale(moq_net::Timescale::MILLI) + .with_max_age(None) } const TIMEOUT: Duration = Duration::from_secs(5); diff --git a/rs/moq-net/tests/integration/finite_relay.rs b/rs/moq-net/tests/integration/finite_relay.rs index 2a0cb226c33..417c62d5750 100644 --- a/rs/moq-net/tests/integration/finite_relay.rs +++ b/rs/moq-net/tests/integration/finite_relay.rs @@ -20,9 +20,12 @@ use moq_net::track::Subscription; use moq_net::{Hop, Timestamp, Version}; use support::harness::{MockConnectOptions, connect_mock}; -/// A millisecond track: the frames written here carry timestamps. +/// A millisecond track with no publisher max age: the frames written here carry timestamps, +/// and superseded groups stay readable. fn timed() -> moq_net::track::Info { - moq_net::track::Info::default().with_timescale(moq_net::Timescale::MILLI) + moq_net::track::Info::default() + .with_timescale(moq_net::Timescale::MILLI) + .with_max_age(None) } const TIMEOUT: Duration = Duration::from_secs(10); diff --git a/rs/moq-net/tests/integration/idle_cancel_refetch.rs b/rs/moq-net/tests/integration/idle_cancel_refetch.rs index 7ca37c81c5a..9b8128e03a3 100644 --- a/rs/moq-net/tests/integration/idle_cancel_refetch.rs +++ b/rs/moq-net/tests/integration/idle_cancel_refetch.rs @@ -23,7 +23,10 @@ async fn a_group_cut_by_an_idle_cancel_is_refetched_whole() { let publisher = produce_origin(1); let broadcast = publisher.create_broadcast("bcast").unwrap(); let track = broadcast - .create_track("audio", moq_net::track::Info::default().with_timescale(None)) + .create_track( + "audio", + moq_net::track::Info::default().with_timescale(None).with_max_age(None), + ) .unwrap(); broadcast.announce(Default::default()).unwrap(); diff --git a/rs/moq-net/tests/integration/range_read.rs b/rs/moq-net/tests/integration/range_read.rs index b2c8682be50..57f3d0ce720 100644 --- a/rs/moq-net/tests/integration/range_read.rs +++ b/rs/moq-net/tests/integration/range_read.rs @@ -67,7 +67,9 @@ async fn fixture( let mut track = broadcast .create_track( "video", - moq_net::track::Info::default().with_timescale(moq_net::Timescale::MILLI), + moq_net::track::Info::default() + .with_timescale(moq_net::Timescale::MILLI) + .with_max_age(None), ) .unwrap(); broadcast.announce(Default::default()).unwrap(); diff --git a/rs/moq-net/tests/integration/received_rewind.rs b/rs/moq-net/tests/integration/received_rewind.rs index 4a8002c79b5..038839bb37b 100644 --- a/rs/moq-net/tests/integration/received_rewind.rs +++ b/rs/moq-net/tests/integration/received_rewind.rs @@ -55,7 +55,7 @@ async fn relay( let publisher = produce_origin(1); let broadcast = publisher.create_broadcast("bcast").unwrap(); let track = broadcast - .create_track("data", Info::default().with_timescale(timescale)) + .create_track("data", Info::default().with_timescale(timescale).with_max_age(None)) .unwrap(); broadcast.announce(Default::default()).unwrap(); @@ -177,7 +177,9 @@ async fn a_timed_track_keeps_its_timestamps_through_a_relay() { async fn fetch_only(version: &str) -> Vec, moq_net::Error>> { let publisher = produce_origin(1); let broadcast = publisher.create_broadcast("bcast").unwrap(); - let track = broadcast.create_track("data", Info::default()).unwrap(); + let track = broadcast + .create_track("data", Info::default().with_max_age(None)) + .unwrap(); broadcast.announce(Default::default()).unwrap(); write_group(&track, 0); write_group(&track, 1); diff --git a/rs/moq-net/tests/integration/rejoin.rs b/rs/moq-net/tests/integration/rejoin.rs index 3489d8d98aa..bfa52354067 100644 --- a/rs/moq-net/tests/integration/rejoin.rs +++ b/rs/moq-net/tests/integration/rejoin.rs @@ -9,9 +9,12 @@ use std::time::Duration; use moq_net::{Hop, Timestamp, Version, announce, group, track}; use support::harness::{MockConnectOptions, connect_mock}; -/// A millisecond track: the frames written here carry timestamps. +/// A millisecond track with no publisher max age: the frames written here carry timestamps, +/// and superseded groups stay readable. fn timed() -> moq_net::track::Info { - moq_net::track::Info::default().with_timescale(moq_net::Timescale::MILLI) + moq_net::track::Info::default() + .with_timescale(moq_net::Timescale::MILLI) + .with_max_age(None) } /// Maximum time any single test may run before being treated as a deadlock. diff --git a/rs/moq-net/tests/integration/relay_upstream_close.rs b/rs/moq-net/tests/integration/relay_upstream_close.rs index 2a31afcf065..7d2785426dc 100644 --- a/rs/moq-net/tests/integration/relay_upstream_close.rs +++ b/rs/moq-net/tests/integration/relay_upstream_close.rs @@ -22,9 +22,12 @@ use moq_net::track::Subscription; use moq_net::{Error, Hop, Timestamp, Version}; use support::harness::{MockConnectOptions, connect_mock}; -/// A millisecond track: the frames written here carry timestamps. +/// A millisecond track with no publisher max age: the frames written here carry timestamps, +/// and superseded groups stay readable. fn timed() -> moq_net::track::Info { - moq_net::track::Info::default().with_timescale(moq_net::Timescale::MILLI) + moq_net::track::Info::default() + .with_timescale(moq_net::Timescale::MILLI) + .with_max_age(None) } const TIMEOUT: Duration = Duration::from_secs(10); diff --git a/rs/moq-net/tests/integration/route_change.rs b/rs/moq-net/tests/integration/route_change.rs index 62814153772..96a72f80329 100644 --- a/rs/moq-net/tests/integration/route_change.rs +++ b/rs/moq-net/tests/integration/route_change.rs @@ -25,9 +25,12 @@ use futures::{StreamExt, channel::mpsc}; use moq_net::{Error, Hop, Timestamp, Version, announce, origin, track}; use support::harness::{MockConnectOptions, MockPair, connect_mock}; -/// A millisecond track: the frames written here carry timestamps. +/// A millisecond track with no publisher max age: the frames written here carry timestamps, +/// and superseded groups stay readable. pub(super) fn timed() -> moq_net::track::Info { - moq_net::track::Info::default().with_timescale(moq_net::Timescale::MILLI) + moq_net::track::Info::default() + .with_timescale(moq_net::Timescale::MILLI) + .with_max_age(None) } const TEST_TIMEOUT: Duration = Duration::from_secs(30); diff --git a/rs/moq-net/tests/integration/settled_end_survives_abort.rs b/rs/moq-net/tests/integration/settled_end_survives_abort.rs index 8319b7f96c3..7aa4ab64f2e 100644 --- a/rs/moq-net/tests/integration/settled_end_survives_abort.rs +++ b/rs/moq-net/tests/integration/settled_end_survives_abort.rs @@ -9,9 +9,12 @@ use crate::support; use moq_net::{Error, Hop, Timestamp}; -/// A millisecond track: the frames written here carry timestamps. +/// A millisecond track with no publisher max age: the frames written here carry timestamps, +/// and superseded groups stay readable. fn timed() -> moq_net::track::Info { - moq_net::track::Info::default().with_timescale(moq_net::Timescale::MILLI) + moq_net::track::Info::default() + .with_timescale(moq_net::Timescale::MILLI) + .with_max_age(None) } fn produce_origin(hop: u64) -> moq_net::origin::Producer { diff --git a/rs/moq-net/tests/integration/slow_joiner.rs b/rs/moq-net/tests/integration/slow_joiner.rs index f3260ef0b3a..87aa0ca22b8 100644 --- a/rs/moq-net/tests/integration/slow_joiner.rs +++ b/rs/moq-net/tests/integration/slow_joiner.rs @@ -32,7 +32,12 @@ async fn stalled_read(version: Version, budget: Duration) -> BTreeSet { let viewer = origin(3); let broadcast = publisher.create_broadcast("live").unwrap(); let source = broadcast - .create_track("audio", track::Info::default().with_timescale(Timescale::MILLI)) + .create_track( + "audio", + track::Info::default() + .with_timescale(Timescale::MILLI) + .with_max_age(None), + ) .unwrap(); broadcast.announce(Default::default()).unwrap(); diff --git a/rs/moq-net/tests/integration/stream_credit.rs b/rs/moq-net/tests/integration/stream_credit.rs index 4e6443fad9f..bcb19788f42 100644 --- a/rs/moq-net/tests/integration/stream_credit.rs +++ b/rs/moq-net/tests/integration/stream_credit.rs @@ -21,7 +21,9 @@ async fn one_stream_credit_serves_every_backlogged_group() { let publisher = origin(1); let viewer = origin(2); let broadcast = publisher.create_broadcast("live").unwrap(); - let info = track::Info::default().with_timescale(moq_net::Timescale::MILLI); + let info = track::Info::default() + .with_timescale(moq_net::Timescale::MILLI) + .with_max_age(None); let tracks: Vec<_> = (0..2) .map(|i| broadcast.create_track(format!("{i}"), info.clone()).unwrap()) .collect(); diff --git a/rs/moq-net/tests/integration/subscribe_ranges.rs b/rs/moq-net/tests/integration/subscribe_ranges.rs index 119e94be3f2..9b65ffcd540 100644 --- a/rs/moq-net/tests/integration/subscribe_ranges.rs +++ b/rs/moq-net/tests/integration/subscribe_ranges.rs @@ -25,6 +25,13 @@ fn produce_origin(hop: u64) -> moq_net::origin::Producer { producer } +/// A millisecond track with no publisher max age, so ranges reach its superseded groups. +fn timed() -> Info { + Info::default() + .with_timescale(moq_net::Timescale::MILLI) + .with_max_age(None) +} + fn write_group(track: &moq_net::track::Producer, sequence: u64) { let mut group = track.create_group(moq_net::group::Info { sequence }).unwrap(); group.write_frame(Timestamp::now(), &b"x"[..]).unwrap(); @@ -62,9 +69,7 @@ async fn subscribe(remote: &moq_net::broadcast::Consumer, subscription: Subscrip async fn ahead_then_live(version: Option<&str>, relay: bool) -> (Vec, Vec) { let publisher = produce_origin(1); let broadcast = publisher.create_broadcast("bcast").unwrap(); - let track = broadcast - .create_track("quiet", Info::default().with_timescale(moq_net::Timescale::MILLI)) - .unwrap(); + let track = broadcast.create_track("quiet", timed()).unwrap(); broadcast.announce(Default::default()).unwrap(); for sequence in 0..=3 { write_group(&track, sequence); @@ -127,9 +132,7 @@ async fn sparse_ranges_reach_the_publisher_on_lite07() { for version in LITE { let publisher = produce_origin(1); let broadcast = publisher.create_broadcast("bcast").unwrap(); - let track = broadcast - .create_track("quiet", Info::default().with_timescale(moq_net::Timescale::MILLI)) - .unwrap(); + let track = broadcast.create_track("quiet", timed()).unwrap(); broadcast.announce(Default::default()).unwrap(); let subscriber = produce_origin(2); @@ -211,9 +214,7 @@ async fn range_fixture_version(version: &str, relay: bool) -> RangeFixture { async fn range_fixture_history(version: &str, relay: bool, history: u64) -> RangeFixture { let publisher = produce_origin(1); let broadcast = publisher.create_broadcast("ranges").unwrap(); - let track = broadcast - .create_track("quiet", Info::default().with_timescale(moq_net::Timescale::MILLI)) - .unwrap(); + let track = broadcast.create_track("quiet", timed()).unwrap(); broadcast.announce(Default::default()).unwrap(); for sequence in 0..history { let mut group = track.create_group(moq_net::group::Info { sequence }).unwrap(); @@ -746,9 +747,7 @@ async fn a_covered_bounded_subscription_stays_open() { for version in LITE { let publisher = produce_origin(1); let broadcast = publisher.create_broadcast("bcast").unwrap(); - let track = broadcast - .create_track("quiet", Info::default().with_timescale(moq_net::Timescale::MILLI)) - .unwrap(); + let track = broadcast.create_track("quiet", timed()).unwrap(); broadcast.announce(Default::default()).unwrap(); for sequence in [0, 1, 2, 4, 5] { write_group(&track, sequence); diff --git a/rs/moq-net/tests/integration/track_tail.rs b/rs/moq-net/tests/integration/track_tail.rs index 88c07b45d78..6f3db524a20 100644 --- a/rs/moq-net/tests/integration/track_tail.rs +++ b/rs/moq-net/tests/integration/track_tail.rs @@ -18,9 +18,12 @@ use std::time::Duration; use moq_net::{Hop, Timestamp, Version}; use support::harness::{MockConnectOptions, connect_mock}; -/// A millisecond track: the frames written here carry timestamps. +/// A millisecond track with no publisher max age: the frames written here carry timestamps, +/// and superseded groups stay readable. fn timed() -> moq_net::track::Info { - moq_net::track::Info::default().with_timescale(moq_net::Timescale::MILLI) + moq_net::track::Info::default() + .with_timescale(moq_net::Timescale::MILLI) + .with_max_age(None) } const TIMEOUT: Duration = Duration::from_secs(10); diff --git a/rs/moq-net/tests/integration/untimed.rs b/rs/moq-net/tests/integration/untimed.rs index db12b66ff39..f09784f9633 100644 --- a/rs/moq-net/tests/integration/untimed.rs +++ b/rs/moq-net/tests/integration/untimed.rs @@ -62,8 +62,9 @@ fn millis(ms: u64) -> Timestamp { Timestamp::from_millis(ms).unwrap() } +/// An untimed track with no publisher max age, so superseded groups stay readable. fn untimed() -> track::Info { - track::Info::default().with_timescale(None) + track::Info::default().with_timescale(None).with_max_age(None) } /// Origins chained by one session per hop, each hop on its own version. diff --git a/rs/moq-net/tests/integration/warm_backfill.rs b/rs/moq-net/tests/integration/warm_backfill.rs index 2c5f2c7251e..c28162fd322 100644 --- a/rs/moq-net/tests/integration/warm_backfill.rs +++ b/rs/moq-net/tests/integration/warm_backfill.rs @@ -67,7 +67,10 @@ async fn a_newcomer_on_a_warm_relay_gets_the_backfill() { let _link = peer(version.parse::().unwrap(), &publisher, &relay).await; let broadcast = publisher.create_broadcast("live").unwrap(); let source = broadcast - .create_track("video", Info::default().with_timescale(Timescale::MILLI)) + .create_track( + "video", + Info::default().with_timescale(Timescale::MILLI).with_max_age(None), + ) .unwrap(); for sequence in 0..GROUPS { let mut group = source.create_group(moq_net::group::Info { sequence }).unwrap(); diff --git a/rs/moq-net/tests/integration/widened_max_age.rs b/rs/moq-net/tests/integration/widened_max_age.rs index 243ac580130..def074c3d6e 100644 --- a/rs/moq-net/tests/integration/widened_max_age.rs +++ b/rs/moq-net/tests/integration/widened_max_age.rs @@ -41,6 +41,11 @@ fn origin(hop: u64) -> origin::Producer { origin } +/// A millisecond track with no publisher max age, so only a reader's budget skips its groups. +fn timed() -> Info { + Info::default().with_timescale(Timescale::MILLI).with_max_age(None) +} + /// A publisher holding every group, a relay, and a viewer behind it. struct Chain { source: track::Producer, @@ -74,9 +79,7 @@ impl Chain { links.push(peer(version, relay, &viewer).await); } let broadcast = publisher.create_broadcast("live").unwrap(); - let source = broadcast - .create_track("video", Info::default().with_timescale(Timescale::MILLI)) - .unwrap(); + let source = broadcast.create_track("video", timed()).unwrap(); broadcast.announce(Default::default()).unwrap(); Self { source, @@ -300,9 +303,7 @@ async fn wider_newcomers_after_the_first_pull_nothing_upstream() { .session(moq_net::Path::from_static("")); let _upstream = connect_mock(options).await; let broadcast = publisher.create_broadcast("live").unwrap(); - let source = broadcast - .create_track("video", Info::default().with_timescale(Timescale::MILLI)) - .unwrap(); + let source = broadcast.create_track("video", timed()).unwrap(); for sequence in 0..GROUPS { let mut group = source.create_group(moq_net::group::Info { sequence }).unwrap(); group diff --git a/rs/moq-relay/src/cache.rs b/rs/moq-relay/src/cache.rs index bfbf68907f4..2cf25f2ad5c 100644 --- a/rs/moq-relay/src/cache.rs +++ b/rs/moq-relay/src/cache.rs @@ -44,16 +44,15 @@ pub struct Config { #[usage(long = "cache-headroom", env = "MOQ_CACHE_HEADROOM", setting = "cache.headroom")] pub headroom: Option, - /// Maximum time a non-latest cached group is retained, e.g. "30s" or "500ms". + /// Maximum age of a non-latest cached group, e.g. "30s" or "500ms". /// - /// Sets both halves of the retention bound. The pool's wall-clock LRU window - /// becomes this: a group nobody has read or written for this long is - /// reclaimed, so actively-read history stays cached. Each track's own media-timestamp - /// retention window is also clamped down to this, so a publisher advertising - /// a longer window can't promise more history than the relay keeps. This - /// bounds memory by age where `capacity` bounds it by bytes. When unset, the - /// LRU window keeps its 30 second default and each track keeps its own - /// retention window. + /// Sets two separate bounds. The pool's wall-clock LRU window becomes this: a + /// group nobody has read or written for this long is reclaimed, so actively-read + /// history stays cached. Each track's max age, how long a superseded group stays + /// fresh, is also clamped down to this, so a publisher advertising a longer max + /// age can't promise more history than the relay serves. The LRU window bounds + /// memory by age where `capacity` bounds it by bytes. When unset, the LRU window + /// keeps its 30 second default and each track keeps its own max age. /// /// One caveat: the latest group of every track is always retained, since it is /// the live edge. This window otherwise holds whether or not a publisher is @@ -67,7 +66,7 @@ pub struct Config { } /// The relay's resolved cache settings: the shared byte-budget pool plus the -/// retention ceiling applied to every track. +/// max age ceiling applied to every track. /// /// The headroom governor, when configured, moves into the /// [`Driver`](crate::cluster::Driver) that [`Cluster::new`](crate::cluster::Cluster::new) @@ -84,9 +83,9 @@ pub struct Cache { /// Also what owns the headroom governor; see the type docs. pub pool: cache::Pool, - /// Ceiling on each track's media-timestamp retention window (the latest group of - /// every track is always kept). [`Duration::MAX`] imposes no ceiling, leaving - /// each track's own window in force. + /// Ceiling on each track's max age (the latest group of every track never goes + /// stale). [`Duration::MAX`] imposes no ceiling, leaving each track's own max age + /// in force. pub duration: Duration, /// The headroom governor, not yet running. diff --git a/rs/moq-relay/src/cluster.rs b/rs/moq-relay/src/cluster.rs index 5346fcbe328..ddf50d403cc 100644 --- a/rs/moq-relay/src/cluster.rs +++ b/rs/moq-relay/src/cluster.rs @@ -998,10 +998,10 @@ pub struct Options { /// Cluster identity, peers, and discovery. pub config: Config, - /// Shared group pool and per-track retention ceiling. + /// Shared group pool and per-track max age ceiling. /// /// `None` uses an unbounded pool with the standard LRU window and no - /// media-timestamp ceiling. + /// max age ceiling. pub cache: Option, /// Stats publishing on the cluster's origin. Disabled by default. diff --git a/rs/moq-relay/tests/drills.rs b/rs/moq-relay/tests/drills.rs index 069a47a113b..f02c381762f 100644 --- a/rs/moq-relay/tests/drills.rs +++ b/rs/moq-relay/tests/drills.rs @@ -33,9 +33,12 @@ use futures::FutureExt; use moq_relay::{Config, Relay}; use moq_tokio::moq_net; -/// A millisecond track: the frames written here carry timestamps. +/// A millisecond track with no publisher max age: the frames written here carry timestamps, +/// and superseded groups stay readable. fn timed() -> moq_net::track::Info { - moq_net::track::Info::default().with_timescale(moq_net::Timescale::MILLI) + moq_net::track::Info::default() + .with_timescale(moq_net::Timescale::MILLI) + .with_max_age(None) } /// Ceiling for anything a drill waits on. Every wait is bounded, so a broken diff --git a/rs/moq-relay/tests/integration/goaway_cluster.rs b/rs/moq-relay/tests/integration/goaway_cluster.rs index 3061289a525..1e90d7fe9ba 100644 --- a/rs/moq-relay/tests/integration/goaway_cluster.rs +++ b/rs/moq-relay/tests/integration/goaway_cluster.rs @@ -15,9 +15,12 @@ use moq_relay::{ }; use url::Url; -/// A millisecond track: the frames written here carry timestamps. +/// A millisecond track with no publisher max age: the frames written here carry timestamps, +/// and superseded groups stay readable. fn timed() -> moq_net::track::Info { - moq_net::track::Info::default().with_timescale(moq_net::Timescale::MILLI) + moq_net::track::Info::default() + .with_timescale(moq_net::Timescale::MILLI) + .with_max_age(None) } const TEST_TIMEOUT: Duration = Duration::from_secs(15); diff --git a/rs/moq-rtc/MIGRATE.md b/rs/moq-rtc/MIGRATE.md index 7d719b8e64b..424cf864612 100644 --- a/rs/moq-rtc/MIGRATE.md +++ b/rs/moq-rtc/MIGRATE.md @@ -4,6 +4,11 @@ How to update your code for each breaking change, newest first. ## Unreleased +### `Config::max_age` of `None` is unlimited ([#7729](https://github.com/moq-dev/moq/pull/7729)) + +`server::Config::max_age` and `client::Config::max_age` default to `Some(hang::container::MAX_AGE)` (30 s), and `None` now sets no publisher limit instead of keeping that default. +Leave the field at its default unless you have a value. + ### `moq_net::Path` has no lifetime `server::{whip, whep}::accept` take `impl Into`: pass a `Path`, from `moq_net::Path::new(s)?` or `moq_net::Path::from_static`. See moq-net's migration for the rest. diff --git a/rs/moq-rtc/src/client/mod.rs b/rs/moq-rtc/src/client/mod.rs index 52042b3691f..e726dd9e9c3 100644 --- a/rs/moq-rtc/src/client/mod.rs +++ b/rs/moq-rtc/src/client/mod.rs @@ -14,15 +14,15 @@ use std::time::Duration; use url::Url; /// Configuration shared by both `client publish` and `client subscribe`. -#[derive(Clone, Debug, Default)] +#[derive(Clone, Debug)] #[non_exhaustive] pub struct Config { /// Public UDP socket addresses to advertise as ICE host candidates in /// our outbound offer. Same semantics as [`crate::server::Config::ice_candidates`]. pub ice_candidates: Vec, - /// How long relays keep a non-latest group of an ingested media track fetchable. - /// Same semantics as [`crate::server::Config::max_age`]. + /// How long a superseded group of an ingested media track stays fresh, or `None` for + /// no publisher limit. Same semantics as [`crate::server::Config::max_age`]. /// /// Ingest only ([`subscribe`](Client::subscribe) / WHEP): a WHIP /// [`publish`](Client::publish) reads a broadcast someone else declared, so it @@ -35,6 +35,16 @@ pub struct Config { pub bandwidth: moq_net::bandwidth::Allocator, } +impl Default for Config { + fn default() -> Self { + Self { + ice_candidates: Vec::new(), + max_age: Some(hang::container::MAX_AGE), + bandwidth: moq_net::bandwidth::Allocator::unlimited(), + } + } +} + /// Outbound WHIP/WHEP dialer. /// /// Owns a [`reqwest::Client`] reused across calls so connection pooling and diff --git a/rs/moq-rtc/src/ingest.rs b/rs/moq-rtc/src/ingest.rs index fc145c45862..b1a8ca841a1 100644 --- a/rs/moq-rtc/src/ingest.rs +++ b/rs/moq-rtc/src/ingest.rs @@ -87,10 +87,10 @@ mod tests { use super::*; use crate::session::MediaSink; - /// The retention the caller configured has to land on the media tracks the codec + /// The max age the caller configured has to land on the media tracks the codec /// bridges mint, not just on the catalog producer it was set on. #[tokio::test] - async fn tracks_inherit_the_configured_retention() { + async fn tracks_inherit_the_configured_max_age() { let broadcast = moq_net::broadcast::Info::new().produce(); let mut sink = IngestSink::new( broadcast.clone(), diff --git a/rs/moq-rtc/src/server/mod.rs b/rs/moq-rtc/src/server/mod.rs index 1cebc8d42e7..ba76f6d12bc 100644 --- a/rs/moq-rtc/src/server/mod.rs +++ b/rs/moq-rtc/src/server/mod.rs @@ -142,13 +142,14 @@ pub struct Config { /// the OS pick a port, which is fine for dev/loopback; production pins it. pub udp_bind: SocketAddr, - /// How long relays keep a non-latest group of an ingested media track fetchable. + /// How long a superseded group of an ingested media track stays fresh, or `None` for no + /// publisher limit. /// - /// A retention budget, not a delivery one: it never makes a subscriber play further - /// behind live, it caps how far back a FETCH can still reach. `None` keeps hang's own - /// default, which suits a segmented egress (HLS/DASH) reading the broadcast downstream: - /// it may only advertise segments that are still fetchable. Lower it when nothing reads - /// history and the memory matters. + /// A freshness bound, not a delivery one: it never makes a subscriber play further + /// behind live, it caps how far back a FETCH can still reach. Defaults to + /// [`MAX_AGE`](hang::container::MAX_AGE), which suits a segmented + /// egress (HLS/DASH) reading the broadcast downstream: it may only advertise segments + /// that are still fetchable. Lower it when nothing reads history. /// /// Ingest only (`server publish` / WHIP): WHEP egress reads a broadcast someone else /// declared, so it ignores this. @@ -169,7 +170,7 @@ impl Default for Config { Self { ice_candidates: Vec::new(), udp_bind: SocketAddr::from(([0, 0, 0, 0], 0)), - max_age: None, + max_age: Some(hang::container::MAX_AGE), bandwidth: moq_net::bandwidth::Allocator::unlimited(), linger: moq_mux::Linger::DEFAULT, } diff --git a/rs/moq-rtmp/MIGRATE.md b/rs/moq-rtmp/MIGRATE.md index c5d24fb52eb..83468537f22 100644 --- a/rs/moq-rtmp/MIGRATE.md +++ b/rs/moq-rtmp/MIGRATE.md @@ -4,6 +4,11 @@ How to update your code for each breaking change, newest first. ## Unreleased +### `with_max_age(None)` is unlimited ([#7729](https://github.com/moq-dev/moq/pull/7729)) + +The ingest builders' `with_max_age` still default to `hang::container::MAX_AGE` (30 s), but `None` now sets no publisher limit instead of keeping that default. +Call `with_max_age` only when you have a value, as with `moq_mux::catalog::Config::with_max_age`. + ### `moq_net::Path` has no lifetime Entry points that took `impl moq_net::AsPath` take `impl Into`: pass a `Path` or `&Path`, from `moq_net::Path::new(s)?` or `moq_net::Path::from_static`, since a string can be too long. See moq-net's migration for the rest. diff --git a/rs/moq-rtmp/src/dial.rs b/rs/moq-rtmp/src/dial.rs index 6bff0f758f0..4f1d73da809 100644 --- a/rs/moq-rtmp/src/dial.rs +++ b/rs/moq-rtmp/src/dial.rs @@ -70,8 +70,8 @@ pub struct Client { /// How long [`publish`](Self::publish)'s FLV muxer waits for a stalled group /// before skipping. max_delay: Duration, - /// Retention declared on the media tracks [`pull`](Self::pull) publishes, or `None` - /// for hang's own default. + /// Max age declared on the media tracks [`pull`](Self::pull) publishes, or `None` for + /// no publisher limit. max_age: Option, /// Connection allocator each track [`pull`](Self::pull) ingests claims its peak-hold bitrate on. bandwidth: moq_net::bandwidth::Allocator, @@ -174,7 +174,7 @@ impl Client { work, app: app.to_string(), max_delay: crate::DEFAULT_MAX_DELAY, - max_age: None, + max_age: Some(hang::container::MAX_AGE), bandwidth: moq_net::bandwidth::Allocator::unlimited(), linger: moq_mux::Linger::DEFAULT, metadata: Default::default(), @@ -191,14 +191,14 @@ impl Client { self } - /// Set how long relays keep a non-latest group of the media tracks - /// [`pull`](Self::pull) publishes fetchable. `None` keeps hang's own default. + /// Set how long a superseded group of the media tracks [`pull`](Self::pull) publishes + /// stays fresh, or `None` for no publisher limit. Defaults to + /// [`MAX_AGE`](hang::container::MAX_AGE). /// - /// A retention budget, not a delivery one: it never makes a subscriber play further + /// A freshness bound, not a delivery one: it never makes a subscriber play further /// behind live, it caps how far back a FETCH can still reach. The default suits a /// segmented egress (HLS/DASH) reading the broadcast downstream, which may only - /// advertise segments that are still fetchable. Lower it when nothing reads history - /// and the memory matters. + /// advertise segments that are still fetchable. Lower it when nothing reads history. /// /// The pull (ingest) direction only; [`publish`](Self::publish) reads a broadcast /// someone else declared, and takes [`with_max_delay`](Self::with_max_delay) instead. diff --git a/rs/moq-rtmp/src/server.rs b/rs/moq-rtmp/src/server.rs index 1accebad879..e9e1a546b42 100644 --- a/rs/moq-rtmp/src/server.rs +++ b/rs/moq-rtmp/src/server.rs @@ -572,8 +572,8 @@ pub struct Publish { stream_key: String, tc_url: Option, peer: SocketAddr, - /// Retention declared on the media tracks this publish mints, or `None` for hang's - /// own default. Override with [`with_max_age`](Self::with_max_age). + /// Max age declared on the media tracks this publish mints, or `None` for no publisher + /// limit. Override with [`with_max_age`](Self::with_max_age). max_age: Option, /// Connection allocator each passthrough track claims its peak-hold bitrate on. /// Override with [`with_bandwidth`](Self::with_bandwidth). @@ -608,14 +608,14 @@ impl Publish { self.peer } - /// Set how long relays keep a non-latest group of this publish's media tracks - /// fetchable. `None` keeps hang's own default. + /// Set how long a superseded group of this publish's media tracks stays fresh, or + /// `None` for no publisher limit. Defaults to + /// [`MAX_AGE`](hang::container::MAX_AGE). /// - /// A retention budget, not a delivery one: it never makes a subscriber play further + /// A freshness bound, not a delivery one: it never makes a subscriber play further /// behind live, it caps how far back a FETCH can still reach. The default suits a /// segmented egress (HLS/DASH) reading the broadcast downstream, which may only - /// advertise segments that are still fetchable. Lower it when nothing reads history - /// and the memory matters. + /// advertise segments that are still fetchable. Lower it when nothing reads history. pub fn with_max_age(mut self, max_age: impl Into>) -> Self { self.max_age = max_age.into(); self @@ -1197,7 +1197,7 @@ async fn accept_until_request(mut stream: S, peer: SocketAddr) -> any stream_key, tc_url, peer, - max_age: None, + max_age: Some(hang::container::MAX_AGE), bandwidth: moq_net::bandwidth::Allocator::unlimited(), linger: moq_mux::Linger::DEFAULT, }))); @@ -2192,10 +2192,10 @@ mod tests { } } - /// The retention a publish declares has to reach the media tracks the FLV importer + /// The max age a publish declares has to reach the media tracks the FLV importer /// mints, not stop at the catalog producer it was set on. #[tokio::test] - async fn publisher_declares_the_configured_retention() { + async fn publisher_declares_the_configured_max_age() { let mut vseq = vec![0x17, 0x00, 0x00, 0x00, 0x00]; vseq.extend_from_slice(&[0x01, 0x42, 0xc0, 0x1f, 0xff, 0xe1, 0x00, 0x04, 0x67, 0x42, 0xc0, 0x1f]); vseq.extend_from_slice(&[0x01, 0x00, 0x04, 0x68, 0xce, 0x3c, 0x80]); diff --git a/rs/moq-srt/Cargo.toml b/rs/moq-srt/Cargo.toml index e9972ee83dd..03ed9a71ff7 100644 --- a/rs/moq-srt/Cargo.toml +++ b/rs/moq-srt/Cargo.toml @@ -17,6 +17,8 @@ categories = ["multimedia", "network-programming", "web-programming"] [dependencies] bytes = { workspace = true } futures = { workspace = true } +# The media max age an ingest declares by default. +hang = { workspace = true } moq-mux = { workspace = true } moq-net = { workspace = true } # Pure-Rust SRT (no libsrt / ffmpeg). SRT carries MPEG-TS, demuxed by moq-mux. @@ -26,8 +28,6 @@ tokio = { workspace = true, features = ["full"] } tracing = { workspace = true } [dev-dependencies] -# Builds the synthetic broadcasts the egress tests mux back to TS. -hang = { path = "../hang" } kio = { workspace = true, features = ["runtime"] } srt-protocol = "0.4" tracing-subscriber = { workspace = true } diff --git a/rs/moq-srt/MIGRATE.md b/rs/moq-srt/MIGRATE.md index 342bc719f31..3f5609e5e0d 100644 --- a/rs/moq-srt/MIGRATE.md +++ b/rs/moq-srt/MIGRATE.md @@ -4,6 +4,11 @@ How to update your code for each breaking change, newest first. ## Unreleased +### `with_max_age(None)` is unlimited ([#7729](https://github.com/moq-dev/moq/pull/7729)) + +The ingest builders' `with_max_age` still default to `hang::container::MAX_AGE` (30 s), but `None` now sets no publisher limit instead of keeping that default. +Call `with_max_age` only when you have a value, as with `moq_mux::catalog::Config::with_max_age`. + ### `moq_net::Path` has no lifetime Entry points that took `impl moq_net::AsPath` take `impl Into`: pass a `Path` or `&Path`, from `moq_net::Path::new(s)?` or `moq_net::Path::from_static`, since a string can be too long. See moq-net's migration for the rest. diff --git a/rs/moq-srt/src/dial.rs b/rs/moq-srt/src/dial.rs index 5f1aac3ff0e..4e3389754f3 100644 --- a/rs/moq-srt/src/dial.rs +++ b/rs/moq-srt/src/dial.rs @@ -43,14 +43,13 @@ pub struct Client { /// for loss recovery. It doubles as [`publish`]'s egress skip threshold. max_delay: Duration, - /// How long relays keep a non-latest group of an ingested media track fetchable, or - /// `None` for hang's own default. + /// How long a superseded group of an ingested media track stays fresh, or `None` for + /// no publisher limit. Defaults to [`MAX_AGE`](hang::container::MAX_AGE). /// - /// A retention budget, not a delivery one: it never makes a subscriber play further + /// A freshness bound, not a delivery one: it never makes a subscriber play further /// behind live, it caps how far back a FETCH can still reach. The default suits a /// segmented egress (HLS/DASH) reading the broadcast downstream, which may only - /// advertise segments that are still fetchable. Lower it when nothing reads history - /// and the memory matters. [`pull`] only; [`publish`] reads a broadcast someone else + /// advertise segments that are still fetchable. Lower it when nothing reads history. [`pull`] only; [`publish`] reads a broadcast someone else /// declared. max_age: Option, @@ -75,13 +74,13 @@ pub struct Client { impl Client { /// Dial `addr` for `resource`, with the default SRT latency (500ms) and the - /// publisher's own media retention. + /// authored media max age. pub fn new(addr: SocketAddr, resource: impl Into) -> Self { Self { addr, resource: resource.into(), max_delay: DEFAULT_LATENCY, - max_age: None, + max_age: Some(hang::container::MAX_AGE), bandwidth: moq_net::bandwidth::Allocator::unlimited(), program: None, linger: moq_mux::Linger::DEFAULT, diff --git a/rs/moq-srt/src/server.rs b/rs/moq-srt/src/server.rs index 2e5412e6ef2..e65e628be61 100644 --- a/rs/moq-srt/src/server.rs +++ b/rs/moq-srt/src/server.rs @@ -247,7 +247,7 @@ impl Server { stream_id, peer, latency: self.latency, - max_age: None, + max_age: Some(hang::container::MAX_AGE), bandwidth: moq_net::bandwidth::Allocator::unlimited(), program: None, linger: moq_mux::Linger::DEFAULT, @@ -279,8 +279,8 @@ struct Pending { peer: SocketAddr, /// The SRT receive latency, reused as the egress delay (at least a second) on a subscribe. latency: Duration, - /// Retention declared on the media tracks an ingest mints, or `None` for hang's own - /// default. Override with [`Publish::with_max_age`]. + /// Max age declared on the media tracks an ingest mints, or `None` for no publisher + /// limit. Override with [`Publish::with_max_age`]. max_age: Option, /// Connection allocator each ingested track claims its peak-hold bitrate on. /// Override with [`Publish::with_bandwidth`]. @@ -366,14 +366,14 @@ impl Publish { self.0.peer } - /// Set how long relays keep a non-latest group of this publish's media tracks - /// fetchable. `None` keeps hang's own default. + /// Set how long a superseded group of this publish's media tracks stays fresh, or + /// `None` for no publisher limit. Defaults to + /// [`MAX_AGE`](hang::container::MAX_AGE). /// - /// A retention budget, not a delivery one: it never makes a subscriber play further + /// A freshness bound, not a delivery one: it never makes a subscriber play further /// behind live, it caps how far back a FETCH can still reach. The default suits a /// segmented egress (HLS/DASH) reading the broadcast downstream, which may only - /// advertise segments that are still fetchable. Lower it when nothing reads history - /// and the memory matters. + /// advertise segments that are still fetchable. Lower it when nothing reads history. /// /// Unrelated to the SRT receive latency [`Server::bind`] negotiates, which is a /// transport buffer on this hop. diff --git a/rs/moq-srt/src/ts.rs b/rs/moq-srt/src/ts.rs index ed32d8eafe5..df0e3f3b593 100644 --- a/rs/moq-srt/src/ts.rs +++ b/rs/moq-srt/src/ts.rs @@ -118,7 +118,7 @@ impl Publisher { /// Wire up the TS importer and catalog for `path` on `origin`, announcing the broadcast /// now, or each program's once its PMT declares its tracks for [`Program::All`]. /// - /// `config` is the catalog the importer publishes into: retention + /// `config` is the catalog the importer publishes into: max age /// (`with_max_age`) and the connection allocator passthrough tracks claim on /// (`with_bandwidth`). pub fn new( @@ -742,10 +742,10 @@ mod tests { assert!(broadcast.is_closed()); } - /// The retention the caller configured has to reach the media tracks the TS importer + /// The max age the caller configured has to reach the media tracks the TS importer /// mints off the PMT, not stop at the catalog producer it was set on. #[tokio::test] - async fn publisher_declares_the_configured_retention() { + async fn publisher_declares_the_configured_max_age() { let origin = produce_origin(); let mut publisher = Publisher::new( &origin, diff --git a/rs/moq-stats/benches/aggregate.rs b/rs/moq-stats/benches/aggregate.rs index eb0117e0332..9a93bb73883 100644 --- a/rs/moq-stats/benches/aggregate.rs +++ b/rs/moq-stats/benches/aggregate.rs @@ -55,7 +55,9 @@ impl Node { let track = source .create_track( group_track(moq_net::Path::from_static("acme")), - moq_net::track::Info::default().with_timescale(moq_net::Timescale::MILLI), + moq_net::track::Info::default() + .with_max_age(None) + .with_timescale(moq_net::Timescale::MILLI), ) .unwrap(); let config = moq_json::snapshot::Config::default().with_deltas(false); diff --git a/rs/moq-tokio/tests/integration/broadcast.rs b/rs/moq-tokio/tests/integration/broadcast.rs index a1944abfedc..13ca71d2468 100644 --- a/rs/moq-tokio/tests/integration/broadcast.rs +++ b/rs/moq-tokio/tests/integration/broadcast.rs @@ -11,9 +11,12 @@ use moq_tokio::moq_net::{self, Hop}; use std::time::Duration; -/// A millisecond track: the frames written here carry timestamps. +/// A millisecond track with no publisher max age: the frames written here carry timestamps, +/// and superseded groups stay readable. fn timed() -> moq_net::track::Info { - moq_net::track::Info::default().with_timescale(moq_net::Timescale::MILLI) + moq_net::track::Info::default() + .with_timescale(moq_net::Timescale::MILLI) + .with_max_age(None) } const TIMEOUT: Duration = Duration::from_secs(10); @@ -497,7 +500,9 @@ async fn lite05_fetch_during_subscribe(scheme: &str) { let track = broadcast .create_track( "video", - moq_net::track::Info::default().with_timescale(Timescale::MICRO), + moq_net::track::Info::default() + .with_timescale(Timescale::MICRO) + .with_max_age(None), ) .expect("failed to create track"); @@ -1594,7 +1599,7 @@ async fn broadcast_negotiate_client_all_server_transport_18() { broadcast_test("moqt", None, Some("moq-transport-18")).await; } -// ── Retention window (track::Info::max_age) ───────────────────── +// ── Freshness bound (track::Info::max_age) ────────────────────── async fn max_age_test(version: &str, published: Option) -> Option { let version: moq_net::Version = version.parse().expect("invalid version"); diff --git a/rs/moq-tokio/tests/integration/sim.rs b/rs/moq-tokio/tests/integration/sim.rs index 180169eb1e2..c4f39266dc9 100644 --- a/rs/moq-tokio/tests/integration/sim.rs +++ b/rs/moq-tokio/tests/integration/sim.rs @@ -144,7 +144,12 @@ async fn serve(network: &Network, version: Version, seed: u64) -> Arrivals { let viewer = origin_producer(2); let broadcast = publisher.create_broadcast("live").unwrap(); let source = broadcast - .create_track("video", track::Info::default().with_timescale(Timescale::MILLI)) + .create_track( + "video", + track::Info::default() + .with_timescale(Timescale::MILLI) + .with_max_age(None), + ) .unwrap(); broadcast.announce(Default::default()).unwrap(); diff --git a/rs/moq-transcode/src/rung.rs b/rs/moq-transcode/src/rung.rs index c6664b15b00..d23f562bf41 100644 --- a/rs/moq-transcode/src/rung.rs +++ b/rs/moq-transcode/src/rung.rs @@ -972,7 +972,10 @@ mod tests { let source_fills = source.create_track("video", None).unwrap().requests(); let output = moq_net::broadcast::Info::default().produce(); - let timed = moq_net::track::Info::default().with_timescale(moq_net::Timescale::MILLI); + // A rung's media max age, as `serve` accepts it, so its history is still fresh to fill. + let timed = moq_net::track::Info::default() + .with_timescale(moq_net::Timescale::MILLI) + .with_max_age(hang::container::MAX_AGE); let mut track = output.create_track("video/120p", timed).unwrap(); let fills = track.requests(); let ascending = |groups| { diff --git a/rs/moq-uring/benches/session_lite.rs b/rs/moq-uring/benches/session_lite.rs index 68759dbf23b..2bd0cb22a0c 100644 --- a/rs/moq-uring/benches/session_lite.rs +++ b/rs/moq-uring/benches/session_lite.rs @@ -38,7 +38,9 @@ mod linux { /// A millisecond track: the frames written here carry timestamps. fn timed() -> moq_net::track::Info { - moq_net::track::Info::default().with_timescale(moq_net::Timescale::MILLI) + moq_net::track::Info::default() + .with_max_age(None) + .with_timescale(moq_net::Timescale::MILLI) } struct Ablation { diff --git a/swift/MIGRATE.md b/swift/MIGRATE.md index 86895a6576a..fead499caa5 100644 --- a/swift/MIGRATE.md +++ b/swift/MIGRATE.md @@ -4,6 +4,10 @@ How to update your code for each breaking change, newest first. ## Unreleased +### Authored tracks default to a zero max age ([#7729](https://github.com/moq-dev/moq/pull/7729)) + +A `nil` `TrackInfo.maxAge`, the default, and a `nil` info now advertise a zero max age, serving only the live edge, instead of no publisher limit. Pass `maxAgeUnlimited: true`, which ignores `maxAge`, where you relied on `nil` meaning no limit. A received track's `info()` sets it when its publisher advertised no limit. + ### Viewer targets are bounded ([#7090](https://github.com/moq-dev/moq/pull/7090)) Viewer ceilings and PROBE target overrides are refused with the new `MoqError.OutOfRange` once they would sum above 2^53 - 1 bps, the most a PROBE target carries; nothing changes on a refusal. `Viewers.watch(maxBps:)` and `setTarget(targetBps:)` and `Viewer.update(maxBps:)` throw it, so call them with `try`. Handle the new variant wherever you match the error exhaustively. Regenerate bindings and rebuild the matching native library together. diff --git a/swift/Tests/MoqTests/SmokeTests.swift b/swift/Tests/MoqTests/SmokeTests.swift index 0d9131a52a8..3f5a3c3b63c 100644 --- a/swift/Tests/MoqTests/SmokeTests.swift +++ b/swift/Tests/MoqTests/SmokeTests.swift @@ -63,7 +63,8 @@ final class SmokeTests: XCTestCase { func testAscendingSubscriptionReadsACachedBacklogOldestFirst() async throws { let broadcast = try BroadcastProducer() - let track = try broadcast.publishTrack(name: "backlog", info: TrackInfo(timescale: 1_000_000)) + let info = TrackInfo(maxAgeUnlimited: true, timescale: 1_000_000) + let track = try broadcast.publishTrack(name: "backlog", info: info) for ms: UInt64 in 0..<3 { let group = try track.appendGroup() try group.writeFrame(Data("x".utf8), timestamp: micros(ms * 1_000)) @@ -561,6 +562,17 @@ final class SmokeTests: XCTestCase { try broadcast.close() } + func testTrackInfoMaxAge() throws { + let broadcast = try BroadcastProducer() + let omitted = try broadcast.publishTrack(name: "omitted").consume().info() + XCTAssertEqual(omitted.maxAge, 0) + let info = TrackInfo(maxAgeUnlimited: true) + let unlimited = try broadcast.publishTrack(name: "unlimited", info: info).consume().info() + XCTAssertNil(unlimited.maxAge) + XCTAssertTrue(unlimited.maxAgeUnlimited) + try broadcast.close() + } + func testRawTrackTimestamps() async throws { let broadcast = try BroadcastProducer() let track = try broadcast.publishTrack(name: "events", info: TrackInfo(timescale: 1_000_000)) diff --git a/test/interop/clients/js-native/tail.ts b/test/interop/clients/js-native/tail.ts index a4dccd60e8b..e0ecb8c92b6 100644 --- a/test/interop/clients/js-native/tail.ts +++ b/test/interop/clients/js-native/tail.ts @@ -119,7 +119,9 @@ try { if (role === "publish") { const broadcastPublication = origin.createBroadcast(Moq.Path.from(path)); const broadcast = broadcastPublication.broadcast; - const track = broadcast.createTrack("tail", { compress, ...(status ? { priority: 2 } : {}) }); + // `cached` and `late` read groups a newer one supersedes, which the default zero max age + // would leave stale. + const track = broadcast.createTrack("tail", { compress, maxAge: null, ...(status ? { priority: 2 } : {}) }); if (cached) write(track); if (history) serveHistory(track); let head: Moq.Group.Producer | undefined; diff --git a/test/interop/clients/js/open-gop/main.ts b/test/interop/clients/js/open-gop/main.ts index 71e367ae54c..f463c677ffc 100644 --- a/test/interop/clients/js/open-gop/main.ts +++ b/test/interop/clients/js/open-gop/main.ts @@ -63,7 +63,8 @@ window.runRecovery = async (packets) => { const publication = origin.createBroadcast(name); publication.announce(); const producer = publication.broadcast; - const track = producer.createTrack("video", { timescale: Moq.Time.Timescale.MICRO }); + // Every group is written before the decoder reads from the first, so none may go stale. + const track = producer.createTrack("video", { timescale: Moq.Time.Timescale.MICRO, maxAge: null }); let group: Moq.Group.Producer | undefined; for (const packet of packets) { if (group?.sequence !== BigInt(packet.group)) { diff --git a/test/interop/clients/js/src/finish.ts b/test/interop/clients/js/src/finish.ts index 6e8c6e66443..7343a022d95 100644 --- a/test/interop/clients/js/src/finish.ts +++ b/test/interop/clients/js/src/finish.ts @@ -78,9 +78,10 @@ export function finish( codedHeight: Catalog.u53(240), container: { kind: "legacy" }, }; + // Late readers read the finished video from group 0. const track = broadcast.createTrack("video", { timescale: Moq.Time.Timescale.MICRO, - maxAge: Milli(Number.MAX_SAFE_INTEGER), + maxAge: null, priority: Catalog.PRIORITY.video, }); const media = new Container.Legacy.Producer(track, new Container.Legacy.Format(config)); @@ -127,7 +128,6 @@ export function finish( catalog.serve( broadcast.createTrack(Catalog.TRACK, { timescale: Moq.Time.Timescale.MILLI, - maxAge: Milli(Number.MAX_SAFE_INTEGER), priority: Catalog.PRIORITY.catalog, }), serving, diff --git a/test/interop/clients/rust/tail.rs b/test/interop/clients/rust/tail.rs index bcd95c5776e..1966f5b051e 100644 --- a/test/interop/clients/rust/tail.rs +++ b/test/interop/clients/rust/tail.rs @@ -110,7 +110,10 @@ async fn main() -> anyhow::Result<()> { "tail", moq_net::track::Info::default() .with_timescale(moq_net::Timescale::MILLI) - .with_compress(compress), + .with_compress(compress) + // `cached` and `late` read groups a newer one supersedes, which the default + // zero max age would leave stale. + .with_max_age(None), )?; broadcast.announce(Default::default())?; if cached { diff --git a/test/interop/ietf-range-updates.ts b/test/interop/ietf-range-updates.ts index 473cd79c18c..8815e6e0d05 100644 --- a/test/interop/ietf-range-updates.ts +++ b/test/interop/ietf-range-updates.ts @@ -17,7 +17,8 @@ const version = (0xff000000 + input.draft) as IetfVersion; const pair = createMockTransportPair(`moqt-${input.draft}`); const origin = new OriginProducer(); const publication = origin.createBroadcast(Path.from("room")); -const track = publication.broadcast.createTrack("video"); +// The updates replay groups a newer one superseded, which the default zero max age would stale. +const track = publication.broadcast.createTrack("video", { maxAge: null }); publication.announce(); const publisher = new Publisher({ quic: pair.server, diff --git a/test/justfile b/test/justfile index 4fe972af832..79ab2b14ed6 100644 --- a/test/justfile +++ b/test/justfile @@ -253,7 +253,7 @@ video: # A desktop display makes software Vulkan request unsupported window surfaces. cd video && bash ../../sh/local.sh env -u DISPLAY -u WAYLAND_DISPLAY bun test ./renderer.browser.ts -# Optional publisher retention across Rust/JS sessions through a Rust relay. +# Optional publisher max age across Rust/JS sessions through a Rust relay. max-age: bash ../sh/local.sh cargo nextest run --locked -p moq-tokio --test integration -E 'test(/^max_age::/)' --run-ignored all diff --git a/test/max-age/README.md b/test/max-age/README.md index d811ef86080..bde5522641d 100644 --- a/test/max-age/README.md +++ b/test/max-age/README.md @@ -1,8 +1,8 @@ -# Publisher retention interop +# Publisher max age interop `just test max-age` runs real WebSocket/QMux sessions through a Rust origin relay. -Rust-to-Rust, Rust-to-JavaScript, and JavaScript-to-Rust check omitted, zero, and -30-second publisher limits on lite-07, IETF draft 18, and IETF draft 22. The relay +Rust-to-Rust, Rust-to-JavaScript, and JavaScript-to-Rust check unlimited (an explicit +`None`/`null`, sent as an omitted wire value), zero, and 30-second publisher max ages on lite-07, IETF draft 18, and IETF draft 22. The relay has a one-second local cache ceiling; received metadata must remain unchanged. The JavaScript client uses Bun and the source checkout. Every listener binds an diff --git a/test/max-age/client.ts b/test/max-age/client.ts index 64b10455b86..68ac059fa12 100644 --- a/test/max-age/client.ts +++ b/test/max-age/client.ts @@ -12,7 +12,8 @@ const [address, protocol, mode] = process.argv.slice(2); if (!address || !protocol || !["publish", "subscribe"].includes(mode)) throw new Error("expected URL ALPN publish|subscribe"); const origin = new Producer(); -const ages = [undefined, Milli(0), Milli(30_000)]; +// `null` is an explicit unlimited: an omitted max age is the zero authored default. +const ages = [null, Milli(0), Milli(30_000)]; if (mode === "publish") { const broadcastPublication = origin.createBroadcast(Path.from("age")); const broadcast = broadcastPublication.broadcast; @@ -47,7 +48,8 @@ try { assert(broadcast); for (const [i, age] of ages.entries()) { const track = broadcast.track(String(i)).subscribe(); - assert.equal((await track.info()).maxAge, age, `${protocol} track ${i}`); + // A track received without a max age has no publisher limit: absent, not null. + assert.equal((await track.info()).maxAge, age ?? undefined, `${protocol} track ${i}`); track.close(); } request.close(); diff --git a/test/receive-credit/sender.ts b/test/receive-credit/sender.ts index 7ea3575d038..0dabf3fa4ca 100644 --- a/test/receive-credit/sender.ts +++ b/test/receive-credit/sender.ts @@ -38,8 +38,10 @@ if (!websocket) install(); const origin = new Moq.Origin.Producer(); const broadcastPublication = origin.createBroadcast(Moq.Path.from("room")); const broadcast = broadcastPublication.broadcast; -const low = broadcast.createTrack("low"); -const high = broadcast.createTrack("high"); +// No publisher limit, so the open `low` group stays the receiver's to give up on rather than +// going stale here once a newer group arrives. +const low = broadcast.createTrack("low", { maxAge: null }); +const high = broadcast.createTrack("high", { maxAge: null }); broadcastPublication.announce(); const session = await Moq.Connection.connect({