multibucket 0.1.0

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


一个轻量、异步、**后端无关** 的对象存储门面。业务代码只针对 [`ObjectStorage`] trait 编写一次,即可对接任意存储桶——这正是 “multibucket”(多桶)的命名由来。

首个(也是目前唯一的)后端是 **七牛云对象存储 Kodo**,直接使用其原始 HTTP API 手写实现,因此不引入笨重的第三方 SDK 依赖树。

> 📚 完整文档:[使用指南 `docs/usage.md`]docs/usage.md | [发布指南 `docs/publishing.md`]docs/publishing.md

---

## 目录


- [特性]#特性
- [运行条件]#运行条件
- [安装]#安装
- [快速开始]#快速开始
- [支持的接口]#支持的接口
- [七牛后端要点]#七牛后端要点
- [运行示例]#运行示例
- [发布到 crates.io]#发布到-cratesio
- [技术架构]#技术架构
- [许可证]#许可证

---

## 特性


- **统一 trait**:`put` / `get` / `delete` / `exists` / `stat` / `list` / `presign_get`,一套接口适配多后端。
- **纯手写七牛鉴权**:上传凭证(uploadToken)、私有下载凭证、`QBox` 管理凭证,签名算法严格对齐[七牛官方文档]https://developer.qiniu.com/kodo。
- **异步 + 纯 Rust TLS**:基于 `tokio` + `reqwest`(`rustls`),在 Windows 上无需 OpenSSL 即可编译。
- **可扩展**:新增 S3 / 阿里云 OSS / 腾讯云 COS 只需在 `src/backends/` 下再实现一次 trait。

## 运行条件


- Rust **1.70+**(edition 2021)。安装见 <https://rustup.rs>。
- 一个七牛账号:开通 [对象存储 Kodo]https://portal.qiniu.com/kodo/bucket,创建 **空间(bucket)**,获取 **AccessKey / SecretKey**。
- 若使用私有空间下载,需为空间绑定一个 **已备案的加速域名**。

## 安装


在本 crate 目录下示例已在 `Cargo.toml` 就绪。若作为依赖引入其它项目:

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

## 快速开始


```rust
use std::time::Duration;
use bytes::Bytes;
use multibucket::{
    ObjectStorage, PutBody, PutOptions,
    backends::qiniu::{QiniuClient, QiniuConfig, Region},
};

#[tokio::main]

async fn main() -> multibucket::Result<()> {
    // 1. 构造客户端
    let cfg = QiniuConfig::new("ACCESS_KEY", "SECRET_KEY", "my-bucket")
        .region(Region::Z0);
    let client = QiniuClient::new(cfg);

    // 2. 上传
    client
        .put("a/b.txt", PutBody::from(Bytes::from("hello")), &PutOptions::default())
        .await?;

    // 3. 下载 / 元信息 / 判断存在 / 删除
    let data = client.get("a/b.txt").await?;
    let meta = client.stat("a/b.txt").await?;
    assert!(client.exists("a/b.txt").await?);
    client.delete("a/b.txt").await?;

    // 4. 生成有时效的下载 URL(私有空间会自动加签名 token)
    let url = client.presign_get("a/b.txt", Duration::from_secs(600))?;
    println!("{url}");
    Ok(())
}
```

完整可运行示例见 [`examples/qiniu_basic.rs`](examples/qiniu_basic.rs)。

## 支持的接口


| 方法 | 说明 | 七牛实现 |
| --- | --- | --- |
| `put(key, body, opts)` | 上传(覆盖写) | 表单上传 `POST up*.qiniup.com/` |
| `get(key)` | 下载到内存 | `GET` 下载域名(私有自动签名) |
| `stat(key)` | 读取对象元信息 | `POST rs*.qiniucs.com/stat/...`(QBox) |
| `exists(key)` | 是否存在 | 基于 `stat`,`612` 视为不存在 |
| `delete(key)` | 删除对象 | `POST rs*.qiniucs.com/delete/...`(QBox) |
| `list(prefix, opts)` | 分页列举 | `GET rsf*.qiniucs.com/list`(QBox) |
| `presign_get(key, expires)` | 生成带时效的下载 URL | 下载凭证签名 |
| `put_resumable(key, body, part_size, opts)` | 分片 / 断点续传上传 | 分片上传 v2(initiate / uploadPart / mkfile,`UpToken` 鉴权) |
| `upload_token(key, ttl)` | 生成前端直传凭证(七牛特有) | uploadToken |

## 七牛后端要点


- **区域与域名**:`Region` 枚举内置 z0/z1/z2/na0/as0/ea0 的上传、管理、列举、下载默认域名。如七牛调整域名或需走私有网关,可在 `QiniuConfig` 上用 `up_host / rs_host / rsf_host` 覆盖。权威域名可用 `GET https://uc.qiniup.com/query?ak=<AK>&bucket=<Bucket>` 查询。
- **私有空间**:`QiniuConfig::private_bucket("download.example.com")` 会开启下载 URL 签名。
- **分片 / 断点续传**:`put_resumable(..)` 走分片上传 v2(默认分片 4 MiB,单片最小 1 MiB,最多 10000 片,逐片自动重试 3 次);需要跨进程恢复时,用 `initiate_multipart_upload` / `upload_part` / `complete` 手动编排并持久化 `upload_id` 与已完成分片(`ResumeState`)。
- **时钟同步**:`deadline` / `e` 均基于本机 Unix 时间,频繁 401 请先校准系统时钟。
- **putTime**:七牛返回的是 100 纳秒单位时间戳,本 crate 已转换为 `SystemTime`。

## 运行示例


```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
```

## 发布到 crates.io


发布流程、`Cargo.toml` 元数据要求、版本号规则、`cargo owner` 管理等详见
**[`docs/publishing.md`](docs/publishing.md)**。速览:

```sh
# 1. 登录(token 会写入 ~/.cargo/credentials)
cargo login <crates.io API Token>

# 2. 自查包内容与编译

cargo package --list
cargo test

# 3. 先演练(只读),再正式发布

cargo publish --dry-run
cargo publish

# 4. 打标签

git tag v0.1.0 && git push --tags
```

## 技术架构


```
multibucket/
├── Cargo.toml
├── README.md
├── LICENSE-MIT / LICENSE-APACHE
├── docs/
│   ├── usage.md          # 使用指南
│   └── publishing.md     # 发布指南
├── examples/
│   └── qiniu_basic.rs
└── src/
    ├── lib.rs            # crate 门面与文档
    ├── error.rs          # Error / Result
    ├── types.rs          # ObjectMetadata / PutBody / PutOptions / ListOutcome
    ├── storage.rs        # ObjectStorage trait + ListOptions
    └── backends/
        ├── mod.rs
        └── qiniu/
            ├── mod.rs    # QiniuClient(实现 ObjectStorage)
            ├── auth.rs   # Mac 签名:uploadToken / 私有下载 / QBox 管理凭证
            ├── config.rs # QiniuConfig(Builder)
            └── region.rs # Region 与各服务域名
```

依赖:`tokio`(异步运行时)、`reqwest`(`rustls`)、`hmac`+`sha1`(签名)、`base64`、`percent-encoding`、`serde`/`serde_json`、`bytes`、`async-trait`、`thiserror`。

## 许可证


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