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
//! multibucket 端到端测试示例。
//!
//! 凭证从环境变量读取(PowerShell 示例):
//!
//! ```powershell
//! $env:QINIU_ACCESS_KEY="..."; $env:QINIU_SECRET_KEY="..."; $env:QINIU_BUCKET="..."
//! cargo run --bin multibucket-test --features cli
//! ```
//!
//! 可选环境变量:
//! * `QINIU_REGION`  桶所在区域(默认 `z0`);桶不存在时会自动创建。
//! * `QINIU_DOMAIN`  已绑定到桶的下载域名。**下载(get)需要它**——新建桶若无
//!   绑定域名,七牛会返回 404 `no such domain`,此时示例会跳过下载校验。
//! * `QINIU_PRIVATE` 设为 `1/true` 表示私有空间(下载 URL 自动加签)。
//!
//! 覆盖:上传 / 下载 / stat / exists / 列举 / 签名下载 URL / 删除 / 分片(断点续传)上传。

use std::env;
use std::time::Duration;

use bytes::Bytes;

use multibucket::backends::qiniu::{QiniuClient, QiniuConfig, Region};
use multibucket::{Error, ListOptions, ObjectStorage, PutBody, PutOptions};

/// 本次测试写入对象所在的前缀目录。
const PREFIX: &str = "multibucket-test";
/// 简单上传 / 下载使用的 key。
const KEY: &str = "multibucket-test/hello.txt";
/// 七牛“桶不存在”的业务错误码。
const NO_SUCH_BUCKET: u16 = 631;

fn main() {
    // 手动构建 tokio 运行时,避免依赖 #[tokio::main] 宏。
    let rt = tokio::runtime::Runtime::new().expect("构建 tokio 运行时失败");
    if let Err(err) = rt.block_on(run()) {
        eprintln!("\n[test] 失败: {err}");
        std::process::exit(1);
    }
    println!("\n[test] 全部通过 ✅");
}

async fn run() -> Result<(), Error> {
    let client = build_client();
    let cfg = client.config();
    println!(
        "[test] backend={}, bucket={}, region={} (up_host={})",
        client.backend(),
        client.bucket(),
        cfg.region.id(),
        cfg.region.up_host()
    );

    // 0. 确保桶存在;不存在则自动创建。
    ensure_bucket(&client).await?;

    // 1. 上传。
    let body = PutBody::from(Bytes::from("hello from multibucket 🦀"));
    let meta = client
        .put(KEY, body, &PutOptions::with_content_type("text/plain"))
        .await?;
    println!(
        "[test] 上传成功  key={} size={} etag={:?}",
        meta.key, meta.size, meta.etag
    );

    // 2. stat / exists。
    let info = client.stat(KEY).await?;
    println!(
        "[test] stat      size={} mime={:?}",
        info.size, info.content_type
    );
    assert!(client.exists(KEY).await?, "上传后 exists 应为 true");
    println!("[test] exists    true");

    // 3. 下载并校验内容(需要已绑定下载域名,否则七牛报 404 no such domain)。
    if env::var("QINIU_DOMAIN").is_ok() {
        let data = client.get(KEY).await?;
        let text = String::from_utf8_lossy(&data).to_string();
        println!("[test] 下载 {} 字节: {:?}", data.len(), text);
        assert_eq!(text, "hello from multibucket 🦀", "下载内容与上传不一致");
    } else {
        println!("[test] 下载   跳过(未设置 QINIU_DOMAIN;新桶无绑定域名时无法通过域名下载)");
    }

    // 4. 生成签名下载 URL(私有空间会自动加签;仅构造字符串,不联网)。
    let url = client.presign_get(KEY, Duration::from_secs(600))?;
    println!("[test] 预签名 URL: {url}");

    // 5. 按前缀列举。
    let page = client.list(PREFIX, &ListOptions::with_limit(10)).await?;
    println!("[test] 列举 {} 条(前缀 {PREFIX})", page.items.len());
    for item in &page.items {
        println!("        - {} ({} 字节)", item.key, item.size);
    }
    assert!(
        page.items.iter().any(|i| i.key == KEY),
        "列举结果中应包含 {KEY}"
    );

    // 6. 分片(断点续传)上传:约 5 MiB,默认 4 MiB 分片 -> 两片。
    //    v2 分片上传对上传主机更严格:若与桶的权威区域不匹配会报
    //    403 "bucket doesn't match with scope",此时可用 QINIU_UP_HOST 指定真实主机。
    let big_key = "multibucket-test/big.bin";
    let big = Bytes::from(vec![0u8; 5 * 1024 * 1024]);
    let resumable_ok = match client
        .put_resumable(big_key, PutBody::from(big), 0, &PutOptions::default())
        .await
    {
        Ok(meta) => {
            println!("[test] 分片上传成功 key={} size={}", meta.key, meta.size);
            assert_eq!(meta.size, 5 * 1024 * 1024, "分片上传大小不符");
            true
        }
        Err(err) => {
            println!("[test] 分片上传 跳过: {err}");
            println!(
                "        提示: v2 分片上传需上传主机与桶权威区域一致。用\n\x20\x20\x20\x20\x20\x20\x20https://uc.qiniuapi.com/v4/query?ak=<AK>&bucket=<bucket>\n\x20\x20\x20\x20\x20\x20\x20查到真实上传主机后,设 $env:QINIU_UP_HOST=<主机> 再重跑。"
            );
            false
        }
    };

    // 7. 删除并确认不存在。
    client.delete(KEY).await?;
    if resumable_ok {
        client.delete(big_key).await?;
        println!("[test] 删除完成  {KEY} / {big_key}");
    } else {
        println!("[test] 删除完成  {KEY}");
    }
    assert!(!client.exists(KEY).await?, "删除后 exists 应为 false");

    Ok(())
}

