hexz_core/store/http/

async_client.rs

//! HTTP storage backend with embedded Tokio runtime.
//!
//! This module provides an HTTP storage backend that wraps the `reqwest` async
//! client in an embedded Tokio runtime. This allows the backend to present a
//! synchronous `StorageBackend` interface while leveraging async I/O internally
//! for efficient concurrent operations.
//!
//! # Architecture
//!
//! The [`HttpBackend`] embeds a Tokio runtime (`Arc<Runtime>`) and uses
//! `runtime.block_on()` to execute async operations synchronously. This design:
//! - Maintains compatibility with the synchronous `StorageBackend` trait
//! - Enables efficient connection pooling and concurrent requests via `reqwest`
//! - Provides async benefits (low memory overhead per connection) without requiring
//!   callers to use async/await
//!
//! # Redirect Handling
//!
//! reqwest's built-in redirect policy drops certain headers (including `Range`)
//! on cross-origin redirects. Since CDNs like GitHub Releases → Azure Blob
//! require cross-origin redirects with range headers, this backend disables
//! auto-redirects and follows them manually, re-sending all headers on each hop.
//!
//! # Thread Safety
//!
//! The backend is fully thread-safe (`Send + Sync`):
//! - The `reqwest::Client` is designed for concurrent use
//! - The `Arc<Runtime>` is shared safely across threads
//! - Multiple threads can call `read_exact()` concurrently without coordination
//!
//! # Security
//!
//! This backend validates URLs to prevent SSRF attacks:
//! - Blocks access to localhost and private networks by default
//! - Set `allow_restricted: true` only in trusted environments
//! - See [`validate_url`](crate::store::utils::validate_url) for details
//!
//! # Examples
//!
//! ```no_run
//! use hexz_core::store::http::HttpBackend;
//! use hexz_core::store::StorageBackend;
//!
//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
//! let backend = HttpBackend::new(
//!     "https://cdn.example.com/snapshots/data.hxz".to_string(),
//!     false // block restricted IPs
//! )?;
//!
//! println!("Snapshot size: {} bytes", backend.len());
//!
//! let header = backend.read_exact(0, 512)?;
//! assert_eq!(header.len(), 512);
//! # Ok(())
//! # }
//! ```

use crate::store::StorageBackend;
use crate::store::runtime::global_handle;
use crate::store::utils::validate_url;
use bytes::Bytes;
use hexz_common::{Error, Result};
use reqwest::Client;
use reqwest::header::HeaderMap;
use reqwest::redirect::Policy;
use std::io::{Error as IoError, ErrorKind};
use tokio::runtime::Handle;

/// Maximum number of redirects to follow before giving up.
const MAX_REDIRECTS: usize = 10;

/// Send an HTTP request, manually following redirects while preserving headers.
///
/// reqwest's built-in redirect policy strips headers like `Range` on cross-origin
/// redirects. This function follows redirects manually and re-sends the provided
/// extra headers on every hop, ensuring range requests work through CDNs.
async fn send_with_redirects(
    client: &Client,
    method: reqwest::Method,
    url: &str,
    extra_headers: HeaderMap,
) -> Result<reqwest::Response> {
    let mut current_url = url.to_string();
    let mut current_method = method;

    for _ in 0..=MAX_REDIRECTS {
        let resp = client
            .request(current_method.clone(), &current_url)
            .headers(extra_headers.clone())
            .send()
            .await
            .map_err(|e| Error::Io(IoError::other(e)))?;

        if !resp.status().is_redirection() {
            if !resp.status().is_success() {
                return Err(Error::Io(IoError::other(format!(
                    "HTTP {} for {}",
                    resp.status(),
                    current_url
                ))));
            }
            return Ok(resp);
        }

        let location = resp
            .headers()
            .get(reqwest::header::LOCATION)
            .and_then(|v| v.to_str().ok())
            .ok_or_else(|| {
                Error::Io(IoError::new(
                    ErrorKind::InvalidData,
                    "Redirect without Location header",
                ))
            })?
            .to_string();

        // 303 See Other: switch to GET; all others preserve method
        if resp.status().as_u16() == 303 {
            current_method = reqwest::Method::GET;
        }

        current_url = location;
    }

    Err(Error::Io(IoError::other(format!(
        "Too many redirects (>{MAX_REDIRECTS})"
    ))))
}

