multibucket 0.3.0

A unified async object-storage trait with from-scratch Qiniu Kodo and Amazon S3 (S3-compatible) backends (upload / download / delete / stat / list / signed URLs).
Documentation
//! Qiniu regions and their service hosts.
//!
//! Both the region ids and the hosts come from Qiniu's "存储区域" table:
//! upload on `up-<region>.qiniup.com`, object management on
//! `rs-<region>.qiniuapi.com`, listing on `rsf-<region>.qiniuapi.com`, source
//! download on `iovip-<region>.qiniuio.com`. Every host can be overridden in
//! [`QiniuConfig`](super::QiniuConfig) — for example to route around a
//! locally-resolved IP or a private gateway — so a wrong default never blocks
//! an integration. The authoritative per-bucket hosts can always be confirmed
//! via `GET https://uc.qiniuapi.com/v4/query?ak=<AccessKey>&bucket=<Bucket>`.

/// A Qiniu Kodo region.
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
pub enum Region {
    /// 华东 - 浙江 (z0)
    #[default]
    Z0,
    /// 华东 - 浙江 2 (cn-east-2)
    CnEast2,
    /// 华北 - 河北 (z1)
    Z1,
    /// 华南 - 广东 (z2)
    Z2,
    /// 北美 - 洛杉矶 (na0)
    Na0,
    /// 亚太 - 新加坡,即早期的“东南亚” (as0)
    As0,
    /// 亚太 - 河内 (ap-southeast-2)
    ///
    /// Already moved to maintenance-only operation: new buckets may not be
    /// creatable here even though the endpoints keep working.
    ApSoutheast2,
    /// 亚太 - 胡志明 (ap-southeast-3)
    ///
    /// Already moved to maintenance-only operation, see
    /// [`ApSoutheast2`](Self::ApSoutheast2).
    ApSoutheast3,
}

impl Region {
    /// Qiniu region id (`z0`, `cn-east-2`, ...), as expected by the control
    /// plane (e.g. `mkbucketv3`).
    pub fn id(self) -> &'static str {
        match self {
            Region::Z0 => "z0",
            Region::CnEast2 => "cn-east-2",
            Region::Z1 => "z1",
            Region::Z2 => "z2",
            Region::Na0 => "na0",
            Region::As0 => "as0",
            Region::ApSoutheast2 => "ap-southeast-2",
            Region::ApSoutheast3 => "ap-southeast-3",
        }
    }

    /// Upload source host (`up-<id>.qiniup.com`).
    pub fn up_host(self) -> &'static str {
        match self {
            Region::Z0 => "up-z0.qiniup.com",
            Region::CnEast2 => "up-cn-east-2.qiniup.com",
            Region::Z1 => "up-z1.qiniup.com",
            Region::Z2 => "up-z2.qiniup.com",
            Region::Na0 => "up-na0.qiniup.com",
            Region::As0 => "up-as0.qiniup.com",
            Region::ApSoutheast2 => "up-ap-southeast-2.qiniup.com",
            Region::ApSoutheast3 => "up-ap-southeast-3.qiniup.com",
        }
    }

    /// Resource-management host (`rs-<id>.qiniuapi.com`): stat / delete / copy.
    pub fn rs_host(self) -> &'static str {
        match self {
            Region::Z0 => "rs-z0.qiniuapi.com",
            Region::CnEast2 => "rs-cn-east-2.qiniuapi.com",
            Region::Z1 => "rs-z1.qiniuapi.com",
            Region::Z2 => "rs-z2.qiniuapi.com",
            Region::Na0 => "rs-na0.qiniuapi.com",
            Region::As0 => "rs-as0.qiniuapi.com",
            Region::ApSoutheast2 => "rs-ap-southeast-2.qiniuapi.com",
            Region::ApSoutheast3 => "rs-ap-southeast-3.qiniuapi.com",
        }
    }

    /// Listing host (`rsf-<id>.qiniuapi.com`).
    pub fn rsf_host(self) -> &'static str {
        match self {
            Region::Z0 => "rsf-z0.qiniuapi.com",
            Region::CnEast2 => "rsf-cn-east-2.qiniuapi.com",
            Region::Z1 => "rsf-z1.qiniuapi.com",
            Region::Z2 => "rsf-z2.qiniuapi.com",
            Region::Na0 => "rsf-na0.qiniuapi.com",
            Region::As0 => "rsf-as0.qiniuapi.com",
            Region::ApSoutheast2 => "rsf-ap-southeast-2.qiniuapi.com",
            Region::ApSoutheast3 => "rsf-ap-southeast-3.qiniuapi.com",
        }
    }

    /// Default download host (`iovip-<id>.qiniuio.com`), used when the bucket
    /// has no custom download domain configured.
    pub fn io_host(self) -> &'static str {
        match self {
            Region::Z0 => "iovip-z0.qiniuio.com",
            Region::CnEast2 => "iovip-cn-east-2.qiniuio.com",
            Region::Z1 => "iovip-z1.qiniuio.com",
            Region::Z2 => "iovip-z2.qiniuio.com",
            Region::Na0 => "iovip-na0.qiniuio.com",
            Region::As0 => "iovip-as0.qiniuio.com",
            Region::ApSoutheast2 => "iovip-ap-southeast-2.qiniuio.com",
            Region::ApSoutheast3 => "iovip-ap-southeast-3.qiniuio.com",
        }
    }
}

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

    /// All documented regions, newest first within each family.
    const ALL: [Region; 8] = [
        Region::Z0,
        Region::CnEast2,
        Region::Z1,
        Region::Z2,
        Region::Na0,
        Region::As0,
        Region::ApSoutheast2,
        Region::ApSoutheast3,
    ];

    #[test]
    fn region_ids_match_the_qiniu_table() {
        let ids: Vec<&str> = ALL.iter().map(|r| r.id()).collect();
        assert_eq!(
            ids,
            [
                "z0",
                "cn-east-2",
                "z1",
                "z2",
                "na0",
                "as0",
                "ap-southeast-2",
                "ap-southeast-3",
            ]
        );
        assert_eq!(Region::default(), Region::Z0);
    }

    /// Guards against a new variant being added with a copy-pasted host: every
    /// host must carry its own region id and land on the documented domain.
    #[test]
    fn every_host_is_derived_from_the_region_id() {
        for region in ALL {
            let id = region.id();
            assert_eq!(region.up_host(), format!("up-{id}.qiniup.com"));
            assert_eq!(region.rs_host(), format!("rs-{id}.qiniuapi.com"));
            assert_eq!(region.rsf_host(), format!("rsf-{id}.qiniuapi.com"));
            assert_eq!(region.io_host(), format!("iovip-{id}.qiniuio.com"));
        }
    }
}