diff --git a/quest/m1/README.md b/quest/m1/README.md index 13b46b1670d..ec09f0c5be0 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -148,6 +148,8 @@ per-frame CPU growth since #5926. - [Drop set](/quest/m1/drop-set.md) - each cursor judges missing groups against its own budget, so a narrow reader drops promptly and a widening re-offers groups already reported dropped on lite-07 - [Datagram tracks](/quest/m1/datagram-tracks/README.md) - a track is datagrams or streams; datagram tracks have their own request and sequence, no ranges, no cache, and map to object ID 0 on moq-transport - [A step back smaller than the delay keeps the TS export](/quest/m1/ts-small-step-back.md) - audio restarts instead of regressing; video stays within its declared depth +- [Taking control of a CARLA truck starts from neutral pedals](/quest/m1/carla-takeover-neutral.md) - a viewer's takeover releases the autopilot's throttle instead of driving off the road on it +- [A wedged CARLA truck nobody drives respawns after the stuck timeout](/quest/m1/carla-stuck-handback.md) - find what kept the 300 s stuck respawn off for a truck wedged after a handback, and fix it - [Finalize moq-lite-07](/quest/m1/lite07-finalize.md) - when the maintainer cuts it, lite-07 negotiates as `moq-lite-07` and the next release ships it - [Sockets](/quest/m1/socket/README.md) - a generic dial/accept `Socket` in moq-net, Rust, JS, and Python, with tracks as streams; moq-boy and CARLA move onto it - [A smaller, safer API than release](/quest/m1/api-audit/README.md) - every surface added since release has a consumer or is gone, overlapping operations are collapsed, names mirror across Rust, JS, and the bindings, and every break says how to migrate diff --git a/quest/m1/carla-stuck-handback.md b/quest/m1/carla-stuck-handback.md new file mode 100644 index 00000000000..b5d99c99ae0 --- /dev/null +++ b/quest/m1/carla-stuck-handback.md @@ -0,0 +1,47 @@ +# [S] A wedged CARLA truck nobody drives respawns after the stuck timeout + +## Goal + +A CARLA truck nobody is driving that stays wedged for `STUCK_TIMEOUT` (300 s) +respawns, including after a viewer hands it back. Observed on the public +demo: after a manual-control handback a truck sat at 0 km/h for 8 minutes and +never respawned, until a viewer took it again and pressed Reset. The PR names +the condition that kept the detector disarmed in that case, and a test +reproduces it. + +## Plan + +The detector (`StuckDetector` in `demo/carla/sim/moq_carla_sim/runtime.py`) +runs on the telemetry tick in `TruckSession._publish_telemetry`, and is reset +on every tick where the truck has a driver, is e-stopped, is not +`Truck.autonomous`, or the world is parked. Reproduce the observed sequence +first (take control, drive off the road, E-stop, hand back, wedge), noting +whether the e-stop was reset before the handback, then find which condition +held it reset. + +Ruled out by the code: a stalled handback. The same tick calls +`Truck.release` for every driverless, un-e-stopped truck, and `handback.plan` +returns `None` at or below `WALKING_PACE` (1 m/s), so a truck at 0 km/h +engages autonomy within one tick. An abandoned lease also cannot hold: the +command watchdog drops it after `COMMAND_TIMEOUT` (1 s). + +Suspects, most likely first: + +- A latched e-stop. An e-stop set before the handback and never reset exempts + the truck forever, on purpose (`_publish_telemetry`'s docstring). Whether a + driverless, latched truck should still respawn after the timeout, and clear + the latch when it does, is a maintainer decision for the PR. Recommended: + yes, since on a public demo nobody may come back to reset it. +- A parked world (`not self._clock.running`): check whether status or video + demand held the clock for the full 8 minutes. +- A truck that rocks against what wedges it: one that moves `STUCK_DISTANCE` + re-anchors the detector and restarts the clock. + +Test the cause in `sim/tests/test_runtime.py` beside +`test_autonomous_truck_wedged_for_the_timeout_is_respawned`, with the fake +clock, not wall time. + +## Related + +- [Taking control of a CARLA truck starts from neutral pedals](/quest/m1/carla-takeover-neutral.md) - the takeover that sent the observed truck off the road +- [CARLA on sockets](/quest/m1/socket/carla.md) - moves the lease and handback; the stuck rule must survive the move diff --git a/quest/m1/carla-takeover-neutral.md b/quest/m1/carla-takeover-neutral.md new file mode 100644 index 00000000000..530ae0131d3 --- /dev/null +++ b/quest/m1/carla-takeover-neutral.md @@ -0,0 +1,36 @@ +# [XS] Taking control of a CARLA truck starts from neutral pedals + +## Goal + +When a viewer takes control of a CARLA truck, the truck gets zero throttle +until the viewer presses a pedal, instead of the autopilot's last pedal +values. Today a truck taken while Traffic Manager was accelerating keeps about +85% throttle until the viewer hits E-stop, and drives off the road. A test of +the control handoff covers it. + +## Plan + +Takeover is bumpless by design today: `takeoverState` (`demo/carla/web/src/input.ts`) +seeds the driver's state from the truck's measured controls, and the worker's +`Drive.synchronize` (`demo/carla/sim/moq_carla_sim/drive.py`) adopts them before +the first claim. Keep that only for steering and gear, so the wheel does not +jump and the claim lands in the right gear. Pedals start released. + +- Brake: recommended, the brake is applied until the viewer's first input, so + a new driver who does nothing brings the truck to rest instead of coasting it + off the road. The other option is zero brake (a coast). Pick in the PR and + record why. Mind `Truck.actuate`'s rule that a resting-state claim leaves + Traffic Manager in control, and the shift interlock, which wants some brake. +- Both sides: the browser seeds the new state, and the worker clamps a + claiming command's pedals the same way, so an old or hostile client cannot + claim at full throttle either. +- Tests: rewrite `test_takeover_synchronizes_gate_with_current_vehicle_controls` + (`sim/tests/test_runtime.py`) and the `beginTakeover` test in + `web/src/truck.test.ts` to assert the new pedals while steering and gear + still follow the truck. Fix the `world.py` module docstring, which says + takeover keeps the pedal demand. + +## Related + +- [CARLA on sockets](/quest/m1/socket/carla.md) - moves the control track; the handoff behaves the same after the move +- [A wedged CARLA truck nobody drives respawns after the stuck timeout](/quest/m1/carla-stuck-handback.md) - the other half of a bad takeover: getting the truck back diff --git a/quest/m2/README.md b/quest/m2/README.md index 82144b76af9..b81476bbfe7 100644 --- a/quest/m2/README.md +++ b/quest/m2/README.md @@ -163,6 +163,7 @@ lite-07; bitrate enforcement is not part of this release. - [Per-app audio on macOS](/quest/m2/capture-app-audio-macos.md) - one application's audio through ScreenCaptureKit - [cpal loads libasound at runtime](/quest/m2/cpal-alsa-runtime.md) - condition: a cpal release whose Linux build carries no load-time libasound requirement - [Audio capture without ALSA link](/quest/m2/capture-alsa-link.md) - moq-audio capture and playback build on Linux without linking libasound, and capture becomes a default feature +- [The moq CLI can publish a changing catalog](/quest/m2/cli-catalog-updates.md) - catalog updates mid-stream, so recovery replays need no hand-built clients - [Ship capture and playback](/quest/m2/cli-packaging.md) - a released moq binary can capture and play, which no distribution currently enables - [Egress profile](/quest/m2/quic-egress-profile.md) - measure relay send-path syscalls, pacing bursts, and allocations before optimizing any of them - [VAAPI encode and decode](/quest/m2/video-vaapi.md) - H.265 encode and decode, pre-generated bindings, and pooled resize surfaces, including the moq-dev/vaapi release that carries them @@ -211,6 +212,7 @@ lite-07; bitrate enforcement is not part of this release. - [No MOQ_* knobs outside the binaries](/quest/m2/env-knobs.md) - test, bench, and library knobs leave the `MOQ_*` prefix - [Clean ALSA playback onset](/quest/m2/audio-alsa-onset.md) - no onset restarts or clicks over PulseAudio - [Interop audit](/quest/m2/audit-interop.md) - our interop runner entries match what we ship, and every red interop cell with a moq.dev side is fixed, reported, or noted as down or unsupported +- [moq-hls exposes each rendition's bound source](/quest/m2/hls-rendition-source.md) - playlists and segments report the source path and instance they read, so a cache can key on the source - [The HLS server follows each path once](/quest/m2/hls-follow-once.md) - `Following` reports synced absence, so moq-hls resolves with one follow - [moq-bench pins the instances it measures](/quest/m2/bench-epoch-pin.md) - pooled requests pin their announced epoch, so a takeover is not counted as the same broadcast - [The memory bench finishes at 1 MiB frames](/quest/m2/memory-bench-hang.md) - the allocation mode's park at `size=1048576` is root-caused and fixed diff --git a/quest/m2/cli-catalog-updates.md b/quest/m2/cli-catalog-updates.md new file mode 100644 index 00000000000..59cdf521dd1 --- /dev/null +++ b/quest/m2/cli-catalog-updates.md @@ -0,0 +1,23 @@ +# [S] The moq CLI can publish a changing catalog + +## Goal + +`moq import` can keep a broadcast's catalog open and publish later catalog +updates, such as adding or removing a track mid-stream, without restarting +the broadcast or minting a new instance. An operator can then replay catalog recovery +cases (a relay restart while a catalog group is open, a reader joining or +resuming mid-update) with stock tools instead of hand-built clients. + +## Plan + +Decided 2026-11-03 (maintainer, `/quest-plan`): m2. A relay-replacement +replay of catalog resume had to build scratch publisher clients because the +CLI publishes one catalog per broadcast (`rs/moq-cli/src/publish.rs`, +`PublishCatalog`). + +- Pick the smallest interface that drives updates from outside: for example a + catalog file the CLI watches, or catalog updates on a control stream. Ask + the maintainer if the choice changes the CLI's public surface. +- Keep the one-catalog default unchanged. +- Test a mid-stream update that a subscribed reader sees exactly once, and a + reader joining after the update. diff --git a/quest/m2/hls-rendition-source.md b/quest/m2/hls-rendition-source.md new file mode 100644 index 00000000000..64a46450c18 --- /dev/null +++ b/quest/m2/hls-rendition-source.md @@ -0,0 +1,38 @@ +# [S] moq-hls exposes each rendition's bound source + +## Goal + +A moq-hls export reports, for every playlist and segment it serves (including +renditions that reference another broadcast's track), the source broadcast +path and instance that supplies it. A caller can then key a cache on the +actual source rather than on the requesting viewer's grants. + +## Plan + +Decided 2026-11-03 (maintainer, `/quest-plan`): m2. A downstream HLS cache +keys entries on a digest of each viewer's subscribe scope, because it can't +tell which source a referenced rendition reads. Viewers holding different +grants for the same broadcast then never share a cached entry. Correctness is +already handled; this recovers the sharing. + +- Identify a source by its bound broadcast's `path` and `instance` + (`moq_net::broadcast::Info`). A content replacement mints a new instance. + The route epoch stays hidden: it is `pub(crate)` in moq-net, and a higher + epoch continues the same instance's sequences, so keying on it would split + a shareable entry for no correctness gain. +- Expose it from the export (`rs/moq-hls/src/export/`, where + `Renditions::sync` resolves sources against the catalog), for example as + response metadata, so an HTTP server in front of it can surface it. +- Report the binding that supplies each resource, not only the rendition's + current one. After a replacement, a rendition keeps listing its + predecessors' rows (`Rendition::after` in `export/rendition.rs`), and a + predecessor's binding supplies those segments' bytes. A segment reports the + source it is muxed from, and a playlist reports every source its listed + segments read. +- The source identity replaces the viewer's grants only in the cache key: a + viewer is still authorized against the source before a cached entry is + served to it. +- Report a change of binding, such as a publisher replacement's new instance, + as a new value rather than reusing the old one. +- Test a local rendition, a referenced rendition, and a replacement while the + predecessor's rows still drain, so one playlist lists both sources. diff --git a/quest/m2/webrtc/README.md b/quest/m2/webrtc/README.md index 7371cd8f3e6..2000042d4aa 100644 --- a/quest/m2/webrtc/README.md +++ b/quest/m2/webrtc/README.md @@ -20,6 +20,7 @@ Decided 2026-10-30 with the maintainer (planning interview), after the str0m wor ## Required +- [A typed DTLS handshake timeout error](/quest/m2/webrtc/dtls-timeout.md) - callers match a DTLS handshake timeout by variant, and session end treats it like an ICE timeout - [Rename moq-rtc to moq-webrtc](/quest/m2/webrtc/rename.md) - one crate holds the gateway, the ICE driver, and the data-channel transport - [Vendor and trim the stack](/quest/m2/webrtc/vendor.md) - str0m, dimpl, `is`, and sctp-proto live in moq-webrtc with unused code removed - [Several bandwidth lines per media section](/quest/m2/webrtc/sdp-bandwidth.md) - answers carry both `b=TIAS` and `b=AS` without splicing diff --git a/quest/m2/webrtc/dtls-after-ice.md b/quest/m2/webrtc/dtls-after-ice.md index a1ce30c0c32..30f9c2597c1 100644 --- a/quest/m2/webrtc/dtls-after-ice.md +++ b/quest/m2/webrtc/dtls-after-ice.md @@ -6,7 +6,7 @@ DTLS sends its first flight only once ICE has nominated a pair, so a peer whose ## Plan -Decided 2026-10-30 with the maintainer (planning interview). Today DTLS starts before ICE connects and dimpl gives up after 1+2+4+8+16 s with jitter (`dimpl/src/config.rs:90-92`), racing moq-ice's 30 s deadline; [moq-dev/moq#7379](https://github.com/moq-dev/moq/pull/7379) papered over the race by reporting an early DTLS failure as a timeout. Hold DTLS activation (around str0m's `lib.rs:1493`) until nomination, then remove #7379's remapping if nothing else needs it. Test on the paused clock: ICE nominating at 29 s still completes DTLS. Added 2026-10-31 from [moq-dev/moq#7379](https://github.com/moq-dev/moq/pull/7379): also test that a DTLS failure after ICE has connected still reports `moq_ice::Error::Rtc`, not `Timeout` (moq-rtc's `IceTimeout`), so the remapping (or its removal) only ever changes a failure before nomination. +Decided 2026-10-30 with the maintainer (planning interview). Today DTLS starts before ICE connects and dimpl gives up after 1+2+4+8+16 s with jitter (`dimpl/src/config.rs:90-92`), racing moq-ice's 30 s deadline; [moq-dev/moq#7379](https://github.com/moq-dev/moq/pull/7379) papered over the race by reporting an early DTLS failure as a timeout. Hold DTLS activation (around str0m's `lib.rs:1493`) until nomination, then remove #7379's remapping if nothing else needs it. Test on the paused clock: ICE nominating at 29 s still completes DTLS. Added 2026-10-31 from [moq-dev/moq#7379](https://github.com/moq-dev/moq/pull/7379): also test that a DTLS failure after ICE has connected still reports a DTLS error (`moq_ice::Error::Rtc`, or the [typed handshake timeout](/quest/m2/webrtc/dtls-timeout.md)), not `Timeout` (moq-rtc's `IceTimeout`), so the remapping (or its removal) only ever changes a failure before nomination. Public API: none. Wire: none. diff --git a/quest/m2/webrtc/dtls-timeout.md b/quest/m2/webrtc/dtls-timeout.md new file mode 100644 index 00000000000..806137f9856 --- /dev/null +++ b/quest/m2/webrtc/dtls-timeout.md @@ -0,0 +1,39 @@ +# [XS] A typed DTLS handshake timeout error + +## Goal + +A DTLS handshake that times out after ICE connects surfaces as its own error +variant in `moq-ice` and `moq-rtc` (or `moq-webrtc`, after the +[rename](/quest/m2/webrtc/rename.md)), so callers match it instead of the text +`rtc error: DTLS error: timeout: handshake` inside `Error::Rtc(String)`. +Session-end handling and logging treat it like an ICE timeout: `session::end` +logs it at debug as abandoned-session churn, not as a warning. + +## Plan + +Today `Agent::drain` (`rs/moq-ice/src/agent.rs`) maps any DTLS failure before +ICE connects to `Error::Timeout`, and stringifies everything else. str0m flattens +dimpl's typed `Error::Timeout(TimeoutError::Handshake)` into +`CryptoError::Other(String)` (`str0m/src/dtls.rs`), so the variant is lost +before moq-ice sees it. + +- Classify it once at the str0m boundary in moq-ice, the only place that sees + str0m's error. Until the [vendored stack](/quest/m2/webrtc/vendor.md) lands, + that is a text match there, pinned by a test against the crate's real + message. If the vendoring lands first, carry dimpl's variant through the + vendored `dtls.rs` typed instead, and add no text match. Otherwise the + vendoring quest replaces the match; its plan says so. +- Add the variant to `moq_ice::Error` and `moq_rtc::Error`, named by role (for + example `DtlsTimeout`), and map it in `moq-rtc`'s session loop and moq-tokio's + `webrtc` transport, which also matches `moq_ice::Error`. +- Decide in the PR whether the variant stays distinct from `IceTimeout` or + folds into one establishment-timeout variant, and record why. Distinct is + recommended: an ICE timeout means no path, a DTLS timeout means a path that + never finished the handshake. + +Public API: additive variants on non-exhaustive error enums. Wire: none. + +## Related + +- [Vendor and trim the WebRTC stack](/quest/m2/webrtc/vendor.md) - replaces this quest's text match with dimpl's typed timeout +- [DTLS waits for ICE](/quest/m2/webrtc/dtls-after-ice.md) - after it, every DTLS handshake timeout comes after nomination, which is the case this types diff --git a/quest/m2/webrtc/vendor.md b/quest/m2/webrtc/vendor.md index 9bcd44282f5..d94aaba5fa3 100644 --- a/quest/m2/webrtc/vendor.md +++ b/quest/m2/webrtc/vendor.md @@ -10,6 +10,7 @@ Decided 2026-10-30 with the maintainer (planning interview); see the [epic](/que - Vendor str0m and str0m-proto at the main-branch revision moq-dev/rind's `rind-str0m` targeted (`dc317173`, on dimpl 0.9 with str0m's pluggable crypto provider), with the dimpl, `is`, and sctp-proto versions it depends on (maintainer, 2026-10-31), so [moq-rtc on rind](/quest/m2/rind/rtc.md) can port rind's provider code unchanged. Commit them unchanged first so later diffs show only our changes, then trim. - Remove: str0m's `bwe/`, leaky pacer, H.266, RED, DTMF, G.7xx and comfort noise, VLA and simulcast layers, RTCP XR and app feedback, stats, `_internal_test_exports`, the crypto backends other than the one rind will replace (keep the provider trait until [moq-rtc on rind](/quest/m2/rind/rtc.md)); dimpl's `dtls13/` and `auto.rs`. Keep upstream's tests for what remains. +- Keep dimpl's typed `TimeoutError::Handshake` through the vendored `dtls.rs`, which str0m flattens into `CryptoError::Other(String)`, and replace moq-ice's text match for it with a typed match if [the typed DTLS timeout](/quest/m2/webrtc/dtls-timeout.md) has landed. - Keep the license files and record each upstream version in the module docs. - Drop the crates.io dependencies on str0m and friends from the workspace once nothing uses them.