/// HTTP storage backend with embedded Tokio runtime.
///
/// This backend wraps an async `reqwest::Client` and Tokio `Runtime` to provide
/// synchronous `StorageBackend` operations while leveraging async I/O internally.
/// It validates URLs for security, maintains a connection pool, and performs
/// range requests to fetch specific byte ranges.
///
/// # Examples
///
/// ```no_run
/// use hexz_core::store::http::HttpBackend;
/// use hexz_core::store::StorageBackend;
///
/// # fn main() -> Result<(), Box<dyn std::error::Error>> {
/// let backend = HttpBackend::new(
///     "https://example.com/snapshot.hxz".to_string(),
///     false
/// )?;
///
/// let data = backend.read_exact(8192, 4096)?;
/// assert_eq!(data.len(), 4096);
/// # Ok(())
/// # }
/// ```
#[derive(Debug)]
pub struct HttpBackend {
    url: String,
    client: Client,
    len: u64,
    handle: Handle,
}

impl HttpBackend {
    /// Creates a new HTTP backend by validating the URL and fetching file metadata.
    ///
    /// This constructor:
    /// 1. Validates the URL for security (blocks restricted IPs unless allowed)
    /// 2. Creates a Tokio runtime for executing async operations
    /// 3. Sends an async HEAD request to verify the server and fetch file size
    /// 4. Extracts the `Content-Length` header to determine snapshot size
    ///
    /// # Parameters
    ///
    /// - `url`: The HTTP/HTTPS URL of the snapshot file
    /// - `allow_restricted`: If `false`, blocks access to localhost and private networks
    pub fn new(url: String, allow_restricted: bool) -> Result<Self> {
        let safe_url = validate_url(&url, allow_restricted)?;

        let handle = global_handle();

        // Disable auto-redirects so we can manually follow them while
        // preserving headers (e.g. Range) across cross-origin redirects.
        let client = Client::builder()
            .redirect(Policy::none())
            .build()
            .map_err(|e| Error::Io(IoError::other(e)))?;

        let len = handle.block_on(async {
            let resp =
                send_with_redirects(&client, reqwest::Method::HEAD, &safe_url, HeaderMap::new())
                    .await?;

            resp.headers()
                .get(reqwest::header::CONTENT_LENGTH)
                .and_then(|val| val.to_str().ok())
                .and_then(|s| s.parse::<u64>().ok())
                .ok_or_else(|| {
                    Error::Io(IoError::new(
                        ErrorKind::InvalidData,
                        "Missing Content-Length header",
                    ))
                })
        })?;

        Ok(Self {
            url: safe_url,
            client,
            len,
            handle,
        })
    }
}

impl StorageBackend for HttpBackend {
    fn read_exact(&self, offset: u64, len: usize) -> Result<Bytes> {
        if len == 0 {
            return Ok(Bytes::new());
        }
        let end = offset + len as u64 - 1;

        let mut headers = HeaderMap::new();
        headers.insert(
            reqwest::header::RANGE,
            format!("bytes={offset}-{end}").parse().unwrap(),
        );

        self.handle.block_on(async {
            let resp =
                send_with_redirects(&self.client, reqwest::Method::GET, &self.url, headers).await?;

            let bytes = resp
                .bytes()
                .await
                .map_err(|e| Error::Io(IoError::other(e)))?;

            if bytes.len() != len {
                return Err(Error::Io(IoError::new(
                    ErrorKind::UnexpectedEof,
                    format!("Expected {} bytes, got {}", len, bytes.len()),
                )));
            }

            Ok(bytes)
        })
    }

    fn len(&self) -> u64 {
        self.len
    }
}