From bd498856fd44b00633a3d0999f8d83b31569a9af Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 9 Nov 2026 05:14:24 -0800 Subject: [PATCH 1/2] chore(quest): claim quest/m2/tokio-resolved-options.md Quest-Claim: 2a76169f296f2739 From e0a112667791ea4de378fd93628e1eeac47ba429 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 9 Nov 2026 05:33:19 -0800 Subject: [PATCH 2/2] refactor(tokio)!: resolved config reports off as None connect::Resolved.timeout, quic::Resolved.{idle_timeout, keep_alive}, and Backoff::{max, timeout}() turn a configured zero into None where the text knobs resolve; CLI/TOML/env/FFI/C keep zero = off. Co-Authored-By: Claude Opus 5.5 --- quest/m2/README.md | 1 - quest/m2/tokio-resolved-options.md | 36 ------------------- rs/moq-c/src/api.rs | 8 ++--- rs/moq-c/src/test.rs | 17 ++++++--- rs/moq-ffi/src/session.rs | 8 ++--- rs/moq-ffi/src/test.rs | 6 ++-- rs/moq-gst/src/connection.rs | 8 ++--- rs/moq-gst/src/sink/imp.rs | 6 ++-- rs/moq-relay/src/cluster.rs | 2 +- rs/moq-relay/src/uring.rs | 3 +- rs/moq-relay/tests/drills.rs | 6 +++- .../tests/integration/goaway_cluster.rs | 2 +- rs/moq-tokio/src/client.rs | 2 +- rs/moq-tokio/src/connect.rs | 9 ++--- rs/moq-tokio/src/connection.rs | 18 +++++----- rs/moq-tokio/src/quic.rs | 28 ++++++++------- rs/moq-tokio/src/quic/backend.rs | 2 +- 17 files changed, 72 insertions(+), 90 deletions(-) delete mode 100644 quest/m2/tokio-resolved-options.md diff --git a/quest/m2/README.md b/quest/m2/README.md index f52ea88f8bc..f472f45b03d 100644 --- a/quest/m2/README.md +++ b/quest/m2/README.md @@ -205,4 +205,3 @@ quests that require them. - [Cut readiness](/quest/m2/cut-gate/README.md) - the checks the cut needs that break nothing: main no slower than release, vendored fixes ported, and moq-c at parity - [Probe](/quest/m2/probe/README.md) - a session probes up to the bitrate it wants to send or receive, so a stopped simulcast rendition resumes and a viewer up-switches; browser padding is parked in m3 (held in m2 by open claims; moves to m3) - [Finish the milestone re-cut](/quest/m2/recut-held.md) - claim-held epics move to the milestone their kind and priority give them once their claims merge -- [moq-tokio's resolved config reports "off" as None](/quest/m2/tokio-resolved-options.md) - resolved timeouts and backoff accessors use `Option` while the text knobs keep `0` = off diff --git a/quest/m2/tokio-resolved-options.md b/quest/m2/tokio-resolved-options.md deleted file mode 100644 index 559573160ba..00000000000 --- a/quest/m2/tokio-resolved-options.md +++ /dev/null @@ -1,36 +0,0 @@ -# [S] moq-tokio's resolved config reports "off" as None - -## Goal - -moq-tokio's resolved values and accessors say "off" with `Option`, not zero, -finishing what -[moq-dev/moq#8265](https://github.com/moq-dev/moq/pull/8265) does for moq-net: -`connect::Resolved.timeout`, `connection::Backoff::{max, timeout}()`, the -GOAWAY handover, and `quic::Resolved.idle_timeout`. The text knobs (CLI, -TOML, env, FFI, C) keep `0` = off, since they need three states and absence -already means "use the default"; the conversion happens once, where they -resolve. - -## Plan - -Planned 2026-11-08 (maintainer, approved follow-up of -[moq-dev/moq#8265](https://github.com/moq-dev/moq/pull/8265), which makes -moq-net's reconnect policy take `Option` and keeps moq-tokio's config layer -on zero). Milestone: m2, since it breaks moq-tokio's public API. - -On `main`: `Backoff::max()` documents "zero leaves the delay uncapped" and -`timeout()` "zero meaning unlimited" (`rs/moq-tokio/src/connection.rs`); -`connect::Resolved.timeout` is a `Duration` whose `--connect-timeout` says -"zero disables this duration" (`rs/moq-tokio/src/connect.rs`); the handover -knob says the same; and `quic::Resolved.idle_timeout` is a `Duration` passed to the transport as -`Some(resolved.idle_timeout)` (`Some(0)` is QUIC's "no idle timeout"), with -zero turned into `None` only in `Resolved::keep_alive_interval` -(`rs/moq-tokio/src/quic.rs`); making the field `Option` replaces both. Audit the -other `Resolved` structs for the same pattern while there. - -Public API: moq-tokio's resolved fields and accessors become `Option`. -Migrate: compare against `None` instead of `Duration::ZERO`. Wire: none. - -## Waiting - -- moq-dev/moq: [moq-dev/moq#8265](https://github.com/moq-dev/moq/pull/8265) merges, since this finishes the change it makes to moq-net. Check with `gh pr view 8265 --json state`; delete this section once it reads `MERGED`. diff --git a/rs/moq-c/src/api.rs b/rs/moq-c/src/api.rs index 458457e1070..1cb12e1b6ca 100644 --- a/rs/moq-c/src/api.rs +++ b/rs/moq-c/src/api.rs @@ -1594,7 +1594,7 @@ pub extern "C" fn moq_client_defaults() -> moq_client_config { let config = crate::client::Config::default(); let connect = config.connect.resolve(); - dst.connect_timeout_us = micros(connect.timeout); + dst.connect_timeout_us = micros(connect.timeout.unwrap_or_default()); dst.has_connect_timeout = true; dst.failover_delay_us = micros(connect.race); dst.has_failover_delay = true; @@ -1611,15 +1611,15 @@ pub extern "C" fn moq_client_defaults() -> moq_client_config { dst.has_backoff_initial = true; dst.backoff_multiplier = config.connect.backoff.multiplier; dst.has_backoff_multiplier = true; - dst.backoff_max_us = micros(config.connect.backoff.max()); + dst.backoff_max_us = micros(config.connect.backoff.max().unwrap_or_default()); dst.has_backoff_max = true; - dst.backoff_timeout_us = micros(config.connect.backoff.timeout()); + dst.backoff_timeout_us = micros(config.connect.backoff.timeout().unwrap_or_default()); dst.has_backoff_timeout = true; let quic = config.quic.resolve(); dst.quic_max_streams = quic.max_streams; dst.has_quic_max_streams = true; - dst.quic_idle_timeout_us = micros(quic.idle_timeout); + dst.quic_idle_timeout_us = micros(quic.idle_timeout.unwrap_or_default()); dst.has_quic_idle_timeout = true; if let Some(keep_alive) = quic.keep_alive { dst.quic_keep_alive_us = micros(keep_alive); diff --git a/rs/moq-c/src/test.rs b/rs/moq-c/src/test.rs index b90e01e91ae..705ee5b512d 100644 --- a/rs/moq-c/src/test.rs +++ b/rs/moq-c/src/test.rs @@ -7435,7 +7435,10 @@ fn defaults_report_what_a_zeroed_config_dials() { let connect = expected.connect.resolve(); assert!(config.has_connect_timeout); - assert_eq!(config.connect_timeout_us, connect.timeout.as_micros() as u64); + assert_eq!( + config.connect_timeout_us, + connect.timeout.unwrap_or_default().as_micros() as u64 + ); assert!(config.has_failover_delay); assert_eq!(config.failover_delay_us, connect.race.as_micros() as u64); assert!(config.has_resolution_delay); @@ -7449,10 +7452,13 @@ fn defaults_report_what_a_zeroed_config_dials() { assert!(config.has_backoff_multiplier); assert_eq!(config.backoff_multiplier, expected.connect.backoff.multiplier); assert!(config.has_backoff_max); - assert_eq!(config.backoff_max_us, expected.connect.backoff.max().as_micros() as u64); + assert_eq!( + config.backoff_max_us, + expected.connect.backoff.max().unwrap_or_default().as_micros() as u64 + ); assert!(config.has_backoff_timeout); assert_eq!( - expected.connect.backoff.timeout(), + expected.connect.backoff.timeout().unwrap_or_default(), std::time::Duration::from_micros(config.backoff_timeout_us) ); @@ -7465,7 +7471,10 @@ fn defaults_report_what_a_zeroed_config_dials() { assert!(config.has_quic_max_streams); assert_eq!(config.quic_max_streams, quic.max_streams); assert!(config.has_quic_idle_timeout); - assert_eq!(config.quic_idle_timeout_us, quic.idle_timeout.as_micros() as u64); + assert_eq!( + config.quic_idle_timeout_us, + quic.idle_timeout.unwrap_or_default().as_micros() as u64 + ); assert_eq!( config.has_quic_keep_alive.then_some(config.quic_keep_alive_us), quic.keep_alive.map(|d| d.as_micros() as u64) diff --git a/rs/moq-ffi/src/session.rs b/rs/moq-ffi/src/session.rs index 0f8e6060e75..1ed24d296ba 100644 --- a/rs/moq-ffi/src/session.rs +++ b/rs/moq-ffi/src/session.rs @@ -248,12 +248,12 @@ pub fn moq_client_defaults() -> MoqClientConfig { let quic = moq_tokio::quic::Config::default().resolve(); MoqClientConfig { - timeout: Some(resolved.timeout), + timeout: Some(resolved.timeout.unwrap_or_default()), race: Some(resolved.race), resolution_delay: Some(resolved.resolution_delay), quic: MoqQuicConfig { max_streams: Some(quic.max_streams), - idle_timeout: Some(quic.idle_timeout), + idle_timeout: Some(quic.idle_timeout.unwrap_or_default()), // Unset: derived from the idle timeout the peers negotiate. keep_alive: quic.keep_alive, ..Default::default() @@ -265,8 +265,8 @@ pub fn moq_client_defaults() -> MoqClientConfig { backoff: MoqBackoff { initial: Some(backoff.initial()), multiplier: Some(backoff.multiplier), - max: Some(backoff.max()), - timeout: Some(backoff.timeout()), + max: Some(backoff.max().unwrap_or_default()), + timeout: Some(backoff.timeout().unwrap_or_default()), }, ..Default::default() } diff --git a/rs/moq-ffi/src/test.rs b/rs/moq-ffi/src/test.rs index a5c9b68ac3c..7f14142b6c6 100644 --- a/rs/moq-ffi/src/test.rs +++ b/rs/moq-ffi/src/test.rs @@ -6571,7 +6571,7 @@ async fn client_defaults_are_what_an_unset_config_dials_with() { let defaults = moq_client_defaults(); let connect = moq_tokio::connect::Config::default().resolve(); - assert_eq!(defaults.timeout, Some(connect.timeout)); + assert_eq!(defaults.timeout, connect.timeout); assert_eq!(defaults.race, Some(connect.race)); assert_eq!(defaults.resolution_delay, Some(connect.resolution_delay)); @@ -6584,8 +6584,8 @@ async fn client_defaults_are_what_an_unset_config_dials_with() { assert_eq!(defaults.websocket.enabled, Some(true)); let backoff = moq_tokio::connection::Backoff::default(); assert_eq!(defaults.backoff.initial, Some(backoff.initial())); - assert_eq!(defaults.backoff.max, Some(backoff.max())); - assert_eq!(defaults.backoff.timeout, Some(backoff.timeout())); + assert_eq!(defaults.backoff.max, Some(backoff.max().unwrap_or_default())); + assert_eq!(defaults.backoff.timeout, Some(backoff.timeout().unwrap_or_default())); // The backend picks these, so there is no single value to report. assert_eq!(defaults.tls.system_roots, None); diff --git a/rs/moq-gst/src/connection.rs b/rs/moq-gst/src/connection.rs index e5bf737b7e6..54abd06ca4b 100644 --- a/rs/moq-gst/src/connection.rs +++ b/rs/moq-gst/src/connection.rs @@ -35,7 +35,7 @@ pub(crate) fn properties() -> Vec { glib::ParamSpecUInt64::builder("quic-idle-timeout") .nick("QUIC idle timeout") .blurb("QUIC idle timeout in milliseconds, 0 to disable locally") - .default_value(duration_millis(quic.idle_timeout)) + .default_value(duration_millis(quic.idle_timeout.unwrap_or_default())) .mutable_ready() .build(), glib::ParamSpecUInt64::builder("quic-keep-alive") @@ -70,7 +70,7 @@ impl Settings { "tls-disable-verify" => self.tls_disable_verify.to_value(), "quic-idle-timeout" => duration_millis( self.quic_idle_timeout - .unwrap_or_else(|| moq_tokio::quic::Resolved::default().idle_timeout), + .unwrap_or_else(|| moq_tokio::quic::Resolved::default().idle_timeout.unwrap_or_default()), ) .to_value(), "quic-keep-alive" => duration_millis(self.quic_keep_alive.unwrap_or_default()).to_value(), @@ -165,8 +165,8 @@ mod tests { assert_eq!(connect.tls.insecure, Some(true)); assert_eq!(connect.backoff.timeout, Some(Duration::ZERO.into())); let quic = quic.resolve(); - assert_eq!(quic.idle_timeout, Duration::from_secs(15)); - assert_eq!(quic.keep_alive, Some(Duration::ZERO)); + assert_eq!(quic.idle_timeout, Some(Duration::from_secs(15))); + assert_eq!(quic.keep_alive, None); assert!(quic.keylog.is_some()); settings.set("connect-version", &"moq-lite-99".to_value()); assert!(settings.resolve().unwrap_err().to_string().contains("moq-lite-99")); diff --git a/rs/moq-gst/src/sink/imp.rs b/rs/moq-gst/src/sink/imp.rs index ea0ea5979c5..99912ba0afa 100644 --- a/rs/moq-gst/src/sink/imp.rs +++ b/rs/moq-gst/src/sink/imp.rs @@ -2629,7 +2629,7 @@ mod tests { let resolved = ResolvedSettings::try_from(sink.imp().settings.lock().unwrap().clone()).unwrap(); let quic = super::super::session::quic_config(&resolved).resolve(); - assert_eq!(quic.idle_timeout, Duration::from_secs(15)); + assert_eq!(quic.idle_timeout, Some(Duration::from_secs(15))); assert_eq!(quic.keep_alive, Some(Duration::from_secs(3))); assert!(!sink.property::("quic-keylog")); assert!(quic.keylog.is_none()); @@ -2639,8 +2639,8 @@ mod tests { sink.set_property("quic-keylog", true); let resolved = ResolvedSettings::try_from(sink.imp().settings.lock().unwrap().clone()).unwrap(); let quic = super::super::session::quic_config(&resolved).resolve(); - assert_eq!(quic.idle_timeout, Duration::ZERO); - assert_eq!(quic.keep_alive, Some(Duration::ZERO)); + assert_eq!(quic.idle_timeout, None); + assert_eq!(quic.keep_alive, None); assert!(quic.keylog.is_some()); } diff --git a/rs/moq-relay/src/cluster.rs b/rs/moq-relay/src/cluster.rs index 26ad25d1d1e..3f64329156f 100644 --- a/rs/moq-relay/src/cluster.rs +++ b/rs/moq-relay/src/cluster.rs @@ -2333,7 +2333,7 @@ impl Cluster { bind.set_port(0); connect.bind = Some(bind); } - if connect.backoff.timeout().is_zero() { + if connect.backoff.timeout().is_none() { connect.backoff.timeout = Some(PEER_RETRY.into()); } if target.is_some_and(|target| target.lan) { diff --git a/rs/moq-relay/src/uring.rs b/rs/moq-relay/src/uring.rs index 17bb3701f76..b669a27b013 100644 --- a/rs/moq-relay/src/uring.rs +++ b/rs/moq-relay/src/uring.rs @@ -493,7 +493,8 @@ fn transport(quic: &moq_tokio::quic::Resolved) -> anyhow::Result handover); + assert!(config.resolve().timeout.is_none_or(|timeout| timeout > handover)); let connection = within( "client connects", diff --git a/rs/moq-tokio/src/client.rs b/rs/moq-tokio/src/client.rs index 71d1359272e..60d748443e7 100644 --- a/rs/moq-tokio/src/client.rs +++ b/rs/moq-tokio/src/client.rs @@ -154,7 +154,7 @@ impl Client { let mut policy = moq_net::reconnect::Config::default(); policy.backoff = config.backoff.resolve(); policy.goaway = config.goaway.resolve(); - policy.timeout = Some(resolved.timeout).filter(|timeout| !timeout.is_zero()); + policy.timeout = resolved.timeout; policy.pinned = !config.tls.fingerprint.is_empty(); let mut moq = moq_net::Client::new() diff --git a/rs/moq-tokio/src/connect.rs b/rs/moq-tokio/src/connect.rs index e5e73673adc..fac49466f21 100644 --- a/rs/moq-tokio/src/connect.rs +++ b/rs/moq-tokio/src/connect.rs @@ -764,7 +764,8 @@ impl Config { .resolution_delay .map(Into::into) .unwrap_or(DEFAULT_RESOLUTION_DELAY), - timeout: self.timeout.map(Into::into).unwrap_or(DEFAULT_TIMEOUT), + // A configured zero turns the deadline off. + timeout: Some(self.timeout.map(Into::into).unwrap_or(DEFAULT_TIMEOUT)).filter(|timeout| !timeout.is_zero()), } } } @@ -782,8 +783,8 @@ pub struct Resolved { pub race: std::time::Duration, /// How long the IPv4-only lookup waits for the full DNS answer. pub resolution_delay: std::time::Duration, - /// The deadline one connection attempt gets, dial and handshake together. - pub timeout: std::time::Duration, + /// The deadline one connection attempt gets, dial and handshake together, or `None` for none. + pub timeout: Option, } #[cfg(test)] @@ -835,6 +836,6 @@ mod duration_tests { timeout, "--connect-timeout", |c: &Config| c.resolve().timeout, - |d| d + |d: std::time::Duration| Some(d).filter(|d| !d.is_zero()) ); } diff --git a/rs/moq-tokio/src/connection.rs b/rs/moq-tokio/src/connection.rs index bc00702cce8..813aaa60758 100644 --- a/rs/moq-tokio/src/connection.rs +++ b/rs/moq-tokio/src/connection.rs @@ -167,14 +167,14 @@ impl Backoff { self.resolve().initial } - /// The configured retry-delay cap, or its default; zero leaves the delay uncapped. - pub fn max(&self) -> Duration { - self.resolve().max.unwrap_or_default() + /// The configured retry-delay cap, or its default; `None` leaves the delay uncapped. + pub fn max(&self) -> Option { + self.resolve().max } - /// The retry deadline window, or its default; zero retries forever. - pub fn timeout(&self) -> Duration { - self.resolve().timeout.unwrap_or_default() + /// The retry deadline window, or its default; `None` retries forever. + pub fn timeout(&self) -> Option { + self.resolve().timeout } /// The policy these knobs configure, with each unset one at its default. @@ -1557,7 +1557,7 @@ mod tests { assert_eq!(parsed.backoff.initial, Some((Duration::from_secs(7)).into())); assert_eq!(parsed.backoff.multiplier, 5); assert_eq!(parsed.backoff.max, Some((Duration::from_secs(11)).into())); - assert_eq!(parsed.backoff.timeout(), Duration::ZERO, "0 means retry forever"); + assert_eq!(parsed.backoff.timeout(), None, "0 means retry forever"); // With no flags, the parser defaults resolve to the policy's defaults. let parsed = Wrapper::parse_from(&[]).unwrap(); @@ -3036,7 +3036,7 @@ mod duration_tests { max, "--connect-backoff-max", |c: &Backoff| c.max(), - |d| d + |d: Duration| Some(d).filter(|d| !d.is_zero()) ); crate::cli::duration::test_config_duration!( timeout_set_in_code_beats_parser_default, @@ -3044,7 +3044,7 @@ mod duration_tests { timeout, "--connect-backoff-timeout", |c: &Backoff| c.timeout(), - |d| d + |d: Duration| Some(d).filter(|d| !d.is_zero()) ); crate::cli::duration::test_config_duration!( handover_set_in_code_beats_parser_default, diff --git a/rs/moq-tokio/src/quic.rs b/rs/moq-tokio/src/quic.rs index 88d30fe90ac..9ca9eefd766 100644 --- a/rs/moq-tokio/src/quic.rs +++ b/rs/moq-tokio/src/quic.rs @@ -598,7 +598,7 @@ impl Config { let resolved = self.resolve(); let mut transport = moq_quic::transport::Config::default(); transport.limits = resolved.limits(); - transport.idle_timeout = Some(resolved.idle_timeout); + transport.idle_timeout = resolved.idle_timeout; match transport.validate() { Ok(()) => {} Err(ConfigError::Limits(LimitsError::MaxStreams)) => return Err(crate::Error::StreamsRange), @@ -627,9 +627,14 @@ impl Config { /// first when the config came from a parser: a released spelling would show up /// here as the default rather than the value that was written. pub fn resolve(&self) -> Resolved { - let idle_timeout = self.idle_timeout.map(Into::into).unwrap_or(DEFAULT_IDLE_TIMEOUT); - // Unset stays unset: the backend derives it from the negotiated idle timeout. - let keep_alive = self.keep_alive.map(Into::into); + // A configured zero turns the idle timeout off. + let idle_timeout = Some(self.idle_timeout.map(Into::into).unwrap_or(DEFAULT_IDLE_TIMEOUT)) + .filter(|timeout: &Duration| !timeout.is_zero()); + // Unset or zero stays unset: the backend derives it from the negotiated idle timeout. + let keep_alive = self + .keep_alive + .map(Into::into) + .filter(|interval: &Duration| !interval.is_zero()); Resolved { max_streams: self.max_streams.unwrap_or(DEFAULT_MAX_STREAMS), @@ -672,9 +677,9 @@ pub struct Resolved { pub max_streams: u64, /// GSO override, or `None` to leave the backend default (on). pub gso: Option, - /// Idle timeout. - pub idle_timeout: Duration, - /// Keep-alive interval, `None` or zero to derive it from the negotiated idle timeout. + /// Idle timeout, or `None` to keep a silent peer forever. + pub idle_timeout: Option, + /// Keep-alive interval, or `None` to derive it from the negotiated idle timeout. /// /// Unset by default, since the interval depends on the peer's idle timeout. pub keep_alive: Option, @@ -725,8 +730,7 @@ impl Resolved { /// ours, using moq-quic's 30s default (a 9s interval) when neither peer sets one. #[cfg(feature = "_transport")] pub fn keep_alive_interval(&self) -> Duration { - let idle_timeout = (!self.idle_timeout.is_zero()).then_some(self.idle_timeout); - moq_quic::transport::keep_alive_interval(self.keep_alive, idle_timeout) + moq_quic::transport::keep_alive_interval(self.keep_alive, self.idle_timeout) } /// The flow-control limits as moq-quic and qmux spell them. @@ -782,7 +786,7 @@ mod tests { assert!(Config::default().keep_alive.is_none()); let quic = Config::default().resolve(); assert_eq!(quic.max_streams, DEFAULT_MAX_STREAMS); - assert_eq!(quic.idle_timeout, DEFAULT_IDLE_TIMEOUT); + assert_eq!(quic.idle_timeout, Some(DEFAULT_IDLE_TIMEOUT)); assert_eq!(quic.keep_alive, None); assert!(!quic.mtu_discovery); assert_eq!(quic.gso, None); @@ -1099,7 +1103,7 @@ mod duration_tests { idle_timeout, "--quic-idle-timeout", |c: &Config| c.resolve().idle_timeout, - |d| d + |d: Duration| Some(d).filter(|d| !d.is_zero()) ); crate::cli::duration::test_config_duration!( keep_alive_set_in_code_beats_parser_default, @@ -1107,6 +1111,6 @@ mod duration_tests { keep_alive, "--quic-keep-alive", |c: &Config| c.resolve().keep_alive, - Some + |d: Duration| Some(d).filter(|d| !d.is_zero()) ); } diff --git a/rs/moq-tokio/src/quic/backend.rs b/rs/moq-tokio/src/quic/backend.rs index 60ef70370db..06127f1a14b 100644 --- a/rs/moq-tokio/src/quic/backend.rs +++ b/rs/moq-tokio/src/quic/backend.rs @@ -15,7 +15,7 @@ use std::time::Duration; /// The transport config the resolved quic knobs describe, for either role. fn transport(quic: &Resolved, role: &str) -> Result { let mut transport = driver::transport::Config::default(); - transport.idle_timeout = Some(quic.idle_timeout); + transport.idle_timeout = quic.idle_timeout; transport.keep_alive = quic.keep_alive; // MTU discovery is enabled by default; disable it unless asked. if !quic.mtu_discovery {