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
//! End-to-end example against a real Qiniu bucket.
//!
//! Run (credentials read from the environment):
//!
//! ```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
//! ```

use std::env;
use std::time::Duration;

use bytes::Bytes;

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

const KEY: &str = "multibucket-example/hello.txt";

#[tokio::main]
async fn main() -> multibucket::Result<()> {
    // 1. Build the client from environment-provided credentials.
    // For a private bucket, chain `.private_bucket("download.example.com")` on the
    // builder below with your download domain.
    let cfg = QiniuConfig::new(
        env::var("QINIU_ACCESS_KEY").expect("set QINIU_ACCESS_KEY"),
        env::var("QINIU_SECRET_KEY").expect("set QINIU_SECRET_KEY"),
        env::var("QINIU_BUCKET").expect("set QINIU_BUCKET"),
    )
    .region(Region::Z0);

    // A shared client with a sane timeout is good practice.
    let http = reqwest::Client::builder()
        .timeout(Duration::from_secs(30))
        .build()
        .expect("build http client");
    let client = QiniuClient::new(cfg).with_http(http);

    println!(
        "backend = {}, bucket = {}",
        client.backend(),
        client.bucket()
    );

    // 2. Upload.
    let body = PutBody::from(Bytes::from("hello from multibucket 🦀"));
    let meta = client
        .put(KEY, body, &PutOptions::with_content_type("text/plain"))
        .await?;
    println!(
        "uploaded  key={} size={} etag={:?}",
        meta.key, meta.size, meta.etag
    );

    // 3. Stat / exists.
    let info = client.stat(KEY).await?;
    println!("stat      size={} mime={:?}", info.size, info.content_type);
    println!("exists    {}", client.exists(KEY).await?);

    // 4. Download.
    let data = client.get(KEY).await?;
    println!(
        "downloaded {} bytes: {:?}",
        data.len(),
        String::from_utf8_lossy(&data)
    );

    // 5. Pre-signed download URL (plain URL for public buckets).
    let url = client.presign_get(KEY, Duration::from_secs(600))?;
    println!("presigned {}", url);

    // 6. List objects under a prefix.
    let page = client
        .list("multibucket-example/", &ListOptions::with_limit(10))
        .await?;
    for item in &page.items {
        println!("list item {} ({} bytes)", item.key, item.size);
    }

    // 7. Delete.
    client.delete(KEY).await?;
    println!("deleted   {}", KEY);
    println!("exists    {}", client.exists(KEY).await?);

    // 8. Resumable / multipart upload (分片上传 v2).
    //    Convenience call: part_size = 0 means the crate default (4 MiB).
    let big = Bytes::from(vec![0u8; 5 * 1024 * 1024]); // ~5 MiB -> two parts
    let meta = client
        .put_resumable(
            "multibucket-example/big.bin",
            PutBody::from(big),
            0,
            &PutOptions::default(),
        )
        .await?;
    println!("resumable uploaded key={} size={}", meta.key, meta.size);

    // 9. Full manual control (use this when you must resume across restarts):
    //    initiate -> upload each part (collect upload_id + partName) -> complete.
    //    NOTE: for a real multi-part upload every non-final part must be >= 1 MiB;
    //    here we use a single part just to show the building blocks.
    let mp = client
        .initiate_multipart_upload("multibucket-example/manual.bin", &PutOptions::default())
        .await?;
    println!("upload_id = {}", mp.upload_id()); // persist this to resume later
    let name1 = mp.upload_part(1, Bytes::from("hello manual parts")).await?;
    let parts = vec![multibucket::backends::qiniu::CompletedPart {
        number: 1,
        name: name1,
    }];
    let meta = mp.complete(&parts).await?;
    println!("manual    finished key={} etag={:?}", meta.key, meta.etag);

    // 10. Clean up the uploads created above.
    client.delete("multibucket-example/big.bin").await?;
    client.delete("multibucket-example/manual.bin").await?;

    Ok(())
}