//! Simple HTTP client module for downloading resources (language packs, etc.)

//!

//! Uses ureq for simple, blocking HTTP requests. Designed to be exposed via C API.

use alloc::string::String;

use alloc::vec::Vec;

use alloc::format;

use core::fmt;

use azul_css::{AzString, U8Vec, impl_vec, impl_vec_clone, impl_vec_debug, impl_vec_partialeq, impl_vec_mut, impl_option, impl_option_inner};

// ============================================================================

// Error types (C-compatible, single field per variant)

// ============================================================================

/// HTTP status error (4xx, 5xx responses)

#[derive(Debug, Clone, PartialEq, Eq)]

#[repr(C)]

pub struct HttpStatusError {

    /// HTTP status code

    pub status_code: u16,

    /// Status message

    pub message: AzString,

}

/// Response too large error

#[derive(Copy, Debug, Clone, PartialEq, Eq)]

#[repr(C)]

pub struct HttpResponseTooLargeError {

    /// Maximum allowed size in bytes

    pub max_size: u64,

    /// Actual size in bytes

    pub actual_size: u64,

}

/// HTTP error types (C-compatible)

#[derive(Debug, Clone, PartialEq, Eq)]

#[repr(C, u8)]

pub enum HttpError {

    /// Invalid URL format

    InvalidUrl(AzString),

    /// Connection failed

    ConnectionFailed(AzString),

    /// Request timed out

    Timeout,

    /// TLS/SSL error

    TlsError(AzString),

    /// HTTP error response (4xx, 5xx)

    HttpStatus(HttpStatusError),

    /// I/O error during request

    IoError(AzString),

    /// Response body too large

    ResponseTooLarge(HttpResponseTooLargeError),

    /// Other error

    Other(AzString),

}

impl HttpError {

}

impl fmt::Display for HttpError {

            }

        }

}

#[cfg(feature = "std")]

impl std::error::Error for HttpError {}

/// Result type for HTTP operations

pub type HttpResult<T> = Result<T, HttpError>;

// FFI-safe Result types for HTTP operations

use azul_css::{impl_result, impl_result_inner};

// Forward declaration - actual impl_result! calls are after HttpResponse definition

// ============================================================================

// Request configuration (C-compatible)

// ============================================================================

/// HTTP header key-value pair

#[derive(Debug, Clone, PartialEq, Eq)]

#[repr(C)]

pub struct HttpHeader {

    /// Header name

    pub name: AzString,

    /// Header value

    pub value: AzString,

}

impl HttpHeader {

}

impl_option!(HttpHeader, OptionHttpHeader, copy = false, [Debug, Clone, PartialEq, Eq]);

impl_vec!(HttpHeader, HttpHeaderVec, HttpHeaderVecDestructor, HttpHeaderVecDestructorType, HttpHeaderVecSlice, OptionHttpHeader);

impl_vec_clone!(HttpHeader, HttpHeaderVec, HttpHeaderVecDestructor);

impl_vec_debug!(HttpHeader, HttpHeaderVec);

impl_vec_partialeq!(HttpHeader, HttpHeaderVec);

impl_vec_mut!(HttpHeader, HttpHeaderVec);

/// HTTP request configuration (C-compatible)

#[derive(Debug, Clone)]

#[repr(C)]

pub struct HttpRequestConfig {

    /// Request timeout in seconds (default: 30)

    pub timeout_secs: u64,

    /// Maximum response size in bytes (default: 100MB, 0 = unlimited)

    pub max_response_size: u64,

    /// User-Agent header value

    pub user_agent: AzString,

    /// Additional headers

    pub headers: HttpHeaderVec,

    /// Disable TLS certificate verification (default: false).

    /// WARNING: This makes HTTPS connections vulnerable to MITM attacks.

    /// Use only for testing or when connecting to servers with self-signed

    /// or cross-signed certificates not in the Mozilla root store.

    pub disable_tls_cert_verification: bool,

}

impl Default for HttpRequestConfig {

}

impl HttpRequestConfig {

    /// Create a new config with default values

    /// Set timeout in seconds

    /// Set maximum response size (0 = unlimited)

    /// Set User-Agent header

    #[must_use]

    /// Add a header

    #[must_use]

    /// Simple HTTP GET request with default configuration

    ///

    /// # Arguments

    /// * `url` - The URL to request

    ///

    /// # Returns

    /// * `ResultHttpResponseHttpError` - The response or an error

    #[cfg(all(feature = "http", not(target_arch = "wasm32")))]

    #[must_use] pub fn http_get_default(url: AzString) -> ResultHttpResponseHttpError {

        let config = Self::default();

