wisegate-core 0.13.0

//! HTTP request handling and proxying.
//!
//! This module contains the core request handling logic for the reverse proxy,
//! including IP validation, rate limiting, URL pattern blocking, and request forwarding.
//!
//! # Architecture
//!
//! The request handling flow:
//! 1. Extract and validate client IP from proxy headers
//! 2. Check if IP is blocked
//! 3. Check for blocked URL patterns
//! 4. Check for blocked HTTP methods
//! 5. Apply rate limiting
//! 6. Forward request to upstream service
//!
//! # Connection Pooling
//!
//! The module accepts a shared [`reqwest::Client`] for HTTP connection pooling,
//! which should be configured by the caller with appropriate timeouts and with
//! redirects disabled (`.redirect(reqwest::redirect::Policy::none())`):
//! reqwest follows up to 10 redirects by default, which would serve targets
//! that never went through wisegate's filters.

use http_body_util::{BodyExt, Full};
use hyper::{Request, Response, StatusCode, body::Incoming};
use std::convert::Infallible;
use std::net::SocketAddr;
use std::sync::Arc;

use crate::error::WiseGateError;
use crate::types::{ConfigProvider, RateLimiter};
use crate::{auth, headers, ip_filter, rate_limiter};

/// Handles an incoming HTTP request through the proxy pipeline.
///
/// This is the main entry point for request processing. It performs:
/// - Client IP extraction and validation from proxy headers
/// - IP blocking checks
/// - URL pattern blocking (e.g., `.php`, `.env` files)
/// - HTTP method blocking (e.g., `PUT`, `DELETE`)
/// - Rate limiting per client IP
/// - Request forwarding to the upstream service
///
/// # Arguments
///
/// * `req` - The incoming HTTP request
/// * `peer_addr` - Address of the TCP peer that sent the request
/// * `forward_host` - The upstream host to forward requests to
/// * `forward_port` - The upstream port to forward requests to
/// * `limiter` - The shared rate limiter instance
/// * `config` - Configuration provider for all settings
/// * `http_client` - HTTP client for forwarding requests (with connection pooling)
///
/// # Returns
///
/// Always returns `Ok` with either:
/// - A successful proxied response from upstream
/// - An error response (403, 404, 405, 429, 502, etc.)
///
/// # Runtime
///
/// This is an async function backed by `reqwest`/`tokio`; it must be awaited
/// from inside a Tokio runtime (`#[tokio::main]`, `Runtime::block_on`, etc.).
///
/// # Security
///
/// * **Strict mode** (proxy allowlist configured): the TCP peer must be in
///   the allowlist (or be a loopback address when
///   [`crate::ProxyProvider::trust_loopback_proxy`] is enabled). Only the last
///   element of the `Forwarded` header, the one that proxy appended, is used:
///   its `by=` must be in the allowlist and its `for=` is the client IP.
///   `X-Forwarded-For` is ignored. Requests failing any of these checks are
///   rejected with `400 Bad Request`.
/// * **Permissive mode** (no allowlist): if a request supplies an
///   `X-Forwarded-For` or `Forwarded` header, the parsed IP is trusted as the
///   real client IP and re-emitted to the upstream as `X-Real-IP`. An
///   attacker can spoof this value by sending fake headers — only enable
///   permissive mode when the proxy sits behind another layer that strips or
///   normalises these headers.
/// * Any client-supplied `X-Real-IP` header is stripped before processing.
/// * The `Authorization` header is stripped before forwarding whenever
///   wisegate performed authentication (see
///   [`crate::AuthenticationProvider::forward_authorization_header`]).
pub async fn handle_request<C: ConfigProvider>(
    req: Request<Incoming>,
    peer_addr: SocketAddr,
    forward_host: Arc<str>,
    forward_port: u16,
    limiter: RateLimiter,
    config: Arc<C>,
    http_client: reqwest::Client,
) -> Result<Response<Full<bytes::Bytes>>, Infallible> {
    // Extract and validate real client IP
    let real_client_ip: Option<String> = match ip_filter::extract_and_validate_real_ip(
        req.headers(),
        peer_addr.ip(),
        config.as_ref(),
    ) {
        Some(ip) => Some(ip),
        None => {
            if config.allowed_proxy_ips().is_none() {
                // Permissive mode: continue without IP-based security
                None
            } else {
                // Strict mode: reject when proxy validation fails
                let err = WiseGateError::InvalidIp("missing or invalid proxy headers".into());
                return Ok(create_error_response(err.status_code(), err.user_message()));
            }
        }
    };

    // Check if IP is blocked
    if let Some(ref ip) = real_client_ip
        && ip_filter::is_ip_blocked(ip, config.as_ref())
    {
        let err = WiseGateError::IpBlocked(ip.clone());
        return Ok(create_error_response(err.status_code(), err.user_message()));
    }

    // Check for blocked URL patterns
    let request_path = req.uri().path();
    if is_url_pattern_blocked(request_path, config.as_ref()) {
        let err = WiseGateError::PatternBlocked(request_path.to_string());
        return Ok(create_error_response(err.status_code(), err.user_message()));
    }

    // Check for blocked HTTP methods
    let request_method = req.method().as_str();
    if is_method_blocked(request_method, config.as_ref()) {
        let err = WiseGateError::MethodBlocked(request_method.to_string());
        return Ok(create_error_response(err.status_code(), err.user_message()));
    }

    // Count attempts before authentication so failed credentials cannot bypass
    // the per-IP budget. Successful requests are charged exactly once.
    if let Some(ref ip) = real_client_ip
        && !rate_limiter::check_rate_limit(&limiter, ip, config.as_ref()).await
    {
        let err = WiseGateError::RateLimitExceeded(ip.clone());
        return Ok(create_error_response(err.status_code(), err.user_message()));
    }

    // Check Authentication if enabled (Basic Auth and/or Bearer Token)
    // Logic: if both are configured, either one passing is sufficient
    if config.is_auth_enabled() {
        let auth_header = req
            .headers()
            .get(headers::AUTHORIZATION)
            .and_then(|v| v.to_str().ok());

        let basic_auth_enabled = config.is_basic_auth_enabled();
        let bearer_auth_enabled = config.is_bearer_auth_enabled();

        let basic_auth_passed = if basic_auth_enabled {
            match auth::check_basic_auth_bounded(auth_header, config.auth_credentials()).await {
                Ok(passed) => passed,
                Err(_) => {
                    return Ok(create_error_response(
                        StatusCode::SERVICE_UNAVAILABLE,
                        "Authentication temporarily unavailable",
                    ));
                }
            }
        } else {
            false
        };
        let bearer_auth_passed =
            bearer_auth_enabled && auth::check_bearer_token(auth_header, config.bearer_token());

        // Authentication fails if neither method passed
        if !basic_auth_passed && !bearer_auth_passed {
            return Ok(create_unauthorized_response(config.auth_realm()));
        }
    }

    // Forward the request. Any client-supplied X-Real-IP is dropped and the
    // validated one (if any) is added after hop-by-hop filtering, so upstream
    // sees only wisegate's value.
    forward_request(
        req,
        real_client_ip.as_deref(),
        &forward_host,
        forward_port,
        config.as_ref(),
        &http_client,
    )
    .await
}

