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 254eb4639f4..fe566282855 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 @@ -77,10 +79,11 @@ QUIC studies there on that rule. - [Shared import clock](/quest/m1/shared-clock.md) - an importer joining a clock already in use offsets its PTS instead of moving it, so captures and imports share one timeline - [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/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 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 a81f28b84af..d4d066fdd0a 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 e50b4965223..113272ae4c9 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