wordval-utils 1.0.0

Wordval utilities: string manipulation, date handling, masking, ID generation, validation, crypto, web helpers
Documentation
//! Web 解析工具:URL 解析、IP 提取、User-Agent 解析等

use std::net::SocketAddr;

/// 检查是否为私有 IP(IPv4/IPv6)
///
/// IPv4 私有地址包括:私有地址(10/8, 172.16/12, 192.168/16)、环回地址(127/8)、
/// 链路本地地址(169.254/16)、未指定地址(0.0.0.0)、组播地址(224/4)
///
/// IPv6 私有地址包括:环回地址(::1)、未指定地址(::)、链路本地单播(fe80::/10)、
/// 唯一本地地址(fc00::/7)、组播地址(ff::/8)
///
/// # 参数
/// - `ip`: IP 地址字符串
///
/// # 返回
/// 若为私有 IP 返回 true,否则返回 false
pub fn is_private_ip(ip: &str) -> bool {
    if let Ok(addr) = ip.parse::<std::net::IpAddr>() {
        match addr {
            std::net::IpAddr::V4(ipv4) => {
                ipv4.is_private()
                    || ipv4.is_loopback()
                    || ipv4.is_link_local()
                    || ipv4.is_unspecified()
                    || ipv4.is_multicast()
            }
            std::net::IpAddr::V6(ipv6) => {
                ipv6.is_loopback()
                    || ipv6.is_unspecified()
                    || ipv6.is_unicast_link_local()
                    || ipv6.is_unique_local()
                    || ipv6.is_multicast()
            }
        }
    } else {
        false
    }
}

/// 安全默认:从直连对端地址提取客户端 IP。
///
/// **不信任任何代理头**(X-Forwarded-For / CF-Connecting-IP 等)。
///
/// 若服务前置可信反代/负载均衡,请改用 [`extract_client_ip_trusted`]
/// 并在配置中声明 `trusted_proxies`,仅在直连对端为可信网段时才读取头部。
pub fn extract_client_ip(_headers: &http::HeaderMap, connect_info: &SocketAddr) -> String {
    connect_info.ip().to_string()
}

/// 可信代理网段集合(支持精确 IP 或 CIDR,如 `10.0.0.0/8`)
pub struct TrustedProxies {
    nets: Vec<(std::net::IpAddr, u32)>,
}

impl TrustedProxies {
    /// 从配置字符串列表解析可信代理(支持 `ip` 或 `ip/bits` CIDR)。
    /// 无法解析的项会被静默忽略。
    pub fn new(specs: &[String]) -> Self {
        let mut nets = Vec::with_capacity(specs.len());
        for s in specs {
            let trimmed = s.trim();
            if trimmed.is_empty() {
                continue;
            }
            let (ip_str, bits) = match trimmed.split_once('/') {
                Some((ip_s, pre_s)) => {
                    match (
                        ip_s.trim().parse::<std::net::IpAddr>(),
                        pre_s.trim().parse::<u32>(),
                    ) {
                        (Ok(ip), Ok(b)) => (ip, b),
                        _ => continue,
                    }
                }
                None => match trimmed.parse::<std::net::IpAddr>() {
                    Ok(ip) => (ip, if ip.is_ipv4() { 32 } else { 128 }),
                    _ => continue,
                },
            };
            nets.push((ip_str, bits));
        }
        TrustedProxies { nets }
    }

    /// 是否为空(未配置任何可信代理)
    pub fn is_empty(&self) -> bool {
        self.nets.is_empty()
    }

    /// 判断给定 IP 是否落在某个可信网段内
    pub fn contains(&self, ip: &std::net::IpAddr) -> bool {
        self.nets
            .iter()
            .any(|(net, bits)| ip_in_net(ip, net, *bits))
    }
}

/// 判断 `ip` 是否落在以 `net` 为网络地址、`bits` 为前缀长度的网络内
fn ip_in_net(ip: &std::net::IpAddr, net: &std::net::IpAddr, bits: u32) -> bool {
    match (ip, net) {
        (std::net::IpAddr::V4(a), std::net::IpAddr::V4(b)) => {
            let bits = bits.min(32);
            if bits == 0 {
                return true;
            }
            let mask = if bits >= 32 {
                u32::MAX
            } else {
                !(u32::MAX >> bits)
            };
            (u32::from(*a) & mask) == (u32::from(*b) & mask)
        }
        (std::net::IpAddr::V6(a), std::net::IpAddr::V6(b)) => {
            let bits = bits.min(128);
            if bits == 0 {
                return true;
            }
            let ma = a.segments();
            let mb = b.segments();
            let mut done = 0u32;
            for i in 0..8 {
                if done >= bits {
                    return true;
                }
                let remain = bits - done;
                let m: u16 = if remain >= 16 {
                    0xFFFF
                } else {
                    !(0xFFFFu16 >> remain)
                };
                if (ma[i] & m) != (mb[i] & m) {
                    return false;
                }
                done += 16;
            }
            true
        }
        _ => false,
    }
}

