feat: dual stack probe if needed (ipv4+v6)

Author: uplg

CHANGELOG.md

@@ -5,6 +5,23 @@ All notable changes to this project are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+### Added
+
+- **Dual-stack verification** (`dual_stack = true`): http, tcp and icmp
+  monitors can probe IPv4 and IPv6 separately (concurrently) and require both
+  families to pass - catching the service whose IPv6 has been silently dead
+  behind a healthy IPv4, or the reverse. One broken family confirms down with
+  the culprit named ("IPv6 failing: connection timed out (IPv4 ok)") and the
+  surviving family's latency recorded; when both families answer, the recorded
+  latency is the slower path's, so `degraded_over_ms` judges the worst case.
+  Anonymous viewers see the collapsed category ("IPv6 failing (IPv4 ok)").
+  Requires a hostname target (an IP literal has a single family), cannot be
+  combined with `proxy`, and the probing host itself needs working IPv4 and
+  IPv6. HTTP probes are steered per family by binding the client's local end
+  to the family's unspecified address.
+
 ## [0.4.1] - 2026-06-10
 
 Security hardening release. See [UPGRADES.md](UPGRADES.md) for the six

README.md

@@ -36,6 +36,12 @@ Named after the **Horai**, the Greek goddesses of the hours.
   annotated with root cause vs. symptom: _"caused by X"_ when an upstream it depends on
   is also down, or _"impacts: A, B, C"_ (the blast radius) when its upstreams are all
   healthy and it is the root cause. The dependency graph is validated acyclic at load.
+- **Dual-stack verification** - `dual_stack = true` probes IPv4 *and* IPv6
+  separately and requires both: the classic silent failure is a service whose
+  IPv6 has been dead for weeks behind a healthy IPv4 (or the reverse), invisible
+  to every single-connection check. One broken family alerts with the culprit
+  named - _"IPv6 failing: connection timed out (IPv4 ok)"_. Works for HTTP, TCP
+  and ICMP monitors with a hostname target.
 - **Root-cause alert grouping** - when a database takes ten services down with it,
   you get **one notification** (the root cause, with its blast radius), not eleven:
   dependent monitors confirmed down within the grouping window fold into their

config.example.toml

@@ -194,6 +194,11 @@ depends_on = ["api"]
 # public_error_detail = true  # optional; publish the raw failure reason (default:
 #                             # anonymous viewers see a safe category only)
 # cert_pin = "abc123..."  # optional; SHA-256 of leaf public key (detects cert changes)
+# dual_stack = true       # optional; probe IPv4 AND IPv6 and require both - catches
+#                         # the service whose IPv6 has been dead for weeks behind a
+#                         # healthy IPv4 ("IPv6 failing: connection timed out (IPv4
+#                         # ok)"). http/tcp/icmp with a hostname target; no proxy.
+#                         # The probing host itself needs working IPv4 and IPv6.
 
 [[monitors]]
 id = "api"

crates/hora-core/src/config.rs

