Add integration and unit tests for monitoring JSON API endpoints

Closes #329

Exercise every JSON REST API endpoint against live SV2 topologies and
strengthen unit-test coverage for edge cases.

Integration tests (monitoring_integration.rs):
- 15 new tests covering /, /api/v1/global, /api/v1/server,
  /api/v1/server/channels, /api/v1/clients, /api/v1/clients/{id},
  /api/v1/clients/{id}/channels, /api/v1/sv1/clients, and
  /api/v1/sv1/clients/{id} for both Pool and tProxy topologies
- Topology setup helpers (PoolWithSv2Miner, TproxyWithSv1Miner)
  eliminate duplicated boilerplate across tests
- 404 endpoints assert both HTTP status code and JSON error body via
  new assert_api_not_found helper

Assertion helpers (prometheus_metrics_assertions.rs):
- fetch_api_json: parse JSON API response
- fetch_api_with_status: return (status_code, json) without panicking
  on non-2xx, enabling 404 testing
- poll_until_api_field_gte: poll JSON endpoint until a field reaches a
  threshold (analogous to poll_until_metric_gte for Prometheus)
- assert_api_root, assert_api_global: reusable structure checks
- assert_api_not_found: verify HTTP 404 + error field
- POLL_TIMEOUT constant to reduce repetition

HTTP helper (utils.rs):
- make_get_request_with_status: returns (status, body) without panicking
  on 4xx responses, unlike make_get_request

Unit tests (http_server.rs):
- 11 new tests for pagination boundaries (limit=0, offset beyond total,
  limit exceeding MAX_LIMIT), missing data sources returning 404,
  invalid/non-existent client IDs, SV1 data in global endpoint, and
  Prometheus metrics with no sources

Dependencies:
- Add serde_json to integration-tests for JSON parsing

Author: Eric Price

integration-tests/Cargo.lock

@@ -24,6 +24,7 @@ tokio-util = { version = "0.7", default-features = false }
 tracing = { version = "0.1.41", default-features = false }
 tracing-subscriber = { version = "0.3.19", default-features = false }
 hex = "0.4.3"
+serde_json = "1"
 
 # Direct dependencies kept only for the embedded `mining_device` module.
 # Remove this block when removing:

integration-tests/Cargo.toml

@@ -2,6 +2,12 @@
 //! exposed by SV2 components during integration tests.
 
 use std::net::SocketAddr;
+use std::time::Duration;
+
+/// Default timeout used when polling for eventually-consistent data.
+/// Needs to be generous enough for the monitoring snapshot cache (1s refresh) to populate
+/// under CI load, where components may take several seconds to complete handshakes.
+pub const POLL_TIMEOUT: Duration = Duration::from_secs(15);
 
 /// Fetch the raw Prometheus text-format metrics from a component's `/metrics` endpoint.
 /// Uses `spawn_blocking` to avoid blocking the tokio runtime with synchronous HTTP calls.
@@ -27,6 +33,124 @@ pub async fn fetch_api(monitoring_addr: SocketAddr, path: &str) -> String {
     .expect("spawn_blocking for fetch_api panicked")
 }
 