/// Forward request to upstream service
async fn forward_request(
    req: Request<Incoming>,
    real_client_ip: Option<&str>,
    host: &str,
    port: u16,
    config: &impl ConfigProvider,
    http_client: &reqwest::Client,
) -> Result<Response<Full<bytes::Bytes>>, Infallible> {
    let proxy_config = config.proxy_config();
    let (parts, body) = req.into_parts();

    // Early rejection based on Content-Length header to prevent memory exhaustion
    if proxy_config.max_body_size > 0
        && let Some(content_length) = parts
            .headers
            .get(headers::CONTENT_LENGTH)
            .and_then(|v| v.to_str().ok())
            .and_then(|v| v.parse::<usize>().ok())
        && content_length > proxy_config.max_body_size
    {
        let err = WiseGateError::BodyTooLarge {
            size: content_length,
            max: proxy_config.max_body_size,
        };
        return Ok(create_body_error_response(&err));
    }

    let body_bytes = match read_request_body(
        body,
        proxy_config.max_body_size,
        config.client_body_timeout(),
    )
    .await
    {
        Ok(bytes) => bytes,
        Err(err) => {
            return Ok(create_body_error_response(&err));
        }
    };

    let strip_auth = config.is_auth_enabled() && !config.forward_authorization_header();
    forward_with_reqwest(
        parts,
        body_bytes,
        real_client_ip,
        host,
        port,
        http_client,
        strip_auth,
    )
    .await
}

