Improve HttpClient in Rust

- Add HttpStatus type with convenience methods
- Add tests

Author: cjdsellers

nautilus_core/network/benches/test_client.rs

@@ -36,7 +36,7 @@ async fn main() {
 
         let resp = futures::future::join_all(reqs.drain(0..)).await;
         assert!(resp.iter().all(|res| if let Ok(resp) = res {
-            resp.status == 200
+            resp.status.is_success()
         } else {
             false
         }));

nautilus_core/network/src/http.rs

@@ -18,14 +18,85 @@
 use std::{collections::HashMap, hash::Hash, str::FromStr, sync::Arc, time::Duration};
 
 use bytes::Bytes;
-use http::HeaderValue;
+use http::{status::InvalidStatusCode, HeaderValue, StatusCode};
 use reqwest::{
     header::{HeaderMap, HeaderName},
     Method, Response, Url,
 };
 
 use crate::ratelimiter::{clock::MonotonicClock, quota::Quota, RateLimiter};
 
+/// Represents a HTTP status code.
+///
+/// Wraps [`http::StatusCode`] to expose a Python-compatible type and reuse
+/// its validation and convenience methods.
+#[derive(Clone, Debug)]
+#[cfg_attr(
+    feature = "python",
+    pyo3::pyclass(module = "nautilus_trader.core.nautilus_pyo3.network")
+)]
+pub struct HttpStatus {
+    inner: StatusCode,
+}
+
+impl HttpStatus {
+    /// Create a new [`HttpStatus`] instance from a given [`StatusCode`].
+    pub fn new(code: StatusCode) -> Self {
+        Self { inner: code }
+    }
+
+    /// Attempts to construct a [`HttpStatus`] from a `u16`.
+    ///
+    /// Returns an error if the code is not in the valid `100..999` range.
+    pub fn from(code: u16) -> Result<Self, InvalidStatusCode> {
+        Ok(Self {
+            inner: StatusCode::from_u16(code)?,
+        })
+    }
+
+    /// Returns the status code as a `u16` (e.g., `200` for OK).
+    #[inline]
+    pub const fn as_u16(&self) -> u16 {
+        self.inner.as_u16()
+    }
+
+    /// Returns the three-digit ASCII representation of this status (e.g., `"200"`).
+    #[inline]
+    pub fn as_str(&self) -> &str {
+        self.inner.as_str()
+    }
+
+    /// Checks if this status is in the 1xx (informational) range.
+    #[inline]
+    pub fn is_informational(&self) -> bool {
+        self.inner.is_informational()
+    }
+
+    /// Checks if this status is in the 2xx (success) range.
+    #[inline]
+    pub fn is_success(&self) -> bool {
+        self.inner.is_success()
+    }
+
+    /// Checks if this status is in the 3xx (redirection) range.
+    #[inline]
+    pub fn is_redirection(&self) -> bool {
+        self.inner.is_redirection()
+    }
+
+    /// Checks if this status is in the 4xx (client error) range.
+    #[inline]
+    pub fn is_client_error(&self) -> bool {
+        self.inner.is_client_error()
+    }
+
+    /// Checks if this status is in the 5xx (server error) range.
+    #[inline]
+    pub fn is_server_error(&self) -> bool {
+        self.inner.is_server_error()
+    }
+}
+
 /// Represents the HTTP methods supported by the `HttpClient`.
 #[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
 #[cfg_attr(
@@ -63,18 +134,17 @@ impl Into<Method> for HttpMethod {
     pyo3::pyclass(module = "nautilus_trader.core.nautilus_pyo3.network")
 )]
 pub struct HttpResponse {
-    /// The HTTP status code returned by the server.
-    pub status: u16,
-    /// The headers returned by the server as a map of key-value pairs.
+    /// The HTTP status code.
+    pub status: HttpStatus,
+    /// The response headers as a map of key-value pairs.
     pub headers: HashMap<String, String>,
-    /// The body of the response as raw bytes.
+    /// The raw response body.
     pub body: Bytes,
 }
 
-/// Represents errors that can occur when using the `HttpClient`.
+/// Errors returned by the HTTP client.
 ///
