diff --git a/quest/m1/export-order.md b/quest/m1/export-order.md new file mode 100644 index 00000000000..d0569e63419 --- /dev/null +++ b/quest/m1/export-order.md @@ -0,0 +1,74 @@ +# [S] Buffered exports pick their group order by measurement + +## Goal + +moq-mux's exports (moq-cli's `ts`, `flv`, `fmp4`, `mp4`, `mkv`, `h264`, +`h265`, HLS, and the RTMP, SRT, and RTSP egress, gst, and ffi consumers built +on its catalog tracks) subscribe in the group order that loses the least +video. The measured case: an MPEG-TS trunk (`moq export ts --delay D`, a +constant 10 to 25 Mb/s) that loses about the length of a 5 s outage even with +an 11.7 s delay, where SRT loses about 0. + +## Plan + +Decided 2026-11-12 (maintainer, `/quest-import` of +[moq-dev/moq#8559](https://github.com/moq-dev/moq/issues/8559)): +✅ measure Ascending against Descending, then pick (rejected: Ascending for +every moq-mux export without measuring; Ascending only for `ts` and `flv` +under `--delay`; changing `Subscription::default()` in moq-net). + +Today every catalog-track subscription in `rs/moq-mux/src/catalog/tracks.rs` +leaves `order` at the default, `Order::Descending`. After an outage the relay +sends the newest groups first, and the group due now expires +(`rs/moq-mux/src/container/consumer.rs`, "current group evicted"). By rough +arithmetic on the issue's path, newest-first leaves the oldest stalled group +waiting about 14.8 s, and oldest-first about 7.4 s. Neither is traced yet. + +The maintainer's reasoning, to keep in view: + +- Descending exists so recovery is prioritized, assuming an adaptive + bitrate player that wants the live edge. +- It also keeps a relay that aggregates subscriptions from starving a short + budget: with `Delay::max` of 1 s and 10 s on one upstream, ascending would + starve the 1 s subscriber. moq-net already handles this: the upstream + aggregate is descending when any live subscriber is, and each downstream + session is served in its own subscriber's order + (`rs/moq-net/src/model/subscription.rs`). So an export's order changes only + its own last hop. +- The right order may depend on the maximum latency. + +The starting hypothesis to measure mirrors +[Buffered playback subscribes in ascending order](/quest/m1/buffered-ascending.md): +an export with a nonzero playout delay (`Delay::min`) wants its window from +the start, and goes Ascending; one that chases the live edge stays +Descending. + +Measure both orders per export kind on two cases, counting video lost and +the number of skips: + +- the issue's outage: one path at 20 Mb/s with `cake`, 100 ms RTT, a + 9.95 Mb/s multiplex, every packet in the relay's direction dropped for 5 s, + at `--delay` 2 s, 5.75 s, and 11.71 s; +- a sustained deficit on bufferbloat: a rate below the multiplex behind a + deep but finite queue that overflows. + +Ship the order that loses less video for each kind, and record the numbers +here or in the PR. Trace the relay's send order after the return with its +qlog, which confirms or refutes the arithmetic above. The reporter offered to +run their matrix against a branch. + +A relay that orders aggregated sends by each subscriber's deadline (earliest +deadline first) instead of "any descending" came up in the interview and is +not planned. The group deadlines in +[Per-stream and per-datagram deadlines](/quest/m4/quic-deadline.md) are the +groundwork it would need. + +Public API: none, unless an export grows an order option. Wire: none. + +## Required + +- [Finalize moq-lite-07](/quest/m2/lite07-finalize.md) - lite-06 and earlier serve an ascending request newest-first + +## Related + +- [A path that's back is used within an RTT](/quest/m3/quic-path-return.md) - the transport half of the same outage diff --git a/quest/m1/pipewire-dmabuf-chunk.md b/quest/m1/pipewire-dmabuf-chunk.md new file mode 100644 index 00000000000..925c2bc40bf --- /dev/null +++ b/quest/m1/pipewire-dmabuf-chunk.md @@ -0,0 +1,51 @@ +# [XS] PipeWire DMA-BUF capture ignores the chunk size + +## Goal + +PipeWire screen capture on Hyprland (xdg-desktop-portal-hyprland) delivers +DMA-BUF frames instead of dropping every one. That portal leaves `maxsize` at +0 and writes a placeholder chunk size of 9 on purpose, flagging a bad frame +with `SPA_CHUNK_FLAG_CORRUPTED` instead. The `pipewire.rs` tests also build +against PipeWire 1.0.x headers, as the library already does. + +## Plan + +Decided 2026-11-12 (maintainer, `/quest-import` of +[moq-dev/moq#8571](https://github.com/moq-dev/moq/issues/8571)): +✅ the fd's allocation size is the only bound (rejected: the reporter's +`dma_buf_maxsize_contains` patch, which keeps a second check that ignores the +offset and that the allocation check already covers; the same fix in m3). + +In `rs/moq-video/src/capture/pipewire.rs`: + +- Delete `dma_buf_chunk_contains` and `dma_buf_chunk_size`. The chunk size + never reads a DMA-BUF: the GPU import and the CPU download go by the + layout, the offset, and the fd's size from `dma_buf_allocation_size`, whose + check (`offset + required <= allocation`) stays the bound. `chunk_kind` + already treats a DMA-BUF chunk size of 0 as data; it keeps rejecting a + CORRUPTED chunk. +- Add a pure-function test with Hyprland's shape: chunk size 9, `maxsize` 0, + a 4K BGRx frame (33,177,600 bytes), an allocation that holds it. A CORRUPTED + chunk is still rejected. +- The test that sets `spa::sys::SPA_VIDEO_TRANSFER_SMPTE2084` fails to build + against PipeWire 1.0.x headers, which lack it. Spell it out as a local + constant (14), the way + [moq-dev/moq#3387](https://github.com/moq-dev/moq/pull/3387) did for + `BT2020_10` and `BT601`. + +Caused by [moq-dev/moq#2839](https://github.com/moq-dev/moq/pull/2839), which +added the chunk-size bound. + +Public API: none. Wire: none. + +## Hosts + +- linux - PipeWire capture + +## Closes + +- [#8571](https://github.com/moq-dev/moq/issues/8571) - every DMA-BUF frame dropped on Hyprland + +## Related + +- [DMA-BUF capture into Vulkan](/quest/m4/2819-moq-video-carry-pipewire-dma-bufs-safely-into-the-vulkan.md) - the zero-copy path this unblocks on Hyprland diff --git a/quest/m2/ietf-scope/README.md b/quest/m2/ietf-scope/README.md index f8ab7bfb5f7..2989da36fe8 100644 --- a/quest/m2/ietf-scope/README.md +++ b/quest/m2/ietf-scope/README.md @@ -40,6 +40,13 @@ Settled with this epic: - Kept, as rejected in the same interview: lite-07's `ietf` object extension and moq-lite 01 to 04. - Not here: `ietf/flate.rs`; compression removal has its own work. +- Narrowed 2026-11-12 (maintainer, `/quest-import` of + [moq-dev/moq#8577](https://github.com/moq-dev/moq/issues/8577)): a Rust + publisher may answer a multi-group FETCH whose every group is cached or + proven never produced, using only draft-defined markers (Prior Group ID Gap + in, End of Non-Existent Range out). [Range FETCH over known + holes](/quest/m4/ietf-range-fetch.md) owns it; until it lands, the docs + state joining FETCH only. Our moq-transport extensions, decided 2026-11-10 (maintainer, on [moq-dev/moq#8444](https://github.com/moq-dev/moq/pull/8444)): diff --git a/quest/m2/subscribe-ranges/README.md b/quest/m2/subscribe-ranges/README.md index 63e756422e2..79f4ff36c2a 100644 --- a/quest/m2/subscribe-ranges/README.md +++ b/quest/m2/subscribe-ranges/README.md @@ -50,7 +50,9 @@ relay bounds a sparse FETCH only if the model can request ranges: (maintainer, 2026-10-28, [moq-dev/moq#7204](https://github.com/moq-dev/moq/pull/7204)), and the [IETF scope freeze](/quest/m2/ietf-scope/README.md) adds no hole-marker - extension that would let a cache answer a range. A FETCH of the track's newest live group is refused + extension that would let a cache answer a range. + [Range FETCH over known holes](/quest/m4/ietf-range-fetch.md) later answers + a range whose every group is cached or proven never produced. A FETCH of the track's newest live group is refused unless its range ends below that group's live edge ([moq-dev/moq#7944](https://github.com/moq-dev/moq/pull/7944), `poll_settle` in `rs/moq-net/src/ietf/publisher.rs`), replacing the diff --git a/quest/m3/quic-path-return.md b/quest/m3/quic-path-return.md new file mode 100644 index 00000000000..73db2f9a2cd --- /dev/null +++ b/quest/m3/quic-path-return.md @@ -0,0 +1,58 @@ +# [M] A path that's back is used within an RTT + +## Goal + +After a link outage in either direction, `moq-quic` resumes sending within +about one RTT of the path's return, and the outage doesn't leave smoothed RTT +inflated. Today a 5 s one-way outage leaves the relay's next send 2.4 s after +the link returns, on its backed-off probe timer. A two-way outage raises +smoothed RTT from 105 ms to between 0.74 and 0.99 s, and puts the next send +0.95 to 7.76 s after the return. The consumer is MPEG-TS trunks under a fixed +`moq export ts --delay`, which compete with SRT on outage loss. + +## Plan + +Decided 2026-11-12 (maintainer, `/quest-import` of +[moq-dev/moq#8559](https://github.com/moq-dev/moq/issues/8559)): +✅ plan this recovery quest in m3 and restore +[Per-stream and per-datagram deadlines](/quest/m4/quic-deadline.md) in m4 +(rejected: recovery only; nothing on QUIC until the order fix is measured). +`quic-careful-resume` stays deleted until a redial's ramp is measured; the +issue reasons it but has not isolated it. + +Verified in `moq-quic`'s connection code: + +- One-way outage. `on_loss_detection_timeout` arms `probe_when_heard` once + ([moq-dev/moq#6178](https://github.com/moq-dev/moq/pull/6178)), and + `probe_on_heard` clears it on the first packet heard. In a one-way outage, + the subscriber's own packets spend it while the relay's direction is still + dead, so nothing remains to fire when that direction returns. + `pto_time_and_space` then waits out `pto_base * 2^pto_count`. +- Two-way outage. `RttEstimator::update` takes the first acknowledgment after + the return as an ordinary sample, which spans the outage (about 5 s), with + no outlier guard. + +Recommended fixes, to be confirmed by measurement: + +- Keep the heard-probe armed until new data is acknowledged, rate-limited so + a one-way outage doesn't send a probe per packet received (#6178's + concern). +- Keep a sample out of smoothed RTT when its packet was sent before a probe + timeout that went unanswered. RFC 9002 leaves this to the implementation. + +Grade on the issue's shape (20 Mb/s `cake`, 100 ms RTT, a 9.95 Mb/s +multiplex, 5 s outage one-way and both ways, three replicates) and on +bufferbloat: time from the return to the first send and to the multiplex's +rate, and video lost under `--delay` 2 s, 5.75 s, and 11.71 s. Report +spurious probes during the outage. + +Public API: none. Wire: none. + +## Closes + +- [#8559](https://github.com/moq-dev/moq/issues/8559) - a 5 s outage costs a trunk about the outage, whatever the delay + +## Related + +- [Buffered exports pick their group order by measurement](/quest/m1/export-order.md) - the send-order half of the same outage +- [Per-stream and per-datagram deadlines](/quest/m4/quic-deadline.md) - faster recovery below a deadline diff --git a/quest/m4/ietf-range-fetch.md b/quest/m4/ietf-range-fetch.md new file mode 100644 index 00000000000..46c3de177ac --- /dev/null +++ b/quest/m4/ietf-range-fetch.md @@ -0,0 +1,82 @@ +# [M] moq-transport FETCH answers ranges over known holes + +## Goal + +A Rust moq-transport publisher answers a Standalone `FETCH` (and a draft 20+ +fill) that spans more than one group, provided the cache knows the status of +every group in the range: each one is either cached or proven never +produced. Groups go out in order on the one fetch stream, and each proven +hole is marked with End of Non-Existent Range (`0x8C`). A range with any +unknown group is refused whole, as today. A moqx edge in front of a +moq-relay origin, and two moq-net relays chained over moq-transport, can +then replay history in one request. + +Not here: a hole-marker extension of our own (deleted under the IETF scope +freeze), hole knowledge for copies fed by peers that send no gap, and JS, +whose publisher refuses every `FETCH`. + +## Plan + +Decided 2026-11-12 (maintainer, `/quest-import` of +[moq-dev/moq#8577](https://github.com/moq-dev/moq/issues/8577)): +✅ a narrow quest in m4 (rejected: won't fix under the freeze; the same in +m3 for the reporter as a named consumer; the proposal as written, which walks +every ID and resets with `UNKNOWN_OBJECT_STATUS`). This narrows +[moq-dev/moq#7204](https://github.com/moq-dev/moq/pull/7204)'s one-group +refusal, whose reason was that "serving moq-transport ranges requires +authoritative knowledge of every group". This quest serves only ranges +where we have that knowledge. It widens the +[frozen scope](/quest/m2/ietf-scope/README.md), which kept only joining +`FETCH`. + +What makes it possible: moq-transport's Prior Group ID Gap object extension, +which [IETF time addressing](/quest/m2/time-addressing/ietf.md) sends on +egress and reads on ingest as a best-effort SUBSCRIBE_SKIP. What counts as +proven: + +- a group in the cache; +- a hole the copy knows was never produced: local, moq-lite SUBSCRIBE_SKIP, + or a received Prior Group ID Gap; +- a budget-independent drop (a cut, or an origin's eviction or expiry). + +Anything else is unknown, and refuses the range: a drop judged under a +narrower budget or range, which proves nothing for a wider `FETCH`; a gap +from a moq-transport peer that sends no Prior Group ID Gap (its absence is +not "no gap"); and a dropped or expired group from a moq-transport upstream, +which has no marker for it. + +- Both refusals in `rs/moq-net/src/ietf/publisher.rs` (Standalone `FETCH` + admission, and `judge` for the draft 20+ forms) answer instead when the + range is fully known. `FETCH_OK`'s End Location is cut at the largest + object, and a start past it stays `INVALID_RANGE`. +- Answer through the existing per-group path in group order, fetching the + next group only when the stream has room, and stop when the requester + cancels. Bound it the way one-group fetches are bounded; the relay keeps + any limit on groups per `FETCH`. +- The `track::Requests` handler shape stays: a `Fill` already separates gone + (`drop_groups`) from unknown (`refuse_groups`). Answer from what the copy + records, without asking upstream group by group. +- Update the "History is served one group at a time" entry in + `doc/concept/standard.md`, and note the narrowed freeze in the IETF scope + docs. + +Test on drafts 18, 20, and 22: a range over cached groups and proven holes is +answered with `0x8C` runs; a range with one unknown group is refused; an +upstream that reports G stale for a narrow subscriber while still holding G +gets G or a refusal for a wider `FETCH` covering G, never `0x8C`; and a chain +of two moq-net relays over moq-transport replays a multi-group run. Run the +interop suite with `--all`. + +Public API: none. Wire: none (draft-defined messages only). + +## Required + +- [IETF time addressing](/quest/m2/time-addressing/ietf.md) - reads Prior Group ID Gap on ingest + +## Closes + +- [#8577](https://github.com/moq-dev/moq/issues/8577) - a Standalone FETCH that spans more than one group is refused + +## Related + +- [Subscribe ranges](/quest/m2/subscribe-ranges/README.md) - owns the one-group refusal note this narrows diff --git a/quest/m4/quic-deadline.md b/quest/m4/quic-deadline.md new file mode 100644 index 00000000000..65da67307ca --- /dev/null +++ b/quest/m4/quic-deadline.md @@ -0,0 +1,104 @@ +# [L] Per-stream and per-datagram deadlines + +## Goal + +A send stream can carry a deadline. Bytes that cannot reach the peer before it +are not retransmitted: the stream is reset instead, so a late group never +competes with a live one for the congestion window. Below the deadline, +recovery gets faster rather than slower: when the last packet of a burst is +still unacknowledged and there is time for an acknowledgment and one +retransmission to land, the sender asks for an immediate ACK and probes early +instead of waiting a full PTO. moq-net sets the deadline per group stream from +the subscription's `max_delay` and the group's expiry, so no MoQ wire +change is needed. Datagrams get the same: a queued datagram past its +deadline is dropped from the send buffer instead of sent late, so a +congested viewer receives fresh datagrams rather than seconds-old ones. + +## Plan + +Implement in `moq-quic`. + +- Add `set_deadline(Instant)` on `SendStream`. A stream without one behaves + exactly as today. +- On loss detection, before queueing a retransmission for a stream with a + deadline, estimate the arrival instant as now plus the forward one-way + delay. Start with `min_rtt / 2`, corrected by the peer's reported ACK delay. + Measure whether receive-time differences (`moq_congestion::Acked::received`, + from the [realtime epic](/quest/m3/quic-realtime/README.md)) improve that + estimate, accounting for clock offset, drift, and uncertainty. They do not + alone measure absolute one-way delay. If the estimate is past the deadline, + reset the stream with a dedicated error code and drop its retransmit ranges, + including bytes already lost, so flow control is returned in one step. +- Proactive tail-loss probe: when the newest in-flight packet carries deadline + data and `now + pto() > deadline - rtt`, send an `IMMEDIATE_ACK` (the + ACK-frequency extension `moq-quic` already implements) on the next packet and arm + a shortened probe at `max(deadline - rtt - now, min_pto)`. Never probe past + the congestion window; the probe is a scheduling choice, not extra credit. +- moq-net cannot call `moq-quic` directly, so the deadline crosses its own + `transport::poll::SendStream` trait, the way + [the ACK hook](/quest/m3/quic-ack-hook.md) does: a method whose default + reports unsupported, implemented by the moq-tokio and moq-uring adapters + over `moq-quic`. A backend without it sends as today. +- moq-net: the per-group `GroupServe` machine in the lite and IETF + publishers (`lite/publisher.rs`, `ietf/publisher.rs`) sets the deadline + when it opens the stream, from the subscription's `max_delay` and the + group's expiry, whichever is sooner; a subscription with neither sets none. The reset error code maps to the + existing group-expired code on the MoQ wire, so a viewer sees the same + signal it sees for a relay-side expiry today. + +Datagrams. Decided 2026-11-01 (maintainer, follow-up planning after the +2026-11-01 /quest-afk run), from +[moq-dev/moq#7517](https://github.com/moq-dev/moq/pull/7517)'s datagram +delivery bench: behind a 2 Mbit/s bottleneck fed 4 Mbit/s, about 25% of +datagrams were lost and the survivors' p99 was about 8.2 s (p50 about 50 ms) +on lite-06, lite-07-wip, and moq-transport-22 alike. Congestion control kept +the shaper's queue from overflowing; the sender's 1 MiB QUIC datagram buffer +absorbed the overload and dropped only on overflow, and nothing expired a +datagram by age. Of #7517's options (a send deadline, a smaller send buffer, +or oldest-first within a subscription), the deadline was picked, because it +uses the delay budget the subscriber already stated instead of a buffer size +or ordering that suits only some rates. + +- moq-quic: a datagram carries an optional deadline, and the send path + drops a queued datagram whose deadline has passed (counted, and reported + in the connection's stats) before building a packet with it. A datagram + without one behaves as today. The same estimate of forward delay applies: + drop one that can't arrive before its deadline. +- moq-net: the datagram writer sets the deadline from the subscription's + max delay (`Delay::max`), through the same `transport::poll` seam as the stream + deadline; a backend without it sends as today. +- Keep newest-first within a subscription; with stale datagrams expiring, + it no longer starves the fresh ones. +- Re-run #7517's `datagram_delivery` bench: p99 behind the bottleneck stays + within the subscription's max delay, and the loopback viewer is unchanged. + Percentiles are over delivered datagrams, so also report offered, + delivered, and expired counts separately, and check that datagrams + delivered within the max delay don't fall below today's: the deadline may + drop only what would have arrived too late anyway. + +Measure on bufferbloat: a rate below the media bitrate behind a deep but +finite queue whose overflow demonstrably drops packets, with competing +loss-based traffic if needed to fill it. Random loss may prove recovery +correctness, but never grades latency or throughput. Report delivery latency +p95 and p99, bytes +retransmitted past their deadline (must be zero), spurious resets under +reordering, and probe overhead versus the default PTO. A proactive probe that +raises loss or latency under any profile stays off by default. + +Restored 2026-11-12 in m4 (maintainer, `/quest-import` of +[moq-dev/moq#8559](https://github.com/moq-dev/moq/issues/8559)) after +[moq-dev/moq#8423](https://github.com/moq-dev/moq/pull/8423) pruned it from +m5 for want of a consumer. The consumer: MPEG-TS trunks under a fixed +`moq export ts --delay`, which compete with SRT on delivering whatever can +still arrive within the delay. The outage loss that issue measured belongs to +[Buffered exports pick their group order by measurement](/quest/m1/export-order.md) +and [A path that's back is used within an RTT](/quest/m3/quic-path-return.md), +not this quest: the early probe never exceeds the congestion window, which is +full of unacknowledged packets during an outage. This quest is the +"below the deadline, recovery gets faster" half and the datagram expiry. +Rejected: restoring `quic-careful-resume` too, whose gain is reasoned, not +measured. + +## Related + +- [ACK hook](/quest/m3/quic-ack-hook.md) - the same pattern for a moq-net method backed by `moq-quic`