        http_get_with_config(url.as_str(), &config).into()

    }

    /// Stub: `http` feature disabled.

    #[cfg(any(not(feature = "http"), target_arch = "wasm32"))]

    /// HTTP GET request using this configuration

    /// 

    /// # Arguments

    /// * `url` - The URL to request

    /// 

    /// # Returns

    /// * `ResultHttpResponseHttpError` - The response or an error

    #[cfg(all(feature = "http", not(target_arch = "wasm32")))]

    #[must_use] pub fn http_get(&self, url: AzString) -> ResultHttpResponseHttpError {

        http_get_with_config(url.as_str(), self).into()

    }

    /// Stub: `http` feature disabled.

    #[cfg(any(not(feature = "http"), target_arch = "wasm32"))]

    /// HTTP request with an arbitrary verb and an optional body, using this

    /// configuration. An EMPTY `body` sends no body (GET/HEAD semantics);

    /// `content_type` is only applied when a body is present.

    ///

    /// # Returns

    /// * `ResultHttpResponseHttpError` - The response or an error

    #[cfg(all(feature = "http", not(target_arch = "wasm32")))]

    #[must_use] pub fn http_request(

        &self,

        method: HttpMethod,

        url: AzString,

        body: U8Vec,

        content_type: AzString,

    ) -> ResultHttpResponseHttpError {

        let body_ref = body.as_ref();

        let body_opt = if body_ref.is_empty() { None } else { Some(body_ref) };

        http_request_with_config(method, url.as_str(), body_opt, content_type.as_str(), self)

            .into()

    }

    /// Stub: `http` feature disabled.

    #[cfg(any(not(feature = "http"), target_arch = "wasm32"))]

    /// HTTP POST with a body, using this configuration.

    ///

    /// # Returns

    /// * `ResultHttpResponseHttpError` - The response or an error

    #[cfg(all(feature = "http", not(target_arch = "wasm32")))]

    #[must_use] pub fn http_post(

        &self,

        url: AzString,

        body: U8Vec,

        content_type: AzString,

    ) -> ResultHttpResponseHttpError {

        http_post_with_config(url.as_str(), body.as_ref(), content_type.as_str(), self).into()

    }

    /// Stub: `http` feature disabled.

    #[cfg(any(not(feature = "http"), target_arch = "wasm32"))]

    /// Download URL to bytes with default configuration

    /// 

    /// # Arguments

    /// * `url` - The URL to download

    /// 

    /// # Returns

    /// * `ResultU8VecHttpError` - The response body or an error

    #[cfg(all(feature = "http", not(target_arch = "wasm32")))]

    #[must_use] pub fn download_bytes_default(url: AzString) -> ResultU8VecHttpError {

        download_bytes(url.as_str()).into()

    }

    /// Stub: `http` feature disabled.

    #[cfg(any(not(feature = "http"), target_arch = "wasm32"))]

    /// Download URL to bytes using this configuration

    /// 

    /// # Arguments

    /// * `url` - The URL to download

    /// 

    /// # Returns

    /// * `ResultU8VecHttpError` - The response body or an error

    #[cfg(all(feature = "http", not(target_arch = "wasm32")))]

    #[must_use] pub fn download_bytes(&self, url: AzString) -> ResultU8VecHttpError {

        download_bytes_with_config(url.as_str(), self).into()

    }

    /// Stub: `http` feature disabled.

    #[cfg(any(not(feature = "http"), target_arch = "wasm32"))]

    /// Check if a URL is reachable (HEAD request)

    /// 

    /// # Arguments

    /// * `url` - The URL to check

    /// 

    /// # Returns

    /// * `bool` - True if reachable (2xx status)

    #[cfg(all(feature = "http", not(target_arch = "wasm32")))]

    #[must_use] pub fn is_url_reachable(url: AzString) -> bool {

        is_url_reachable(url.as_str())

    }

    /// Stub: `http` feature disabled.

    ///

    /// The Result-returning siblings self-describe via

    /// `HttpError::other("http feature not enabled")`; a bare `false` is the

    /// one answer here that reads exactly like "server down", so say the

    /// truth once. (The `const fn` free-function twin below cannot log.)

    #[cfg(any(not(feature = "http"), target_arch = "wasm32"))]

        static ANNOUNCE: std::sync::Once = std::sync::Once::new();

            );

}

// ============================================================================

// Response (C-compatible)

// ============================================================================

/// HTTP response with status code, headers, and body

#[derive(Debug, Clone, PartialEq)]

#[repr(C)]

pub struct HttpResponse {

    /// HTTP status code (200, 404, etc.)

    pub status_code: u16,

    /// Response body as bytes

    pub body: U8Vec,

    /// Content-Type header value

    pub content_type: AzString,

    /// Content-Length header value (0 if unknown)

    pub content_length: u64,

    /// Response headers

    pub headers: HttpHeaderVec,

}

impl HttpResponse {

    /// Check if the response was successful (2xx status)

    /// Check if the response is a redirect (3xx status)

    /// Check if the response is a client error (4xx status)

    /// Check if the response is a server error (5xx status)

    /// Try to convert the body to a UTF-8 string

}

// FFI-safe Result types for HTTP operations (must be after HttpResponse definition)

