From 004ace4f01ddcbc1f36b726ba1e37add2a406f03 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 5 Oct 2026 10:36:32 -0700 Subject: [PATCH 1/2] quest: plan typed timedness, an IETF rejoin, capture and refusal follow-ups Records the 2026-10-05 /quest-plan decisions: timedness is per track, a mock-up lands before #4822 adapts, an IETF rejoin loses its open group, a spent capture budget reports its error, refusal reasons split expired from invalid tokens, and unannounce-demand-release gates the release. Co-Authored-By: Claude Opus 5.5 --- quest/m0/broadcast-epoch/README.md | 4 ++ quest/m1/README.md | 7 +++- quest/m1/capture-exhausted-error.md | 16 ++++++++ quest/m1/ietf-rejoin-open-group.md | 25 ++++++++++++ quest/m1/ietf-timestamp-units.md | 4 ++ quest/m1/js-untimed-model.md | 36 ++++++++++------- quest/m1/lite-untimed.md | 14 +++++-- quest/m1/plan-ts-pes-untimed.md | 7 +++- quest/m1/publish-timestamp.md | 7 +++- quest/m1/subscribe-live-time.md | 4 +- quest/m1/typed-timedness.md | 50 +++++++++++++++++++++++ quest/m1/untimed-failover.md | 14 ++++--- quest/m1/untimed-model.md | 62 +++++++++++++++++------------ quest/m2/README.md | 1 + quest/m2/refusal-reasons.md | 28 +++++++++++++ quest/m2/watch-data-sync.md | 8 ++-- 16 files changed, 226 insertions(+), 61 deletions(-) create mode 100644 quest/m1/capture-exhausted-error.md create mode 100644 quest/m1/ietf-rejoin-open-group.md create mode 100644 quest/m1/typed-timedness.md create mode 100644 quest/m2/refusal-reasons.md diff --git a/quest/m0/broadcast-epoch/README.md b/quest/m0/broadcast-epoch/README.md index 1b8bb4567f9..9aba1577073 100644 --- a/quest/m0/broadcast-epoch/README.md +++ b/quest/m0/broadcast-epoch/README.md @@ -55,6 +55,9 @@ Decided: [Stats epochs](/quest/m1/stats-epoch.md), which also gates the release (decided 2026-10-04): a restarted stats node under a reused name stalls its viewers the same way. +- [Retracted demand release](/quest/m1/unannounce-demand-release.md) also + gates the release (decided 2026-10-05): a regression from #4741 on main that + `release` lacks. - Derived output mirrors the epoch it came from (`.pro/transcode//foo.hang/@e`, per the [wildcard](/quest/m0/wildcard/README.md) line's derived-output layout), so @@ -80,3 +83,4 @@ This README owns: - [GStreamer and OBS](/quest/m0/broadcast-epoch/gst-obs.md) - moqsink and the OBS plugin publish each run under a fresh epoch - [Remove `--hop`](/quest/m0/broadcast-epoch/hop-removal.md) - `moq` takes an optional `--epoch` instead of `--hop`, a plain publisher declares a random Hop ID, and the per-session hop stamp and NO_CAPACITY are gone - [Stats epochs](/quest/m1/stats-epoch.md) - moq-stats publishes each node under its own epoch, so a restarted node never stalls its viewers +- [Retracted demand release](/quest/m1/unannounce-demand-release.md) - a retracted broadcast's track demand is released when its last subscriber leaves, as before #4741 diff --git a/quest/m1/README.md b/quest/m1/README.md index fef5e2a0e84..2b45456149c 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -50,12 +50,14 @@ QUIC studies there on that rule. - [DTX timestamps](/quest/m1/opus-dtx-timestamps.md) - Opus DTX keeps the capture timeline, so voice enables it by default again - [LIFO cleanups](/quest/m1/signals-lifo.md) - signals effects clean up last-in, first-out, so nested teardown runs first - [Still screen share](/quest/m1/capture-still-frame.md) - video capture keeps its latest frame and replays it, re-stamped, to late subscribers +- [Spent capture budget errors](/quest/m1/capture-exhausted-error.md) - a camera or microphone that runs out of retries sets `out.error` instead of failing silently - [SUBSCRIBE_DROP](/quest/m1/subscribe-drop.md) - every stream group in a lite subscription arrives or is dropped by name, and lite-07 drops its stream count for it - [Subscribe ranges](/quest/m1/subscribe-ranges/README.md) - a lite-07 SUBSCRIBE asks for past and live ranges in either order and replaces FETCH; relays fill misses by range, including over moq-transport - [Live media time](/quest/m1/subscribe-live-time.md) - a lite-07 SUBSCRIBE_OK carries the publisher's current media time, so readers judge a cache against the live edge - [Cross-relay bursts](/quest/m1/cross-relay-bursts.md) - bursty small-group tracks cross two relays without lost groups, unanswered FETCHes, or stalls - [Fetched heads stay visible](/quest/m1/lite07-head-fetch-arrival.md) - on lite-07, a relay fetching the head of a group it receives mid-group still delivers that group to new subscribers - [Late lower groups](/quest/m1/lite-late-lower-group.md) - a moq-lite subscriber with a floor receives a group created below the first served one, as moq-transport does +- [IETF rejoin keeps the open group](/quest/m1/ietf-rejoin-open-group.md) - on moq-transport-19/22, a reader that rejoins mid-group still receives the open group's later frames - [JS cache window](/quest/m1/js-prune-cache-window.md) - js/net ages idle groups on a cache window and keeps max_age as media-time staleness, as Rust does - [JSON stream budget](/quest/m1/json-stream-budget.md) - an oversized JSON stream record is refused without ending the log, and a JS subscribe to a gone track answers NotFound - [A watch and publish release ships assets()](/quest/m1/assets-release.md) - the release that lets the sites host the worklets @@ -74,10 +76,11 @@ QUIC studies there on that rule. - [Ship capture and playback](/quest/m1/cli-packaging.md) - a released moq binary can capture and play, which no distribution currently enables - [Publishing never invents a timestamp](/quest/m1/publish-timestamp.md) - no Rust or binding publish API fills in a timestamp; an untimed payload goes out untimed - [JS publishing never invents a timestamp](/quest/m1/js-publish-timestamp.md) - the same in @moq/json, @moq/flate, and @moq/net -- [Untimed model](/quest/m1/untimed-model.md) - moq-net frames and datagrams carry an absent timestamp to every subscriber; no receiver fills in arrival time +- [Typed timedness](/quest/m1/typed-timedness.md) - a track is all timed or all untimed, `Info.timescale` is optional, and `Timed` loses its clock parameter, in Rust, JS, and the bindings +- [Untimed model](/quest/m1/untimed-model.md) - an untimed moq-net track reaches every subscriber untimed; no receiver fills in arrival time - [Untimed failover](/quest/m1/untimed-failover.md) - a resumed group no route continues is given up even when media time can't judge its drift - [JS untimed model](/quest/m1/js-untimed-model.md) - the same in @moq/net -- [Untimed lite-07](/quest/m1/lite-untimed.md) - lite-07 encodes an absent timestamp in both languages; lite-05/06 write send time +- [Untimed lite-07](/quest/m1/lite-untimed.md) - lite-07 carries an untimed track in both languages; lite-05/06 write send time - [Plan: untimed verbatim PES](/quest/m1/plan-ts-pes-untimed.md) - decide how a verbatim TS track carries a PES that has no PTS, then write the implementation quest - [Data consumer timestamps](/quest/m1/data-consumer-timestamps.md) - json and binary consumers return each value's timestamp, in Rust and every binding; snapshots add `latest()` beside an in-order `next()` - [JS data consumer timestamps](/quest/m1/js-data-consumer-timestamps.md) - @moq/json and @moq/flate consumers return each value's timestamp, with snapshot `next()` and `latest()` diff --git a/quest/m1/capture-exhausted-error.md b/quest/m1/capture-exhausted-error.md new file mode 100644 index 00000000000..ce056416ac0 --- /dev/null +++ b/quest/m1/capture-exhausted-error.md @@ -0,0 +1,16 @@ +# [XS] A spent capture retry budget reports its error + +## Goal + +When an ended camera or microphone track uses up the `Retry` budget in +js/publish (`js/publish/src/source/{camera,microphone,retry}.ts`), `out.error` +is set to the last error instead of the capture failing silently. A +regression test covers it. + +## Plan + +An open failure that spends the budget already sets `out.error`. A track that +ends calls `Retry.failed()` from its `ended` handler, and nothing reports it +when that was the last attempt. The gap predates #4827. + +Public API: none. Wire: none. diff --git a/quest/m1/ietf-rejoin-open-group.md b/quest/m1/ietf-rejoin-open-group.md new file mode 100644 index 00000000000..3ef18f8a11b --- /dev/null +++ b/quest/m1/ietf-rejoin-open-group.md @@ -0,0 +1,25 @@ +# [S] A rejoined IETF reader keeps its open group + +## Goal + +On moq-transport-19 and 22, a client that leaves a track and rejoins while a +group is still open keeps receiving that group's later frames. Today the +rejoined client's open group ends with `Ok(None)` before the next frame. + +## Plan + +Repro: in `rejoin_mid_group_keeps_the_head_for_later_readers` +(`rs/moq-net/tests/rejoin.rs`, from #4828), write a frame `a1` to the open +group after the later relay reader's head check, and assert the rejoined +reader gets `a1`. It passes on every lite version and fails on IETF 19 and +22. A first subscription on IETF does receive the later frames, so the loss +is specific to the rejoin. + +When fixed, keep the later-frame assertion in that test for every version. + +Public API: none. Wire: none. + +## Related + +- [Fetched heads stay visible](/quest/m1/lite07-head-fetch-arrival.md) - another mid-group join that loses part of a group +- [Rejoin after the copy goes idle](/quest/m1/test-flakes-2/rejoin-idle-race.md) - a different IETF rejoin bug, serving a stale cache diff --git a/quest/m1/ietf-timestamp-units.md b/quest/m1/ietf-timestamp-units.md index cb9343378e2..da7f2119a74 100644 --- a/quest/m1/ietf-timestamp-units.md +++ b/quest/m1/ietf-timestamp-units.md @@ -16,6 +16,10 @@ drafts 14-16 carry timestamps without units. The Rust subscriber ignores them. Gate the Timestamp property on a timescale actually sent. Check js/net's `stamped` flag (`js/net/src/ietf/publisher.ts`) for the same gap. +Confirmed 2026-10-05 by [Typed timedness](/quest/m1/typed-timedness.md): +tracks on drafts 14-16 are untimed, so sending none there is the plan, not +an object-scope TIMESCALE beside each Timestamp. + Before landing, check whether an interop peer on draft-14 reads the Timestamp property without TIMESCALE. If one does, ask whether to keep it. diff --git a/quest/m1/js-untimed-model.md b/quest/m1/js-untimed-model.md index 15e25b840d4..1bcd975f4a6 100644 --- a/quest/m1/js-untimed-model.md +++ b/quest/m1/js-untimed-model.md @@ -3,9 +3,9 @@ ## Goal `@moq/net` mirrors [moq-net carries untimed frames -faithfully](/quest/m1/untimed-model.md). A frame or datagram without a -timestamp stays untimed from publisher to consumer, and js/net never fills in -`Timestamp.now()` on receive. Covers `@moq/net` and its in-repo callers +faithfully](/quest/m1/untimed-model.md). An untimed track stays untimed from +publisher to consumer, and js/net never fills in `Timestamp.now()` on +receive. Covers `@moq/net` and its in-repo callers (`@moq/hang`, `@moq/loc`, `@moq/watch`). ## Plan @@ -16,6 +16,10 @@ long-running and would stall the JS timestamp quests. Whichever lands second absorbs the other. The semantics, the end-marker rule and the reasons are in the Rust quest; keep the two in step. +Decided (2026-10-05): timedness is per track, in the shape [Typed +timedness](/quest/m1/typed-timedness.md) mirrors into `@moq/net`. Where the +notes below assume a per-frame optional timestamp, that shape wins. + Things to look out for: - Receive-side fills: lite frames on a track with no timescale, and IETF @@ -25,22 +29,24 @@ Things to look out for: that an untimed track starts at the latest group. - A track's `Info.timescale` is required today, with a default. Like Rust, a track that never declared one must not claim a timeline downstream. -- A FETCH keeps timestamps whenever the track or the object gives units. - Only objects with neither are untimed. -- On drafts 14-16, where SUBSCRIBE_OK can't carry TIMESCALE, the publisher - writes an object-scope TIMESCALE beside each Timestamp (the `stamped` path - in `js/net/src/ietf/publisher.ts`), as Rust does once #4822 lands. This - replaces the JS half of [IETF timestamp - units](/quest/m1/ietf-timestamp-units.md), which planned to send none there. -- `Frame.timestamp` and `Datagram.timestamp` become optional. Update callers - in js/hang and js/loc (end markers) and anything in js/watch that reads - them. +- A FETCH is timed only when it learns the track's units when accepted. +- Tracks on drafts 14-16, where SUBSCRIBE_OK can't carry TIMESCALE, are + untimed (decided 2026-10-05), so the publisher sends no Timestamp there, as + [IETF timestamp units](/quest/m1/ietf-timestamp-units.md) plans. This + replaces the earlier plan to write an object-scope TIMESCALE beside each + Timestamp. +- Update callers in js/hang and js/loc (end markers) and anything in + js/watch that reads frame timestamps. Test: an untimed frame survives a JS subscribe on each receive path. Run `just test interop --all`. -Public API: breaking. Wire: on drafts 14-16, timed objects gain an -object-scope TIMESCALE beside the Timestamp; nothing else changes. +Public API: breaking. Wire: none beyond what IETF timestamp units +changes. + +## Required + +- [Typed timedness](/quest/m1/typed-timedness.md) - the per-track types this mirrors ## Related diff --git a/quest/m1/lite-untimed.md b/quest/m1/lite-untimed.md index b97f81ff8c3..c5b6b50cd3e 100644 --- a/quest/m1/lite-untimed.md +++ b/quest/m1/lite-untimed.md @@ -1,14 +1,22 @@ -# [S] lite-07 encodes an absent timestamp +# [S] lite-07 carries an untimed track ## Goal -On moq-lite-07, an untimed frame or datagram crosses the wire as untimed in -both Rust and JS, so absence survives a lite relay hop. lite-05 and lite-06 +On moq-lite-07, an untimed track's frames and datagrams cross the wire as +untimed in both Rust and JS, so absence survives a lite relay hop. lite-05 and lite-06 keep writing the encoder's send time, documented as a downgrade for old peers. Covers `rs/moq-net`, `js/net` and `drafts/draft-lcurley-moq-lite.md`. ## Plan +Decided (2026-10-05, maintainer): timedness is per track ([Typed +timedness](/quest/m1/typed-timedness.md)), and an untimed track sends no +TIMESCALE and no Timestamp. On lite-07 that likely means an optional +Timescale in TRACK_INFO and no Timestamp fields on an untimed track. The +per-frame shift below was planned for an absent timestamp inside a timed +track, which no longer exists, so re-plan the encoding once Typed timedness +settles the shape, and drop the shift if nothing needs it. + Decided (2026-10-01, maintainer): shift the FRAME Timestamp Delta and the DATAGRAM Timestamp by one, so 0 means absent. An absent frame doesn't move the delta baseline. Rejected: a bare 0 as a sentinel, which collides with a diff --git a/quest/m1/plan-ts-pes-untimed.md b/quest/m1/plan-ts-pes-untimed.md index 19e7079d02c..f6970547edd 100644 --- a/quest/m1/plan-ts-pes-untimed.md +++ b/quest/m1/plan-ts-pes-untimed.md @@ -15,7 +15,12 @@ Both are invented times, which [moq-net carries untimed frames faithfully](/quest/m1/untimed-model.md) rules out for moq-net itself. -Making the moq-net timestamp optional isn't enough on its own. Verbatim +Timedness is per track since 2026-10-05 ([Typed +timedness](/quest/m1/typed-timedness.md)): a timed track refuses an untimed +frame, so a PES without a PTS can only go out untimed on an untimed track. +Weigh that in the carriage decision. + +An untimed track isn't enough on its own. Verbatim tracks use the legacy container, whose payload always starts with a timestamp, and its decoder reads the time from there, not from the frame. So the decision covers: diff --git a/quest/m1/publish-timestamp.md b/quest/m1/publish-timestamp.md index c272d8daa05..1abd76da66f 100644 --- a/quest/m1/publish-timestamp.md +++ b/quest/m1/publish-timestamp.md @@ -24,8 +24,11 @@ fill `Timestamp::now()` (moq-net's clock, not the broadcast's), and moq-mux's data producers fill the broadcast clock's `now()`. The FFI raw `MoqFrame.timestamp_us` and `MoqDatagram.timestamp_us` default to 0. -- `moq_net::Timed` keeps its name and its `at: Option`; only the - meaning of `None` changes. The json/flate consumers return the same type +- `moq_net::Timed` takes the shape [Typed + timedness](/quest/m1/typed-timedness.md) settles, without its clock + parameter `T`. Timedness is per track there (decided 2026-10-05), so an + untimed payload belongs on an untimed track, and one appended to a timed + track is refused. The json/flate consumers return the same type (see [Data consumer timestamps](/quest/m1/data-consumer-timestamps.md)). - moq-json (snapshot, stream, and window, whose `push` always stamps now) and moq-flate producers take `Timed<_, Timestamp>` and write `None` as untimed. diff --git a/quest/m1/subscribe-live-time.md b/quest/m1/subscribe-live-time.md index 3068133a146..a330fdfb62f 100644 --- a/quest/m1/subscribe-live-time.md +++ b/quest/m1/subscribe-live-time.md @@ -33,8 +33,8 @@ Decided in planning (2026-10-03): every hop adds shows up honestly. - **Optional on the wire.** An untimed track (see [Untimed lite-07](/quest/m1/lite-untimed.md)) has no media time, so the field - is absent, encoded the same way as an absent frame timestamp. A track whose - frames are all untimed never reports one, and no receiver invents one. + is absent, as its frame timestamps are. An untimed track never reports one, + and no receiver invents one. - **lite-07 only.** It is still WIP (`moq-lite-07-wip`), so the field is added without negotiation. Older versions keep the gap rule. - **API: `track::Subscriber::live().await`** resolves once the route answered, to diff --git a/quest/m1/typed-timedness.md b/quest/m1/typed-timedness.md new file mode 100644 index 00000000000..0750323fc5f --- /dev/null +++ b/quest/m1/typed-timedness.md @@ -0,0 +1,50 @@ +# [S] A track is all timed or all untimed + +## Goal + +Prototype moq-net types that make a track all-timed or all-untimed, for +example `track::Timed` and `track::Untimed`, and settle the shape that +[#4822](https://github.com/moq-dev/moq/pull/4822) adapts to. + +- `track::Info.timescale` becomes an `Option`, where `None` means untimed: no + TIMESCALE and no Timestamp on the wire, and no receiver-made local stamps. +- Appending a frame whose timedness doesn't match its track is refused, as + `Error::TimestampMismatch` already refuses a mismatched timescale. +- `moq_net::Timed` (`rs/moq-net/src/model/timed.rs`) folds into this shape, + dropping its unused clock parameter `T`. That's a breaking change and gets + an upgrade note. + +Mirror the shape in `@moq/net` and the bindings. + +## Plan + +Decided (2026-10-05, maintainer): + +- Timedness is a track property. Rejected: `Option` on every frame + and groups that mix timed and untimed frames ("Option is just really + annoying as an API and revolves into a lot of unwrap()"), and a frame type + generic over its timestamp (`Frame`). +- Rejected: receiver-made arrival stamps on untimed tracks. +- A receiver learns the property when it accepts the track. Drafts and + versions that can't declare it up front are untimed: IETF drafts 14-16, a + standalone FETCH that learns no timescale, and lite-01 to lite-04. +- Mock-up first, then #4822 adapts, so contributors and callers take one + breaking change instead of two. Folding `Timed`'s `T` in here, rather than + a separate quest, keeps that to one break too. + +Look out for: + +- Where an untimed track's frames still need ordering or "has a frame" + answers (group start, expiry, the live edge), without a timestamp to read. +- What a receiver does with timing that arrives on a track it accepted as + untimed, such as an IETF object-scope TIMESCALE and Timestamp (imquic + publishes this way). Refusing would break peers that play today. +- lite-05 and lite-06 always send a Timescale, so an untimed track goes out + there as timed, with the encoder's send time, as + [Untimed model](/quest/m1/untimed-model.md) decided. +- Callers built on `Timed`: [Publishing never invents a + timestamp](/quest/m1/publish-timestamp.md), its JS mirror, and the data + consumer quests. + +Public API: breaking (`track::Info.timescale`, `Timed`). Wire: none until +the untimed quests use it. diff --git a/quest/m1/untimed-failover.md b/quest/m1/untimed-failover.md index af55674f5a5..9e3abca8f04 100644 --- a/quest/m1/untimed-failover.md +++ b/quest/m1/untimed-failover.md @@ -25,20 +25,24 @@ Decided 2026-10-05 11:39 +0200: right after it. - The rule: when drift can't be measured (no timed live edge, or the successor is untimed), give up once the serving copy holds a newer group - and no route or recovery fetch can still fill this one. This applies to - mixed tracks too, so there is one rule. No clock is involved. + and no route or recovery fetch can still fill this one. No clock is + involved. Rejected: a wall-clock deadline of `max_age` after the stall, which stands wall time in for media time, the substitution the untimed model removed. Also rejected: leaving it and documenting it. +Since 2026-10-05 timedness is per track ([Typed +timedness](/quest/m1/typed-timedness.md)), so no track mixes timed and +untimed groups. The rule applies to untimed tracks and to a timed track whose +drift can't be measured yet. + Settle what "nothing pending" means against the recovery fetch (`a_pending_recovery_fetch_does_not_disable_expiry`), so a fetch about to fill the group isn't cut short. A FETCH reader has no budget and stays as it is. -Test: a model test in `resume.rs` failing over an all-untimed track with an -abandoned group, plus one where the successor is untimed on a timed track. -Both fail without the fix. Run each against a cold route and against one +Test: a model test in `resume.rs` failing over an untimed track with an +abandoned group. It fails without the fix. Run it against a cold route and against one whose copy already caches untimed groups past the resumed one, so a cursor that skips ahead can't hide the stall. #4822 is changing `Cursor::new` so an explicit start is honoured on untimed tracks; build on that, not on the diff --git a/quest/m1/untimed-model.md b/quest/m1/untimed-model.md index bb043c6831a..4875d9e34fd 100644 --- a/quest/m1/untimed-model.md +++ b/quest/m1/untimed-model.md @@ -2,11 +2,12 @@ ## Goal -A frame or datagram published without a timestamp reaches every subscriber -without one, through any number of relays. moq-net's model carries -`Option`. No receiver fills in arrival time, and a relay forwards -absence as absence. IETF objects on a track without TIMESCALE or without a -Timestamp property, and lite-01 to lite-04 frames, arrive untimed. Covers +A track published untimed reaches every subscriber untimed, through any +number of relays, in the per-track shape [Typed +timedness](/quest/m1/typed-timedness.md) settles. No receiver fills in +arrival time, and a relay forwards an untimed track as untimed. IETF tracks +accepted without TIMESCALE, every track on drafts 14-16, a standalone FETCH +that learns no units, and lite-01 to lite-04 tracks arrive untimed. Covers moq-net, moq-relay, every in-repo caller of the model, and `drafts/draft-lcurley-moq-timestamp.md`. @@ -18,6 +19,15 @@ timestamp](/quest/m1/lite-untimed.md)), and JS ## Plan +Decided (2026-10-05, maintainer): timedness is per track, not per frame. +[#4822](https://github.com/moq-dev/moq/pull/4822) waits on [Typed +timedness](/quest/m1/typed-timedness.md), whose mock-up settles the types, +and then adapts to it, so contributors and callers take one breaking change +instead of two. The track's property is learned when it is accepted, so the +per-frame `Option`, groups that mix timed and untimed frames, and +object-scope timing on an untimed track are out. Notes below that assume +them are superseded where they disagree. + Decided (2026-10-01, maintainer): faithful absence on both the publish and the subscribe side. Today every receiver stamps local arrival time, as the timestamp draft mandates, and on lite-05 and later a relay forwards those @@ -30,10 +40,10 @@ content out, and the pool's wall-clock expiry is the bound). Decided (2026-10-02, planning this split): -- An IETF object that carries its own TIMESCALE and Timestamp properties is - timed, even when the track sent no TIMESCALE. The draft already allows an - object-scope TIMESCALE. Reading it is faithful, not invented. imquic's LOC - examples publish this way. +- Superseded 2026-10-05: an IETF object carrying its own TIMESCALE and + Timestamp no longer makes it timed on a track accepted without TIMESCALE; + the track decides. imquic's LOC examples publish this way, so they arrive + untimed. - A legacy or LOC end marker (an empty frame) that arrives untimed is ignored. The group then ends without a precise end bound. Its frames still play from their payload timestamps, and only the last frame's duration is @@ -61,33 +71,29 @@ Things to look out for: - The live edge skips unstamped groups. Reach and successor search (`track.rs`) deliberately stop at the immediate successor and leave the bound unknown while it is unstamped, because skipping ahead - could expire content that is still valid. An untimed successor keeps that - bound unknown for good, so the timed group before it is kept. Preserve - that, and check that an untimed track neither stalls a cursor nor replays - everything. Cover tracks that mix timed and untimed groups. + could expire content that is still valid. Preserve that, and check that an + untimed track neither stalls a cursor nor replays everything. - `track::Info.timescale` always has a value today. A relay subscribed to an IETF track without TIMESCALE currently announces one downstream. It must - not claim a timeline the source never had. + not claim a timeline the source never had. Typed timedness makes it an + `Option`. - Model docs that recommend `Timestamp::now` for untimed data (`model/{frame,group,track,subscription}.rs`) change with the type. - In-repo callers follow the type change: - moq-mux container consumers and end markers; - moq-e2ee; - libmoq; - - moq-ffi's frame and datagram records, whose `timestamp_us` becomes - optional; + - moq-ffi's frame and datagram records and track info; - the binding wrappers. Media consumers that need a time refuse an untimed frame, except for the end-marker rule above. -- Only objects with neither track units nor object-level units are untimed. - A FETCH learns track units from SUBSCRIBE_OK (a joining or fill FETCH), - from TRACK_STATUS ([Fetch without SUBSCRIBE](/quest/m1/ietf-fetch-only.md)), - or from [FETCH_OK properties](/quest/m1/fetch-ok-properties.md), whichever - applies. Until those last two land, a standalone FETCH keeps timestamps - only on objects that carry their own units. Test that known units, from - the track or the object, still yield timestamps, alongside the untimed - cases. +- A FETCH learns track units from SUBSCRIBE_OK (a joining or fill FETCH). + A standalone FETCH that learns none when it is accepted is untimed (decided + 2026-10-05), until [FETCH_OK properties](/quest/m1/fetch-ok-properties.md) + or TRACK_STATUS ([Fetch without SUBSCRIBE](/quest/m1/ietf-fetch-only.md)) + carry them. Test that a track accepted with units still yields + timestamps, alongside the untimed cases. Interop facts (2026-10-02): @@ -108,10 +114,14 @@ forwarded as untimed. Tests: each receive path (lite before lite-05, IETF subgroup, fetch and datagram) yields an untimed frame, and a relay forwards one untimed. -Public API: breaking (`Frame`, `Datagram` and track info -timestamps become optional). Wire: no encoding change. Receive semantics on +Public API: breaking, in the shape Typed timedness settles. Wire: no +encoding change. Receive semantics on published drafts change as the timestamp draft says. +## Required + +- [Typed timedness](/quest/m1/typed-timedness.md) - settles the per-track types this adapts to + ## Related - [IETF timestamp units](/quest/m1/ietf-timestamp-units.md) - drafts 14-16 stop sending timestamps without units, which then arrive untimed diff --git a/quest/m2/README.md b/quest/m2/README.md index 736fd67ebe0..f007b515518 100644 --- a/quest/m2/README.md +++ b/quest/m2/README.md @@ -66,6 +66,7 @@ waiting on an upstream release waits in [m4](/quest/m4/README.md). reads its viewers' feedback and adapts its bitrate - [Text availability](/quest/m2/text-schema.md) - a text track publishes its own coverage index instead of copying the media timeline - [Closure counters](/quest/m2/closure-counters.md) - a departed node's return never regresses the closure counters a consumer already saw +- [Refusal reasons](/quest/m2/refusal-reasons.md) - refused-session metrics tell an expired token from an invalid one, and count gateway admissions - [Bench coverage](/quest/m2/bench-coverage.md) - Criterion targets for moq-pattern matching first, then the stats producer, moq-mux containers, the hang catalog, and moq-auth - [Signed priority](/quest/m2/signed-priority.md) - every API priority is an `i8` with 0 as the unset midpoint, and hang's built-ins sit above it - [AV1 metadata separation](/quest/m2/av1-metadata.md) - retain metadata OBUs inline while evaluating separate delivery diff --git a/quest/m2/refusal-reasons.md b/quest/m2/refusal-reasons.md new file mode 100644 index 00000000000..1b29c0cbd51 --- /dev/null +++ b/quest/m2/refusal-reasons.md @@ -0,0 +1,28 @@ +# [S] Refusal reasons tell an expired token apart + +## Goal + +`moq_relay_sessions_refused_total` (added in #4825, documented in +`doc/bin/relay/http.md`) tells an expired token from a forged or otherwise +invalid one. It also counts sessions a gateway admits through +`Cluster::admit` and `Cluster::scope`, which #4825 left uncounted. + +## Plan + +Found in #4825: `moq auth serve` (`rs/moq-auth/src/serve.rs`) writes its +refusal into the 403 body, but `moq_auth`'s client returns `Refused` without +reading it, and the server reports both cases as `InvalidToken` with a +message. Decided (2026-10-05): the auth server returns a structured refusal +reason and `moq_auth`'s client maps it, so `refused` can split. + +Decided (2026-10-05): count gateway admissions too. #4825 counted where the +relay tells the client no, so a gateway session shows in +`moq_relay_sessions_opened_total` while its refusals don't. + +Public API: `moq_auth`'s refusal error gains a reason. Wire: the auth +server's refusal body gains a structured reason; check older relays still +read it. + +## Related + +- [Expired token error](/quest/m1/auth/expired-error.md) - the session-level `Expired` a client sees diff --git a/quest/m2/watch-data-sync.md b/quest/m2/watch-data-sync.md index c63a06bf99c..99b3a2d30ff 100644 --- a/quest/m2/watch-data-sync.md +++ b/quest/m2/watch-data-sync.md @@ -17,11 +17,9 @@ releases it. - Snapshot tracks release the newest state at or before the playhead, picked from the in-order states the consumer yields; stream tracks release every record in order. -- An untimed payload adds no timestamp wait of its own. On a stream track it - still waits for the records before it, so a timed record at 11s followed by - an untimed one releases both at an 11s playhead, in order. An untimed - snapshot state applies once the states before it have. Test both - sequences. +- An untimed track's payloads add no timestamp wait; they apply in order as + they arrive. Since 2026-10-05 a track is all timed or all untimed ([Typed + timedness](/quest/m1/typed-timedness.md)), so no stream mixes the two. - OneTooMany is the application this waited for (2026-10-01): their web frontend holds KLV and MAVLink telemetry back to the video playhead with its own sync code, which this replaces. In m2 rather than m1 because From 722a4945e6f36d4634f171401640f60c86ae9926 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 5 Oct 2026 10:39:56 -0700 Subject: [PATCH 2/2] quest: link typed timedness from cmaf-frame-timestamp --- quest/m1/cmaf-frame-timestamp.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/quest/m1/cmaf-frame-timestamp.md b/quest/m1/cmaf-frame-timestamp.md index d4a7957ab1a..055a92b6246 100644 --- a/quest/m1/cmaf-frame-timestamp.md +++ b/quest/m1/cmaf-frame-timestamp.md @@ -33,7 +33,9 @@ shifts `trun` data offsets. Open PR [#4826](https://github.com/moq-dev/moq/pull/4826) implements this. It lands after [#4822](https://github.com/moq-dev/moq/pull/4822) ([untimed model](/quest/m1/untimed-model.md)), which brings untimed frames to -`main` and itself waits on a typed-timedness mock-up quest. +`main` and itself waits on the [typed timedness](/quest/m1/typed-timedness.md) +mock-up. Timedness is per track there, so the decoder can check the track +rather than each frame. Test: in Rust and JS, a fragment whose `tfdt` disagrees with its frame timestamp decodes at the frame timestamp, with B-frame offsets preserved, and