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 S3 (or S3-compatible) bucket.
//!
//! Run (credentials read from the environment):
//!
//! ```sh
//! # Windows PowerShell
//! $env:AWS_ACCESS_KEY_ID="..."; $env:AWS_SECRET_ACCESS_KEY="..."; $env:S3_BUCKET="..."
//! cargo run --example s3_basic
//! ```
//!
//! ```sh
//! # macOS / Linux (AWS S3, us-east-1)
//! AWS_ACCESS_KEY_ID=... AWS_SECRET_ACCESS_KEY=... S3_BUCKET=... cargo run --example s3_basic
//! ```
//!
//! ```sh
//! # macOS / Linux (MinIO / path-style compatible service)
//! AWS_ACCESS_KEY_ID=... AWS_SECRET_ACCESS_KEY=... S3_BUCKET=mybucket \
//!   S3_ENDPOINT=localhost:9000 S3_FORCE_PATH_STYLE=1 cargo run --example s3_basic
//! ```

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

use bytes::Bytes;

use multibucket::backends::s3::{CompletedPart, S3Client, S3Config};
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.
    let access_key = env::var("AWS_ACCESS_KEY_ID").expect("set AWS_ACCESS_KEY_ID");
    let secret_key = env::var("AWS_SECRET_ACCESS_KEY").expect("set AWS_SECRET_ACCESS_KEY");
    let bucket = env::var("S3_BUCKET").expect("set S3_BUCKET");

    let mut builder = S3Config::new(access_key, secret_key, bucket);
    if let Ok(region) = env::var("AWS_REGION") {
        builder = builder.region(region);
    }
    if let Ok(endpoint) = env::var("S3_ENDPOINT") {
        builder = builder.endpoint(endpoint);
    }
    if env::var("S3_FORCE_PATH_STYLE").is_ok() {
        builder = builder.force_path_style(true);
    }

    let http = reqwest::Client::builder()
        .timeout(Duration::from_secs(30))
        .build()
        .expect("build http client");
    let client = S3Client::new(builder).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 (query-string auth; works without the secret).
    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. Multipart upload (自动分片, part_size = 0 表示使用默认 8 MiB).
    let big = Bytes::from(vec![0u8; 5 * 1024 * 1024]); // ~5 MiB -> 走分片
    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. 完全手动编排分片上传(可用于跨进程续传).
    let mp = client
        .create_multipart_upload("multibucket-example/manual.bin", &PutOptions::default())
        .await?;
    println!("upload_id = {}", mp.upload_id()); // 持久化以便中断后恢复
    let name1 = mp.upload_part(1, Bytes::from("hello manual parts")).await?;
    let parts = vec![CompletedPart {
        number: 1,
        etag: name1,
    }];
    let meta = mp.complete(&parts).await?;
    println!("manual    finished key={} etag={:?}", meta.key, meta.etag);

    // 10. 清理.
    client.delete("multibucket-example/big.bin").await?;
    client.delete("multibucket-example/manual.bin").await?;

    Ok(())
}