Merge pull request #112 from michaelklishin/mk-reachability

Reachability-related (connectivity + authN, authZ) API improvements

Author: michaelklishin

CHANGELOG.md

@@ -2,7 +2,16 @@
 
 ## v0.80.0 (in development)
 
-(no changes yet)
+### Enhancements
+
+ * New `HttpClientError` helpers for "transport-level" connection error classification: `is_connection_error`, `is_timeout`,
+   `is_tls_handshake_error`, `as_reqwest_error`
+ * `Client#probe_reachability` tests whether the node is reachable and the configured credentials are accepted.
+   Returns a `ReachabilityProbeOutcome` enum rather than a `Result` because both outcomes are expected,
+   so using the `?` operator would be semantically wrong
+ * Improved `TagList` ergonomics with `can_access_http_api`, `is_administrator`, `can_access_monitoring_endpoints`
+ * `TagList` now implements `From<Vec<String>>`
+ * `ClientBuilder#with_connect_timeout` sets the TCP connection timeout independently of the overall request timeout
 
 
 ## v0.79.0 (Feb 11, 2026)

src/api/client.rs

@@ -58,6 +58,7 @@ pub struct ClientBuilder<E = &'static str, U = &'static str, P = &'static str> {
     password: P,
     client: Option<HttpClient>,
     retry_settings: RetrySettings,
+    connect_timeout: Option<Duration>,
     request_timeout: Option<Duration>,
 }
 
@@ -82,6 +83,7 @@ impl ClientBuilder {
             password: "guest",
             client: None,
             retry_settings: RetrySettings::default(),
+            connect_timeout: None,
             request_timeout: None,
         }
     }
@@ -122,6 +124,7 @@ where
             password,
             client: self.client,
             retry_settings: self.retry_settings,
+            connect_timeout: self.connect_timeout,
             request_timeout: self.request_timeout,
         }
     }
@@ -140,6 +143,7 @@ where
             password: self.password,
             client: self.client,
             retry_settings: self.retry_settings,
+            connect_timeout: self.connect_timeout,
             request_timeout: self.request_timeout,
         }
     }
@@ -148,7 +152,7 @@ where
     ///
     /// Use a custom HTTP client to configure custom timeouts, proxy settings, TLS configuration.
     ///
-    /// Note: If you provide a custom client, the timeout set via [`with_request_timeout`]
+    /// Note: If you provide a custom client, timeouts set via builder methods
     /// will be ignored. Configure timeouts directly on your custom client instead.
     pub fn with_client(self, client: HttpClient) -> Self {
         ClientBuilder {
@@ -157,6 +161,21 @@ where
         }
     }
 
+    /// Sets the TCP connection timeout.
+    ///
+    /// This timeout applies only to the connection establishment phase (TCP + TLS handshake),
+    /// not to the overall request. Useful for failing fast on unreachable hosts without
+    /// cutting off slow-but-valid responses.
+    ///
+    /// **Important**: this setting is ignored if a custom HTTP client is used via [`with_client`].
+    /// In that case, configure the timeout on the custom client instead.
+    pub fn with_connect_timeout(self, timeout: Duration) -> Self {
+        ClientBuilder {
+            connect_timeout: Some(timeout),
+            ..self
+        }
+    }
+
     /// Sets the request timeout for HTTP operations.
     ///
     /// This timeout applies to the entire request/response cycle, including connection establishment,