/// 从环境变量构建客户端。
///
/// 域名/私有策略:
/// * 设置 `QINIU_DOMAIN` 且 `QINIU_PRIVATE=1/true` → 私有空间,下载 URL 加签。
/// * 仅设置 `QINIU_DOMAIN` → 公有空间,指定下载域名。
/// * 未设置 `QINIU_DOMAIN` → 公有、回退区域默认 io 主机(新桶无域名时下载会失败,
///   因此 run() 会跳过下载校验)。
fn build_client() -> QiniuClient {
    let access_key = env::var("QINIU_ACCESS_KEY").expect("请设置 QINIU_ACCESS_KEY");
    let secret_key = env::var("QINIU_SECRET_KEY").expect("请设置 QINIU_SECRET_KEY");
    let bucket = env::var("QINIU_BUCKET").expect("请设置 QINIU_BUCKET");

    // 区域需与桶实际所在区域一致,否则七牛会报 "no such bucket"(631)。
    // 查询真实区域: https://uc.qiniuapi.com/v4/query?ak=<AK>&bucket=<bucket>
    let region = parse_region(&env::var("QINIU_REGION").unwrap_or_else(|_| "z0".to_string()));
    let mut cfg = QiniuConfig::new(access_key, secret_key, bucket).region(region);

    if let Ok(domain) = env::var("QINIU_DOMAIN") {
        if is_private() {
            cfg = cfg.private_bucket(domain);
        } else {
            cfg = cfg.download_domain(domain);
        }
    }

    // 主机覆盖:当默认区域主机与实际不符(尤其 v2 分片上传)时,用查询接口得到的真实主机。可单独
    // 验证上传主机: POST https://uc.qiniuapi.com/v4/query?ak=<AK>&bucket=<bucket> 里 regions[].up 域名。
    if let Ok(h) = env::var("QINIU_UP_HOST") {
        println!("[test] 覆盖 up_host = {h}");
        cfg = cfg.up_host(h);
    }
    if let Ok(h) = env::var("QINIU_RS_HOST") {
        println!("[test] 覆盖 rs_host = {h}");
        cfg = cfg.rs_host(h);
    }
    if let Ok(h) = env::var("QINIU_RSF_HOST") {
        println!("[test] 覆盖 rsf_host = {h}");
        cfg = cfg.rsf_host(h);
    }

    let http = reqwest::Client::builder()
        .timeout(Duration::from_secs(30))
        .build()
        .expect("构建 HTTP 客户端失败");

    QiniuClient::new(cfg).with_http(http)
}

/// 是否按私有空间处理(`QINIU_PRIVATE=1/true/yes`)。
fn is_private() -> bool {
    match env::var("QINIU_PRIVATE") {
        Ok(v) => matches!(v.trim().to_ascii_lowercase().as_str(), "1" | "true" | "yes"),
        Err(_) => false,
    }
}

/// 探测配置的桶是否存在;若七牛返回 631(no such bucket)则自动创建。
///
/// `QINIU_PRIVATE=1/true` 时按私有空间创建(`private=true`),否则公有。
/// 注意:`create_bucket` 是账号级控制面调用,所用 AK/SK 需具备管理桶的权限。
async fn ensure_bucket(client: &QiniuClient) -> Result<(), Error> {
    match client.list(PREFIX, &ListOptions::with_limit(1)).await {
        Ok(_) => Ok(()),
        Err(Error::Api { status, .. }) if status == NO_SUCH_BUCKET => {
            let private = is_private();
            println!(
                "[test] 桶 {:?} 不存在,正在自动创建 (private={private}) ...",
                client.bucket()
            );
            client.create_bucket(private).await?;
            println!("[test] 桶创建成功 ✅");
            Ok(())
        }
        Err(other) => Err(other),
    }
}

/// 把七牛区域 id(如 `z0` / `cn-east-2`)解析为 [`Region`];无法识别时回退 `z0`。
fn parse_region(id: &str) -> Region {
    match id.trim().to_ascii_lowercase().as_str() {
        "z0" | "east-china" => Region::Z0,
        "cn-east-2" | "east-china-2" => Region::CnEast2,
        "z1" | "north-china" => Region::Z1,
        "z2" | "south-china" => Region::Z2,
        "na0" | "north-america" => Region::Na0,
        "as0" | "singapore" | "southeast-asia" => Region::As0,
        "ap-southeast-2" => Region::ApSoutheast2,
        "ap-southeast-3" => Region::ApSoutheast3,
        other => {
            eprintln!("[test] 未知区域 {other:?},回退到 z0");
            Region::Z0
        }
    }
}