impl_result!(

    HttpResponse,

    HttpError,

    ResultHttpResponseHttpError,

    copy = false,

    clone = false,

    [Debug, Clone, PartialEq]

);

impl_result!(

    U8Vec,

    HttpError,

    ResultU8VecHttpError,

    copy = false,

    clone = false,

    [Debug, Clone, PartialEq, Eq]

);

/// Simple HTTP GET request

///

/// # Arguments

/// * `url` - The URL to request

///

/// # Returns

/// * `HttpResult<HttpResponse>` - The response or an error

#[cfg(all(feature = "http", not(target_arch = "wasm32")))]

pub fn http_get(url: &str) -> HttpResult<HttpResponse> {

    http_get_with_config(url, &HttpRequestConfig::default())

}

/// Stub: `http` feature disabled.

#[cfg(any(not(feature = "http"), target_arch = "wasm32"))]

/// # Errors

///

/// Returns an `HttpError` if the request fails (network/status error, or the networking feature is disabled).

/// HTTP GET request with custom configuration

/// 

/// # Arguments

/// * `url` - The URL to request

/// * `config` - Request configuration

/// 

/// # Returns

/// * `HttpResult<HttpResponse>` - The response or an error

#[cfg(all(feature = "http", not(target_arch = "wasm32")))]

fn make_agent(timeout_secs: u64, disable_tls_cert_verification: bool) -> ureq::Agent {

    use std::time::Duration;

    let mut tls_builder = ureq::tls::TlsConfig::builder()

        .provider(ureq::tls::TlsProvider::Rustls)

        .unversioned_rustls_crypto_provider(

            std::sync::Arc::new(rustls_rustcrypto::provider())

        );

    if disable_tls_cert_verification {

        tls_builder = tls_builder.disable_verification(true);

    } else {

        tls_builder = tls_builder.root_certs(ureq::tls::RootCerts::WebPki);

    }

    let tls_config = tls_builder.build();

    ureq::Agent::config_builder()

        .tls_config(tls_config)

        .timeout_global(Some(Duration::from_secs(timeout_secs)))

        .http_status_as_error(false)

        .build()

        .new_agent()

}

/// HTTP verb for [`http_request_with_config`].

///

/// Rust-side only — this type deliberately has no C-ABI mirror in `api.json`;

/// the C bindings keep the pre-existing `HttpRequestConfig::http_get` /

/// `download_bytes` entry points.

#[derive(Debug, Copy, Clone, PartialEq, Eq, Hash)]

#[repr(C)]

pub enum HttpMethod {

    Get,

    Head,

    Post,

    Put,

    Patch,

    Delete,

}

impl HttpMethod {

    /// The uppercase wire name of the verb.

    #[must_use]

        }

    /// Whether this verb carries a request body.

    ///

    /// Mirrors ureq's request typestate split: `POST`/`PUT`/`PATCH` build a

    /// `WithBody` request terminated by `send()`, while `GET`/`HEAD`/`DELETE`

    /// build a `WithoutBody` one terminated by `call()`.

    #[must_use]

}

impl fmt::Display for HttpMethod {

}

/// Maps a ureq transport error onto the C-ABI-safe [`HttpError`].

#[cfg(all(feature = "http", not(target_arch = "wasm32")))]

fn map_ureq_error(url: &str, e: &ureq::Error) -> HttpError {

    match e {

        ureq::Error::Timeout(_) => HttpError::Timeout,

        ureq::Error::HostNotFound => {

            HttpError::connection_failed(format!("DNS resolution failed for {url}").into())

        }

        ureq::Error::ConnectionFailed => {

            HttpError::connection_failed(format!("Connection failed: {url}").into())

        }

        ureq::Error::Io(io_err) => HttpError::io_error(format!("{io_err}").into()),

        ureq::Error::BadUri(msg) => HttpError::invalid_url(format!("{url}: {msg}").into()),

        ureq::Error::Tls(msg) => HttpError::tls_error(format!("TLS error: {msg}").into()),

        // Catch-all for feature-gated variants (Rustls, Pem, etc.)

        _ => {

            let msg = e.to_string();

            if msg.starts_with("rustls:") || msg.contains("TLS") || msg.contains("certificate") {

                HttpError::tls_error(msg.into())

            } else {

                HttpError::other(msg.into())

            }

        }

    }

}

/// Turns a ureq response into the C-ABI [`HttpResponse`], enforcing

/// `config.max_response_size` both on the advertised `Content-Length` and on

/// the actual number of bytes read.

#[cfg(all(feature = "http", not(target_arch = "wasm32")))]