-/// This enum provides variants for general HTTP errors and timeout errors,
-/// allowing for more granular error handling.
+/// Includes generic transport errors and timeouts.
 #[derive(thiserror::Error, Debug)]
 pub enum HttpClientError {
     #[error("HTTP error occurred: {0}")]
@@ -100,7 +170,10 @@ impl From<String> for HttpClientError {
     }
 }
 
-/// A high-performance HTTP client with rate limiting and timeout capabilities.
+/// An HTTP client that supports rate limiting and timeouts.
+///
+/// Built on `reqwest` for async I/O. Allows per-endpoint and default quotas
+/// through [`RateLimiter`].
 ///
 /// This struct is designed to handle HTTP requests efficiently, providing
 /// support for rate limiting, timeouts, and custom headers. The client is
@@ -152,19 +225,17 @@ impl HttpClient {
         }
     }
 
-    /// Send an HTTP request.
+    /// Sends an HTTP request.
     ///
-    /// `method`: The HTTP method to call.
-    /// `url`: The request is sent to this url.
-    /// `headers`: The header key value pairs in the request.
-    /// `body`: The bytes sent in the body of request.
-    /// `keys`: The keys used for rate limiting the request.
+    /// - `method`: The [`Method`] to use (GET, POST, etc.).
+    /// - `url`: The target URL.
+    /// - `headers`: Additional headers for this request.
+    /// - `body`: Optional request body.
+    /// - `keys`: Rate-limit keys to control request frequency.
+    /// - `timeout_secs`: Optional request timeout in seconds.
     ///
     /// # Example
-    ///
-    /// When a request is made the URL should be split into all relevant keys within it.
-    ///
-    /// For request /foo/bar, should pass keys ["foo/bar", "foo"] for rate limiting.
+    /// If requesting `/foo/bar`, pass rate-limit keys `["foo/bar", "foo"]`.
     #[allow(clippy::too_many_arguments)]
     pub async fn request(
         &self,
@@ -184,9 +255,9 @@ impl HttpClient {
     }
 }
 
-/// A high-performance `HttpClient` for HTTP requests.
+/// Internal implementation backing [`HttpClient`].
 ///
-/// The client is backed by a hyper Client which keeps connections alive and
+/// The client is backed by a [`reqwest::Client`] which keeps connections alive and
 /// can be cloned cheaply. The client also has a list of header fields to
 /// extract from the response.
 ///
