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
backends::s3— Amazon S3 / S3-compatible. SeeS3Client.backends::qiniu— Qiniu Kodo. SeeQiniuClient.
§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 /
QBoxmanagement) follows the official Qiniu algorithm docs and is implemented inbackends::qiniu::Mac. - Large files can be uploaded with the resumable / multipart API
(
ObjectStorage::put_resumable); both backends expose the lower-levelMultipartUpload/ QiniuMultipartUploadhandles. - 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-agnosticObjectStoragetrait. - All uploads/downloads go through a single reusable
reqwest::Client; pass your own viaS3Client::with_httporQiniuClient::with_httpto control timeouts and proxies.
Modules§
- backends
- Concrete storage backends.
Structs§
- List
Options - Options for a listing request.
- List
Outcome - Result of a listing operation.
- Object
Metadata - 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§
- Object
Storage - A unified asynchronous object-storage interface.
Type Aliases§
- Result
- Convenient result alias used across the crate.