diff --git a/quest/m0/3291-moq-net-zero-budget-shedding-drops-discontinuity-markers.md b/quest/m0/3291-moq-net-zero-budget-shedding-drops-discontinuity-markers.md deleted file mode 100644 index 7918bf59240..00000000000 --- a/quest/m0/3291-moq-net-zero-budget-shedding-drops-discontinuity-markers.md +++ /dev/null @@ -1,37 +0,0 @@ -# [S] moq-net: a zero-budget subscriber still receives discontinuity markers - -## Goal - -On `dev`, a live-edge subscriber (`max_age` budget of zero, the default) -still receives an empty group, so the codec reset it marks reaches the -decoder. Today `is_stale` sheds the empty group the moment a newer group -exists, the container consumer sees a plain sequence gap, `discontinuity()` -never bumps, and the decoder is fed the new epoch without a reset. - -## Plan - -A dev-only regression from the interaction of max-age shedding (#3251) with -the idle-capture markers (#3214): an empty group's reach is bounded by its -successor's start, so its age equals the successor's span and a zero budget -sheds it. With undeclared rewinds going away -([Monotonic timeline](/quest/m1/monotonic-timeline.md)), the declared marker -is the only reset signal there is, so losing it is not an option. - -Exempt a finished empty group from `is_stale`: it costs nothing to deliver -and carries the reset. The alternative, having the container layer infer a -discontinuity from any sequence gap, would fire on every ordinary shed and -reset decoders that need no reset. State the exemption in the moq-lite draft's -expiration text if the wording implies every group ages alike. - -Test: a producer emits group 1, an empty group, then group 2; a zero-budget -subscriber observes `[1, 0, 1]` at the transport layer and the container -consumer's `discontinuity()` bumps once. Fix on `dev`. - -## Closes - -- [#3291](https://github.com/moq-dev/moq/issues/3291) - close this issue when the quest finishes - -## Related - -- [Monotonic timeline](/quest/m1/monotonic-timeline.md) - makes the declared marker the only reset signal -- [#3161](/quest/m1/3161-retention-should-reclaim-idle-open-groups-now-that-expiry.md) - the other open-group lifecycle rule in the same area diff --git a/quest/m0/3326-moq-audio-held-resampler-frames-keep-their-source-timestamp.md b/quest/m0/3326-moq-audio-held-resampler-frames-keep-their-source-timestamp.md new file mode 100644 index 00000000000..b83d516478b --- /dev/null +++ b/quest/m0/3326-moq-audio-held-resampler-frames-keep-their-source-timestamp.md @@ -0,0 +1,42 @@ +# [S] moq-audio: held resampler frames keep their source timestamp + +## Goal + +`decode::Consumer` stamps resampled output where its first sample came from, +in every phase, instead of subtracting held-frame counts from the newest +packet's timestamp. A forward gap can no longer place audio up to a packet +away from where it belongs, and `Frame::activity`, keyed by the same stamp, +labels the right span. + +## Plan + +`starts_at` in `rs/moq-audio/src/decode/consumer.rs` rewinds the current +packet's `decoded_at` by `pending` input frames and `skipped` startup frames; +`Resampler` in `rs/moq-audio/src/resample.rs` exposes only counts +(`pending_frames`, `skipped`), never where the held samples came from. #3386 +mitigated the reported case on both branches: `Consumer::read` detects an +undeclared hole before decoding (`discontinuous(next, mux_frame.timestamp)`), +drains the resampler through `gap()`, and stamps the tail from the pre-gap +`tail`. Two holes remain: the gap check is skipped once `self.end` is set (the +terminal phase), and a jump inside `discontinuous()`'s slack still rewinds +across silently. + +- The resampler records the source timestamp of the oldest held input frame, + fed alongside the samples, and `starts_at` reads it; the `skipped` startup + frames rewind from that. +- Delete the derived subtraction; `pending_frames` stays for the drain + accounting. +- Regression: a 10 ms packet at 0 leaves 10 ms held, the next packet lands at + 1 s, and the output is stamped from 0 rather than near 990 ms, in the + terminal phase too, with the activity span labelled from the held packet. + Cover a jump inside the slack. +- [Duration marker](/quest/m2/duration-marker.md) removes the audio end marker + and the terminal phase; whichever lands second simplifies the other. + +## Closes + +- [#3326](https://github.com/moq-dev/moq/issues/3326) - close this issue when the quest finishes + +## Related + +- [Duration marker](/quest/m2/duration-marker.md) - removes the terminal phase this quest has to cover diff --git a/quest/m0/3359-moq-net-subscribe-error-sends-hardcoded-404.md b/quest/m0/3359-moq-net-subscribe-error-sends-hardcoded-404.md deleted file mode 100644 index de151a7ed35..00000000000 --- a/quest/m0/3359-moq-net-subscribe-error-sends-hardcoded-404.md +++ /dev/null @@ -1,38 +0,0 @@ -# [S] moq-net: SUBSCRIBE_ERROR carries a registered error code - -## Goal - -An IETF subscribe the publisher cannot serve is rejected with the error code -the negotiated draft registers for that reason, never a literal `404`, and -`Error::NotFound`'s wire value agrees with it. The moq-interop-runner's -`subscribe-error` and `subscribe-before-announce` cases pass without the -peer's compatibility branch, which is being removed upstream. - -## Plan - -Both not-found paths in `rs/moq-net/src/ietf/publisher.rs` call -`reject_subscribe(.., 404, ..)`, and `reject_subscribe` takes a bare `u64` -because SUBSCRIBE_ERROR (`0x05`) has no named code type. `TrackStatusCode` -in `ietf/track.rs` is the wrong registry (TRACK_STATUS). Separately -`Error::NotFound` maps to `13` in `rs/moq-net/src/error.rs`, so one relay -signals not-found as `404` on one path and `13` on the other. - -Add a named SUBSCRIBE_ERROR code type mapped to the registered values, and -make it version-aware in the style of the existing `Encode` / -`Decode` impls, since the registry moved between draft-14 and -draft-19. Use it at both call sites and route `Error::NotFound` through the -same mapping so the two paths agree. This is the SUBSCRIBE_ERROR half of the -per-protocol code mapping that -[#3001](/quest/m1/3001-ietf-stream-resets-send-moq-lite-error-codes-so-routine.md) -asks for on stream resets; build one table both draw from rather than two. - -Tests: the rejection code per negotiated version for a missing broadcast and -a missing track, and the interop-runner cases against a strict peer. - -## Closes - -- [#3359](https://github.com/moq-dev/moq/issues/3359) - close this issue when the quest finishes - -## Related - -- [#3001](/quest/m1/3001-ietf-stream-resets-send-moq-lite-error-codes-so-routine.md) - the stream-reset half of the same per-protocol code mapping diff --git a/quest/m0/3361-js-every-moq-package-a-package-imports-is-declared.md b/quest/m0/3361-js-every-moq-package-a-package-imports-is-declared.md new file mode 100644 index 00000000000..882929b9228 --- /dev/null +++ b/quest/m0/3361-js-every-moq-package-a-package-imports-is-declared.md @@ -0,0 +1,35 @@ +# [XS] js: every @moq package a package imports is a declared dependency + +## Goal + +No published `@moq/*` package imports another `@moq/*` package it does not +declare, and a check keeps it that way. `@moq/watch` on Firefox 140 ESR either +plays or fails with a mechanism named in #3361. + +## Plan + +`js/watch/src/broadcast.ts` imports `@moq/json` (`new +Json.Snapshot.Consumer(...)` in `#runCatalog`), but `js/watch/package.json` +does not declare it. `js/watch/vite.config.ts` externalizes every `@moq/*` +import, so the published bundle resolves it only through hoisting from +`@moq/hang`. A consumer whose resolver stubs it gets `Json.Snapshot` undefined +and exactly the reported `can't access property "Consumer", (void 0) is +undefined` inside an effect. The import predates 0.3.2, so it is not the +whole story: the only Firefox-relevant change between 0.3.2 and 0.5.2 is the +bowser user-agent gate (#2943, a new CJS runtime dependency in js/net), and +Firefox 140 takes the WebSocket path either way. + +- Declare `@moq/json` in js/watch with the workspace range, and audit the other + packages the same way. +- Add a check under `js/`, run by `just js check`, that every bare `@moq/*` + specifier under a package's `src/` appears in that package's dependencies + or peer dependencies. It fails on the current tree; fix what it finds. +- Reproduce on Firefox 140 ESR against `just relay` and `just pub bbb` with a + source map. If the undeclared dependency was the mechanism, close; otherwise + record the real stack in the issue and rescope. +- Firefox is not in the browser harness: add it to `test/wasm`'s Playwright + matrix if the harness can drive it, or record why it cannot. + +## Closes + +- [#3361](https://github.com/moq-dev/moq/issues/3361) - close this issue when the quest finishes diff --git a/quest/m0/3361-js-watch-fails-on-firefox-esr.md b/quest/m0/3361-js-watch-fails-on-firefox-esr.md deleted file mode 100644 index 8bc42e22903..00000000000 --- a/quest/m0/3361-js-watch-fails-on-firefox-esr.md +++ /dev/null @@ -1,27 +0,0 @@ -# [S] js/watch: moq-watch fails on Firefox ESR - -## Goal - -`@moq/watch` plays on Firefox 140 ESR, as 0.3.2 did. On 0.5.2 the element -dies in an effect with `TypeError: can't access property "Consumer", (void 0) -is undefined` before playing anything. - -## Plan - -`(void 0).Consumer` is a module namespace read before that module finished -evaluating, which is what an import cycle looks like under an evaluator -that handles cycles differently from Chrome, or a bundle whose output order -Firefox ESR's module loader resolves differently. It can also be a WebCodecs -or WebTransport feature the ESR line lacks, surfacing as an undefined -namespace after a failed dynamic import. Reproduce on Firefox ESR with the -Svelte page from the issue, bisect between 0.3.2 and 0.5.2, and fix the -cause: break the cycle or gate the feature with the same detection -`@moq/watch/support` already does for other capabilities, so the element -reports what is missing rather than throwing from an effect. - -Firefox is not in the browser harness. Add it to `test/wasm`'s Playwright -matrix if the harness can drive it, or record why it cannot. - -## Closes - -- [#3361](https://github.com/moq-dev/moq/issues/3361) - close this issue when the quest finishes diff --git a/quest/m0/3363-js-watch-a-broadcast-republished-on-one-session-keeps-resuming.md b/quest/m0/3363-js-watch-a-broadcast-republished-on-one-session-keeps-resuming.md new file mode 100644 index 00000000000..353be1b767b --- /dev/null +++ b/quest/m0/3363-js-watch-a-broadcast-republished-on-one-session-keeps-resuming.md @@ -0,0 +1,50 @@ +# [S] js/watch: a broadcast republished under its name on one session keeps resuming + +## Goal + +A watcher of a broadcast that its publisher drops and republishes under the +same name on the same session re-consumes every generation, not just the +first. The reported shape is an `invisible` `` toggling `muted`: +with no media left the element unpublishes, and each unmute publishes again. + +## Plan + +Reported on `@moq/watch` 0.3.2 (#3363); nobody has retested 0.5.3, and three +fixes since target this path: #2617 (`announcedBroadcast`, lite restarts +resolved by publisher identity), #2976 (keep a republished broadcast when its +predecessor closes), #3368 (a refused duplicate namespace does not strand the +first). + +Mechanism on main: `js/publish/src/element.ts` derives `hasMedia` from the +audio and video sources, and `Microphone` stops its track when `muted`, so an +`invisible` publisher with `muted` set has no media and `#publishEnabled` goes +false; `js/publish/src/broadcast.ts` `Broadcast.#run` closes the +`Moq.Broadcast.Producer` (the broadcast is unannounced), and unmute creates a +fresh producer and calls `connection.publish(name, broadcast)` again. The +watcher's `js/watch/src/broadcast.ts` `#runBroadcast` delegates to +`conn.announcedBroadcast(name)`, and `js/net/src/announced.ts` keeps a live +handle across a redundant re-announce (`current.closed.peek() === undefined` +continues). If the retraction is coalesced away or lands late, the watcher +holds the dead generation and the wire resets its tracks: play, then close, +until a fresh session (a publisher reload) forces an unambiguous retraction. +dev's `#runBroadcast` builds on `Moq.Origin.Table` and `Announce.Broadcast` +instead, but the publisher chain and the audio source are the same. + +- Regression first: a js/net test that publishes, unpublishes, and republishes + one path on one session three times, and asserts the announced-broadcast + handle re-consumes each generation and the audio track yields frames after + each. Run it on main (0.5.3) and dev. +- If it fails, key the re-announce on a generation identity so an announce + that follows a retraction always swaps the handle. If it passes, keep the + test and close. +- Manual check per the issue: `just relay`, an `invisible muted` + `` toggling `muted`, a `` on the same name. + +## Closes + +- [#3363](https://github.com/moq-dev/moq/issues/3363) - close this issue when the quest finishes + +## Related + +- [#2985](/quest/m1/2985-js-net-path-keyed-publisher-state-goes-stale-when-a.md) - the publisher side of a same-path replacement +- [#2991](/quest/m1/2991-net-coalesce-dynamic-tracks-and-preserve-sequences-across.md) - sequences across replacements diff --git a/quest/m0/3363-js-watch-audio-only-stream-does-not-resume.md b/quest/m0/3363-js-watch-audio-only-stream-does-not-resume.md deleted file mode 100644 index 4023e9a7805..00000000000 --- a/quest/m0/3363-js-watch-audio-only-stream-does-not-resume.md +++ /dev/null @@ -1,32 +0,0 @@ -# [S] js/watch: an audio-only stream resumes every time the publisher unmutes - -## Goal - -A subscriber on an audio-only broadcast keeps playing each time the publisher -toggles `muted` back to `false`, not only the first time. Today the second and -every later unmute is detected, played, and immediately closed, until the -publisher reloads its page, which buys exactly one more resume. - -## Plan - -Reproduce with `just relay`, a `` on a `hang`, and a `` -started `invisible` and `muted`, toggling `muted` a few times. Two candidate -mechanisms, and the fix depends on which one it is: - -- The publisher side retracts and re-creates the audio rendition or its - track on each toggle, and `js/watch` treats the second appearance of the - same rendition name as the end of the one it was playing (a stale - `closed` handler from the first subscription evicting the second, the - shape [#2985](/quest/m1/2985-js-net-path-keyed-publisher-state-goes-stale-when-a.md) - describes on the publisher side). -- The watch audio backend keys its "already started" state on the rendition - and never re-arms after the track ends, so the resubscribe races its own - teardown. - -Find which by logging track lifetimes on both ends, fix it where the state -goes stale rather than by retrying the subscribe, and add a `js/watch` test -that unmutes three times and asserts audio frames keep arriving after each. - -## Closes - -- [#3363](https://github.com/moq-dev/moq/issues/3363) - close this issue when the quest finishes diff --git a/quest/m0/README.md b/quest/m0/README.md index eb4c35a23d0..7b0c7fdda7b 100644 --- a/quest/m0/README.md +++ b/quest/m0/README.md @@ -16,15 +16,15 @@ regression test per Root Cause First. ## Quests - [#2405](/quest/m0/2405-js-net-connect-logs-on-every-connection-at-the-wrong.md) - js/net: connect logs print the JWT in the relay URL -- [#3361](/quest/m0/3361-js-watch-fails-on-firefox-esr.md) - js/watch: `` throws from an effect on Firefox ESR, a regression since 0.3.2 - [#3360](/quest/m0/3360-js-watch-broadcast-is-undefined-at-initialization.md) - js/watch: a framework binding the element reads `broadcast` before the custom element is upgraded -- [#3363](/quest/m0/3363-js-watch-audio-only-stream-does-not-resume.md) - js/watch: an audio-only stream resumes only the first time the publisher unmutes -- [#3359](/quest/m0/3359-moq-net-subscribe-error-sends-hardcoded-404.md) - moq-net: SUBSCRIBE_ERROR sends a literal 404 instead of the draft's registered code - [Adapter namespace map](/quest/m0/rs-adapter-namespace-map.md) - moq-net: a duplicate PUBLISH_NAMESPACE on draft-14/15 strands the first request, and the map never shrinks +- [IETF error codes](/quest/m0/ietf-error-codes.md) - every code on a moq-transport wire is a registered value for the negotiated draft, requests and stream resets alike - [Resume info](/quest/m0/resume-info-newest.md) - moq-net: resume reports segment zero's track info, so a replaced broadcast rescales timestamps on the predecessor's timescale - [#3080](/quest/m0/3080-fix-watch-audio-ring-truncate-can-race-the-worklet-reader.md) - watch: an audio ring truncate can race the worklet reader for one quantum -- [#3291](/quest/m0/3291-moq-net-zero-budget-shedding-drops-discontinuity-markers.md) - moq-net (dev): zero-budget shedding drops the empty group that marks a codec reset +- [#3363](/quest/m0/3363-js-watch-a-broadcast-republished-on-one-session-keeps-resuming.md) - js/watch: a broadcast republished under its name on one session keeps resuming +- [#3361](/quest/m0/3361-js-every-moq-package-a-package-imports-is-declared.md) - js: every @moq package a package imports is a declared dependency - [#2833](/quest/m0/2833-moq-export-ts-a-rewound-timeline-stalls-the-si-table.md) - moq export ts: a rewound timeline stalls SI tables, PCR, and pacing until the media clock catches up +- [#3326](/quest/m0/3326-moq-audio-held-resampler-frames-keep-their-source-timestamp.md) - moq-audio: held resampler frames keep their source timestamp - [#2799](/quest/m0/2799-moq-video-capture-negotiates-twice-so-a-window-resize.md) - moq-transcode: the ladder follows a source resolution change instead of keeping the one it started with - [Group charge](/quest/m0/group-charge.md) - charge real per-group cost so MOQ_CACHE_CAPACITY bounds real memory - [uring all-features](/quest/m0/uring-all-features-build.md) - moq-uring does not compile with `--all-features`, so the nightly features gate fails on it diff --git a/quest/m0/ietf-error-codes.md b/quest/m0/ietf-error-codes.md new file mode 100644 index 00000000000..f90385afa66 --- /dev/null +++ b/quest/m0/ietf-error-codes.md @@ -0,0 +1,74 @@ +# [M] IETF error codes come from the draft registry + +## Goal + +Every error code moq-net and js/net put on a moq-transport wire is a +registered value for the negotiated draft, in both directions: the +SUBSCRIBE_ERROR, FETCH_ERROR, and REQUEST_ERROR payloads, and the RESET_STREAM +and STOP_SENDING codes on data and request streams. A relay built on these +crates passes the interop runner's subscribe-error and subscribe-before-announce +cases without the peer's compatibility branch, and a routine cancellation is +read as CANCELLED rather than INTERNAL_ERROR. + +Boundaries: moq-lite's own code spaces are untouched, and js/net's inability to +carry a code on a locally raised stream error stays with +[JS stream codes](/quest/m1/js-net-stream-error-codes.md), which is about the +moq-lite space and the abstraction, not the registry. + +## Plan + +What the tree does today, identically on main and dev: + +- `rs/moq-net/src/ietf/publisher.rs` `run_subscribe` rejects with the literal + `404` at three sites and `run_fetch_stream` with `500`; + `rs/moq-net/src/ietf/subscriber.rs` `write_error` uses `400`. + `reject_subscribe`, `reject_fetch`, and `write_error` take a bare `u64`, and + `ietf::SubscribeError`, `ietf::FetchError`, and `ietf::RequestError` carry a + bare `error_code`. The only named IETF code type is `TrackStatusCode` + (`rs/moq-net/src/ietf/track.rs`), for a different registry, plus a + function-local `NOT_SUPPORTED: u64 = 0x3` in the subscriber. +- `js/net/src/ietf/publisher.ts` `runSubscribe` writes `errorCode: 404` on both + the draft-14 `SubscribeError` and the draft-15+ `RequestError` branch; + `js/net/src/ietf/subscriber.ts` uses `400` and `409`; `errorCode` is a plain + number everywhere. +- `js/net/src/ietf/subscriber.ts` `runPublish` writes a draft-14 `PublishError` + with the function-local `NOT_SUPPORTED` and a `RequestError` on later + drafts; the Rust subscriber's publish handling is the same shape. +- Stream resets on an IETF session send `Error::to_code()`, the moq-lite space + where `Cancel` is `0`; draft-19 section 3.3.4 assigns `0x0` to INTERNAL_ERROR + and `0x1` to CANCELLED. `Error::from_transport` maps only `0` back to + `Cancel`, so both directions have to move together. #2993 fixed one site + (`cancel_subscribe`, a named `STREAM_CANCELLED`). +- `Version::Draft14` through `Draft20` are all negotiated, straddling the + draft-19 consolidation into REQUEST_ERROR, so the values are per version. + +The work: + +- One named code type per registry (request errors, stream errors), with + `Encode` and `Decode` in the `TrackStatusCode` style, that + maps `Error` variants to the registered value for the negotiated draft and + back. An incoming code with no named value decodes to the remote/opaque + variant, never to a named one. Cite the draft section each value comes from + in the type's docs. +- Use it at every construction site above, in Rust and JS, and in + `Reader::abort` / `Writer::abort` on IETF sessions. Delete the literals and + the function-local constant. `Error::NotFound`'s IETF wire value comes from + the same mapping. +- Tests: encode/decode round-trips per version; a draft-14 PublishError and a + draft-15+ RequestError round-trip for the publish path; a subscribe for a missing + broadcast rejects with the not-found value of each draft; a cancelled + subscription resets with CANCELLED and a moq-net peer reads it back as + `Cancel`; the two interop runner cases pass without their COMPAT branch. + +The reporter of #3359 offered a PR and asked whether to prefer a version-aware +enum over a flat one: version-aware, per the above. + +## Closes + +- [#3359](https://github.com/moq-dev/moq/issues/3359) - close this issue when the quest finishes +- [#3001](https://github.com/moq-dev/moq/issues/3001) - close this issue when the quest finishes + +## Related + +- [JS stream codes](/quest/m1/js-net-stream-error-codes.md) - the moq-lite half for js/net +- [#3187](/quest/m1/3187-preserve-structured-protocol-error-codes-across-ffi-and-c.md) - the same codes crossing the FFI diff --git a/quest/m1/3001-ietf-stream-resets-send-moq-lite-error-codes-so-routine.md b/quest/m1/3001-ietf-stream-resets-send-moq-lite-error-codes-so-routine.md deleted file mode 100644 index 2cab7ac4a66..00000000000 --- a/quest/m1/3001-ietf-stream-resets-send-moq-lite-error-codes-so-routine.md +++ /dev/null @@ -1,33 +0,0 @@ -# [S] IETF stream resets send moq-lite error codes, so routine events read as INTERNAL_ERROR - -## Goal - -Implement and verify the behavior tracked in [#3001](https://github.com/moq-dev/moq/issues/3001) -within the issue's stated scope and boundaries. - -## Plan - -Use the public issue's scope, implementation notes, and acceptance criteria -below as the starting plan. Reconcile paths and assumptions with the current -tree before implementation. - -### Issue context - -Split out of #2993, where the cancellation path was fixed narrowly and the general case deliberately was not. - -`Error::to_code()` encodes the moq-lite space, where `Cancel` is `0`. On the moq-transport wire, draft-19 section 3.3.4 assigns `0x0` to `INTERNAL_ERROR` and `0x1` to `CANCELLED`. Every IETF stream reset that goes through `Reader::abort`/`Writer::abort` therefore sends a code from the wrong registry. - -The most visible case is `ietf/session.rs`, where a failed `run_uni_group` does `reader.abort(&err)`. A group arriving for an alias the subscriber retired by its own cancellation is an expected late object, and it stops the stream with `0` -- the publisher reads a routine event as an internal failure on our side. - -\#2993 fixed exactly one site (`cancel_subscribe`, via a named `STREAM_CANCELLED` and a raw-code `Reader::stop`) because it could be shown safe there: the publisher treats its request stream reader closing as `Ok(())` and never inspects the code. - -The general fix is not a matter of passing `1` at each remaining site, which is why it was not folded in: - -- `Error::from_transport` maps only `0` back to `Cancel`. Changing outgoing codes without it makes two moq-net IETF peers disagree, so a routine cancellation surfaces as `Remote(1)` and can move an expected event into error paths. -- Both directions have to change together, and the mapping is shared with moq-lite, whose code space is unrelated. - -So this wants a per-protocol code mapping (outgoing and incoming) rather than a scattering of literals. The js/net counterpart is #2999: there the abstraction cannot express a code at all. - -## Closes - -- [#3001](https://github.com/moq-dev/moq/issues/3001) - close this issue when the quest finishes diff --git a/quest/m1/3049-moq-net-outbound-hop-path-construction-is-never.md b/quest/m1/3049-moq-net-outbound-hop-path-construction-is-never.md deleted file mode 100644 index 2a9606552b1..00000000000 --- a/quest/m1/3049-moq-net-outbound-hop-path-construction-is-never.md +++ /dev/null @@ -1,76 +0,0 @@ -# [M] moq-net: outbound HOP_PATH construction is never validated - -## Goal - -A hop chain is validated where it is emitted, not only where it is parsed, so -moq-net cannot construct an advertisement that a conforming receiver must -close the session over. - -Every outbound path enforces the rule once: the entries exactly fill `Length`, -the list is non-empty, and no non-zero Hop ID appears twice. Publisher route -selection skips a route that cannot be legally advertised instead of emitting -it, and the moq-lite ingress cannot introduce a duplicate that later reaches an -IETF cluster peer. - -Boundaries: a route that is invalid to advertise may still be fine to serve -locally, so it is dropped from advertisement rather than from the origin. The -per-path ingress guards added by [#3042](https://github.com/moq-dev/moq/issues/3042) -stay working; this replaces the need for the next route source to remember the -rule again. - -## Plan - -Use the public issue's scope and implementation notes below as the starting -plan. Reconcile paths and assumptions with the current tree before -implementation. - -### Issue context - -`HopPath::validate` runs only on decode, so nothing stops us building and -sending an outbound HOP_PATH that a conforming receiver must reject. - -`ietf::cluster::HopPath::validate` rejects an empty list and a repeated -non-zero Hop ID, but it is only called from `param_decode`. `Advert::forward` -appends our own Hop ID and wraps the result without revalidating, and the -encode path does not check either. A `broadcast::Route` whose `hops` already -carry a duplicate therefore goes out as-is. - -That matters because `draft-lcurley-moq-cluster` requires the receiver to treat -it as fatal: "A receiver MUST close the session with a PROTOCOL_VIOLATION if -the entries do not exactly fill `Length`, if the list is empty, or if a -non-zero Hop ID appears twice." So a malformed chain we construct does not -degrade our own routing, it closes the downstream session. - -Routes reach the model from more than one place, and only the IETF decode path -is checked: - -- The moq-lite ingress builds hop chains itself. `OriginList` caps length but - does not reject duplicates, so a lite chain may legally carry one and, once - shared through the origin, be forwarded to an IETF cluster peer. -- `broadcast::Route` is public with a public `hops` field, so any in-process - producer can attach one. - -[#3042](https://github.com/moq-dev/moq/issues/3042) closed the two reachable -cases it introduced, both at ingress: `ietf::Subscriber::route` discards a chain -already carrying the identity assigned to the peer, and `lite::Subscriber`'s two -responder-append sites do the same. Those are per-path guards. The general gap -is that validity is enforced where a chain is parsed rather than where one is -emitted. - -### Design notes - -Validate in the outbound constructor (`Advert::forward`, or the encode path) and -have publisher route selection skip a route that cannot be legally advertised. -Making the invalid state unrepresentable is preferable to a check callers must -remember: a constructor that can only produce a valid chain means the next route -source gets the rule for free. - -Found by Codex during adversarial review of #3042. - -## Closes - -- [#3049](https://github.com/moq-dev/moq/issues/3049) - close this issue when the quest finishes - -## Related - -- [#3060](/quest/m1/3060-moq-net-ban-hop-id-0-from-hop-chains.md) - bans Hop ID 0 from chains outright, and builds on this diff --git a/quest/m1/3060-moq-net-ban-hop-id-0-from-hop-chains.md b/quest/m1/3060-moq-net-ban-hop-id-0-from-hop-chains.md index 6d0358df51c..4f9a950be3c 100644 --- a/quest/m1/3060-moq-net-ban-hop-id-0-from-hop-chains.md +++ b/quest/m1/3060-moq-net-ban-hop-id-0-from-hop-chains.md @@ -52,12 +52,9 @@ The section's honest summary today, `Declaring 0 therefore trades loop detection Every `== Origin::UNKNOWN` / `!= Origin::UNKNOWN` test that exists to ask "does this chain entry name anybody" is gone, across `lite/subscriber.rs`, `ietf/{subscriber,publisher,cluster}.rs`, and `model/{origin,broadcast}.rs`. The marker survives only where it means "this field is absent". Any survivor in the first category means 0 is still special somewhere and the change is incomplete. -Targets `dev`: it changes published `moq-net` API alongside -[#3049](/quest/m1/3049-moq-net-outbound-hop-path-construction-is-never.md), and lands on top of it. - -## Required - -- [#3049](/quest/m1/3049-moq-net-outbound-hop-path-construction-is-never.md) - validates hop chains where they are emitted; this quest lands on top of it +Targets `dev`: it changes published `moq-net` API. The outbound validation it +builds on landed in #3066, where `Hops::push` enforces the duplicate rule +wherever a chain is built. ## Closes diff --git a/quest/m1/README.md b/quest/m1/README.md index 19fae5412cc..478c6d98638 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -29,6 +29,7 @@ with the current dev tree before starting. - [#2853](/quest/m1/2853-quiche-with-a-pinned-source-port-can-dial-only-a-broken.md) - quiche with a pinned source port can dial only a broken IPv4 address - [#2624](/quest/m1/2624-moq-native-goaway-redirect-guard-classifies-hosts-by-name.md) - moq-native: GOAWAY redirect guard classifies hosts by name, not by resolved address - [#3161](/quest/m1/3161-retention-should-reclaim-idle-open-groups-now-that-expiry.md) - Retention should reclaim idle open groups now that expiry is timestamp-only +- [Gap discontinuity](/quest/m1/gap-discontinuity.md) - a hole in the delivered group sequence is the discontinuity unless the boundary proves continuity; no marker has to arrive - [Monotonic timeline](/quest/m1/monotonic-timeline.md) - a track's timestamps never fall below its live edge; publishers declare a discontinuity and continue forward, consumers stop detecting rewinds - [Group overflow](/quest/m1/group-overflow-abort.md) - an oversized open group aborts for every reader instead of shedding its head - [#2895](/quest/m1/2895-add-an-atomic-readiness-gate-for-origin-broadcasts.md) - Add an atomic readiness gate for Origin broadcasts @@ -46,7 +47,6 @@ with the current dev tree before starting. - [Plan: binding rate control](/quest/m1/plan-binding-rate-control.md) - settle how a non-Rust publisher follows the send estimate before wiring five bindings - [#2709](/quest/m1/2709-per-broadcast-bandwidth-estimates-and-reservation.md) - js/net mirrors the send-side bandwidth allocator so each publisher encodes against its own share - [#3000](/quest/m1/3000-track-teardown-on-poll-unused-is-not-atomic-against-a.md) - Track teardown on poll_unused is not atomic against a consumer reattaching -- [#3001](/quest/m1/3001-ietf-stream-resets-send-moq-lite-error-codes-so-routine.md) - IETF stream resets send moq-lite error codes, so routine events read as INTERNAL_ERROR - [JS stream codes](/quest/m1/js-net-stream-error-codes.md) - js/net: a locally raised group error reaches the wire as INTERNAL_ERROR - [#3002](/quest/m1/3002-no-test-drives-a-late-group-through-the-ietf-dispatch-loop.md) - No test drives a late group through the IETF dispatch loop - [#3187](/quest/m1/3187-preserve-structured-protocol-error-codes-across-ffi-and-c.md) - Preserve structured protocol error codes across FFI and C bindings @@ -65,6 +65,6 @@ with the current dev tree before starting. - [#3208](/quest/m1/3208-make-2-5-ms-opus-frame-durations-work-across-bindings.md) - Make 2.5 ms Opus frame durations work across bindings - [#2152](/quest/m1/2152-libmoq-c-abi-catch-up-with-the-moq-ffi-surface.md) - libmoq: C ABI catch-up with the moq-ffi surface - [Plan: route cold cost](/quest/m1/plan-route-cold-cost.md) - settle how a route's cold cost crosses the bindings without being rewritten on the way back -- [#3049](/quest/m1/3049-moq-net-outbound-hop-path-construction-is-never.md) - moq-net: validate a hop chain where it is emitted, not only where it is parsed - [#3060](/quest/m1/3060-moq-net-ban-hop-id-0-from-hop-chains.md) - moq-net: ban Hop ID 0 from hop chains - [#2248](/quest/m1/2248-moq-mux-rebase-fmp4-export-timestamps-for-late-subscribers.md) - moq-mux: rebase fMP4 export timestamps for late subscribers +- [Merge dev](/quest/m1/merge-dev.md) - dev lands on main with a closing keyword for every issue it fixed diff --git a/quest/m1/gap-discontinuity.md b/quest/m1/gap-discontinuity.md new file mode 100644 index 00000000000..101fd4e364a --- /dev/null +++ b/quest/m1/gap-discontinuity.md @@ -0,0 +1,92 @@ +# [M] A gap in the group sequence is a discontinuity unless the boundary proves continuity + +## Goal + +A consumer resets codec state and its timeline whenever the group sequence it +delivers has a hole it cannot prove harmless, whatever made it: the publisher +skipped a sequence to declare a break, the relay or the subscriber's budget +shed a group, or a group was lost. A hole is harmless only when the previous +group's end meets the next group's first timestamp within the rounding +tolerance the js consumer already uses (`CONTIGUITY_TOLERANCE`), which keeps the legal +non-sequential numbering (DTS-derived ids, the HLS importer's packed epoch +bits) playing through. No signal that has to arrive carries the reset, +because moq-lite is lossy and any marker group can be shed before the +container layer sees it. An empty group stops meaning anything. + +## Plan + +Today `drafts/draft-lcurley-moq-hang.md` says an empty group declares a +discontinuity between codec epochs, and both container consumers key on it: +`rs/moq-mux/src/container/consumer.rs` waits for a zero-frame group's FIN in +`GroupBuffer::poll_empty` and bumps the counter in `mark_discontinuities` +(on the latency-skip path too); `js/hang/src/container/consumer.ts` does the +same through `Group.empty` and `#markDiscontinuity`. The one producer is +`rs/moq-mux/src/container/producer.rs` `Producer::discontinuity()`, which +appends and immediately finishes an empty group; its callers are the +h264, h265, and opus importers, `rs/moq-video`'s idle capture path +(`capture_stopped`), `rs/moq-audio`'s deferred `pending_discontinuity`, and +moq-boy. js/publish never emits one. On dev, `TrackState::is_stale` in +`rs/moq-net/src/model/track.rs` sheds a finished empty group under a zero +budget, since its reach is its successor's start, so a live-edge subscriber +never sees the marker and the reset is lost end to end (#3291). + +- Draft: replace the empty-group sentence with the gap rule. A publisher + declares a discontinuity by skipping at least one group sequence. A consumer + MUST reset codec state, reapplying startup delay and pre-skip, before + decoding the first group after a gap in the sequence it delivers, declared + or not, unless the previous group's end meets the next group's first + timestamp within a rounding tolerance of about a microsecond, since a + 1024-sample AAC frame has no integer microsecond duration and independently + rounded stamps differ by one. Video knows its end from the + [duration marker](/quest/m2/duration-marker.md); audio from its + codec-defined frame durations. An empty group is permitted and carries no + meaning. Group sequences stay free to be non-sequential. + A contiguous boundary is what every ordinary group boundary already is: + the keyframe that opens the next group resets prediction state and carries + its parameter sets, and a codec config change rides the catalog, so an + encoder replacement on a continuous clock needs nothing more. A publisher + that wants the consumer to re-apply startup delay presents a hole. +- Consumers, both languages: `discontinuity()` bumps when the delivered + sequence advances by more than one and the boundary is not contiguous + (`ptsContiguous` in the js consumer is the shape, now exact rather than + upper-bound), and the empty-group state machine + (`poll_empty`, `Group.empty`, the FIN wait) goes. The max-age skip path + already resets through the same counter. `rs/moq-audio`'s undeclared-hole + handling from #3386 (`gap()`) becomes the declared path as well. +- Cost to check: a video decoder reset on every shed group. Measure a + WebCodecs reset plus configure, and a VideoToolbox or openh264 reset, on the + keyframe that follows a skip. If it is material, make the container-level + reset a timeline reset and let the decoder decide whether the keyframe needs + a flush. +- Gap gate: the mux consumer cannot tell a skipped sequence from a late group + (#3258, `max_ts - next_start >= max_age`), so a declared skip resumes only + when the gate trips or the timestamp jump already exceeds the budget. Decide + by measurement whether `Producer::discontinuity()` keeps writing an empty + group purely as a walk-now hint, harmless when shed, or stops; record the + resume latency either way. +- Producers: `Producer::discontinuity()` skips a sequence, and every caller + above follows; the importers re-estimate as today. +- Tests: the transport-level regression for #3291 (a zero-budget subscriber, + an idle publisher, a resume: the reset happens); the mux tests + `empty_group_declares_a_discontinuity`, + `latency_skip_preserves_empty_group_discontinuity`, and + `empty_group_advances`, with their js equivalents, rewritten for the gap + rule; a shed group resets; an empty group does nothing; a non-sequential id + jump with a contiguous boundary (`consumer.nonsequential.test.ts`) does not + reset. + +Branch from dev, where `is_stale` and the current consumers live. + +## Required + +- [Duration marker](/quest/m2/duration-marker.md) - a video group has to know its own end before a boundary can prove continuity + +## Closes + +- [#3291](https://github.com/moq-dev/moq/issues/3291) - close this issue when the quest finishes + +## Related + +- [Monotonic timeline](/quest/m1/monotonic-timeline.md) - requires this: a declared discontinuity is what a forward-only timeline continues from +- [#3056](/quest/m1/3056-watch-video-decoder-captures-the-rewind-generation-at.md) - the watch decoder reset that fires on the counter +- [#3161](/quest/m1/3161-retention-should-reclaim-idle-open-groups-now-that-expiry.md) - the retention half of timestamp-only expiry diff --git a/quest/m1/group-overflow-abort.md b/quest/m1/group-overflow-abort.md index 368a4234909..1b4b7fbacac 100644 --- a/quest/m1/group-overflow-abort.md +++ b/quest/m1/group-overflow-abort.md @@ -56,7 +56,7 @@ evicted prefix. still holds. - **The IETF wire keeps its own mapping.** Sending the new code on the moq-transport wire belongs to - [#3001](/quest/m1/3001-ietf-stream-resets-send-moq-lite-error-codes-so-routine.md), + [IETF error codes](/quest/m0/ietf-error-codes.md), which is fixing the whole registry confusion rather than one variant. ### What actually gets deleted @@ -128,4 +128,4 @@ already claims its top end "intentionally reaches the raised - [Group charge](/quest/m0/group-charge.md) - pool-level budget accounting, unaffected by this change - [#3161](/quest/m1/3161-retention-should-reclaim-idle-open-groups-now-that-expiry.md) - also turns "open group hit a limit" into an abort, so the two must not collide on the error variant - [JS stream codes](/quest/m1/js-net-stream-error-codes.md) - without it a JS publisher sends this new code to the wire as Internal -- [#3001](/quest/m1/3001-ietf-stream-resets-send-moq-lite-error-codes-so-routine.md) - the moq-transport half of the code mapping +- [IETF error codes](/quest/m0/ietf-error-codes.md) - the moq-transport half of the code mapping diff --git a/quest/m1/js-net-stream-error-codes.md b/quest/m1/js-net-stream-error-codes.md index e55c63a1438..f781fb17a8a 100644 --- a/quest/m1/js-net-stream-error-codes.md +++ b/quest/m1/js-net-stream-error-codes.md @@ -42,7 +42,7 @@ disagree about what a code means. Scope is the moq-lite code space, matching what Rust sends today. The moq-transport registry is a separate confusion tracked by -[#3001](/quest/m1/3001-ietf-stream-resets-send-moq-lite-error-codes-so-routine.md), +[IETF error codes](/quest/m0/ietf-error-codes.md), which is fixing both directions there; do not fold the two together. Land it with a test that a JS publisher's reset arrives at a peer as the right @@ -55,5 +55,5 @@ code, and drop the `js/json` workaround once the class check is redundant. ## Related - [Group overflow](/quest/m1/group-overflow-abort.md) - adds a new stream code that a JS publisher cannot currently send -- [#3001](/quest/m1/3001-ietf-stream-resets-send-moq-lite-error-codes-so-routine.md) - the moq-transport half +- [IETF error codes](/quest/m0/ietf-error-codes.md) - the moq-transport half - [#3187](/quest/m1/3187-preserve-structured-protocol-error-codes-across-ffi-and-c.md) - the same structured-code loss across FFI and C diff --git a/quest/m1/merge-dev.md b/quest/m1/merge-dev.md new file mode 100644 index 00000000000..6eb681739c1 --- /dev/null +++ b/quest/m1/merge-dev.md @@ -0,0 +1,58 @@ +# [L] Merge dev into main + +## Goal + +`main` carries everything on `dev`: the thread-per-core runtime, the net model +and allocator work, the announce handle and its bindings, the archive line, and +every fix that only dev has. The merge PR closes each issue dev fixed with a +closing keyword, and the release that follows is the one moq.pro adopts. + +## Plan + +As of 2026-09-05 dev is 243 commits ahead of main and main 16 ahead of dev. +Merge main into dev first and resolve there, then open the merge PR from dev +with the list below as closing keywords. Run `just check-all`, `just test all`, +`just test smoke-full`, and `just bench origin/main` on the merged tree. The +breaking-change targeting rules in CONTRIBUTING.md govern the release that +follows, and [Dart announce](/quest/m1/dart-announce.md) unblocks when this +lands. + +## Required + +- [Archive](/quest/m1/archive/README.md) - moq.pro needs archive-backed recording on the release dev produces +- [Announce handle](/quest/m1/announce-handle.md) - the origin surface the merge ships +- [#3190](/quest/m1/3190-align-origin-broadcast-creation-naming-across-language.md) - every native binding on that surface +- [JS announce](/quest/m1/js-announce.md) - js/net on that surface +- [Gap discontinuity](/quest/m1/gap-discontinuity.md) - so the lost-reset regression does not ship + +## Closes + +- [#3173](https://github.com/moq-dev/moq/issues/3173) - moq-uring: worker drop cancels staged receives (8acbeb306) +- [#3107](https://github.com/moq-dev/moq/issues/3107) - moq-relay: the io_uring listener serves its certificate fingerprint (#3116) +- [#3112](https://github.com/moq-dev/moq/issues/3112) - moq-relay: the io_uring listener authenticates mTLS peers (#3116) +- [#3160](https://github.com/moq-dev/moq/issues/3160) - moq-tokio: a rustls backend without a crypto provider is a compile error (#3210) +- [#3119](https://github.com/moq-dev/moq/issues/3119) - moq-uring: UDP pools grow when a socket starves (#3133) +- [#3111](https://github.com/moq-dev/moq/issues/3111) - moq-uring: an unmappable HTTP/3 code lands in `Error::Http3` (#3110) +- [#2627](https://github.com/moq-dev/moq/issues/2627) - js: a detached element's connection lingers for a real window (#2705) +- [#2628](https://github.com/moq-dev/moq/issues/2628) - js: one connection per relay URL (#2705) +- [#2532](https://github.com/moq-dev/moq/issues/2532) - js/publish: files are demuxed and decoded, not captured (#2541) +- [#2609](https://github.com/moq-dev/moq/issues/2609) - moq-ffi: sessions reconnect automatically (#2618) +- [#2807](https://github.com/moq-dev/moq/issues/2807) - js/net: a group pop and its frame-range snapshot are one step (#2820) +- [#2808](https://github.com/moq-dev/moq/issues/2808) - js/net: the bounds snapshot is atomic with the pop (#2820) +- [#2892](https://github.com/moq-dev/moq/issues/2892) - js/net: the subscriber latency budget is enforced (#2926) +- [#2517](https://github.com/moq-dev/moq/issues/2517) - net: subscriptions resume across routes sharing a first hop (#3312) +- [#2934](https://github.com/moq-dev/moq/issues/2934) - moq export ts: SI is emitted when the snapshot changes, repeats are floored (#2971) +- [#3049](https://github.com/moq-dev/moq/issues/3049) - moq-net: `Hops::push` enforces the loop-free chain wherever one is built (#3066) +- [#1238](https://github.com/moq-dev/moq/issues/1238) - js: standalone components default to enabled (#2872) +- [#3260](https://github.com/moq-dev/moq/issues/3260) - stream consumers detect a rolled log without waiting for the group to end (#3282) +- [#3174](https://github.com/moq-dev/moq/issues/3174) - js/publish: the gain target is set before the first frame (#2541) +- [#3171](https://github.com/moq-dev/moq/issues/3171) - js/publish: fanout queue limits are validated (7bb180fdc) +- [#3172](https://github.com/moq-dev/moq/issues/3172) - js/net: Reload stops after a terminal failure (#3177) +- [#2401](https://github.com/moq-dev/moq/issues/2401) - the route linger is gone; overlapping routes resume instead (#2704, #3312) +- [#2217](https://github.com/moq-dev/moq/issues/2217) - moq-ffi: the announce handle carries the lifecycle (announce-handle, #3190) +- [#980](https://github.com/moq-dev/moq/issues/980) - dual-stack binding on main; happy eyeballs in `moq-tokio::resolve` (#2749) +- [#2153](https://github.com/moq-dev/moq/issues/2153) - go: the wrapper caught up on main; hops landed on dev (#2168) + +## Related + +- [Dart announce](/quest/m1/dart-announce.md) - waits on this merge, so it cannot be required here diff --git a/quest/m1/monotonic-timeline.md b/quest/m1/monotonic-timeline.md index fcce20b0292..3596acd003d 100644 --- a/quest/m1/monotonic-timeline.md +++ b/quest/m1/monotonic-timeline.md @@ -4,8 +4,8 @@ A track's timestamps never fall below the live edge its earlier groups reached. A publisher that has to reset (a flush, a seek, a source restart) -declares an empty-group discontinuity and continues forward from where it -was; it can no longer rewind. Inside a group timestamps still reorder freely, +declares a discontinuity by leaving a gap in the group sequence and +continues forward from where it was; it can no longer rewind. Inside a group timestamps still reorder freely, since B-frames present before the frames that precede them in decode order, and open-GOP leading pictures still qualify because they sit above the previous group's reach. @@ -19,9 +19,10 @@ Today both container consumers (`Rewind` in `rs/moq-mux/src/container/consumer.rs` and in `js/hang/src/container/consumer.ts`) classify a newer group whose timestamps land before the live edge as a rewind, drop the reneged buffer, and bump the -same counter a declared discontinuity bumps. The hang draft says an empty -group declares a discontinuity "whether the resumed timestamps move backward -or forward". That machinery is what goes. +same counter a declared discontinuity bumps. The hang draft says a declared +discontinuity applies "whether the resumed timestamps move backward or +forward". That machinery is what goes; how a publisher declares one is +[Gap discontinuity](/quest/m1/gap-discontinuity.md). - **Publisher side, in both container producers.** The track producer refuses a frame whose timestamp is below the live edge established by the groups @@ -61,10 +62,12 @@ state. ## Required +- [Gap discontinuity](/quest/m1/gap-discontinuity.md) - settles how a publisher declares the discontinuity this rule continues from - [moq#3375](https://github.com/moq-dev/moq/pull/3375) has merged, so the TS export reset it adds is keyed on the discontinuity counter before this quest trims it ## Related +- [Duration marker](/quest/m2/duration-marker.md) - the empty frame that closes a group, which is not a discontinuity - [#3056](/quest/m1/3056-watch-video-decoder-captures-the-rewind-generation-at.md) - the watch decoder reset that keeps mattering for declared discontinuities - [#3115](/quest/m2/3115-moqsink-the-publication-has-no-generation-so-a-flush.md) - moqsink's generation model after EOS, the same publisher - [#2833](/quest/m0/2833-moq-export-ts-a-rewound-timeline-stalls-the-si-table.md) - the TS export fix this trims once it lands diff --git a/quest/m2/3247-moq-audio-cpal-allocates-on-the-audio-thread.md b/quest/m2/3247-moq-audio-cpal-allocates-on-the-audio-thread.md deleted file mode 100644 index f9342e05fad..00000000000 --- a/quest/m2/3247-moq-audio-cpal-allocates-on-the-audio-thread.md +++ /dev/null @@ -1,37 +0,0 @@ -# [S] moq-audio: no allocator call on the audio thread when cpal reports an error - -## Goal - -A cpal stream error raised from the real-time render thread reaches -`moq-audio` without an allocation or a free on that thread. Today cpal's -`From` runs `format!` on the render thread before our -callback sees the error, and the callback then drops the owned `Error`, -freeing on the same thread; either can block on the allocator lock and cause -a dropout, exactly when playback is already degraded. - -## Plan - -`FailureReporter::report` in `rs/moq-audio/src/playback/driver.rs` is already -allocation-free (atomics and `Thread::unpark`). What remains is upstream and -the hand-off: - -- The dominant allocation is upstream; the - [cpal release](/quest/m2/cpal-release.md) gate quest carries that proposal - and the pin bump, and this quest waits on it. -- Pre-check in `moq-audio` what can be checked before `stream.play()`, so - fewer errors are raised from the render path at all. -- Document the residual constraint beside the driver: the callback owns the - `Error`, so the overflow path still drops it on the callback thread, and no - bounded hand-off removes that entirely. - -Test: an allocation-counting harness around the error callback, the same -shape the capture-callback quest used, proving no allocation or free after -construction on the paths this repo controls. - -## Required - -- [cpal release](/quest/m2/cpal-release.md) - the upstream fix has to ship before the audio thread can be allocation-free - -## Closes - -- [#3247](https://github.com/moq-dev/moq/issues/3247) - close this issue when the quest finishes diff --git a/quest/m2/README.md b/quest/m2/README.md index 5d66c60ef77..22bcbc52989 100644 --- a/quest/m2/README.md +++ b/quest/m2/README.md @@ -35,6 +35,8 @@ can act on. Each still carries its own plan and regression test. - [SEI](/quest/m2/sei/README.md) - H.26x SEI moves into its own track, readable without subscribing to video - [Processor](/quest/m2/processor/README.md) - a customer-run worker publishes an on-demand contribution with scoped access - [Timeline wall](/quest/m2/timeline-wall.md) - every built-in publisher anchors its timeline to wall time; the anchor is data, never a sync source +- [Duration marker](/quest/m2/duration-marker.md) - a video group ends with an empty frame that closes its last frame's duration; audio never writes one +- [LOC duration marker](/quest/m2/loc-duration-marker.md) - LOC producers write the marker once released consumers skip it - [#2278](/quest/m2/2278-watch-absolute-wall-clock-latency-target-for-synchronized.md) - hang: a timeline consumer exposes the wall anchor, and the library never syncs playback on it - [#2279](/quest/m2/2279-hang-typed-scte-35-ad-cue-signaling-carried-opaquely.md) - hang: SCTE-35 cues ride a per-rendition sidecar a player can act on - [Caption import](/quest/m2/captions-import.md) - fMP4 and MKV subtitle tracks import as text renditions instead of erroring or being dropped @@ -67,8 +69,6 @@ can act on. Each still carries its own plan and regression test. - [Cluster flags](/quest/m2/cluster-flags.md) - a discovery mechanism carries its own prerequisites, so an incomplete cluster config cannot be expressed - [Plan: revalidation updates](/quest/m2/plan-revalidation-updates.md) - settle which fields an auth re-check may update on a live session and which force a reconnect - [#3137](/quest/m2/3137-moqsrc-bound-the-pending-rendition-subscriptions-a.md) - moqsrc: bound the pending rendition subscriptions a catalog can open -- [cpal release](/quest/m2/cpal-release.md) - a cpal release that emits errors from its real-time paths without allocating -- [#3247](/quest/m2/3247-moq-audio-cpal-allocates-on-the-audio-thread.md) - moq-audio: cpal allocates and frees on the audio thread when it reports a stream error - [#3115](/quest/m2/3115-moqsink-the-publication-has-no-generation-so-a-flush.md) - moqsink: a flushing restart after EOS opens a new publication generation - [#709](/quest/m2/709-automatic-letsencrypt-support.md) - the relay provisions and renews its own ACME certificate over HTTP-01, persisted on disk - [Room SDK](/quest/m2/room-sdk.md) - a headless room package: a room is a path prefix, no service, no storage diff --git a/quest/m2/cpal-release.md b/quest/m2/cpal-release.md deleted file mode 100644 index d883d62c011..00000000000 --- a/quest/m2/cpal-release.md +++ /dev/null @@ -1,23 +0,0 @@ -# [XS] cpal release with allocation-free error emission - -## Goal - -A published cpal release emits stream errors from its real-time paths without -allocating, so `moq-audio` can pin it and stop paying an allocator call on -the audio thread when a device fails. - -## Plan - -Propose the change upstream: a `&'static str` message on the RT emission -paths, or deferring the `format!` in `From` (and the other -hosts' equivalents) to a non-RT thread. Record the maintainers' answer here. -When a release carries it, remove the bullet below, bump the pin, and -complete this quest; that unblocks the dependent one. - -## Required - -- A cpal release that emits errors from its real-time paths without allocating - -## Related - -- [#3247](/quest/m2/3247-moq-audio-cpal-allocates-on-the-audio-thread.md) - the moq-audio work that waits on this release diff --git a/quest/m2/duration-marker.md b/quest/m2/duration-marker.md new file mode 100644 index 00000000000..69b7efe79e6 --- /dev/null +++ b/quest/m2/duration-marker.md @@ -0,0 +1,62 @@ +# [M] Empty frames close the previous frame's duration + +## Goal + +In the legacy (hang) container every video group ends with an empty frame +stamped at the exclusive end of its last frame, so a group's last frame has a +duration without peeking at the next group, and the LOC consumers are ready +to skip the same marker before LOC producers start writing it. Audio writes no empty +frames: its durations are codec-defined, and the end-of-track marker and its +terminal-packet rule go. CMAF is untouched, since it carries sample durations. +An empty frame is never submitted to a decoder and never means the track +ended. + +## Plan + +Today only `rs/moq-audio`'s `publish_terminal` writes an empty frame, as the +first frame of a final group followed by the encoder's flush packets, and the +draft's legacy section defines it as the end marker: consumers discard decoded +samples at or after it (the decode consumer's terminal phase in +`rs/moq-audio/src/decode/consumer.rs`, `js/watch/src/audio/terminal.ts`). +`rs/moq-mux/src/container/consumer.rs` latches `end` sticky from any empty +payload and `js/hang/src/container/consumer.ts` returns it positionally. The +last frame of every group is otherwise timed by a guess: +`rs/moq-mux/src/container/fmp4/fragmenter.rs` times a group's trailing frame +by the catalog cadence because a group boundary is never a duration, +`rs/moq-hls`'s rendition export accumulates whole segments to see each frame's +successor, and the timeline recorder's `end(pts)` gets a bound only when a +caller passes `cut(Some(end))`. + +- Draft: the legacy and LOC sections say an empty frame is the exclusive end + of the frame before it, a video group ends with one, audio has none, and a + consumer skips it. Remove the end-marker and terminal-packet paragraph. +- Producers: the `rs/moq-mux` container `Producer` writes the marker at `cut` + and `finish` for video tracks, at the caller's bound or the last timestamp + plus its estimated duration; the js/hang container producer does the same; + `publish_terminal` stops writing it and its flush packets become ordinary + frames, so a few ms of encoder padding play at the end unless the consumer + trims by the codec delay. +- Consumers: the mux consumer records a per-group boundary that feeds + `max_end`, the last frame's `duration`, and the timeline recorder, instead + of a sticky `end`; the audio terminal phase goes; js/hang and js/watch + follow. The fragmenter and the HLS export use the boundary for the trailing + sample. +- Compatibility: released legacy video consumers already skip empty frames, + since only the audio decoder reads `end()`, so a legacy publisher is safe + against an old player, and a new consumer still skips an audio marker from + an old publisher. Released LOC consumers (`rs/moq-mux/src/container/loc`, + `js/loc`) submit an empty payload to the decoder, so this quest lands the + LOC consumer-side skip only; LOC producers start writing the marker in + [LOC duration marker](/quest/m2/loc-duration-marker.md) once skipping + consumers have shipped. This lands on main. +- Tests: a group's last frame carries the marker's duration through fmp4 + export and HLS; an audio track end has no marker and plays out; an old-style + audio marker is skipped; CMAF is unchanged. + +## Related + +- [Gap discontinuity](/quest/m1/gap-discontinuity.md) - the reset signal, which this marker is not +- [Monotonic timeline](/quest/m1/monotonic-timeline.md) - the forward-only rule the boundary sits under +- [Timeline](/quest/m1/archive/timeline.md) - the archive index that wants honest final durations +- [#3326](/quest/m0/3326-moq-audio-held-resampler-frames-keep-their-source-timestamp.md) - covers the terminal phase this quest removes +- [LOC duration marker](/quest/m2/loc-duration-marker.md) - the LOC producer half, gated on a release diff --git a/quest/m2/loc-duration-marker.md b/quest/m2/loc-duration-marker.md new file mode 100644 index 00000000000..df9b7c7603d --- /dev/null +++ b/quest/m2/loc-duration-marker.md @@ -0,0 +1,20 @@ +# [XS] LOC producers write the duration marker + +## Goal + +LOC video groups end with the empty frame that closes their last frame's +duration, the same contract the legacy container carries, once every released +LOC consumer skips it. + +## Plan + +[Duration marker](/quest/m2/duration-marker.md) lands the consumer-side skip +in `rs/moq-mux/src/container/loc` and `js/loc` but leaves LOC producers alone, +because a released LOC consumer submits an empty payload to the decoder. When +the bullet below clears, have the LOC producers write the marker at `cut` and +`finish` exactly as the legacy producer does, and extend the same tests. + +## Required + +- [Duration marker](/quest/m2/duration-marker.md) - the consumer-side skip and the contract +- A release of `moq-mux` and `@moq/loc` whose consumers skip an empty LOC payload has shipped diff --git a/quest/m2/quic/noq-parity.md b/quest/m2/quic/noq-parity.md index 153b9bd7d89..c594998ac73 100644 --- a/quest/m2/quic/noq-parity.md +++ b/quest/m2/quic/noq-parity.md @@ -16,9 +16,12 @@ Quinn and quiche backends, and the merge recorded matched throughput with a lower RSS. What remains is the gate that lets quiche go. Benchmark chat, media 1:1, media fanout, handshake churn, and idle-connection -memory on `moq-uring` with noq against quiche, on the same worker and crypto -configuration, with `just bench`. Adoption requires no material latency, -capacity, or RSS regression and a written explanation of any CPU tradeoff. +memory with `just bench`, on the same worker and crypto configuration, across +four cells: noq and quiche on `moq-uring`, and noq and quinn on the tokio +workers. noq on both runtimes is the matched control #3124 asked for, since +quiche cannot serve per-core tokio workers; the report states which QUIC +stack each runtime mode ran, so runtime and stack are never confounded again. +Adoption requires no material latency, capacity, or RSS regression and a written explanation of any CPU tradeoff. Run the browser and interop gates on the noq path: `just test wasm`, the TypeScript interop cases, `just test smoke-full`, and connection draining @@ -40,3 +43,7 @@ backend docs and feature matrix in the same PR. parity cannot be claimed without it - [Release the fork stack](/quest/m2/quic/release.md) - the relay must pin released noq sources before quiche goes + +## Closes + +- [#3124](https://github.com/moq-dev/moq/issues/3124) - the parity report is the matched runtime-versus-QUIC-stack measurement the issue asked for