fn decode_response(

    response: ureq::http::Response<ureq::Body>,

    config: &HttpRequestConfig,

) -> HttpResult<HttpResponse> {

    use std::io::Read;

    let status_code = response.status().as_u16();

    let content_type = AzString::from(

        response.headers().get("Content-Type")

            .and_then(|v| v.to_str().ok())

            .unwrap_or("application/octet-stream")

            .to_string()

    );

    let content_length = response.headers().get("Content-Length")

        .and_then(|v| v.to_str().ok())

        .and_then(|s| s.parse::<u64>().ok())

        .unwrap_or(0);

    // Collect response headers

    let mut headers = Vec::new();

    for (name, value) in response.headers() {

        if let Ok(v) = value.to_str() {

            headers.push(HttpHeader::new(name.to_string(), v.to_string()));

        }

    }

    // Check response size limit

    if config.max_response_size > 0 && content_length > config.max_response_size {

        return Err(HttpError::response_too_large(

            config.max_response_size,

            content_length,

        ));

    }

    // Read body with size limit

    let mut body = Vec::new();

    let limit = if config.max_response_size > 0 {

        config.max_response_size as usize

    } else {

        usize::MAX

    };

    let mut body_reader = response.into_body();

    let mut reader = body_reader.as_reader().take(limit as u64);

    reader.read_to_end(&mut body).map_err(|e| HttpError::io_error(e.to_string().into()))?;

    Ok(HttpResponse {

        status_code,

        body: U8Vec::from(body),

        content_type,

        content_length,

        headers: HttpHeaderVec::from_vec(headers),

    })

}

/// Generic HTTP request with an optional body — the single code path every

/// verb-specific helper in this module funnels through.

///

/// `content_type` is applied only when a body is present; explicit entries in

/// `config.headers` are applied afterwards and therefore win. To gzip a

/// request body, compress it yourself and pass

/// `HttpRequestConfig::with_header("Content-Encoding", "gzip")`.

///

/// Note that 4xx/5xx are returned as an `Ok(HttpResponse)` with the status

/// code set (the agent is built with `http_status_as_error(false)`); only

/// transport failures produce an `Err`.

///

/// # Errors

///

/// Returns an `HttpError` on DNS/connect/TLS/IO failure, on timeout, if the

/// response exceeds `config.max_response_size`, or if the `http` feature is

/// disabled.

#[cfg(all(feature = "http", not(target_arch = "wasm32")))]

pub fn http_request_with_config(

    method: HttpMethod,

    url: &str,

    body: Option<&[u8]>,

    content_type: &str,

    config: &HttpRequestConfig,

) -> HttpResult<HttpResponse> {

    let agent = make_agent(config.timeout_secs, config.disable_tls_cert_verification);

    // ureq 3.x splits the request builder by typestate: `WithoutBody` for

    // GET/HEAD/DELETE (terminated by `.call()`) and `WithBody` for

    // POST/PUT/PATCH (terminated by `.send()`). The two are different types,

    // so the header application is written out per branch.

    let response = if method.takes_body() {

        let mut request = match method {

            HttpMethod::Put => agent.put(url),

            HttpMethod::Patch => agent.patch(url),

            // `takes_body()` admits only POST/PUT/PATCH here.

            _ => agent.post(url),

        };

        if !config.user_agent.as_str().is_empty() {

            request = request.header("User-Agent", config.user_agent.as_str());

        }

        if !content_type.is_empty() {

            request = request.header("Content-Type", content_type);

        }

        for header in config.headers.as_slice() {

            request = request.header(header.name.as_str(), header.value.as_str());

        }

        request

            .send(body.unwrap_or(&[]))

            .map_err(|e| map_ureq_error(url, &e))?

    } else {

        let mut request = match method {

            HttpMethod::Head => agent.head(url),

            HttpMethod::Delete => agent.delete(url),

            // `takes_body()` admits only GET/HEAD/DELETE here.

            _ => agent.get(url),

        };

        if !config.user_agent.as_str().is_empty() {

            request = request.header("User-Agent", config.user_agent.as_str());

        }

        for header in config.headers.as_slice() {

            request = request.header(header.name.as_str(), header.value.as_str());

        }

        request.call().map_err(|e| map_ureq_error(url, &e))?

    };

    decode_response(response, config)

}

/// Stub: `http` feature disabled.

///

/// # Errors

///

/// Always returns an `HttpError` — the networking feature is disabled.

#[cfg(any(not(feature = "http"), target_arch = "wasm32"))]

/// HTTP GET request with custom configuration.

///

/// # Errors

///

/// See [`http_request_with_config`].

#[cfg(all(feature = "http", not(target_arch = "wasm32")))]

pub fn http_get_with_config(url: &str, config: &HttpRequestConfig) -> HttpResult<HttpResponse> {

    http_request_with_config(HttpMethod::Get, url, None, "", config)

}

/// Stub: `http` feature disabled.

#[cfg(any(not(feature = "http"), target_arch = "wasm32"))]

/// # Errors

///

/// Returns an `HttpError` if the request fails (network/status error, or the networking feature is disabled).

/// HTTP POST with the default configuration.

///

/// # Errors

///

/// See [`http_request_with_config`].

/// HTTP POST with custom configuration.

///