async fn read_request_body<B>(
    body: B,
    max_size: usize,
    timeout: std::time::Duration,
) -> Result<bytes::Bytes, WiseGateError>
where
    B: hyper::body::Body<Data = bytes::Bytes> + Unpin,
    B::Error: std::fmt::Display,
{
    tokio::time::timeout(timeout, collect_request_body(body, max_size))
        .await
        .map_err(|_| WiseGateError::ClientBodyTimeout)?
}

fn create_body_error_response(err: &WiseGateError) -> Response<Full<bytes::Bytes>> {
    let mut response = create_error_response(err.status_code(), err.user_message());
    // The unread body must not be reused as a subsequent HTTP/1 request.
    response.headers_mut().insert(
        headers::CONNECTION,
        hyper::header::HeaderValue::from_static("close"),
    );
    response
}

/// Enforce the limit as frames arrive, including when no Content-Length exists.
/// Reject the first oversized frame before buffering it or waiting for EOF.
async fn collect_request_body<B>(
    mut body: B,
    max_size: usize,
) -> Result<bytes::Bytes, WiseGateError>
where
    B: hyper::body::Body<Data = bytes::Bytes> + Unpin,
    B::Error: std::fmt::Display,
{
    let mut buffer = bytes::BytesMut::new();
    while let Some(frame) = body.frame().await {
        let frame = frame.map_err(|err| WiseGateError::BodyReadError(err.to_string()))?;
        if let Ok(data) = frame.into_data() {
            let size = buffer.len().saturating_add(data.len());
            if max_size > 0 && size > max_size {
                return Err(WiseGateError::BodyTooLarge {
                    size,
                    max: max_size,
                });
            }
            buffer.extend_from_slice(&data);
        }
    }
    Ok(buffer.freeze())
}