@@ -202,6 +221,9 @@ where
             Some(c) => c,
             None => {
                 let mut builder = HttpClient::builder();
+                if let Some(timeout) = self.connect_timeout {
+                    builder = builder.connect_timeout(timeout);
+                }
                 if let Some(timeout) = self.request_timeout {
                     builder = builder.timeout(timeout);
                 }

src/api/mod.rs

@@ -35,6 +35,7 @@ mod parameters;
 mod permissions;
 mod policies;
 mod queues_and_streams;
+mod reachability;
 mod rebalancing;
 mod shovels;
 mod tanzu;

src/api/reachability.rs

@@ -0,0 +1,43 @@
+// Copyright (C) 2023-2025 RabbitMQ Core Team (teamrabbitmq@gmail.com)
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+use std::fmt::Display;
+use std::time::Instant;
+
+use crate::responses::{ReachabilityProbeDetails, ReachabilityProbeOutcome};
+
+use super::client::Client;
+
+impl<E, U, P> Client<E, U, P>
+where
+    E: Display,
+    U: Display,
+    P: Display,
+{
+    /// Tests whether the node is reachable and the configured credentials are accepted.
+    ///
+    /// Calls `GET /api/whoami`. Does not check node health, cluster identity,
+    /// or resource alarms — the caller can compose those after a `Reached` result.
+    pub async fn probe_reachability(&self) -> ReachabilityProbeOutcome {
+        let start = Instant::now();
+
+        match self.current_user().await {
+            Ok(current_user) => ReachabilityProbeOutcome::Reached(ReachabilityProbeDetails {
+                current_user,
+                duration: start.elapsed(),
+            }),
+            Err(e) => ReachabilityProbeOutcome::Unreachable(Box::new(e)),
+        }
+    }
+}

src/blocking_api/client.rs

@@ -57,6 +57,7 @@ pub struct ClientBuilder<E = &'static str, U = &'static str, P = &'static str> {
     password: P,
     client: Option<HttpClient>,
     retry_settings: RetrySettings,
+    connect_timeout: Option<Duration>,
     request_timeout: Option<Duration>,
 }
 
@@ -81,6 +82,7 @@ impl ClientBuilder {
             password: "guest",
             client: None,
             retry_settings: RetrySettings::default(),
+            connect_timeout: None,
             request_timeout: None,
         }
     }
@@ -132,6 +134,7 @@ where
             password,
             client: self.client,
             retry_settings: self.retry_settings,
+            connect_timeout: self.connect_timeout,
             request_timeout: self.request_timeout,
         }
     }
@@ -150,6 +153,7 @@ where
             password: self.password,
             client: self.client,
             retry_settings: self.retry_settings,
+            connect_timeout: self.connect_timeout,
             request_timeout: self.request_timeout,
         }
     }
@@ -158,7 +162,7 @@ where
     ///
     /// Use a custom HTTP client to configure custom timeouts, proxy settings, TLS configuration.
     ///
-    /// Note: If you provide a custom client, the timeout set via [`with_request_timeout`]
+    /// Note: If you provide a custom client, timeouts set via builder methods
     /// will be ignored. Configure timeouts directly on your custom client instead.
     pub fn with_client(self, client: HttpClient) -> Self {
         ClientBuilder {
@@ -167,6 +171,21 @@ where
         }
     }
 
+    /// Sets the TCP connection timeout.
+    ///
+    /// This timeout applies only to the connection establishment phase (TCP + TLS handshake),
+    /// not to the overall request. Useful for failing fast on unreachable hosts without
+    /// cutting off slow-but-valid responses.
+    ///
+    /// **Important**: this setting is ignored if a custom HTTP client is used via [`with_client`].
+    /// In that case, configure the timeout on the custom client instead.
+    pub fn with_connect_timeout(self, timeout: Duration) -> Self {
+        ClientBuilder {
+            connect_timeout: Some(timeout),
+            ..self
+        }
+    }
+
     /// Sets the request timeout for HTTP operations.
     ///
     /// This timeout applies to the entire request/response cycle, including connection establishment,
@@ -212,6 +231,9 @@ where
             Some(c) => c,
             None => {
                 let mut builder = HttpClient::builder();
+                if let Some(timeout) = self.connect_timeout {
+                    builder = builder.connect_timeout(timeout);
+                }
                 if let Some(timeout) = self.request_timeout {
                     builder = builder.timeout(timeout);
                 }

src/blocking_api/mod.rs

@@ -35,6 +35,7 @@ mod parameters;
 mod permissions;
 mod policies;
 mod queues_and_streams;
+mod reachability;
 mod rebalancing;
 mod shovels;
 mod tanzu;

src/blocking_api/reachability.rs

@@ -0,0 +1,43 @@
+// Copyright (C) 2023-2025 RabbitMQ Core Team (teamrabbitmq@gmail.com)
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+use std::fmt::Display;
+use std::time::Instant;
+
+use crate::responses::{ReachabilityProbeDetails, ReachabilityProbeOutcome};
+
+use super::client::Client;
+
+impl<E, U, P> Client<E, U, P>
+where
+    E: Display,
+    U: Display,
+    P: Display,
+{
+    /// Tests whether the node is reachable and the configured credentials are accepted.
+    ///
+    /// Calls `GET /api/whoami`. Does not check node health, cluster identity,
+    /// or resource alarms — the caller can compose those after a `Reached` result.
+    pub fn probe_reachability(&self) -> ReachabilityProbeOutcome {
+        let start = Instant::now();
+
+        match self.current_user() {
+            Ok(current_user) => ReachabilityProbeOutcome::Reached(ReachabilityProbeDetails {
+                current_user,
+                duration: start.elapsed(),
+            }),
+            Err(e) => ReachabilityProbeOutcome::Unreachable(Box::new(e)),
+        }
+    }
+}

src/error.rs

@@ -251,6 +251,58 @@ impl HttpClientError {
         }
     }
 