/// This is the transport under the telemetry uploader (OTLP/HTTP JSON), crash

/// bundle upload and the update-manifest fetch.

///

/// # Errors

///

/// See [`http_request_with_config`].

/// HTTP PUT with custom configuration.

///

/// # Errors

///

/// See [`http_request_with_config`].

/// Download a URL to bytes (convenience wrapper with default config)

/// 

/// # Arguments

/// * `url` - The URL to download

/// 

/// # Returns

/// * `HttpResult<U8Vec>` - The response body or an error

#[cfg(all(feature = "http", not(target_arch = "wasm32")))]

pub fn download_bytes(url: &str) -> HttpResult<U8Vec> {

    download_bytes_with_config(url, &HttpRequestConfig::default())

}

/// Stub: `http` feature disabled.

#[cfg(any(not(feature = "http"), target_arch = "wasm32"))]

/// # Errors

///

/// Returns an `HttpError` if the request fails (network/status error, or the networking feature is disabled).

/// Download a URL to bytes with custom configuration

/// 

/// # Arguments

/// * `url` - The URL to download

/// * `config` - Request configuration (timeout, max size, etc.)

/// 

/// # Returns

/// * `HttpResult<U8Vec>` - The response body or an error

#[cfg(all(feature = "http", not(target_arch = "wasm32")))]

pub fn download_bytes_with_config(url: &str, config: &HttpRequestConfig) -> HttpResult<U8Vec> {

    let response = http_get_with_config(url, config)?;

    // Check for successful status

    if response.status_code >= 400 {

        return Err(HttpError::http_status(

            response.status_code,

            format!("HTTP error {}", response.status_code).into(),

        ));

    }

    Ok(response.body)

}

/// Stub: `http` feature disabled.

#[cfg(any(not(feature = "http"), target_arch = "wasm32"))]

/// # Errors

///

/// Returns an `HttpError` if the request fails (network/status error, or the networking feature is disabled).

/// Check if a URL is reachable (HEAD request)

/// 

/// # Arguments

/// * `url` - The URL to check

/// 

/// # Returns

/// * `bool` - True if reachable (2xx status)

#[cfg(all(feature = "http", not(target_arch = "wasm32")))]

#[must_use] pub fn is_url_reachable(url: &str) -> bool {

    const REACHABILITY_TIMEOUT_SECS: u64 = 10;

    let agent = make_agent(REACHABILITY_TIMEOUT_SECS, false);

    match agent.head(url).call() {

        Ok(resp) => {

            let code = resp.status().as_u16();

            (200..300).contains(&code)

        }

        Err(_) => false,

    }

}

/// Stub: `http` feature disabled.

#[cfg(any(not(feature = "http"), target_arch = "wasm32"))]

#[cfg(test)]

mod tests {

    use super::*;

    #[test]

    #[test]

    #[test]

}

#[cfg(test)]

mod autotest_generated {

    use super::*;

    // =========================================================================

    // Shared fixtures

    //

    // Everything below is offline: the `http`-gated tests only touch URIs that

    // fail during URI parsing (no DNS lookup, no socket) or construct a ureq

    // agent without ever calling it.

    // =========================================================================

    /// 256 KiB of ASCII — used to check the constructors don't choke on big payloads.

    fn huge_ascii() -> String {

        "A".repeat(256 * 1024)

    }

    /// A string designed to break naive formatting / escaping.

    const NASTY: &str = "\u{0}\r\n\t\"{}{{}}%s%n\u{7f}héllo·🦀·\u{202e}\u{feff}";

    fn response_with_status(status_code: u16) -> HttpResponse {

        HttpResponse {

            status_code,

            body: U8Vec::from(Vec::new()),

            content_type: AzString::from("application/octet-stream"),

            content_length: 0,

            headers: HttpHeaderVec::from_const_slice(&[]),

        }

    }

    fn response_with_body(body: Vec<u8>) -> HttpResponse {

        HttpResponse {

            status_code: 200,

            body: U8Vec::from(body),

            content_type: AzString::from("text/plain"),

            content_length: 0,

            headers: HttpHeaderVec::from_const_slice(&[]),

        }

    }

    // =========================================================================

    // HttpError constructors (`other` category) — extreme AzString payloads

    // =========================================================================

    #[test]

    fn http_error_string_constructors_store_payload_verbatim() {

        for payload in ["", "http://example.com", NASTY, huge_ascii().as_str()] {

            let s = AzString::from(payload);

            assert_eq!(

                HttpError::invalid_url(s.clone()),

                HttpError::InvalidUrl(s.clone())

            );

            assert_eq!(

                HttpError::connection_failed(s.clone()),

                HttpError::ConnectionFailed(s.clone())

            );

            assert_eq!(

                HttpError::tls_error(s.clone()),

                HttpError::TlsError(s.clone())

            );

            assert_eq!(

                HttpError::io_error(s.clone()),

                HttpError::IoError(s.clone())

            );

            assert_eq!(HttpError::other(s.clone()), HttpError::Other(s.clone()));

            // The payload survives the round-trip through the enum untouched:

            // no truncation at NUL, no escaping, no normalization.

            match HttpError::invalid_url(s.clone()) {

                HttpError::InvalidUrl(inner) => assert_eq!(inner.as_str(), payload),

                other => panic!("wrong variant: {other:?}"),

            }

        }

    }