/// Shared forwarding logic using reqwest with connection pooling
async fn forward_with_reqwest(
    parts: hyper::http::request::Parts,
    body_bytes: bytes::Bytes,
    real_client_ip: Option<&str>,
    host: &str,
    port: u16,
    client: &reqwest::Client,
    strip_auth: bool,
) -> Result<Response<Full<bytes::Bytes>>, Infallible> {
    // Construct destination URI
    let destination_uri = format!(
        "http://{}:{}{}",
        host,
        port,
        parts.uri.path_and_query().map_or("", |pq| pq.as_str())
    );

    // Build the request with the original HTTP method
    let method = match reqwest::Method::from_bytes(parts.method.as_str().as_bytes()) {
        Ok(m) => m,
        Err(_) => {
            let err =
                WiseGateError::MethodBlocked(format!("{} (unsupported)", parts.method.as_str()));
            return Ok(create_error_response(err.status_code(), err.user_message()));
        }
    };
    let mut req_builder = client.request(method, &destination_uri);

    // Add headers (excluding host, content-length, and hop-by-hop headers per
    // RFC 9110 section 7.6.1, including those nominated by `Connection`).
    // When `strip_auth` is set, also drop Authorization so the upstream cannot
    // re-validate or log credentials wisegate just consumed.
    let nominated = headers::connection_nominated(&parts.headers);
    for (name, value) in parts.headers.iter() {
        if name != headers::HOST
            && name != headers::CONTENT_LENGTH
            && name != headers::X_REAL_IP
            && !(strip_auth && name == headers::AUTHORIZATION)
            && !headers::is_hop_by_hop_for(name.as_str(), &nominated)
            && let Ok(header_value) = value.to_str()
        {
            req_builder = req_builder.header(name.as_str(), header_value);
        }
    }
    if let Some(ip) = real_client_ip {
        req_builder = req_builder.header(headers::X_REAL_IP, ip);
    }

    // Add body if not empty
    if !body_bytes.is_empty() {
        req_builder = req_builder.body(body_bytes);
    }

    // Send request
    match req_builder.send().await {
        Ok(response) => {
            let status = response.status();
            let resp_headers = response.headers().clone();

            match response.bytes().await {
                Ok(body_bytes) => {
                    let mut hyper_response = match Response::builder()
                        .status(status.as_u16())
                        .body(Full::new(body_bytes))
                    {
                        Ok(resp) => resp,
                        Err(e) => {
                            let err = WiseGateError::ProxyError(format!(
                                "Failed to build response: {}",
                                e
                            ));
                            return Ok(create_error_response(
                                err.status_code(),
                                err.user_message(),
                            ));
                        }
                    };

                    // Copy response headers, skipping hop-by-hop ones. `append`
                    // keeps every value of repeated fields such as Set-Cookie.
                    let nominated = headers::connection_nominated(&resp_headers);
                    for (name, value) in resp_headers.iter() {
                        if !headers::is_hop_by_hop_for(name.as_str(), &nominated)
                            && let (Ok(hyper_name), Ok(hyper_value)) = (
                                hyper::header::HeaderName::from_bytes(name.as_str().as_bytes()),
                                hyper::header::HeaderValue::from_bytes(value.as_bytes()),
                            )
                        {
                            hyper_response.headers_mut().append(hyper_name, hyper_value);
                        }
                    }

                    Ok(hyper_response)
                }
                Err(e) => {
                    let err = WiseGateError::BodyReadError(format!("response: {}", e));
                    Ok(create_error_response(err.status_code(), err.user_message()))
                }
            }
        }
        Err(err) => {
            // More specific error handling using WiseGateError
            let wise_err = if err.is_timeout() {
                WiseGateError::UpstreamTimeout(err.to_string())
            } else if err.is_connect() {
                WiseGateError::UpstreamConnectionFailed(err.to_string())
            } else {
                WiseGateError::ProxyError(err.to_string())
            };
            Ok(create_error_response(
                wise_err.status_code(),
                wise_err.user_message(),
            ))
        }
    }
}

/// Creates a standardized error response.
///
/// Builds an HTTP response with the given status code and plain text message.
/// Falls back to a minimal 500 response if building fails (should never happen
/// with valid StatusCode).
///
/// # Arguments
///
/// * `status` - The HTTP status code for the response
/// * `message` - The plain text error message body
///
/// # Returns
///
/// An HTTP response with `content-type: text/plain` header.
///
/// # Example
///
/// ```
/// use wisegate_core::request_handler::create_error_response;
/// use hyper::StatusCode;
///
/// let response = create_error_response(StatusCode::NOT_FOUND, "Resource not found");
/// assert_eq!(response.status(), StatusCode::NOT_FOUND);
/// ```
pub fn create_error_response(status: StatusCode, message: &str) -> Response<Full<bytes::Bytes>> {
    Response::builder()
        .status(status)
        .header(headers::CONTENT_TYPE, "text/plain")
        .body(Full::new(bytes::Bytes::from(message.to_string())))
        .unwrap_or_else(|_| {
            // Fallback response if builder fails (extremely unlikely)
            Response::new(Full::new(bytes::Bytes::from("Internal Server Error")))
        })
}

