multibucket 0.2.1

A unified async object-storage trait with a from-scratch Qiniu Kodo backend (upload / download / delete / stat / list / signed URLs).
Documentation
# multibucket


异步、后端无关的对象存储门面:业务代码只针对 `ObjectStorage` trait 编写一次,即可对接任意存储桶。当前内置 **七牛云对象存储 Kodo** 后端,直连其原始 HTTP API,不引入第三方 SDK。

## 安装


```toml
[dependencies]
multibucket = "0.2"
tokio = { version = "1", features = ["rt-multi-thread", "macros"] }
bytes = "1"
```

需要 Rust 1.70+。TLS 使用 `rustls`,Windows 上无需 OpenSSL。

## 构造客户端


```rust
use multibucket::backends::qiniu::{QiniuClient, QiniuConfig, Region};

let cfg = QiniuConfig::new("ACCESS_KEY", "SECRET_KEY", "my-bucket")
    // Region: Z0 / CnEast2 / Z1 / Z2 / Na0 / As0 / ApSoutheast2 / ApSoutheast3
    .region(Region::Z0);
let client = QiniuClient::new(cfg);
```

私有空间的下载 URL 必须带签名。两种方式:

- 已绑定自定义下载域名(推荐,生产用):

  ```rust
  let cfg = QiniuConfig::new("ACCESS_KEY", "SECRET_KEY", "my-bucket")
      .region(Region::Z0)
      .private_bucket("download.example.com");
  ```

- 还没绑定自定义域名:用 `.private()` 直接标记私有,签名会落到七牛默认的
  `iovip-<region>.qiniuio.com` 下载主机上(标准私有下载机制,无需域名):

  ```rust
  let cfg = QiniuConfig::new("ACCESS_KEY", "SECRET_KEY", "my-bucket")
      .region(Region::Z0)
      .private();
  ```

内置域名若不适用(私有网关、七牛调整域名、需要直连指定 IP),可逐个覆盖:`up_host(..)` / `rs_host(..)` / `rsf_host(..)` / `download_domain(..)`;`use_https(false)` 可切回 http。要控制超时与代理,传入自己的 `reqwest::Client`:

```rust
let http = reqwest::Client::builder()
    .timeout(std::time::Duration::from_secs(30))
    .build()?;
let client = QiniuClient::new(cfg).with_http(http);
```

## 创建空间(可选)


不想在控制台手工建空间时,可以直接用代码创建(控制面接口,需要该密钥具备管理空间的权限):

```rust
// 空间名 = QiniuConfig::new 的第三个参数,区域 = .region(..)
client.create_bucket(true).await?;         // 创建并设为私有
client.set_bucket_private(false).await?;   // 只切换已有空间的访问权限
```

空间名称在七牛全系统内唯一,规则为 3~63 位小写字母 / 数字 / `-` 且首尾为字母或数字(不合法的名字会在发请求前报 `Error::InvalidInput`)。`create_bucket(true)` 是两次请求,若第二步失败空间已存在但仍为公开,可再调 `set_bucket_private(true)`。

## 上传


```rust
use bytes::Bytes;
use multibucket::{ObjectStorage, PutBody, PutOptions};

let meta = client
    .put(
        "docs/readme.txt",
        PutBody::from(Bytes::from("hello")),
        &PutOptions::with_content_type("text/plain"),
    )
    .await?;
println!("{} {} bytes, etag={:?}", meta.key, meta.size, meta.etag);
```

`PutBody` 可由 `Bytes`、`Vec<u8>`、`&'static [u8]` 转来;同名 key 直接覆盖写,`PutOptions { insert_only: true, .. }` 可改为拒绝覆盖。

## 下载 / 元信息 / 存在 / 删除


```rust
let data = client.get("docs/readme.txt").await?; // Bytes
let meta = client.stat("docs/readme.txt").await?;
if client.exists("docs/readme.txt").await? {
    client.delete("docs/readme.txt").await?;
}
```

## 列举


```rust
use multibucket::ListOptions;

let mut opts = ListOptions::with_limit(200);
loop {
    let page = client.list("docs/", &opts).await?;
    for item in &page.items {
        println!("{} ({} bytes)", item.key, item.size);
    }
    match page.next_marker {
        Some(marker) => opts.marker = Some(marker),
        None => break,
    }
}
```

