crawlrs 0.2.0

crawlrs - Enterprise-grade web scraping and crawling platform built with Rust
Documentation
// Copyright (c) 2025-2026 Kirky.X🌠
// SPDX-License-Identifier: Apache-2.0

//! GeoLocation domain service trait and models
//!
//! This module defines the domain-level abstraction for IP geolocation services.
//! The trait is defined in the domain layer, while implementations reside in the
//! infrastructure layer, following the Dependency Inversion Principle.

use anyhow::Result;
use serde::{Deserialize, Serialize};
use std::net::{IpAddr, Ipv4Addr, Ipv6Addr};

/// IP地理位置信息
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct GeoLocation {
    /// IP地址
    pub ip: String,
    /// 国家代码 (ISO 3166-1 alpha-2)
    pub country_code: String,
    /// 国家名称
    pub country_name: String,
    /// 地区/州
    pub region: Option<String>,
    /// 城市
    pub city: Option<String>,
    /// 纬度
    pub latitude: Option<f64>,
    /// 经度
    pub longitude: Option<f64>,
    /// ISP
    pub isp: Option<String>,
    /// 组织
    pub org: Option<String>,
}

impl Default for GeoLocation {
    fn default() -> Self {
        Self {
            ip: String::new(),
            country_code: "UNKNOWN".to_string(),
            country_name: "Unknown".to_string(),
            region: None,
            city: None,
            latitude: None,
            longitude: None,
            isp: None,
            org: None,
        }
    }
}

/// IP地理定位服务Trait
///
/// 定义IP地址地理位置查询的抽象接口。
/// 实现此trait的具体服务位于基础设施层。
#[async_trait::async_trait]
pub trait GeoLocationService: Send + Sync {
    /// 获取指定IP地址的地理位置信息
    ///
    /// # 参数
    ///
    /// * `ip` - IP地址
    ///
    /// # 返回值
    ///
    /// * `Ok(GeoLocation)` - 地理位置信息
    /// * `Err(anyhow::Error)` - 查询失败
    async fn get_location(&self, ip: &IpAddr) -> Result<GeoLocation>;
}

/// 检查IP地址是否在CIDR范围内
///
/// # 参数
///
/// * `ip` - IP地址
/// * `cidr` - CIDR表示法 (如 "192.168.1.0/24")
///
/// # 返回值
///
/// * `bool` - 如果IP在CIDR范围内返回true,否则返回false
pub fn is_ip_in_cidr(ip: &IpAddr, cidr: &str) -> bool {
    // use split_once instead of split.collect::<Vec>
    let (network_str, prefix_str) = match cidr.split_once('/') {
        Some(pair) => pair,
        None => return false,
    };
    // fail-closed(CWE-1229):畸形前缀(如 "/abc"、"/999")不得回退为 /0
    // 全匹配——解析失败按"不匹配"处理并告警,避免白名单被静默放行
    let prefix_length = match prefix_str.parse::<u8>() {
        Ok(p) => p,
        Err(_) => {
            log::warn!(
                "Invalid CIDR prefix length in '{}', treating as non-match",
                cidr
            );
            return false;
        }
    };

    match (ip, network_str.parse::<IpAddr>()) {
        (IpAddr::V4(ip_v4), Ok(IpAddr::V4(network_v4))) => {
            is_ipv4_in_cidr(ip_v4, &network_v4, prefix_length)
        }
        (IpAddr::V6(ip_v6), Ok(IpAddr::V6(network_v6))) => {
            is_ipv6_in_cidr(ip_v6, &network_v6, prefix_length)
        }
        _ => false,
    }
}

fn is_ipv4_in_cidr(ip: &Ipv4Addr, network: &Ipv4Addr, prefix_length: u8) -> bool {
    if prefix_length > 32 {
        return false;
    }

    let ip_int = u32::from_be_bytes(ip.octets());
    let network_int = u32::from_be_bytes(network.octets());
    let mask = if prefix_length == 0 {
        0
    } else {
        (!0u32) << (32 - prefix_length)
    };

    (ip_int & mask) == (network_int & mask)
}

fn is_ipv6_in_cidr(ip: &Ipv6Addr, network: &Ipv6Addr, prefix_length: u8) -> bool {
    if prefix_length > 128 {
        return false;
    }

    let ip_segments = ip.segments();
    let network_segments = network.segments();

    let full_segments = prefix_length / 16;
    let remaining_bits = prefix_length % 16;

    for i in 0..full_segments.min(8) {
        if ip_segments[i as usize] != network_segments[i as usize] {
            return false;
        }
    }

    if remaining_bits > 0 && full_segments < 8 {
        let mask = (!0u16) << (16 - remaining_bits);
        if (ip_segments[full_segments as usize] & mask)
            != (network_segments[full_segments as usize] & mask)
        {
            return false;
        }
    }

    true
}

#[cfg(test)]
mod tests {
    use super::*;
    use std::net::{Ipv4Addr, Ipv6Addr};