/// Creates a 401 Unauthorized response with WWW-Authenticate header.
///
/// Used when Basic Authentication is enabled and the request is not authenticated
/// or has invalid credentials.
///
/// # Arguments
///
/// * `realm` - The authentication realm to display in the browser dialog
///
/// # Returns
///
/// An HTTP 401 response with `WWW-Authenticate: Basic realm="..."` header.
pub fn create_unauthorized_response(realm: &str) -> Response<Full<bytes::Bytes>> {
    // Sanitize realm: escape backslashes and quotes per RFC 7235 quoted-string
    let sanitized_realm = realm.replace('\\', "\\\\").replace('"', "\\\"");
    Response::builder()
        .status(StatusCode::UNAUTHORIZED)
        .header(
            headers::WWW_AUTHENTICATE,
            format!("Basic realm=\"{}\"", sanitized_realm),
        )
        .header(headers::CONTENT_TYPE, "text/plain")
        .body(Full::new(bytes::Bytes::from("401 Unauthorized")))
        .unwrap_or_else(|_| Response::new(Full::new(bytes::Bytes::from("401 Unauthorized"))))
}

/// Check if URL path contains any blocked patterns
/// Decodes URL-encoded characters to prevent bypass via encoding (e.g., .ph%70 for .php)
fn is_url_pattern_blocked(path: &str, config: &impl ConfigProvider) -> bool {
    let blocked_patterns = config.blocked_patterns();
    if blocked_patterns.is_empty() {
        return false;
    }

    // Decode URL-encoded path to prevent bypass attacks
    let decoded_path = url_decode(path);
    let has_encoding = decoded_path != path;

    // Case-insensitive matching to prevent bypass via case variation
    let path_lower = path.to_lowercase();
    // Only allocate decoded lowercase if URL actually contained percent-encoding
    let decoded_lower = if has_encoding {
        Some(decoded_path.to_lowercase())
    } else {
        None
    };

    // Patterns are expected to be pre-normalized to lowercase
    blocked_patterns.iter().any(|pattern| {
        path_lower.contains(pattern.as_str())
            || decoded_lower
                .as_ref()
                .is_some_and(|dl| dl.contains(pattern.as_str()))
    })
}

/// Decode URL-encoded string (percent-encoding)
/// Handles common bypass attempts like %2e for '.', %70 for 'p', etc.
/// Properly handles multi-byte UTF-8 sequences.
fn url_decode(input: &str) -> String {
    let mut bytes = Vec::with_capacity(input.len());
    let input_bytes = input.as_bytes();
    let mut i = 0;

    while i < input_bytes.len() {
        if input_bytes[i] == b'%' && i + 2 < input_bytes.len() {
            // Try to decode two hex digits without allocating
            let hi = hex_digit(input_bytes[i + 1]);
            let lo = hex_digit(input_bytes[i + 2]);
            if let (Some(h), Some(l)) = (hi, lo) {
                bytes.push(h << 4 | l);
                i += 3;
                continue;
            }
        }
        bytes.push(input_bytes[i]);
        i += 1;
    }

    // Convert bytes to string, replacing invalid UTF-8 with replacement character
    String::from_utf8_lossy(&bytes).into_owned()
}

/// Converts an ASCII hex digit to its numeric value.
fn hex_digit(b: u8) -> Option<u8> {
    match b {
        b'0'..=b'9' => Some(b - b'0'),
        b'a'..=b'f' => Some(b - b'a' + 10),
        b'A'..=b'F' => Some(b - b'A' + 10),
        _ => None,
    }
}

