Skip to main content

Crate multibucket

Crate multibucket 

Source
Expand description

§multibucket

A small, async, backend-agnostic object-storage facade. Application code is written once against the ObjectStorage trait and can be pointed at any bucket — the “multi-bucket” idea. Two backends ship today:

  • Qiniu Kodo (七牛云对象存储) — backends::qiniu.
  • Amazon S3 (and S3-compatible services) — backends::s3, speaking AWS Signature Version 4, so it also covers MinIO, Cloudflare R2, Aliyun OSS, Tencent COS and Qiniu’s own S3 interface.

Both are implemented from the raw HTTP API (no heavyweight SDK), so the crate pulls in almost no backend-specific dependencies.

§Quick start — S3

use std::time::Duration;
use bytes::Bytes;
use multibucket::{ObjectStorage, PutBody, PutOptions, backends::s3::{S3Client, S3Config}};

// AWS S3, us-east-1 (default virtual-hosted addressing).
let cfg = S3Config::new("AK", "SK", "my-bucket");
let client = S3Client::new(cfg);

// Upload (simple PUT; `put_resumable` switches to multipart for large files).
client.put("docs/readme.txt", PutBody::from(Bytes::from("hello")), &PutOptions::default()).await?;

// Download.
let data = client.get("docs/readme.txt").await?;

// Metadata / existence / delete.
let _meta = client.stat("docs/readme.txt").await?;
assert!(client.exists("docs/readme.txt").await?);
client.delete("docs/readme.txt").await?;

// Time-limited, pre-signed download URL (query-string auth, no secret in it).
let url = client.presign_get("docs/readme.txt", Duration::from_secs(600))?;

§Quick start — Qiniu Kodo

use bytes::Bytes;
use multibucket::{ObjectStorage, PutBody, PutOptions, backends::qiniu::{QiniuClient, QiniuConfig, Region}};

let cfg = QiniuConfig::new("AK", "SK", "my-bucket").region(Region::Z0);
let client = QiniuClient::new(cfg);
client.put("docs/readme.txt", PutBody::from(Bytes::from("hello")), &PutOptions::default()).await?;
let _data = client.get("docs/readme.txt").await?;

§Backends

§Feature notes

  • S3 signing uses AWS Signature Version 4, implemented from scratch in [backends::s3::sigv4]; the two canonical AWS worked examples are encoded as unit tests there, so the bytes are known-good.
  • Qiniu signing (upload token / private download / QBox management) follows the official Qiniu algorithm docs and is implemented in backends::qiniu::Mac.
  • Large files can be uploaded with the resumable / multipart API (ObjectStorage::put_resumable); both backends expose the lower-level MultipartUpload / Qiniu MultipartUpload handles.
  • TLS uses rustls (no OpenSSL needed), so it builds cleanly on Windows.
  • Creating a bucket or switching it between public / private is available on the Qiniu client (QiniuClient::create_bucket, set_bucket_private). Those are account-level control-plane calls, so they deliberately stay out of the backend-agnostic ObjectStorage trait.
  • All uploads/downloads go through a single reusable reqwest::Client; pass your own via S3Client::with_http or QiniuClient::with_http to control timeouts and proxies.

Modules§

backends
Concrete storage backends.

Structs§

ListOptions
Options for a listing request.
ListOutcome
Result of a listing operation.
ObjectMetadata
Metadata describing a single stored object.
PutOptions
Options accepted when uploading an object.

Enums§

Error
All errors produced by multibucket.
PutBody
A body that can be uploaded. Accepts in-memory bytes and owned buffers.

Traits§

ObjectStorage
A unified asynchronous object-storage interface.

Type Aliases§

Result
Convenient result alias used across the crate.