zlsrs 0.1.6

//! HTTP 客户端的核心类型定义
//!
//! 这个模块包含了 HTTP 客户端所需的所有核心类型定义，包括：
//! - HTTP 请求方法
//! - 请求体格式
//! - HTTP 响应
//! - 客户端配置
//! - 错误处理

use crate::zfile;
use crate::zfile::ZPath;
use std::collections::HashMap;
use std::time::Duration;

/// HTTP 请求方法
///
/// 支持标准的 HTTP 方法，包括 GET、POST、PUT、DELETE 等。
///
/// # 示例
/// ```
/// use zlsrs::zhttp::Method;
///
/// let method = Method::GET;
/// assert_eq!(method.as_str(), "GET");
/// ```
#[derive(Debug, Clone, Eq, PartialEq)]
pub enum Method {
    /// HTTP GET 方法，用于获取资源
    GET,
    /// HTTP POST 方法，用于创建资源
    POST,
    /// HTTP PUT 方法，用于更新资源
    PUT,
    /// HTTP DELETE 方法，用于删除资源
    DELETE,
    /// HTTP HEAD 方法，类似 GET 但只返回头部
    HEAD,
    /// HTTP OPTIONS 方法，用于获取服务器支持的方法
    OPTIONS,
    /// HTTP PATCH 方法，用于部分更新资源
    PATCH,
}

impl Method {
    pub(crate) fn as_str(&self) -> &str {
        match self {
            Method::GET => "GET",
            Method::POST => "POST",
            Method::PUT => "PUT",
            Method::DELETE => "DELETE",
            Method::HEAD => "HEAD",
            Method::OPTIONS => "OPTIONS",
            Method::PATCH => "PATCH",
        }
    }
}

/// 请求体格式定义
///
/// 支持多种常见的请求体格式，包括表单、JSON、纯文本等。
///
/// # 示例
/// ```
/// use zlsrs::zhttp::BodyFormat;
///
/// let format = BodyFormat::Json;
/// assert_eq!(format.content_type(), "application/json");
/// ```
#[derive(Debug, Clone, PartialEq)]
pub enum BodyFormat {
    /// application/x-www-form-urlencoded 格式
    /// 用于普通的表单提交
    FormUrlEncoded,
    /// application/json 格式
    /// 用于 JSON 数据传输
    Json,
    /// text/plain 格式
    /// 用于纯文本数据
    Text,
    /// multipart/form-data 格式
    /// 用于文件上传等场景，需要指定 boundary
    FormData(String),
    /// 自定义 Content-Type 格式
    /// 用于不在预定义范围内的格式
    Custom(String),
}

impl BodyFormat {
    pub(crate) fn content_type(&self) -> String {
        match self {
            BodyFormat::FormUrlEncoded => "application/x-www-form-urlencoded".to_string(),
            BodyFormat::Json => "application/json".to_string(),
            BodyFormat::Text => "text/plain".to_string(),
            BodyFormat::FormData(boundary) => format!("multipart/form-data; boundary={}", boundary),
            BodyFormat::Custom(content_type) => content_type.clone(),
        }
    }
}

/// HTTP 响应结构
///
/// 包含了 HTTP 响应的完整信息，包括状态码、响应头和响应体。
/// 提供了多种方法来访问和解析响应内容。
///
/// # 示例
/// ```
/// use zlsrs::zhttp::{Client, Response};
///
/// async fn example() -> Result<()> {
///     let client = Client::new();
///     let response = client.get("https://api.example.com").send().await?;
///     
///     println!("Status: {}", response.status);
///     println!("Body: {}", response.text()?);
///     Ok(())
/// }
/// ```
#[derive(Debug)]
pub struct Response {
    /// HTTP 状态码
    pub status: u16,
    /// 响应头
    pub(crate) headers: HashMap<String, String>,
    /// 响应体
    pub(crate) body: Vec<u8>,
}

impl Response {
    /// 获取响应体的文本内容
    pub fn text(&self) -> Result<String, Error> {
        String::from_utf8(self.body.clone()).map_err(|e| Error::Custom(e.to_string()))
    }