+/// Fetch a JSON API endpoint and parse the response into a `serde_json::Value`.
+pub async fn fetch_api_json(monitoring_addr: SocketAddr, path: &str) -> serde_json::Value {
+    let body = fetch_api(monitoring_addr, path).await;
+    serde_json::from_str(&body).unwrap_or_else(|e| {
+        panic!(
+            "Failed to parse JSON from {} response: {}\nBody: {}",
+            path, e, body
+        )
+    })
+}
+
+/// Fetch a JSON API endpoint returning both the HTTP status code and parsed JSON body.
+/// Unlike `fetch_api_json`, this does **not** panic on non-2xx responses, so it can be
+/// used to test error endpoints (e.g. 404).
+pub async fn fetch_api_with_status(
+    monitoring_addr: SocketAddr,
+    path: &str,
+) -> (i32, serde_json::Value) {
+    let url = format!("http://{}{}", monitoring_addr, path);
+    tokio::task::spawn_blocking(move || {
+        let (status, bytes) = crate::utils::http::make_get_request_with_status(&url, 5);
+        let body = String::from_utf8(bytes).expect("api response should be valid UTF-8");
+        let json: serde_json::Value = serde_json::from_str(&body).unwrap_or_else(|e| {
+            panic!(
+                "Failed to parse JSON from {} (status {}): {}\nBody: {}",
+                url, status, e, body
+            )
+        });
+        (status, json)
+    })
+    .await
+    .expect("spawn_blocking for fetch_api_with_status panicked")
+}
+
+/// Assert that an endpoint returns HTTP 404 with a JSON `{"error": "..."}` body.
+pub async fn assert_api_not_found(monitoring_addr: SocketAddr, path: &str) {
+    let (status, json) = fetch_api_with_status(monitoring_addr, path).await;
+    assert_eq!(
+        status, 404,
+        "{} should return HTTP 404, got {} with body: {}",
+        path, status, json
+    );
+    assert!(
+        json["error"].is_string(),
+        "{} should return JSON with 'error' field, got: {}",
+        path,
+        json
+    );
+}
+
+/// Poll a JSON API endpoint until a numeric field at `json_pointer` (RFC 6901, e.g.
+/// `"/sv2_clients/total_clients"`) reaches `>= min`. Returns the full JSON value once
+/// satisfied. Panics if the condition is not met within `timeout`.
+///
+/// This is the JSON equivalent of `poll_until_metric_gte` — use it for endpoints whose
+/// data only appears after the monitoring snapshot cache has refreshed.
+pub async fn poll_until_api_field_gte(
+    monitoring_addr: SocketAddr,
+    path: &str,
+    json_pointer: &str,
+    min: f64,
+    timeout: std::time::Duration,
+) -> serde_json::Value {
+    let deadline = tokio::time::Instant::now() + timeout;
+    loop {
+        // Use fetch_api_with_status so that transient non-2xx responses (e.g. 404
+        // before the snapshot cache has populated) are retried instead of panicking.
+        let (status, json) = fetch_api_with_status(monitoring_addr, path).await;
+        if (200..300).contains(&status) {
+            if let Some(val) = json.pointer(json_pointer) {
+                let num = val.as_f64().unwrap_or(0.0);
+                if num >= min {
+                    return json;
+                }
+            }
+        }
+        if tokio::time::Instant::now() >= deadline {
+            panic!(
+                "JSON field '{}' at {} never reached >= {} within {:?}. Last status: {}. Last response:\n{}",
+                json_pointer,
+                path,
+                min,
+                timeout,
+                status,
+                serde_json::to_string_pretty(&json).unwrap_or_default()
+            );
+        }
+        tokio::time::sleep(std::time::Duration::from_millis(500)).await;
+    }
+}
+
+/// Assert that the root endpoint (`/`) returns the expected API listing structure.
+pub async fn assert_api_root(monitoring_addr: SocketAddr) {
+    let json = fetch_api_json(monitoring_addr, "/").await;
+    assert_eq!(
+        json["service"], "SRI Monitoring API",
+        "Root endpoint should return service name, got: {}",
+        json
+    );
+    assert!(
+        json["endpoints"].is_object(),
+        "Root endpoint should list endpoints, got: {}",
+        json
+    );
+}
+
+/// Assert that `/api/v1/global` returns a valid response with the expected structure.
+/// Returns the parsed JSON for further assertions.
+pub async fn assert_api_global(monitoring_addr: SocketAddr) -> serde_json::Value {
+    let json = fetch_api_json(monitoring_addr, "/api/v1/global").await;
+    assert!(
+        json["uptime_secs"].as_u64().is_some(),
+        "Global endpoint should contain uptime_secs, got: {}",
+        json
+    );
+    json
+}
+
 /// Parse a specific metric value from Prometheus text format.
 /// Returns `None` if the metric line is not found.
 ///

integration-tests/lib/prometheus_metrics_assertions.rs

@@ -407,6 +407,43 @@ pub fn into_static(m: AnyMessage<'_>) -> AnyMessage<'static> {
 }
 
 pub mod http {
+    /// Make a GET request that returns both the HTTP status code and the response body.
+    /// Unlike `make_get_request`, this does NOT panic on non-2xx status codes (e.g. 404),
+    /// making it suitable for testing API error responses.
+    /// Only retries on 5xx errors or connection failures.
+    pub fn make_get_request_with_status(url: &str, retries: usize) -> (i32, Vec<u8>) {
+        for attempt in 1..=retries {
+            let response = minreq::get(url).send();
+            match response {
+                Ok(res) => {
+                    let status_code = res.status_code;
+                    if (500..600).contains(&status_code) {
+                        eprintln!(
+                            "Attempt {attempt}: URL {url} returned a server error code {status_code}"
+                        );
+                    } else {
+                        return (status_code, res.as_bytes().to_vec());
+                    }
+                }
+                Err(err) => {
+                    eprintln!(
+                        "Attempt {}: Failed to fetch URL {}: {:?}",
+                        attempt + 1,
+                        url,
+                        err
+                    );
+                }
+            }
+
+            if attempt < retries {
+                let delay = 1u64 << (attempt - 1);
+                eprintln!("Retrying in {delay} seconds (exponential backoff)...");
+                std::thread::sleep(std::time::Duration::from_secs(delay));
+            }
+        }
+        panic!("Cannot reach URL {url} after {retries} attempts");
+    }
+
     pub fn make_get_request(download_url: &str, retries: usize) -> Vec<u8> {
         for attempt in 1..=retries {
             let response = minreq::get(download_url).send();