/// 从请求头提取客户端真实 IP(仅在直连对端为可信代理时读取头部)。
///
/// 算法:
/// 1. 若直连对端 IP 不在可信网段内,直接返回直连 IP(不读取任何头部)。
/// 2. 若直连对端可信,则优先取 `CF-Connecting-IP`;否则解析 `X-Forwarded-For`
///    从右向左遍历,跳过可信网段与私有/环回/未指定地址,取第一个真实公网 IP。
pub fn extract_client_ip_trusted(
    headers: &http::HeaderMap,
    connect_info: &SocketAddr,
    trusted: &TrustedProxies,
) -> String {
    let peer = connect_info.ip();
    if !trusted.contains(&peer) {
        return peer.to_string();
    }

    // 直连对端是可信代理,从头部取真实 IP
    if let Some(v) = headers
        .get("CF-Connecting-IP")
        .and_then(|h| h.to_str().ok())
    {
        if let Ok(ip) = v.trim().parse::<std::net::IpAddr>() {
            if !trusted.contains(&ip) {
                return ip.to_string();
            }
        }
    }

    if let Some(v) = headers.get("X-Forwarded-For").and_then(|h| h.to_str().ok()) {
        let mut ips: Vec<std::net::IpAddr> = v
            .split(',')
            .filter_map(|p| p.trim().parse::<std::net::IpAddr>().ok())
            .collect();
        ips.reverse();
        for ip in ips {
            if trusted.contains(&ip) || is_internal_ip(&ip) {
                continue;
            }
            return ip.to_string();
        }
    }

    peer.to_string()
}

/// 判断 IP 是否为内部/不可路由地址(私有、环回、未指定、IPv6 唯一本地)
fn is_internal_ip(ip: &std::net::IpAddr) -> bool {
    match ip {
        std::net::IpAddr::V4(a) => a.is_private() || a.is_loopback() || a.is_unspecified(),
        std::net::IpAddr::V6(a) => a.is_loopback() || a.is_unspecified() || a.is_unique_local(),
    }
}

/// Web 解析工具
///
/// 提供 URL 解析、真实 IP 获取、私网 IP 判断、查询字符串构造等功能。
pub struct WebExt;

impl WebExt {
    /// 拆分 URL:返回 `(host[:port], 路径部分)`。路径部分含开头 `/`,无路径时为 None。
    /// 仅支持带 `scheme://` 的绝对 URL(与原 url crate 行为一致:相对 URL 返回 None)。
    fn split_authority(url_str: &str) -> Option<(&str, Option<&str>)> {
        let rest = url_str.split_once("://")?.1;
        let (authority, path_part) = match rest.find(['/', '?', '#']) {
            Some(i) => (&rest[..i], Some(&rest[i..])),
            None => (rest, None),
        };
        // authority 中跳过 userinfo(`user:pass@`),取最后一个 `@` 之后
        let host_port = authority
            .rsplit_once('@')
            .map(|(_, h)| h)
            .unwrap_or(authority);
        Some((host_port, path_part))
    }

    /// 解析 URL 获取域名(自研实现,替代 url crate)
    ///
    /// 支持 userinfo、IPv6 括号形式;端口会被剥离,IPv6 返回无括号形式。
    pub fn domain(url_str: &str) -> Option<String> {
        let (host_port, _) = Self::split_authority(url_str)?;
        if host_port.is_empty() {
            return None;
        }
        if let Some(ipv6) = host_port.strip_prefix('[') {
            return ipv6.find(']').map(|end| ipv6[..end].to_string());
        }
        host_port.split(':').next().map(|h| h.to_string())
    }

    /// 解析 URL 获取路径(含开头的 `/`,不含 query/fragment;自研实现,替代 url crate)
    pub fn path(url_str: &str) -> Option<String> {
        let (_, path_part) = Self::split_authority(url_str)?;
        match path_part {
            None => Some("/".to_string()),
            Some(p) => {
                if p.starts_with('?') || p.starts_with('#') {
                    return Some("/".to_string());
                }
                let end = p.find(['?', '#']).unwrap_or(p.len());
                Some(p[..end].to_string())
            }
        }
    }

    /// 从请求头获取真实 IP(X-Forwarded-For 或 X-Real-IP)。
    ///
    /// # 安全警告
    ///
    /// 本方法**无条件信任** `X-Forwarded-For` / `X-Real-IP` 头,任何客户端都能
    /// 伪造这些头来伪装来源 IP。**切勿**用于限流、鉴权、审计等安全敏感场景。
    /// 仅当服务确定运行在可信反向代理之后、且该代理会覆盖这些头时才可使用。
    ///
    /// 安全场景请改用 [`extract_client_ip_trusted`],它会校验直连对端是否为
    /// 可信代理网段后再读取头部。
    pub fn real_ip(headers: &[(String, String)], remote_addr: &str) -> String {
        for (key, val) in headers {
            if key.eq_ignore_ascii_case("x-forwarded-for") {
                // 取最左侧(最接近原始客户端)的有效 IP
                if let Some(ip) = val
                    .split(',')
                    .filter_map(|p| p.trim().parse::<std::net::IpAddr>().ok())
                    .next()
                {
                    return ip.to_string();
                }
            }
            if key.eq_ignore_ascii_case("x-real-ip") {
                if let Ok(ip) = val.trim().parse::<std::net::IpAddr>() {
                    return ip.to_string();
                }
            }
        }
        remote_addr
            .split(':')
            .next()
            .unwrap_or(remote_addr)
            .to_string()
    }
    /// 检查是否为私有 IP(委托给公共函数 `is_private_ip`)
    pub fn is_private_ip(ip: &str) -> bool {
        is_private_ip(ip)
    }
    /// 构建 URL 查询字符串
    pub fn build_query(params: &[(&str, &str)]) -> String {
        if params.is_empty() {
            return String::new();
        }
        let parts: Vec<String> = params
            .iter()
            .map(|(k, v)| format!("{}={}", urlencoding(k), urlencoding(v)))
            .collect();
        format!("?{}", parts.join("&"))
    }
}

fn urlencoding(s: &str) -> String {
    let mut result = String::with_capacity(s.len() * 3);
    for byte in s.bytes() {
        match byte {
            b'A'..=b'Z' | b'a'..=b'z' | b'0'..=b'9' | b'-' | b'_' | b'.' | b'~' => {
                result.push(byte as char);
            }
            _ => {
                result.push_str(&format!("%{:02X}", byte));
            }
        }
    }
    result
}