/// Check if HTTP method is blocked
fn is_method_blocked(method: &str, config: &impl ConfigProvider) -> bool {
    let blocked_methods = config.blocked_methods();
    blocked_methods
        .iter()
        .any(|blocked_method| blocked_method.eq_ignore_ascii_case(method))
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::test_utils::TestConfig;
    use http_body_util::BodyExt;

    #[tokio::test]
    async fn body_limit_rejects_chunked_stream_without_waiting_for_eof() {
        use futures::{FutureExt, StreamExt, stream};
        use hyper::body::Frame;

        let frames = stream::iter([
            Ok::<_, Infallible>(Frame::data(bytes::Bytes::from_static(b"abc"))),
            Ok(Frame::data(bytes::Bytes::from_static(b"def"))),
        ])
        .chain(stream::pending());
        let body = http_body_util::StreamBody::new(frames);
        let result = collect_request_body(body, 5)
            .now_or_never()
            .expect("must reject before the stream ends");
        assert!(matches!(
            result,
            Err(WiseGateError::BodyTooLarge { size: 6, max: 5 })
        ));
    }

    #[tokio::test]
    async fn body_limit_accepts_exact_limit_and_zero_remains_unlimited() {
        for limit in [0, 6] {
            let result =
                collect_request_body(Full::new(bytes::Bytes::from_static(b"abcdef")), limit)
                    .await
                    .unwrap();
            assert_eq!(result.as_ref(), b"abcdef");
        }
    }

    #[tokio::test]
    async fn unfinished_body_times_out_and_closes_connection() {
        use futures::stream;
        use hyper::body::Frame;

        let stream = stream::pending::<Result<Frame<bytes::Bytes>, Infallible>>();
        let err = read_request_body(
            http_body_util::StreamBody::new(stream),
            0,
            std::time::Duration::from_millis(1),
        )
        .await
        .unwrap_err();
        let response = create_body_error_response(&err);
        assert_eq!(response.status(), StatusCode::REQUEST_TIMEOUT);
        assert_eq!(response.headers()[headers::CONNECTION], "close");
        assert!(!err.is_server_error());
    }

    // ===========================================
    // url_decode tests
    // ===========================================

    #[test]
    fn test_url_decode_no_encoding() {
        assert_eq!(url_decode("/path/to/file"), "/path/to/file");
        assert_eq!(url_decode("hello"), "hello");
        assert_eq!(url_decode(""), "");
    }

    #[test]
    fn test_url_decode_simple_encoding() {
        assert_eq!(url_decode("%20"), " ");
        assert_eq!(url_decode("hello%20world"), "hello world");
        assert_eq!(url_decode("%2F"), "/");
    }

    #[test]
    fn test_url_decode_dot_encoding() {
        // Common bypass attempts
        assert_eq!(url_decode("%2e"), ".");
        assert_eq!(url_decode("%2E"), ".");
        assert_eq!(url_decode(".%2ephp"), "..php");
    }

    #[test]
    fn test_url_decode_php_bypass() {
        // Attacker tries to bypass .php blocking
        assert_eq!(url_decode(".ph%70"), ".php");
        assert_eq!(url_decode("%2ephp"), ".php");
        assert_eq!(url_decode(".%70%68%70"), ".php");
    }

    #[test]
    fn test_url_decode_env_bypass() {
        // Attacker tries to bypass .env blocking
        assert_eq!(url_decode(".%65nv"), ".env");
        assert_eq!(url_decode("%2eenv"), ".env");
        assert_eq!(url_decode("%2e%65%6e%76"), ".env");
    }

    #[test]
    fn test_url_decode_multiple_encodings() {
        assert_eq!(url_decode("%2F%2e%2e%2Fetc%2Fpasswd"), "/../etc/passwd");
    }

    #[test]
    fn test_url_decode_invalid_hex() {
        // Invalid hex should be preserved
        assert_eq!(url_decode("%GG"), "%GG");
        assert_eq!(url_decode("%"), "%");
        assert_eq!(url_decode("%2"), "%2");
        assert_eq!(url_decode("%ZZ"), "%ZZ");
    }

    #[test]
    fn test_url_decode_mixed_content() {
        assert_eq!(url_decode("path%2Fto%2Ffile.txt"), "path/to/file.txt");
        assert_eq!(url_decode("hello%20%26%20world"), "hello & world");
    }

    #[test]
    fn test_url_decode_unicode() {
        // UTF-8 encoded characters
        assert_eq!(url_decode("%C3%A9"), "é"); // é in UTF-8
        assert_eq!(url_decode("caf%C3%A9"), "café");
    }

    // ===========================================
    // is_url_pattern_blocked tests
    // ===========================================

    #[test]
    fn test_url_pattern_blocked_simple() {
        let config = TestConfig::new().with_blocked_patterns(vec![".php", ".env"]);

        assert!(is_url_pattern_blocked("/file.php", &config));
        assert!(is_url_pattern_blocked("/.env", &config));
        assert!(is_url_pattern_blocked("/path/to/file.php", &config));
    }

    #[test]
    fn test_url_pattern_not_blocked() {
        let config = TestConfig::new().with_blocked_patterns(vec![".php", ".env"]);

        assert!(!is_url_pattern_blocked("/file.html", &config));
        assert!(!is_url_pattern_blocked("/path/to/file.js", &config));
        assert!(!is_url_pattern_blocked("/", &config));
    }

    #[test]
    fn test_url_pattern_blocked_empty_patterns() {
        let config = TestConfig::new();

        assert!(!is_url_pattern_blocked("/file.php", &config));
        assert!(!is_url_pattern_blocked("/.env", &config));
    }

    #[test]
    fn test_url_pattern_blocked_bypass_attempt() {
        let config = TestConfig::new().with_blocked_patterns(vec![".php", ".env", "admin"]);

        // URL-encoded bypass attempts should still be blocked
        assert!(is_url_pattern_blocked("/.ph%70", &config)); // .php
        assert!(is_url_pattern_blocked("/%2eenv", &config)); // .env
        assert!(is_url_pattern_blocked("/adm%69n", &config)); // admin
    }

    #[test]
    fn test_url_pattern_blocked_double_encoding_attempt() {
        let config = TestConfig::new().with_blocked_patterns(vec![".php"]);

        // Single encoding should be caught
        assert!(is_url_pattern_blocked("/.ph%70", &config));
    }

    #[test]
    fn test_url_pattern_blocked_case_insensitive() {
        let config = TestConfig::new().with_blocked_patterns(vec![".php"]);

        // Pattern matching is case-insensitive to prevent bypass
        assert!(is_url_pattern_blocked("/file.PHP", &config));
        assert!(is_url_pattern_blocked("/file.php", &config));
        assert!(is_url_pattern_blocked("/file.Php", &config));
    }

    #[test]
    fn test_url_pattern_blocked_partial_match() {
        let config = TestConfig::new().with_blocked_patterns(vec!["admin"]);

        assert!(is_url_pattern_blocked("/admin/panel", &config));
        assert!(is_url_pattern_blocked("/path/admin", &config));
        assert!(is_url_pattern_blocked("/administrator", &config)); // Contains "admin"
    }

    // ===========================================
    // is_method_blocked tests
    // ===========================================

    #[test]
    fn test_method_blocked() {
        let config = TestConfig::new().with_blocked_methods(vec!["TRACE", "CONNECT"]);

        assert!(is_method_blocked("TRACE", &config));
        assert!(is_method_blocked("CONNECT", &config));
    }

    #[test]
    fn test_method_not_blocked() {
        let config = TestConfig::new().with_blocked_methods(vec!["TRACE", "CONNECT"]);

        assert!(!is_method_blocked("GET", &config));
        assert!(!is_method_blocked("POST", &config));
        assert!(!is_method_blocked("PUT", &config));
        assert!(!is_method_blocked("DELETE", &config));
    }

    #[test]
    fn test_method_blocked_empty_list() {
        let config = TestConfig::new();

        assert!(!is_method_blocked("TRACE", &config));
        assert!(!is_method_blocked("GET", &config));
    }

    #[test]
    fn test_method_blocked_case_insensitive() {
        let config = TestConfig::new().with_blocked_methods(vec!["TRACE"]);

        assert!(is_method_blocked("TRACE", &config));
        assert!(is_method_blocked("trace", &config));
        assert!(is_method_blocked("Trace", &config));
    }

    // ===========================================
    // create_error_response tests
    // ===========================================

    #[test]
    fn test_create_error_response_status() {
        let response = create_error_response(StatusCode::NOT_FOUND, "Not Found");
        assert_eq!(response.status(), StatusCode::NOT_FOUND);

        let response = create_error_response(StatusCode::FORBIDDEN, "Forbidden");
        assert_eq!(response.status(), StatusCode::FORBIDDEN);

        let response = create_error_response(StatusCode::TOO_MANY_REQUESTS, "Rate limited");
        assert_eq!(response.status(), StatusCode::TOO_MANY_REQUESTS);
    }

    #[test]
    fn test_create_error_response_content_type() {
        let response = create_error_response(StatusCode::NOT_FOUND, "Not Found");
        assert_eq!(
            response.headers().get("content-type").unwrap(),
            "text/plain"
        );
    }

    #[tokio::test]
    async fn test_create_error_response_body() {
        let response = create_error_response(StatusCode::NOT_FOUND, "Resource not found");
        let body = response.into_body().collect().await.unwrap().to_bytes();
        assert_eq!(body, "Resource not found");
    }

    #[tokio::test]
    async fn test_create_error_response_empty_message() {
        let response = create_error_response(StatusCode::NO_CONTENT, "");
        let body = response.into_body().collect().await.unwrap().to_bytes();
        assert_eq!(body, "");
    }

    // ===========================================
    // create_unauthorized_response tests
    // ===========================================

    #[test]
    fn test_unauthorized_response_status() {
        let response = create_unauthorized_response("WiseGate");
        assert_eq!(response.status(), StatusCode::UNAUTHORIZED);
    }

    #[test]
    fn test_unauthorized_response_www_authenticate_header() {
        let response = create_unauthorized_response("WiseGate");
        let header = response
            .headers()
            .get("www-authenticate")
            .unwrap()
            .to_str()
            .unwrap();
        assert_eq!(header, "Basic realm=\"WiseGate\"");
    }

    #[test]
    fn test_unauthorized_response_realm_with_quotes() {
        let response = create_unauthorized_response("My \"Realm\"");
        let header = response
            .headers()
            .get("www-authenticate")
            .unwrap()
            .to_str()
            .unwrap();
        assert_eq!(header, "Basic realm=\"My \\\"Realm\\\"\"");
    }

    #[test]
    fn test_unauthorized_response_realm_with_backslash() {
        let response = create_unauthorized_response("My\\Realm");
        let header = response
            .headers()
            .get("www-authenticate")
            .unwrap()
            .to_str()
            .unwrap();
        assert_eq!(header, "Basic realm=\"My\\\\Realm\"");
    }

    #[test]
    fn test_unauthorized_response_content_type() {
        let response = create_unauthorized_response("WiseGate");
        assert_eq!(
            response.headers().get("content-type").unwrap(),
            "text/plain"
        );
    }

    // ===========================================
    // double-encoding test
    // ===========================================

    #[test]
    fn test_url_decode_double_encoding_not_decoded_twice() {
        // %252e decodes to %2e on first pass — should NOT become '.'
        assert_eq!(url_decode("%252e"), "%2e");
        assert_eq!(url_decode("%2565nv"), "%65nv");
    }
}