    #[test]

    fn http_error_variants_are_not_conflated() {

        let s = AzString::from("x");

        assert_ne!(HttpError::invalid_url(s.clone()), HttpError::other(s.clone()));

        assert_ne!(HttpError::tls_error(s.clone()), HttpError::io_error(s.clone()));

        assert_ne!(HttpError::connection_failed(s.clone()), HttpError::Timeout);

    }

    // =========================================================================

    // HttpError::http_status / response_too_large (`numeric` category)

    // =========================================================================

    #[test]

    fn http_status_accepts_full_u16_range_without_clamping() {

        // 0 and u16::MAX are not valid HTTP status codes, but the constructor is

        // a plain data carrier: it must store them as-is rather than clamp/panic.

        for code in [0_u16, 1, 99, 100, 200, 299, 400, 599, 600, 999, u16::MAX] {

            let err = HttpError::http_status(code, AzString::from("msg"));

            match err {

                HttpError::HttpStatus(ref e) => {

                    assert_eq!(e.status_code, code);

                    assert_eq!(e.message.as_str(), "msg");

                }

                ref other => panic!("wrong variant: {other:?}"),

            }

            // Display must render the raw number, never a saturated stand-in.

            assert!(err.to_string().contains(&code.to_string()));

        }

    }

    #[test]

    fn http_status_with_empty_and_huge_message() {

        let empty = HttpError::http_status(u16::MAX, AzString::from(""));

        assert_eq!(empty.to_string(), "HTTP 65535 - ");

        let big = huge_ascii();

        let huge = HttpError::http_status(0, AzString::from(big.as_str()));

        assert_eq!(huge.to_string().len(), "HTTP 0 - ".len() + big.len());

    }

    #[test]

    fn response_too_large_stores_both_sizes_at_u64_limits() {

        // Includes the nonsensical actual < max ordering: the constructor performs

        // no validation and no arithmetic, so nothing can overflow here.

        for (max, actual) in [

            (0_u64, 0_u64),

            (0, u64::MAX),

            (u64::MAX, 0),

            (u64::MAX, u64::MAX),

            (1, 1),

            (100, 200),

            (u64::MAX, u64::MAX - 1),

        ] {

            let err = HttpError::response_too_large(max, actual);

            match err {

                HttpError::ResponseTooLarge(ref e) => {

                    assert_eq!(e.max_size, max);

                    assert_eq!(e.actual_size, actual);

                }

                ref other => panic!("wrong variant: {other:?}"),

            }

            let msg = err.to_string();

            assert!(msg.contains(&actual.to_string()));

            assert!(msg.contains(&max.to_string()));

        }

    }

    // =========================================================================

    // Display impl (`serializer` category)

    // =========================================================================

    #[test]

    fn display_is_non_empty_for_every_variant() {

        let variants = [

            HttpError::invalid_url(AzString::from("u")),

            HttpError::connection_failed(AzString::from("c")),

            HttpError::Timeout,

            HttpError::tls_error(AzString::from("t")),

            HttpError::http_status(500, AzString::from("s")),

            HttpError::io_error(AzString::from("i")),

            HttpError::response_too_large(1, 2),

            HttpError::other(AzString::from("o")),

        ];

        for v in &variants {

            let s = v.to_string();

            assert!(!s.is_empty(), "empty Display for {v:?}");

        }

        assert_eq!(HttpError::Timeout.to_string(), "Request timed out");

    }

    #[test]

    fn display_does_not_interpret_the_payload_as_a_format_string() {

        // A payload full of `{}` / `%s` must be echoed literally — a Display impl

        // that re-formatted its own output would either panic or eat the braces.

        let err = HttpError::other(AzString::from("{} {0} {{}} %s %n"));

        assert_eq!(err.to_string(), "HTTP error: {} {0} {{}} %s %n");

    }

    #[test]

    fn display_preserves_nul_newlines_and_unicode() {

        let err = HttpError::invalid_url(AzString::from(NASTY));

        let s = err.to_string();

        assert!(s.starts_with("Invalid URL: "));

        assert!(s.ends_with(NASTY));

        assert!(s.contains('\u{0}'));

        assert!(s.contains('🦀'));

    }

    #[test]

    fn display_of_edge_numeric_values_does_not_panic() {

        assert_eq!(

            HttpError::http_status(u16::MAX, AzString::from("x")).to_string(),

            "HTTP 65535 - x"

        );

        assert_eq!(

            HttpError::response_too_large(u64::MAX, u64::MAX).to_string(),

            format!(

                "Response too large: {} bytes (max: {})",

                u64::MAX,

                u64::MAX

            )

        );

        assert_eq!(

            HttpError::response_too_large(0, 0).to_string(),

            "Response too large: 0 bytes (max: 0)"

        );

    }