+    /// Returns true if the error is a connection failure
+    /// that is NOT a TLS handshake error (a hostname resolution failure, TCP connection refused, etc).
+    pub fn is_connection_error(&self) -> bool {
+        matches!(
+            self,
+            HttpClientError::RequestError { error, .. }
+            if error.is_connect() && !self.is_tls_handshake_error()
+        )
+    }
+
+    /// Returns true if the error is a request timeout.
+    pub fn is_timeout(&self) -> bool {
+        matches!(
+            self,
+            HttpClientError::RequestError { error, .. }
+            if error.is_timeout()
+        )
+    }
+
+    /// Returns true if the error is likely a TLS/SSL handshake failure.
+    /// Uses a heuristic on the error chain since reqwest doesn't expose
+    /// a first-class TLS error type.
+    ///
+    /// The patterns below are tested against rustls debug output.
+    /// native-tls may produce different casing; most cases are still
+    /// caught because the error chain typically includes at least one
+    /// of the lowercase or variant-name matches.
+    pub fn is_tls_handshake_error(&self) -> bool {
+        match self {
+            HttpClientError::RequestError { error, .. } if error.is_connect() => {
+                let debug = format!("{error:?}");
+                debug.contains("certificate")
+                    || debug.contains("CertificateRequired")
+                    || debug.contains("HandshakeFailure")
+                    || debug.contains("InvalidCertificate")
+                    || debug.contains("tls")
+                    || debug.contains("TLS")
+                    || debug.contains("ssl")
+                    || debug.contains("SSL")
+            }
+            _ => false,
+        }
+    }
+
+    /// Returns the underlying `reqwest::Error` for transport-level errors.
+    pub fn as_reqwest_error(&self) -> Option<&reqwest::Error> {
+        match self {
+            HttpClientError::RequestError { error, .. } => Some(error),
+            _ => None,
+        }
+    }
+
     /// Returns a user-friendly error message, preferring API-provided details when available.
     pub fn user_message(&self) -> String {
         match self {

src/responses.rs

@@ -128,6 +128,11 @@ pub use consumers::Consumer;
 pub mod users;
 pub use users::{CurrentUser, User, UserLimits};
 
+#[cfg(any(feature = "async", feature = "blocking"))]
+pub mod reachability;
+#[cfg(any(feature = "async", feature = "blocking"))]
+pub use reachability::{ReachabilityProbeDetails, ReachabilityProbeOutcome};
+
 #[derive(Debug, Serialize, Deserialize, Clone, PartialEq, Eq, Hash)]
 pub struct TagList(pub Vec<String>);
 
@@ -151,6 +156,38 @@ impl TagList {
     pub fn iter_mut(&mut self) -> std::slice::IterMut<'_, String> {
         self.0.iter_mut()
     }
+
+    /// Returns true if the user can access the HTTP API.
+    ///
+    /// RabbitMQ grants HTTP API access to users with any of
+    /// these tags: `management`, `monitoring`, `policymaker`, or `administrator`.
+    pub fn can_access_http_api(&self) -> bool {
+        self.0.iter().any(|t| {
+            matches!(
+                t.as_str(),
+                "management" | "monitoring" | "policymaker" | "administrator"
+            )
+        })
+    }
+
+    /// Returns true if the user has the `administrator` tag.
+    pub fn is_administrator(&self) -> bool {
+        self.contains("administrator")
+    }
+
+    /// Returns true if the user has monitoring-level access
+    /// (`monitoring` or `administrator`).
+    pub fn can_access_monitoring_endpoints(&self) -> bool {
+        self.0
+            .iter()
+            .any(|t| matches!(t.as_str(), "monitoring" | "administrator"))
+    }
+}
+
+impl From<Vec<String>> for TagList {
+    fn from(v: Vec<String>) -> Self {
+        TagList(v)
+    }
 }
 
 impl Deref for TagList {