    /// 尝试将响应体解析为 JSON
    #[cfg(feature = "json")]
    pub fn json<T: serde::de::DeserializeOwned>(&self) -> Result<T, Error> {
        serde_json::from_slice(&self.body).map_err(|e| Error::Custom(e.to_string()))
    }

    /// 获取响应体的原始字节
    pub fn bytes(&self) -> &[u8] {
        &self.body
    }

    /// 获取指定响应头的值
    pub fn header(&self, name: &str) -> Option<&String> {
        // 不区分大小写的头部查找
        self.headers.iter().find_map(|(key, value)| {
            if key.eq_ignore_ascii_case(name) {
                Some(value)
            } else {
                None
            }
        })
    }

    /// 获取所有响应头
    pub fn headers(&self) -> &HashMap<String, String> {
        &self.headers
    }

    /// 检查响应是否成功 (2xx)
    pub fn is_success(&self) -> bool {
        (200..300).contains(&self.status)
    }

    /// 检查是否为重定向响应 (3xx)
    pub fn is_redirect(&self) -> bool {
        (300..400).contains(&self.status)
    }

    /// 检查是否为客户端错误 (4xx)
    pub fn is_client_error(&self) -> bool {
        (400..500).contains(&self.status)
    }

    /// 检查是否为服务器错误 (5xx)
    pub fn is_server_error(&self) -> bool {
        (500..600).contains(&self.status)
    }

    /// 获取响应体的长度
    pub fn content_length(&self) -> usize {
        self.body.len()
    }

    /// 获取响应的内容类型
    pub fn content_type(&self) -> Option<&String> {
        self.header("Content-Type")
    }

    /// 将响应内容保存到文件
    ///
    /// # 参数
    ///
    /// * `path` - 文件保存路径，支持字符串或 PathBuf
    ///
    /// # 示例
    ///
    /// ```rust
    /// use zlsrs::zhttp::Client;
    ///
    /// async fn example() {
    ///     let client = Client::new();
    ///     let response = client
    ///         .get("https://example.com/file.pdf")
    ///         .send()
    ///         .unwrap();
    ///
    ///     // 保存到指定路径
    ///     response.save_to_file("downloads/file.pdf");
    /// }
    /// ```
    #[cfg(feature = "zfile")]
    pub fn save_to_file<P: AsRef<std::path::Path>>(&self, path: P) -> Result<ZPath, Error> {
        zfile::write_file(
            &path.as_ref().to_string_lossy(),
            &String::from_utf8_lossy(&self.body),
            false,
        )
        .map_err(|e| Error::Custom(format!("保存文件失败: {}", e)))
        .map(|path| ZPath::new(&path.as_ref().to_string_lossy()))
    }

    /// 将响应内容保存到文件，并自动从 Content-Disposition 或 URL 推断文件名
    ///
    /// # 参数
    ///
    /// * `dir` - 保存目录的路径
    ///
    /// # 返回值
    ///
    /// 返回保存的文件路径
    ///
    /// # 示例
    ///
    /// ```rust
    /// use zlsrs::zhttp::Client;
    ///
    /// async fn example() -> Result<(), Box<dyn std::error::Error>> {
    ///     let client = Client::new();
    ///     let response = client
    ///         .get("https://example.com/file.pdf")
    ///         .send()
    ///         .await?;
    ///
    ///     // 自动保存到 downloads 目录，文件名从响应中推断
    ///     let saved_path = response.save_to_dir("downloads")?;
    ///     println!("文件已保存到: {}", saved_path.display());
    ///     Ok(())
    /// }
    /// ```
    #[cfg(feature = "zfile")]
    pub fn save_to_dir<P: AsRef<std::path::Path>>(
        &self,
        dir: P,
    ) -> Result<std::path::PathBuf, Error> {
        use crate::zfile;
        use std::path::PathBuf;

        // 创建目录（如果不存在）
        zfile::create_dir(&dir.as_ref().to_string_lossy())
            .map_err(|e| Error::Custom(format!("创建目录失败: {}", e)))?;

        // 尝试从 Content-Disposition 获取文件名
        let filename = self
            .get_filename_from_disposition()
            .or_else(|| self.get_filename_from_url())
            .unwrap_or_else(|| "downloaded_file".to_string());

        let path = PathBuf::from(dir.as_ref()).join(filename);

        // 写入文件
        zfile::write_file(
            &path.to_string_lossy(),
            &String::from_utf8_lossy(&self.body),
            false,
        )
        .map_err(|e| Error::Custom(format!("保存文件失败: {}", e)))?;

        Ok(path)
    }