    // =========================================================================

    // HttpHeader::new (`constructor` category)

    // =========================================================================

    #[test]

    fn http_header_new_keeps_fields_exactly_as_given() {

        for (name, value) in [

            ("", ""),

            ("Content-Type", "text/html; charset=utf-8"),

            (NASTY, NASTY),

            (huge_ascii().as_str(), ""),

            ("", huge_ascii().as_str()),

        ] {

            let h = HttpHeader::new(name, value);

            assert_eq!(h.name.as_str(), name);

            assert_eq!(h.value.as_str(), value);

        }

    }

    #[test]

    fn http_header_new_does_not_sanitize_crlf() {

        // Documented behaviour, not an endorsement: HttpHeader is a dumb pair, so a

        // CRLF-bearing name is stored verbatim. Rejecting it is the transport's job

        // (ureq validates at request time) — assert the value is at least not

        // silently truncated at the newline, which would hide the injection attempt.

        let h = HttpHeader::new("X-Evil\r\nInjected: 1", "v\r\nSet-Cookie: pwned=1");

        assert_eq!(h.name.as_str(), "X-Evil\r\nInjected: 1");

        assert_eq!(h.value.as_str(), "v\r\nSet-Cookie: pwned=1");

    }

    #[test]

    fn http_header_new_accepts_string_and_str() {

        let from_str = HttpHeader::new("a", "b");

        let from_string = HttpHeader::new(String::from("a"), String::from("b"));

        assert_eq!(from_str, from_string);

    }

    // =========================================================================

    // HttpRequestConfig builders (`constructor` category)

    // =========================================================================

    #[test]

    fn config_new_matches_default_and_documented_values() {

        let a = HttpRequestConfig::new();

        let b = HttpRequestConfig::default();

        assert_eq!(a.timeout_secs, b.timeout_secs);

        assert_eq!(a.max_response_size, b.max_response_size);

        assert_eq!(a.user_agent.as_str(), b.user_agent.as_str());

        assert_eq!(a.headers.len(), b.headers.len());

        assert_eq!(

            a.disable_tls_cert_verification,

            b.disable_tls_cert_verification

        );

        assert_eq!(a.timeout_secs, 30);

        assert_eq!(a.max_response_size, 100 * 1024 * 1024);

        assert!(a.headers.is_empty());

        // Secure by default: certificate verification must be ON unless opted out.

        assert!(!a.disable_tls_cert_verification);

    }

    #[test]

    fn with_timeout_stores_extremes_verbatim() {

        for secs in [0_u64, 1, 30, u64::MAX / 2, u64::MAX - 1, u64::MAX] {

            let cfg = HttpRequestConfig::new().with_timeout(secs);

            assert_eq!(cfg.timeout_secs, secs);

            // Nothing else may be disturbed by the setter.

            assert_eq!(cfg.max_response_size, 100 * 1024 * 1024);

            assert!(cfg.headers.is_empty());

        }

    }

    #[test]

    fn with_max_size_stores_extremes_verbatim() {

        for max in [0_u64, 1, u64::MAX] {

            let cfg = HttpRequestConfig::new().with_max_size(max);

            assert_eq!(cfg.max_response_size, max);

            assert_eq!(cfg.timeout_secs, 30);

        }

        // 0 is the documented "unlimited" sentinel, not a "reject everything" limit.

        assert_eq!(HttpRequestConfig::new().with_max_size(0).max_response_size, 0);

    }

    #[test]

    fn builder_setters_are_last_write_wins_and_independent() {

        let cfg = HttpRequestConfig::new()

            .with_timeout(1)

            .with_timeout(u64::MAX)

            .with_max_size(5)

            .with_max_size(0)

            .with_user_agent("first")

            .with_user_agent("second");

        assert_eq!(cfg.timeout_secs, u64::MAX);

        assert_eq!(cfg.max_response_size, 0);

        assert_eq!(cfg.user_agent.as_str(), "second");

    }

    #[test]

    fn with_user_agent_accepts_empty_and_extreme_values() {

        let empty = HttpRequestConfig::new().with_user_agent("");

        // Empty UA is meaningful: http_get_with_config skips the header entirely.

        assert!(empty.user_agent.as_str().is_empty());

        let unicode = HttpRequestConfig::new().with_user_agent(NASTY);

        assert_eq!(unicode.user_agent.as_str(), NASTY);

        let big = huge_ascii();

        let huge = HttpRequestConfig::new().with_user_agent(big.clone());

        assert_eq!(huge.user_agent.as_str().len(), big.len());

    }

    #[test]