@@ -620,6 +620,14 @@ pub struct Monitor {
     /// record every raw probe result. Not applicable to push monitors.
     #[serde(default)]
     pub probe_retries: Option<u32>,
+    /// Probe both address families and require both to pass - the classic
+    /// silent failure is a service whose IPv6 has been dead for weeks behind a
+    /// healthy IPv4. One broken family marks the monitor down, naming it in
+    /// the reason ("IPv6 failing: connection timed out (IPv4 ok)"). For http,
+    /// tcp and icmp monitors with a hostname target; not combinable with
+    /// `proxy`. The probing host itself needs working IPv4 *and* IPv6.
+    #[serde(default)]
+    pub dual_stack: Option<bool>,
     /// Restrict this monitor's alerts to these channel names (e.g. `["ops"]`).
     /// Unset = every configured channel.
     #[serde(default)]
@@ -714,6 +722,7 @@ impl std::fmt::Debug for Monitor {
             .field("json_expected", &self.json_expected)
             .field("max_body_kb", &self.max_body_kb)
             .field("probe_retries", &self.probe_retries)
+            .field("dual_stack", &self.dual_stack)
             .field("notify", &self.notify)
             .field("proxy", &self.proxy.as_deref().map(redact_url_credentials))
             .field("push_token", &self.push_token)
@@ -762,6 +771,12 @@ impl Monitor {
         Duration::from_secs(self.interval_secs)
     }
 
+    /// Whether this monitor probes both address families (default off).
+    #[must_use]
+    pub fn dual_stack(&self) -> bool {
+        self.dual_stack.unwrap_or(false)
+    }
+
     /// Whether this monitor should have its TLS certificate expiry checked.
     #[must_use]
     pub fn checks_cert(&self) -> bool {
@@ -1344,10 +1359,49 @@ fn validate_monitor_io(monitor: &Monitor) -> anyhow::Result<()> {
             monitor.id
         );
     }
+    if monitor.dual_stack() {
+        validate_dual_stack(monitor)?;
+    }
     validate_schedule_and_slo(monitor)?;
     Ok(())
 }
 
+/// `dual_stack` needs a probe that can be steered per address family: an
+/// active kind, no proxy in the way, and a hostname target (an IP literal has
+/// a single family by construction). Runs after the per-kind target checks,
+/// so the target is already known to be well-shaped.
+fn validate_dual_stack(monitor: &Monitor) -> anyhow::Result<()> {
+    anyhow::ensure!(
+        matches!(monitor.kind, Kind::Http | Kind::Tcp | Kind::Icmp),
+        "monitor {}: dual_stack requires an http, tcp or icmp monitor",
+        monitor.id
+    );
+    anyhow::ensure!(
+        monitor.proxy.is_none(),
+        "monitor {}: dual_stack cannot go through a proxy (only the proxy hop's family would be tested)",
+        monitor.id
+    );
+    let host = match monitor.kind {
+        Kind::Http => reqwest::Url::parse(&monitor.target)
+            .ok()
+            .and_then(|url| url.host_str().map(str::to_owned)),
+        Kind::Tcp => monitor
+            .target
+            .rsplit_once(':')
+            .map(|(host, _port)| host.to_owned()),
+        _ => Some(monitor.target.clone()),
+    };
+    // URL and tcp hosts may carry an IPv6 literal in brackets.
+    let host = host.unwrap_or_default();
+    let bare = host.trim_start_matches('[').trim_end_matches(']');
+    anyhow::ensure!(
+        bare.parse::<std::net::IpAddr>().is_err(),
+        "monitor {}: dual_stack requires a hostname target (an IP literal has a single address family)",
+        monitor.id
+    );
+    Ok(())
+}
+
 /// Validate the push `schedule`/`grace_secs` pair and the availability SLO
 /// fields. The cron expression is parsed here so a typo fails at load, not at
 /// the first missed heartbeat.
@@ -1708,6 +1762,59 @@ mod tests {
         assert!(error.contains("require an http monitor"), "got: {error}");
     }
 
+    #[test]
+    fn dual_stack_validation() {
+        let base = |body: &str| {
+            format!(
+                r#"
+                [page]
+                [server]
+                [[monitors]]
+                id = "x"
+                name = "X"
+                interval_secs = 60
+                dual_stack = true
+                {body}
+            "#
+            )
+        };
+
+        // Hostname targets pass for the three active kinds.
+        for body in [
+            "target = \"https://example.com\"",
+            "kind = \"tcp\"\ntarget = \"db.example.com:5432\"",
+            "kind = \"icmp\"\ntarget = \"gw.example.com\"",
+        ] {
+            validate(&parse(&base(body))).expect("hostname target valid");
+        }
+
+        // An IP literal has a single family - rejected, brackets included.
+        for body in [
+            "target = \"https://192.0.2.1/health\"",
+            "target = \"https://[2001:db8::1]/health\"",
+            "kind = \"tcp\"\ntarget = \"192.0.2.1:5432\"",
+            "kind = \"icmp\"\ntarget = \"2001:db8::1\"",
+        ] {
+            let error = validate(&parse(&base(body))).unwrap_err().to_string();
+            assert!(error.contains("requires a hostname"), "got: {error}");
+        }
+
+        // Wrong kind, and proxy combination.
+        let error = validate(&parse(&base("kind = \"dns\"\ntarget = \"example.com\"")))
+            .unwrap_err()
+            .to_string();
+        assert!(
+            error.contains("requires an http, tcp or icmp monitor"),
+            "got: {error}"
+        );
+        let error = validate(&parse(&base(
+            "target = \"https://example.com\"\nproxy = \"http://127.0.0.1:8080\"",
+        )))
+        .unwrap_err()
+        .to_string();
+        assert!(error.contains("cannot go through a proxy"), "got: {error}");
+    }
+
     #[test]
     fn maintenance_window_mutes_selected_monitor() {
         let config = parse(

crates/hora-core/src/http.rs

@@ -13,7 +13,7 @@ use reqwest::redirect::Policy;
 ///
 /// Returns an error if the proxy URL is invalid or the client cannot be built.
 pub fn client(proxy: Option<&str>) -> reqwest::Result<Client> {
-    build(proxy, Policy::default())
+    build(proxy, Policy::default(), None)
 }
 
 /// Like [`client`], but never auto-follows redirects: probes follow them
@@ -26,13 +26,31 @@ pub fn client(proxy: Option<&str>) -> reqwest::Result<Client> {
 ///
 /// Returns an error if the proxy URL is invalid or the client cannot be built.
 pub fn probe_client(proxy: Option<&str>) -> reqwest::Result<Client> {
-    build(proxy, Policy::none())
+    build(proxy, Policy::none(), None)
 }
 
-fn build(proxy: Option<&str>, redirect: Policy) -> reqwest::Result<Client> {
+/// Like [`probe_client`], but restricted to one address family by binding the
+/// local end to `local` (the family's unspecified address): the connector then
+/// only attempts resolved addresses of that family. Used by dual-stack probes;
+/// never proxied - config validation rejects the combination, since through a
+/// proxy only the proxy hop's family would be tested.
+///
+/// # Errors
+///
+/// Returns an error if the client cannot be built.
+pub fn probe_client_family(local: std::net::IpAddr) -> reqwest::Result<Client> {
+    build(None, Policy::none(), Some(local))
+}
+
+fn build(
+    proxy: Option<&str>,
+    redirect: Policy,
+    local: Option<std::net::IpAddr>,
+) -> reqwest::Result<Client> {
     let mut builder = Client::builder()
         .user_agent(concat!("hora/", env!("CARGO_PKG_VERSION")))
         .redirect(redirect)
+        .local_address(local)
         // Backstop for requests without a per-request timeout (notifiers); probes
         // override this with the monitor's own timeout.
         .timeout(Duration::from_secs(15))