garrison 0.9.0

Garrison - 面向 Rust 生态的一站式身份认证鉴权框架
Documentation
// Copyright (c) 2026 Kirky.X🌠
// SPDX-License-Identifier: Apache-2.0

//! IP 地理位置查询抽象(firewall-anomalous / firewall-geoip 共享):`GeoLookup` 提供 IP → 坐标(供
//! haversine 距离计算),`CountryLookup` 提供 IP → ISO 3166-1 alpha-2 国家码(供 allow/block 匹配)。
//! 生产实现委托 limiteron `GeoMatcher`(mmdb 读取 + LRU 缓存),测试可用 mock 避免依赖真实数据库文件。

use crate::error::{GarrisonError, GarrisonResult};
use async_trait::async_trait;

/// limiteron GeoMatcher 生产后端(由 `firewall-maxminddb` feature 启用)。
#[cfg(feature = "firewall-maxminddb")]
pub mod matcher;

/// 地理坐标(纬度 / 经度,十进制度);`lat ∈ [-90, 90]`、`lon ∈ [-180, 180]`、非 NaN 不变量由
/// [`GeoCoord::new`] / [`GeoCoord::from_csv`] 构造时校验。
///
/// **字段为 `pub`**(crate 内外均有直接读取方,无法私有化),可用结构体字面量绕过校验注入 NaN /
/// 越界值,污染 haversine 距离与 allow/block 判定;**调用方应始终经 `new` / `from_csv` 构造**,
/// 消费侧对不可信来源的坐标可用 [`GeoCoord::new`] 二次校验。
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct GeoCoord {
    /// 纬度(-90.0 ~ 90.0);可由字面量绕过 `new` 校验(见类型文档)。
    pub lat: f64,
    /// 经度(-180.0 ~ 180.0);可由字面量绕过 `new` 校验(见类型文档)。
    pub lon: f64,
}

impl GeoCoord {
    /// 创建地理坐标,校验 lat ∈ [-90, 90]、lon ∈ [-180, 180](越界返回 `InvalidParam`)。
    pub fn new(lat: f64, lon: f64) -> Result<Self, GarrisonError> {
        if !(-90.0..=90.0).contains(&lat) {
            return Err(GarrisonError::InvalidParam(format!(
                "firewall-geo-lat-out-of-range::{}",
                lat
            )));
        }
        if !(-180.0..=180.0).contains(&lon) {
            return Err(GarrisonError::InvalidParam(format!(
                "firewall-geo-lon-out-of-range::{}",
                lon
            )));
        }
        Ok(Self { lat, lon })
    }

    /// 序列化为 "lat,lon" 字符串(用于 oxcache 存储)。
    pub fn to_csv(self) -> String {
        format!("{},{}", self.lat, self.lon)
    }

    /// 从 "lat,lon" 字符串解析;格式错误或坐标越界返回 `None`。
    pub fn from_csv(s: &str) -> Option<Self> {
        let mut parts = s.splitn(2, ',');
        let lat: f64 = parts.next()?.trim().parse().ok()?;
        let lon: f64 = parts.next()?.trim().parse().ok()?;
        Self::new(lat, lon).ok()
    }
}

/// IP 地理坐标查询 trait:生产实现 `GeoMatcherLookup`(委托 limiteron GeoMatcher),测试实现 `MockGeoLookup`。
#[async_trait]
pub trait GeoLookup: Send + Sync {
    /// 查询 IP 坐标;无法定位(私有 IP、数据库无记录)返回 `Ok(None)`,查询失败返回 `Err`。
    async fn lookup(&self, ip: &str) -> GarrisonResult<Option<GeoCoord>>;
}

/// IP → 国家码查询 trait:返回 ISO 3166-1 alpha-2 国家码(如 `"CN"` / `"US"`,大写,供 allow/block 匹配);
/// 生产实现 `GeoMatcherCountryLookup`,测试实现 `MockCountryLookup`。
#[async_trait]
pub trait CountryLookup: Send + Sync {
    /// 查询 IP 的国家码(ISO 3166-1 alpha-2,大写);无法定位返回 `Ok(None)`,查询失败返回 `Err`。
    async fn lookup_country(&self, ip: &str) -> GarrisonResult<Option<String>>;
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn geo_coord_csv_roundtrip() {
        let coord = GeoCoord::new(39.9042, 116.4074).unwrap();
        let csv = coord.to_csv();
        let parsed = GeoCoord::from_csv(&csv).unwrap();
        assert_eq!(coord, parsed);
    }

    #[test]
    fn geo_coord_from_csv_rejects_invalid() {
        assert!(GeoCoord::from_csv("invalid").is_none());
        assert!(GeoCoord::from_csv("abc,def").is_none());
        assert!(GeoCoord::from_csv("").is_none());
        assert!(GeoCoord::from_csv("1.0").is_none());
    }

