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/publishing.md


目录


特性

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

运行条件

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

安装

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

[dependencies]

multibucket = "0.1"

tokio = { version = "1", features = ["rt-multi-thread", "macros"] }

bytes = "1"

快速开始

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。

支持的接口

方法 说明 七牛实现
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。

运行示例

# Windows PowerShell

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

# macOS / Linux

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

发布到 crates.io

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

# 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 双许可。