From 0056d18707706d21164afc29d8a1a0f1552fd0fc Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sun, 1 Nov 2026 06:27:21 -0800 Subject: [PATCH 1/3] chore(quest): claim quest/m1/max-age-defaults.md Quest-Claim: 79cd6109c477b5ee From f0e56ead3214ab55695625d46fdf6921ce4cd2e7 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sun, 1 Nov 2026 06:34:16 -0800 Subject: [PATCH 2/3] docs(quest): audit max-age defaults and propose finite authoring retention Co-Authored-By: GPT-6.1 Sol --- quest/m1/max-age-defaults.md | 90 +++++++++++++++++++++++++++++++++--- 1 file changed, 84 insertions(+), 6 deletions(-) diff --git a/quest/m1/max-age-defaults.md b/quest/m1/max-age-defaults.md index 52fcb3a82b8..8f5df0a799b 100644 --- a/quest/m1/max-age-defaults.md +++ b/quest/m1/max-age-defaults.md @@ -2,14 +2,92 @@ ## Goal -Every max-age and cache-retention default in Rust, JS, and FFI is listed with where it applies (producers, relay cache, the IETF absent-MAX_AGE meaning), and the maintainer has a concrete proposal for a finite default to decide on, so no retention is unlimited by accident. +The audit is recorded below. The remaining outcome is the maintainer's choice of retention defaults and an implementation quest through `/quest-plan`. No runtime defaults, public API, or wire semantics change in this checkpoint. ## Plan -Decided 2026-10-30 (maintainer): asked whether max-age should default to 0 instead of infinite, like max_delay, which [moq-dev/moq#7403](https://github.com/moq-dev/moq/pull/7403) settled (JS and Rust default 0; unlimited is explicit `None`/`null`). For max-age, audit first and propose. +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 recommendations below are proposals, not maintainer decisions. -- Inventory each default with path:line: `track::Producer`/catalog/media producers, the relay cache's eviction and pool, JS `maxAge` (omitted means no publisher limit in `@moq/net`'s `Info`, while `@moq/hang`'s `trackInfo` substitutes 30 s, matching `hang::container::MAX_AGE`), FFI, and the IETF publisher treating an absent MAX_AGE as unlimited (wire semantics; likely kept). -- Say what 0 would break: late joiners, fetch of a non-latest group, DVR/archive. -- Propose a default with its reason and the migration; the maintainer decides, then a follow-up implements it. +### Audit scope and overlapping work -Public API: none in this quest. Wire: none. +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. 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 choosing an authored default. No wire omission is reinterpreted in this proposal. + +### 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. + +### Proposal for the maintainer + +**Recommendation: use 30 s for newly authored raw tracks as well as media, with explicit unlimited available; preserve received absence and archive playback semantics.** This reuses the existing Rust/JS media window and leaves more than the recorder's default 10 s reorder allowance under normal cache availability. It avoids zero's loss of overlapping groups without making live viewers wait. It is a product default, not a measured optimal duration or a memory safety claim. Do not change relay transit ceilings, byte budgets, cache expiry, wire codecs, or absence semantics as part of that choice. + +Choose one authored policy: + +1. **30 s raw and media (recommended).** Omitted authoring configuration becomes finite across Rust, JS, and bindings. Snapshot/catalog producers may explicitly choose zero because their latest group bootstraps a join; retain explicit longer application policies where needed. This bounds accidental readable history but changes consumers that relied on unlimited raw history. +2. **0 raw, keep 30 s media.** Cheapest ordinary historical delivery for raw snapshots/live data, but append logs, catch-up, warmup, and past-fetch users must opt in. Zero still does not imply immediate payload reclamation. This requires a broader consumer audit before implementation. +3. **Keep raw unlimited; finite media only (today).** No migration, but accidentally unbounded publisher freshness remains. The 30 s idle cache does not replace an authored age policy. + +The scope choice is also the maintainer's: preserve relay `duration` unset as no ceiling (**recommended**), or default it to 30 s too. A finite relay ceiling limits long-DVR/archive delivery regardless of an explicit unlimited publisher; it needs a clear operator opt-out and a deliberate product decision. It cannot be smuggled in as parity with the existing 30 s idle LRU. + +### Migration and implementation boundaries, if approved + +- Separate an omitted *authoring* option from explicit unlimited and from absent *received metadata*. Rust `None` and FFI null already mean unlimited; preserve that meaning. Rust authored defaults would become `Some(30 s)`, while conversions must preserve explicit `None` instead of conditionally inheriting a changed default. C's absent presence flag needs the same deliberate treatment. +- JS currently conflates omitted authoring fields with absent decoded metadata in `infoDefaults`, and has no publisher-null unlimited value. A possible authoring shape is omitted/undefined = 30 s, `null` = unlimited, finite milliseconds = that policy; decoded `Info` must still preserve wire absence. This public API shape needs maintainer approval. Prefer applying defaults at producer construction, with nullable authoring options that preserve decoded metadata. An alternative is an explicit default/unlimited/finite retention type across authoring APIs, at the cost of a new surface in every binding. Do not change `infoDefaults` globally and silently give incoming tracks 30 s. +- UniFFI generated constructor defaults and hand-written Python, Swift, Kotlin, Go, Dart, C, and C++ wrappers must consistently distinguish omission and explicit unlimited. In particular, the current UniFFI `if let Some` and C `if max_age_present` conversions would inherit a changed Rust default for explicit unlimited. Fix those conversions in the implementation, rather than advertising an escape hatch that fails. +- Existing media stays at 30 s. Rust mux `with_max_age(None)` and JS hang's omitted helper option currently mean inherit, so an unlimited-media option needs a deliberate API decision, not a new interpretation of those calls without migration. Preserve explicit archive `.with_max_age(None)`, catalog/snapshot usability, and application-specific 5 s/one-day policies unless their consumers justify a change. +- Raw publishers relying on more than 30 s must explicitly request a longer window or unlimited at construction; do this before publishing a new track/broadcast identity. Readers asking for history must also set a sufficient max-delay and ranges. Configure relay ceilings and cache capacity/expiry for the intended service; disabling publisher age alone is insufficient. +- The implementation is a behavioral/API change: identify released affected surfaces, mark a breaking PR title with `!` where applicable, describe migration in its Impact, update Rust/JS/bindings and user docs together, and leave release-owned `MIGRATE.md` sections to the release cut. Wire values/absence remain unchanged; only authored advertisements differ. Any separately chosen wire change needs its matching draft updated. +- Verify authored omission versus explicit unlimited, decoded absence, timed/untimed supersession, a late join to an unchanged latest snapshot, direct old-group fetch, media segment fetch, and archive replay across the chosen window. Use mocked time and existing test harnesses; run selected checks and all-language interop for the implementation's API/FFI/wire scope. Re-check overlapping PRs rather than duplicating their fixes. + +Remaining work: the maintainer chooses authored policy, relay-ceiling scope, and the authoring API boundary/unlimited representation; then `/quest-plan` records the implementation. This draft is a research checkpoint, not approval to implement or merge. From d94ad2c5ea0aec7c1bdde5c5f693db7332fbab83 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sun, 1 Nov 2026 10:17:50 -0800 Subject: [PATCH 3/3] docs(quest): record the 30 s authored max-age decisions The maintainer accepted the audit's three proposals on 2026-11-01: 30 s for raw and media authored retention, no change to the relay's unset ceiling, and defaults applied at construction with explicit unlimited. Rewrite the quest into the implementation that remains. Co-Authored-By: Claude Opus 5.5 --- quest/m1/README.md | 2 +- quest/m1/max-age-defaults.md | 46 +++++++++++++++++++----------------- 2 files changed, 25 insertions(+), 23 deletions(-) diff --git a/quest/m1/README.md b/quest/m1/README.md index dfde045a690..cedf21c48b4 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -170,7 +170,7 @@ removed). - [Legacy lite close drain](/quest/m1/lite-legacy-close-drain.md) - a lite-01..06 graceful close never cuts a final group the subscriber has not read - [JS join tests cover draft 20](/quest/m1/join-tests-draft20.md) - join.test.ts runs on every supported draft, not just 18 and 22 - [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 -- [Audit retention defaults](/quest/m1/max-age-defaults.md) - every max-age default listed, with a proposed finite default for the maintainer +- [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 - [JS ordered reads wait only on owed groups](/quest/m1/js-ordered-owed.md) - @moq/net matches Rust's owed-group wait - [Binding announcements always carry captures](/quest/m1/ffi-required-captures.md) - moq-ffi and its generated bindings make `captures` a required list, as #7266 always sets it - [HLS export follows a resolution change](/quest/m1/hls-reinit-same-codec.md) - a decoder-identity change under the same codec string starts a new init and segment tag diff --git a/quest/m1/max-age-defaults.md b/quest/m1/max-age-defaults.md index 8f5df0a799b..091579dfa29 100644 --- a/quest/m1/max-age-defaults.md +++ b/quest/m1/max-age-defaults.md @@ -1,12 +1,18 @@ -# [S] Audit retention defaults and propose a finite max-age +# [L] Authored tracks default to a 30 s max-age, with explicit unlimited ## Goal -The audit is recorded below. The remaining outcome is the maintainer's choice of retention defaults and an implementation quest through `/quest-plan`. No runtime defaults, public API, or wire semantics change in this checkpoint. +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 recommendations below are proposals, not maintainer decisions. +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 @@ -56,7 +62,7 @@ Cache capacity is a converging target, not a hard memory limit. Live edges remai - 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 choosing an authored default. No wire omission is reinterpreted in this proposal. +- 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 @@ -68,26 +74,22 @@ HLS/DASH needs past media for listed segments and players starting several targe 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. -### Proposal for the maintainer - -**Recommendation: use 30 s for newly authored raw tracks as well as media, with explicit unlimited available; preserve received absence and archive playback semantics.** This reuses the existing Rust/JS media window and leaves more than the recorder's default 10 s reorder allowance under normal cache availability. It avoids zero's loss of overlapping groups without making live viewers wait. It is a product default, not a measured optimal duration or a memory safety claim. Do not change relay transit ceilings, byte budgets, cache expiry, wire codecs, or absence semantics as part of that choice. - -Choose one authored policy: +### Implementation -1. **30 s raw and media (recommended).** Omitted authoring configuration becomes finite across Rust, JS, and bindings. Snapshot/catalog producers may explicitly choose zero because their latest group bootstraps a join; retain explicit longer application policies where needed. This bounds accidental readable history but changes consumers that relied on unlimited raw history. -2. **0 raw, keep 30 s media.** Cheapest ordinary historical delivery for raw snapshots/live data, but append logs, catch-up, warmup, and past-fetch users must opt in. Zero still does not imply immediate payload reclamation. This requires a broader consumer audit before implementation. -3. **Keep raw unlimited; finite media only (today).** No migration, but accidentally unbounded publisher freshness remains. The 30 s idle cache does not replace an authored age policy. +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. -The scope choice is also the maintainer's: preserve relay `duration` unset as no ceiling (**recommended**), or default it to 30 s too. A finite relay ceiling limits long-DVR/archive delivery regardless of an explicit unlimited publisher; it needs a clear operator opt-out and a deliberate product decision. It cannot be smuggled in as parity with the existing 30 s idle LRU. +- **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 [Subscriptions take a Delay](/quest/m1/subscription-delay.md) sets for max-delay. 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. -### Migration and implementation boundaries, if approved +Public API: breaking in Rust, JS, and every binding (the authored default, and mux `with_max_age(None)`). Wire: none; only authored advertisements change. -- Separate an omitted *authoring* option from explicit unlimited and from absent *received metadata*. Rust `None` and FFI null already mean unlimited; preserve that meaning. Rust authored defaults would become `Some(30 s)`, while conversions must preserve explicit `None` instead of conditionally inheriting a changed default. C's absent presence flag needs the same deliberate treatment. -- JS currently conflates omitted authoring fields with absent decoded metadata in `infoDefaults`, and has no publisher-null unlimited value. A possible authoring shape is omitted/undefined = 30 s, `null` = unlimited, finite milliseconds = that policy; decoded `Info` must still preserve wire absence. This public API shape needs maintainer approval. Prefer applying defaults at producer construction, with nullable authoring options that preserve decoded metadata. An alternative is an explicit default/unlimited/finite retention type across authoring APIs, at the cost of a new surface in every binding. Do not change `infoDefaults` globally and silently give incoming tracks 30 s. -- UniFFI generated constructor defaults and hand-written Python, Swift, Kotlin, Go, Dart, C, and C++ wrappers must consistently distinguish omission and explicit unlimited. In particular, the current UniFFI `if let Some` and C `if max_age_present` conversions would inherit a changed Rust default for explicit unlimited. Fix those conversions in the implementation, rather than advertising an escape hatch that fails. -- Existing media stays at 30 s. Rust mux `with_max_age(None)` and JS hang's omitted helper option currently mean inherit, so an unlimited-media option needs a deliberate API decision, not a new interpretation of those calls without migration. Preserve explicit archive `.with_max_age(None)`, catalog/snapshot usability, and application-specific 5 s/one-day policies unless their consumers justify a change. -- Raw publishers relying on more than 30 s must explicitly request a longer window or unlimited at construction; do this before publishing a new track/broadcast identity. Readers asking for history must also set a sufficient max-delay and ranges. Configure relay ceilings and cache capacity/expiry for the intended service; disabling publisher age alone is insufficient. -- The implementation is a behavioral/API change: identify released affected surfaces, mark a breaking PR title with `!` where applicable, describe migration in its Impact, update Rust/JS/bindings and user docs together, and leave release-owned `MIGRATE.md` sections to the release cut. Wire values/absence remain unchanged; only authored advertisements differ. Any separately chosen wire change needs its matching draft updated. -- Verify authored omission versus explicit unlimited, decoded absence, timed/untimed supersession, a late join to an unchanged latest snapshot, direct old-group fetch, media segment fetch, and archive replay across the chosen window. Use mocked time and existing test harnesses; run selected checks and all-language interop for the implementation's API/FFI/wire scope. Re-check overlapping PRs rather than duplicating their fixes. +## Related -Remaining work: the maintainer chooses authored policy, relay-ceiling scope, and the authoring API boundary/unlimited representation; then `/quest-plan` records the implementation. This draft is a research checkpoint, not approval to implement or merge. +- [Subscriptions take a Delay](/quest/m1/subscription-delay.md) - the max-delay binding defaults and explicit-unlimited flags this quest's bindings mirror