    fn with_header_appends_in_order_and_keeps_duplicates() {

        let mut cfg = HttpRequestConfig::new();

        assert!(cfg.headers.is_empty());

        for i in 0..100_usize {

            cfg = cfg.with_header(format!("H{i}"), format!("v{i}"));

        }

        // Duplicate names are kept, not deduplicated or overwritten.

        cfg = cfg.with_header("H0", "second-value");

        assert_eq!(cfg.headers.len(), 101);

        let slice = cfg.headers.as_slice();

        for (i, h) in slice.iter().take(100).enumerate() {

            assert_eq!(h.name.as_str(), format!("H{i}"));

            assert_eq!(h.value.as_str(), format!("v{i}"));

        }

        assert_eq!(slice[100].name.as_str(), "H0");

        assert_eq!(slice[100].value.as_str(), "second-value");

    }

    #[test]

    fn with_header_accepts_empty_name_and_value() {

        let cfg = HttpRequestConfig::new().with_header("", "");

        assert_eq!(cfg.headers.len(), 1);

        assert!(cfg.headers.as_slice()[0].name.as_str().is_empty());

        assert!(cfg.headers.as_slice()[0].value.as_str().is_empty());

    }

    #[test]

    fn cloning_a_config_gives_an_independent_header_vec() {

        // The header vec is an FFI vec with a destructor field; a shallow clone that

        // aliased the original's buffer would show up here (and later double-free).

        let base = HttpRequestConfig::new().with_header("A", "1");

        let cloned = base.clone().with_header("B", "2");

        assert_eq!(base.headers.len(), 1);

        assert_eq!(cloned.headers.len(), 2);

        assert_eq!(base.headers.as_slice()[0].name.as_str(), "A");

        assert_eq!(cloned.headers.as_slice()[0].name.as_str(), "A");

        assert_eq!(cloned.headers.as_slice()[1].name.as_str(), "B");

        drop(cloned);

        // `base` must still be readable after the clone is dropped.

        assert_eq!(base.headers.as_slice()[0].value.as_str(), "1");

    }

    // =========================================================================

    // HttpResponse predicates (`predicate` category)

    // =========================================================================

    #[test]

    fn status_predicates_at_class_boundaries() {

        let cases: &[(u16, bool, bool, bool, bool)] = &[

            // status, success, redirect, client_err, server_err

            (0, false, false, false, false),

            (100, false, false, false, false),

            (199, false, false, false, false),

            (200, true, false, false, false),

            (204, true, false, false, false),

            (299, true, false, false, false),

            (300, false, true, false, false),

            (399, false, true, false, false),

            (400, false, false, true, false),

            (499, false, false, true, false),

            (500, false, false, false, true),

            (599, false, false, false, true),

            (600, false, false, false, false),

            (999, false, false, false, false),

            (u16::MAX, false, false, false, false),

        ];

        for &(status, success, redirect, client, server) in cases {

            let r = response_with_status(status);

            assert_eq!(r.is_success(), success, "is_success({status})");

            assert_eq!(r.is_redirect(), redirect, "is_redirect({status})");

            assert_eq!(r.is_client_error(), client, "is_client_error({status})");

            assert_eq!(r.is_server_error(), server, "is_server_error({status})");

        }

    }

    #[test]

    fn status_predicates_are_mutually_exclusive_over_the_whole_u16_range() {

        let mut r = response_with_status(0);

        for status in 0..=u16::MAX {

            r.status_code = status;

            let hits = u8::from(r.is_success())

                + u8::from(r.is_redirect())

                + u8::from(r.is_client_error())

                + u8::from(r.is_server_error());

            assert!(hits <= 1, "status {status} matched {hits} classes");

            // Exactly one class must match inside 200..=599, and none outside it.

            let expected = u8::from((200_u16..600_u16).contains(&status));

            assert_eq!(hits, expected, "status {status}");

        }

    }

    #[test]

    fn status_predicates_ignore_body_and_headers() {

        let mut r = response_with_body(vec![0xFF; 1024]);

        r.status_code = 503;

        r.content_length = u64::MAX;

        r.headers = HttpHeaderVec::from_vec(vec![HttpHeader::new("X", "Y")]);

        assert!(r.is_server_error());

        assert!(!r.is_success());

    }

    // =========================================================================

    // HttpResponse::body_as_string (`getter` category)

    // =========================================================================

    #[test]

    fn body_as_string_on_empty_body_is_some_empty_string() {

        let r = response_with_body(Vec::new());

        let s = r.body_as_string().expect("empty body is valid UTF-8");

        assert_eq!(s.as_str(), "");

    }

    #[test]

    fn body_as_string_round_trips_valid_utf8() {

        for text in ["hello", NASTY, "🦀🦀🦀", "a\u{0}b"] {

            let r = response_with_body(text.as_bytes().to_vec());

            let s = r.body_as_string().expect("valid UTF-8 must decode");

            assert_eq!(s.as_str(), text);

            assert_eq!(s.as_str().len(), text.len());

        }