@@ -199,13 +270,13 @@ pub struct InnerHttpClient {
 }
 
 impl InnerHttpClient {
-    /// Sends an HTTP request with the specified method, URL, headers, and body.
+    /// Sends an HTTP request and returns an [`HttpResponse`].
     ///
-    /// - `method`: The HTTP method to use (e.g., GET, POST).
-    /// - `url`: The URL to send the request to.
-    /// - `headers`: A map of header key-value pairs to include in the request.
-    /// - `body`: An optional body for the request, represented as a byte vector.
-    /// - `timeout_secs`: An optional timeout for the request in seconds.
+    /// - `method`: The HTTP method (e.g. GET, POST).
+    /// - `url`: The target URL.
+    /// - `headers`: Extra headers to send.
+    /// - `body`: Optional request body.
+    /// - `timeout_secs`: Optional request timeout in seconds.
     pub async fn send_request(
         &self,
         method: Method,
@@ -266,7 +337,7 @@ impl InnerHttpClient {
             .filter_map(|(key, val)| val.to_str().map(|v| (key, v)).ok())
             .map(|(k, v)| (k.clone(), v.to_owned()))
             .collect();
-        let status = response.status().as_u16();
+        let status = HttpStatus::new(response.status());
         let body = response.bytes().await.map_err(HttpClientError::from)?;
 
         Ok(HttpResponse {
@@ -323,6 +394,14 @@ mod tests {
             .route("/post", post(|| async { StatusCode::OK }))
             .route("/patch", patch(|| async { StatusCode::OK }))
             .route("/delete", delete(|| async { StatusCode::OK }))
+            .route("/notfound", get(|| async { StatusCode::NOT_FOUND }))
+            .route(
+                "/slow",
+                get(|| async {
+                    tokio::time::sleep(Duration::from_secs(2)).await;
+                    "Eventually responded"
+                }),
+            )
     }
 
     async fn start_test_server() -> Result<SocketAddr, Box<dyn std::error::Error + Send + Sync>> {
@@ -350,7 +429,7 @@ mod tests {
             .await
             .unwrap();
 
-        assert_eq!(response.status, StatusCode::OK);
+        assert!(response.status.is_success());
         assert_eq!(String::from_utf8_lossy(&response.body), "hello-world!");
     }
 
@@ -371,7 +450,7 @@ mod tests {
             .await
             .unwrap();
 
-        assert_eq!(response.status, StatusCode::OK);
+        assert!(response.status.is_success());
     }
 
     #[tokio::test]
@@ -405,7 +484,7 @@ mod tests {
             .await
             .unwrap();
 
-        assert_eq!(response.status, StatusCode::OK);
+        assert!(response.status.is_success());
     }
 
     #[tokio::test]
@@ -425,7 +504,7 @@ mod tests {
             .await
             .unwrap();
 
-        assert_eq!(response.status, StatusCode::OK);
+        assert!(response.status.is_success());
     }
 
     #[tokio::test]
@@ -445,6 +524,41 @@ mod tests {
             .await
             .unwrap();
 
-        assert_eq!(response.status, StatusCode::OK);
+        assert!(response.status.is_success());
+    }
+
+    #[tokio::test]
+    async fn test_not_found() {
+        let addr = start_test_server().await.unwrap();
+        let url = format!("http://{addr}/notfound");
+        let client = InnerHttpClient::default();
+
+        let response = client
+            .send_request(reqwest::Method::GET, url, None, None, None)
+            .await
+            .unwrap();
+
+        assert!(response.status.is_client_error());
+        assert_eq!(response.status.as_u16(), 404);
+    }
+
+    #[tokio::test]
+    async fn test_timeout() {
+        let addr = start_test_server().await.unwrap();
+        let url = format!("http://{addr}/slow");
+        let client = InnerHttpClient::default();
+
+        // We'll set a 1-second timeout for a route that sleeps 2 seconds
+        let result = client
+            .send_request(reqwest::Method::GET, url, None, None, Some(1))
+            .await;
+
+        match result {
+            Err(HttpClientError::TimeoutError(msg)) => {
+                println!("Got expected timeout error: {msg}");
+            }
+            Err(other) => panic!("Expected a timeout error, got: {other:?}"),
+            Ok(resp) => panic!("Expected a timeout error, but got a successful response: {resp:?}"),
+        }
     }
 }

nautilus_core/network/src/python/http.rs

@@ -19,10 +19,11 @@ use std::{
 };
 
 use bytes::Bytes;
+use nautilus_core::python::to_pyvalue_err;
 use pyo3::{create_exception, exceptions::PyException, prelude::*};
 
 use crate::{
-    http::{HttpClient, HttpClientError, HttpMethod, HttpResponse},
+    http::{HttpClient, HttpClientError, HttpMethod, HttpResponse, HttpStatus},
     ratelimiter::quota::Quota,
 };
 
@@ -54,19 +55,18 @@ impl HttpMethod {
 #[pymethods]
 impl HttpResponse {
     #[new]
-    #[must_use]
-    pub fn py_new(status: u16, body: Vec<u8>) -> Self {
-        Self {
-            status,
+    pub fn py_new(status: u16, body: Vec<u8>) -> PyResult<Self> {
+        Ok(Self {
+            status: HttpStatus::from(status).map_err(to_pyvalue_err)?,
             headers: HashMap::new(),
             body: Bytes::from(body),
-        }
+        })
     }
 
     #[getter]
     #[pyo3(name = "status")]
     pub const fn py_status(&self) -> u16 {
-        self.status
+        self.status.as_u16()
     }
 
     #[getter]
@@ -118,7 +118,7 @@ impl HttpClient {
         Self::new(default_headers, header_keys, keyed_quotas, default_quota)
     }
 
-    /// Send an HTTP request.
+    /// Sends an HTTP request.
     ///
     /// `method`: The HTTP method to call.
     /// `url`: The request is sent to this url.