`ListOptions` 另有 `delimiter`(支持 `/`,用于按目录分组)。

## 有时效的下载 URL


```rust
use std::time::Duration;

let url = client.presign_get("docs/readme.txt", Duration::from_secs(300))?;
```

公有桶返回普通 URL,私有桶自动附带下载凭证(同步方法,不发请求)。

> **七牛对私有下载凭证的 `e`(过期时间戳)有硬性上限**:下载服务器只接受 `e` 比其服务器时钟最多超前约 5 分钟的令牌,否则返回 `403 RequestExpiresTooSkewed`(实测 `e=now+300` 可用、`e=now+600` 被拒)。因此本库把下载 URL 的 TTL **自动封顶在 300 秒**,无论调用方传入多大值;上传令牌不受影响(仍用 3600 秒)。若客户端机器时钟与七牛偏差过大,再调用 `client.sync_clock().await` 自动对齐。

## 大文件:分片与断点续传


便捷调用,内部走分片上传 v2,逐片自动重试:

```rust
// part_size = 0 表示使用默认 4 MiB
let meta = client
    .put_resumable("video/big.mp4", PutBody::from(bytes), 0, &PutOptions::default())
    .await?;
```

需要跨进程恢复时,自行持久化 `upload_id` 与已完成分片:

```rust
use multibucket::backends::qiniu::ResumeState;

let state = ResumeState {
    upload_id: saved_upload_id,           // 从你的存储里读回
    parts: saved_parts,                   // BTreeMap<分片号, partName>
};
client
    .put_resumable_resume(
        "video/big.mp4",
        PutBody::from(bytes),
        4 * 1024 * 1024,
        &PutOptions::default(),
        &state,
    )
    .await?;
```

完全手动编排(并发控制、进度上报等场景):

```rust
use multibucket::backends::qiniu::CompletedPart;

let mp = client
    .initiate_multipart_upload("video/big.mp4", &PutOptions::default())
    .await?;
let upload_id = mp.upload_id().to_string(); // 立刻持久化,便于中断后恢复

let name1 = mp.upload_part(1, part1).await?; // 返回 partName,需保存
let name2 = mp.upload_part(2, part2).await?;
let meta = mp
    .complete(&[
        CompletedPart {
            number: 1,
            name: name1,
        },
        CompletedPart {
            number: 2,
            name: name2,
        },
    ])
    .await?;
```

约束:分片号从 1 开始、最多 10000 片;除最后一片外每片不得小于 1 MiB。中断后可用 `client.multipart_upload(key, upload_id)` 重新接上已存在的上传任务。

## 前端直传凭证


```rust
use std::time::Duration;

let token = client.upload_token("docs/readme.txt", Duration::from_secs(3600))?;
```

把 `token` 下发给浏览器 / 移动端,让它们直接 POST 到七牛上传域名。

## 错误处理


所有方法返回 `multibucket::Result<T>`;后端非 2xx 会收敛为 `Error::Api`:

```rust
use multibucket::Error;

if let Err(Error::Api {
    status,
    qiniu_code,
    body,
}) = client.stat("not-exist.txt").await
{
    // 七牛业务码 612 表示文件不存在
    println!("http {status}, qiniu {qiniu_code:?}: {body}");
}
```

`exists()` 已把 612 处理为 `false`,不会报错。签名依赖本机时间,频繁 401 请先校准系统时钟。

## 运行示例


端到端示例覆盖上文全部用法(上传 → 元信息 → 下载 → 签名 URL → 列举 → 删除 → 分片 / 手动编排),凭证从环境变量读取:

```sh
# Windows PowerShell

$env:QINIU_ACCESS_KEY="..."; $env:QINIU_SECRET_KEY="..."; $env:QINIU_BUCKET="..."
cargo run --example qiniu_basic
```

```sh
# macOS / Linux

QINIU_ACCESS_KEY=... QINIU_SECRET_KEY=... QINIU_BUCKET=... cargo run --example qiniu_basic
```

## 许可证


本项目采用 **MIT OR Apache-2.0** 双许可。