Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions quest/m1/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
47 changes: 47 additions & 0 deletions quest/m1/carla-stuck-handback.md
Original file line number Diff line number Diff line change
@@ -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
36 changes: 36 additions & 0 deletions quest/m1/carla-takeover-neutral.md
Original file line number Diff line number Diff line change
@@ -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
2 changes: 2 additions & 0 deletions quest/m2/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down
23 changes: 23 additions & 0 deletions quest/m2/cli-catalog-updates.md
Original file line number Diff line number Diff line change
@@ -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.
38 changes: 38 additions & 0 deletions quest/m2/hls-rendition-source.md
Original file line number Diff line number Diff line change
@@ -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.
1 change: 1 addition & 0 deletions quest/m2/webrtc/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion quest/m2/webrtc/dtls-after-ice.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
39 changes: 39 additions & 0 deletions quest/m2/webrtc/dtls-timeout.md
Original file line number Diff line number Diff line change
@@ -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
1 change: 1 addition & 0 deletions quest/m2/webrtc/vendor.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
Loading