    #[test]
    fn test_is_ipv4_in_cidr() {
        let ip = Ipv4Addr::new(192, 168, 1, 100);
        let network = Ipv4Addr::new(192, 168, 1, 0);
        assert!(is_ipv4_in_cidr(&ip, &network, 24));

        let ip = Ipv4Addr::new(10, 0, 0, 5);
        let network = Ipv4Addr::new(10, 0, 0, 0);
        assert!(is_ipv4_in_cidr(&ip, &network, 8));

        let ip = Ipv4Addr::new(172, 16, 0, 1);
        let network = Ipv4Addr::new(172, 16, 0, 0);
        assert!(is_ipv4_in_cidr(&ip, &network, 16));

        // 不在范围内的情况
        let ip = Ipv4Addr::new(192, 168, 2, 100);
        let network = Ipv4Addr::new(192, 168, 1, 0);
        assert!(!is_ipv4_in_cidr(&ip, &network, 24));
    }

    #[test]
    fn test_is_ipv6_in_cidr() {
        let ip = Ipv6Addr::new(0x2001, 0x0db8, 0x85a3, 0, 0, 0x8a2e, 0x370, 0x7334);
        let network = Ipv6Addr::new(0x2001, 0x0db8, 0x85a3, 0, 0, 0, 0, 0);
        assert!(is_ipv6_in_cidr(&ip, &network, 48));

        // 不在范围内的情况
        let ip = Ipv6Addr::new(0x2001, 0x0db9, 0x85a3, 0, 0, 0x8a2e, 0x370, 0x7334);
        let network = Ipv6Addr::new(0x2001, 0x0db8, 0x85a3, 0, 0, 0, 0, 0);
        assert!(!is_ipv6_in_cidr(&ip, &network, 48));
    }

    #[test]
    fn test_is_ip_in_cidr() {
        let ip: IpAddr = "192.168.1.100".parse().unwrap();
        assert!(is_ip_in_cidr(&ip, "192.168.1.0/24"));
        assert!(!is_ip_in_cidr(&ip, "192.168.2.0/24"));

        let ip: IpAddr = "2001:db8::1".parse().unwrap();
        assert!(is_ip_in_cidr(&ip, "2001:db8::/32"));
        assert!(!is_ip_in_cidr(&ip, "2001:db9::/32"));
    }

    #[test]
    fn test_is_ip_in_cidr_invalid_format_returns_false() {
        let ip: IpAddr = "192.168.1.1".parse().unwrap();
        // No slash → parts.len != 2
        assert!(!is_ip_in_cidr(&ip, "192.168.1.0"));
        // Unparsable network address → parse::<IpAddr> fails → _ => false
        assert!(!is_ip_in_cidr(&ip, "not-an-ip/24"));
    }

    #[test]
    fn test_is_ip_in_cidr_invalid_prefix_is_fail_closed() {
        let ip: IpAddr = "192.168.1.1".parse().unwrap();
        // 非数字前缀:不得回退 /0 全匹配
        assert!(!is_ip_in_cidr(&ip, "0.0.0.0/abc"));
        // 超范围前缀(u8 溢出):不得回退 /0 全匹配
        assert!(!is_ip_in_cidr(&ip, "0.0.0.0/999"));
        // 负数前缀:同上
        assert!(!is_ip_in_cidr(&ip, "0.0.0.0/-1"));
    }

    #[test]
    fn test_is_ip_in_cidr_mismatched_ip_version_returns_false() {
        // V4 IP with V6 network → _ => false
        let ip: IpAddr = "192.168.1.1".parse().unwrap();
        assert!(!is_ip_in_cidr(&ip, "::1/128"));
        // V6 IP with V4 network → _ => false
        let ip: IpAddr = "::1".parse().unwrap();
        assert!(!is_ip_in_cidr(&ip, "192.168.1.0/24"));
    }

    #[test]
    fn test_is_ipv4_in_cidr_prefix_length_edge_cases() {
        let ip = Ipv4Addr::new(192, 168, 1, 1);
        let network = Ipv4Addr::new(0, 0, 0, 0);
        // prefix_length == 0 → mask = 0, any IP matches
        assert!(is_ipv4_in_cidr(&ip, &network, 0));
        // prefix_length > 32 → returns false
        assert!(!is_ipv4_in_cidr(&ip, &network, 33));
    }

    #[test]
    fn test_is_ipv6_in_cidr_prefix_length_edge_cases() {
        let ip = Ipv6Addr::new(0x2001, 0x0db8, 0x85a3, 0, 0, 0x8a2e, 0x370, 0x7334);
        let network = Ipv6Addr::new(0, 0, 0, 0, 0, 0, 0, 0);
        // prefix_length > 128 → returns false
        assert!(!is_ipv6_in_cidr(&ip, &network, 129));

        // remaining_bits > 0 branch: partial-segment mismatch → false
        // prefix 120 = 7 full segments (0-6) + 8 remaining bits in segment 7.
        // Segments 0-6 must match ip; segment 7's top 8 bits differ.
        let network_diff = Ipv6Addr::new(0x2001, 0x0db8, 0x85a3, 0, 0, 0x8a2e, 0x370, 0xff34);
        assert!(!is_ipv6_in_cidr(&ip, &network_diff, 120));

        // remaining_bits > 0 branch: partial-segment match → true
        // Segment 7's top 8 bits (0x73) match ip (0x7334 & 0xFF00 = 0x7300).
        let network_match = Ipv6Addr::new(0x2001, 0x0db8, 0x85a3, 0, 0, 0x8a2e, 0x370, 0x7300);
        assert!(is_ipv6_in_cidr(&ip, &network_match, 120));
    }
}