multibucket 0.3.0

A unified async object-storage trait with from-scratch Qiniu Kodo and Amazon S3 (S3-compatible) backends (upload / download / delete / stat / list / signed URLs).
Documentation
//! # 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
//!
//! ```no_run
//! use std::time::Duration;
//! use bytes::Bytes;
//! use multibucket::{ObjectStorage, PutBody, PutOptions, backends::s3::{S3Client, S3Config}};
//!
//! # async fn run() -> multibucket::Result<()> {
//! // 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))?;
//! # Ok(())
//! # }
//! ```
//!
//! ## Quick start — Qiniu Kodo
//!
//! ```no_run
//! use bytes::Bytes;
//! use multibucket::{ObjectStorage, PutBody, PutOptions, backends::qiniu::{QiniuClient, QiniuConfig, Region}};
//!
//! # async fn run() -> multibucket::Result<()> {
//! 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?;
//! # Ok(())
//! # }
//! ```
//!
//! ## Backends
//!
//! * [`backends::s3`] — Amazon S3 / S3-compatible. See [`S3Client`](backends::s3::S3Client).
//! * [`backends::qiniu`] — Qiniu Kodo. See [`QiniuClient`](backends::qiniu::QiniuClient).
//!
//! ## 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`](backends::s3::MultipartUpload) / Qiniu
//!   [`MultipartUpload`](backends::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`](backends::qiniu::QiniuClient::create_bucket),
//!   [`set_bucket_private`](backends::qiniu::QiniuClient::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`](backends::s3::S3Client::with_http) or
//!   [`QiniuClient::with_http`](backends::qiniu::QiniuClient::with_http) to
//!   control timeouts and proxies.

#![warn(missing_docs)]
#![warn(rust_2018_idioms)]

pub mod backends;
mod error;
mod storage;
mod types;

pub use error::{Error, Result};
pub use storage::{ListOptions, ObjectStorage};
pub use types::{ListOutcome, ObjectMetadata, PutBody, PutOptions};