    /// 验证 `GeoCoord::new` 拒绝纬度越界(> 90 / < -90),错误消息含 "lat"。
    #[test]
    fn geo_coord_new_rejects_lat_out_of_range() {
        let above = GeoCoord::new(90.5, 0.0);
        assert!(
            matches!(&above, Err(GarrisonError::InvalidParam(msg)) if msg.contains("lat")),
            "纬度 90.5 应返回 InvalidParam 且消息含 'lat',实际: {:?}",
            above
        );
        let below = GeoCoord::new(-90.5, 0.0);
        assert!(
            matches!(&below, Err(GarrisonError::InvalidParam(msg)) if msg.contains("lat")),
            "纬度 -90.5 应返回 InvalidParam 且消息含 'lat',实际: {:?}",
            below
        );
    }

    /// 验证 `GeoCoord::new` 拒绝经度越界(> 180 / < -180),错误消息含 "lon"。
    #[test]
    fn geo_coord_new_rejects_lon_out_of_range() {
        let above = GeoCoord::new(0.0, 180.5);
        assert!(
            matches!(&above, Err(GarrisonError::InvalidParam(msg)) if msg.contains("lon")),
            "经度 180.5 应返回 InvalidParam 且消息含 'lon',实际: {:?}",
            above
        );
        let below = GeoCoord::new(0.0, -180.5);
        assert!(
            matches!(&below, Err(GarrisonError::InvalidParam(msg)) if msg.contains("lon")),
            "经度 -180.5 应返回 InvalidParam 且消息含 'lon',实际: {:?}",
            below
        );
    }

    /// 验证 `GeoCoord::new` 接受边界值(±90 纬度 / ±180 经度均合法)。
    #[test]
    fn geo_coord_new_accepts_boundary_values() {
        assert!(GeoCoord::new(-90.0, -180.0).is_ok());
        assert!(GeoCoord::new(90.0, 180.0).is_ok());
        assert!(GeoCoord::new(0.0, 0.0).is_ok());
    }

    /// 验证 `GeoCoord::new` 拒绝 NaN(NaN 不在任何区间内,fail-closed)。
    #[test]
    fn geo_coord_new_rejects_nan() {
        assert!(GeoCoord::new(f64::NAN, 0.0).is_err());
        assert!(GeoCoord::new(0.0, f64::NAN).is_err());
    }

    /// 验证 `from_csv` 解析时 trim 前后空白(与 oxcache 存储格式兼容)。
    #[test]
    fn geo_coord_from_csv_trims_whitespace() {
        let parsed = GeoCoord::from_csv(" 39.9042 , 116.4074 ").expect("带空白 CSV 应可解析");
        assert_eq!(parsed.lat, 39.9042);
        assert_eq!(parsed.lon, 116.4074);
    }

    /// 验证 `from_csv` 对坐标合法但越界的输入返回 None(内部走 `GeoCoord::new` 校验)。
    #[test]
    fn geo_coord_from_csv_rejects_out_of_range_coords() {
        assert!(GeoCoord::from_csv("91.0,0.0").is_none(), "纬度越界应 None");
        assert!(GeoCoord::from_csv("-90.5,0.0").is_none(), "纬度越界应 None");
        assert!(GeoCoord::from_csv("0.0,181.0").is_none(), "经度越界应 None");
        assert!(
            GeoCoord::from_csv("0.0,-180.5").is_none(),
            "经度越界应 None"
        );
    }

    /// 验证 `to_csv` 输出 "lat,lon" 精确格式(逗号分隔、无空格)。
    #[test]
    fn geo_coord_to_csv_format() {
        let coord = GeoCoord::new(-33.865143, 151.209900).unwrap();
        assert_eq!(coord.to_csv(), "-33.865143,151.2099");
    }

    /// mock `GeoLookup` / `CountryLookup` 可经 trait 对象调用(测试用 mock 避免依赖真实数据库文件)。
    #[tokio::test]
    async fn mock_geo_and_country_lookup_trait_objects() {
        struct MockGeo;
        struct MockCountry;

        #[async_trait]
        impl GeoLookup for MockGeo {
            async fn lookup(&self, ip: &str) -> GarrisonResult<Option<GeoCoord>> {
                if ip == "1.2.3.4" {
                    Ok(Some(GeoCoord::new(1.0, 2.0).unwrap()))
                } else {
                    Ok(None)
                }
            }
        }

        #[async_trait]
        impl CountryLookup for MockCountry {
            async fn lookup_country(&self, ip: &str) -> GarrisonResult<Option<String>> {
                if ip == "1.2.3.4" {
                    Ok(Some("CN".to_string()))
                } else {
                    Ok(None)
                }
            }
        }

        let geo: std::sync::Arc<dyn GeoLookup> = std::sync::Arc::new(MockGeo);
        let country: std::sync::Arc<dyn CountryLookup> = std::sync::Arc::new(MockCountry);

        let hit = geo.lookup("1.2.3.4").await.unwrap();
        assert_eq!(hit, Some(GeoCoord { lat: 1.0, lon: 2.0 }));
        assert_eq!(geo.lookup("unknown").await.unwrap(), None);

        assert_eq!(
            country.lookup_country("1.2.3.4").await.unwrap(),
            Some("CN".into())
        );
        assert_eq!(country.lookup_country("unknown").await.unwrap(), None);
    }
}