    /// 从 Content-Disposition 头部获取文件名
    fn get_filename_from_disposition(&self) -> Option<String> {
        self.header("Content-Disposition").and_then(|cd| {
            cd.split(';')
                .find(|part| part.trim().starts_with("filename="))
                .and_then(|filename_part| {
                    filename_part
                        .trim()
                        .strip_prefix("filename=")
                        .map(|filename| filename.trim_matches('"').trim_matches('\'').to_string())
                })
        })
    }

    /// 从 URL 获取文件名
    fn get_filename_from_url(&self) -> Option<String> {
        self.header("Location")
            .or_else(|| self.header("X-Original-URL"))
            .and_then(|url| {
                url.split('/')
                    .last()
                    .map(|s| s.split('?').next().unwrap_or(s).to_string())
            })
    }
}

/// HTTP 客户端配置
///
/// 用于自定义 HTTP 客户端的行为，包括超时设置、重试策略等。
///
/// # 示例
/// ```
/// use zlsrs::zhttp::{Client, ClientConfig};
/// use std::time::Duration;
///
/// let config = ClientConfig {
///     timeout: Duration::from_secs(60),
///     max_retries: 5,
///     ..Default::default()
/// };
/// let client = Client::with_config(config);
/// ```
#[derive(Debug, Clone)]
pub struct ClientConfig {
    /// 请求超时时间
    pub timeout: Duration,
    /// 自定义 User-Agent 字符串
    pub user_agent: String,
    /// 请求失败时的最大重试次数
    pub max_retries: u32,
    /// 重试之间的等待时间
    pub retry_interval: Duration,
    /// 是否自动处理重定向
    pub allow_redirects: bool,
    /// 最大允许的重定向次数
    pub max_redirects: u32,
    /// 是否验证 SSL 证书
    pub verify_ssl: bool,
    /// 是否启用调试模式
    pub debug: bool,
}

impl Default for ClientConfig {
    fn default() -> Self {
        Self {
            timeout: Duration::from_secs(30),
            user_agent: "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/132.0.0.0 Safari/537.36".to_string(),
            max_retries: 3,
            retry_interval: Duration::from_secs(1),
            allow_redirects: true,
            max_redirects: 10,
            verify_ssl: true,
            debug: false,
        }
    }
}

/// HTTP 错误类型
///
/// 定义了在 HTTP 请求过程中可能遇到的各种错误。
///
/// # 示例
/// ```
/// use zlsrs::zhttp::Error;
///
/// fn handle_error(err: Error) {
///     match err {
///         Error::Timeout => println!("请求超时"),
///         Error::Network(e) => println!("网络错误: {}", e),
///         _ => println!("其他错误: {}", err),
///     }
/// }
/// ```
#[derive(Debug, thiserror::Error)]
pub enum Error {
    /// 请求超时错误
    #[error("请求超时")]
    Timeout,
    /// 网络相关错误
    #[error("网络错误: {0}")]
    Network(#[from] std::io::Error),
    /// URL 解析错误
    #[error("URL 解析错误: {0}")]
    UrlParse(#[from] url::ParseError),
    /// 响应解析错误
    #[error("响应解析错误: {0}")]
    ResponseParse(String),
    /// 重定向次数超过限制
    #[error("重定向次数过多")]
    TooManyRedirects,
    /// SSL 证书验证失败
    #[error("SSL 证书验证失败")]
    SslVerification,
    /// 无效的 HTTP 状态码
    #[error("无效的状态码")]
    InvalidStatus,
    /// 自定义错误
    #[error("自定义错误: {0}")]
    Custom(String),
}

impl From<serde_json::Error> for Error {
    fn from(err: serde_json::Error) -> Self {
        Error::Custom(err.to_string())
    }
}