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
//! [`S3Config`] — everything needed to talk to one S3 (or S3-compatible) bucket.

/// Configuration for a single [`S3Client`](super::S3Client).
///
/// Construct with [`S3Config::new`] and chain the optional setters:
///
/// ```no_run
/// use multibucket::backends::s3::{S3Client, S3Config};
///
/// // AWS S3 (us-east-1), virtual-hosted addressing (the default).
/// let cfg = S3Config::new("AK", "SK", "my-bucket");
/// let _client = S3Client::new(cfg);
///
/// // MinIO / a path-style compatible service.
/// let cfg = S3Config::new("AK", "SK", "my-bucket")
///     .endpoint("localhost:9000")
///     .force_path_style(true);
/// ```
///
/// The backend speaks AWS Signature Version 4, so it works against AWS S3 as
/// well as S3-compatible services (MinIO, Cloudflare R2, Aliyun OSS, Tencent
/// COS, Qiniu Kodo's S3 interface, …) — only the `endpoint` / `region` /
/// `force_path_style` differ.
#[derive(Debug, Clone)]
pub struct S3Config {
    /// S3 access key id.
    pub access_key: String,
    /// S3 secret access key.
    pub secret_key: String,
    /// Session token for temporary credentials (STS / assumed role). `None`
    /// for long-lived keys.
    pub session_token: Option<String>,
    /// Target bucket name.
    pub bucket: String,
    /// Region id (e.g. `us-east-1`, `cn-north-1`, `auto` for R2).
    pub region: String,
    /// Custom API host **without** scheme, e.g. `localhost:9000`,
    /// `s3.us-east-1.amazonaws.com` or `<id>.r2.cloudflarestorage.com`.
    /// When `None`, the AWS default `s3.<region>.amazonaws.com` is used.
    pub endpoint: Option<String>,
    /// Use path-style URLs (`https://<host>/<bucket>/<key>`) instead of the
    /// default virtual-hosted style (`https://<bucket>.<host>/<key>`). Required
    /// for MinIO and on-premise gateways; virtual-hosted works for AWS, R2 and
    /// most public clouds.
    pub force_path_style: bool,
    /// Use HTTPS (default `true`).
    pub use_https: bool,
}

impl S3Config {
    /// Create a config with the required credentials and bucket.
    pub fn new(
        access_key: impl Into<String>,
        secret_key: impl Into<String>,
        bucket: impl Into<String>,
    ) -> Self {
        S3Config {
            access_key: access_key.into(),
            secret_key: secret_key.into(),
            session_token: None,
            bucket: bucket.into(),
            region: "us-east-1".to_string(),
            endpoint: None,
            force_path_style: false,
            use_https: true,
        }
    }

    /// Set the region.
    pub fn region(mut self, region: impl Into<String>) -> Self {
        self.region = region.into();
        self
    }

    /// Set a custom API endpoint host (no scheme; see [`S3Config::endpoint`]).
    pub fn endpoint(mut self, host: impl Into<String>) -> Self {
        self.endpoint = Some(host.into());
        self
    }

    /// Force path-style addressing (see [`S3Config::force_path_style`]).
    pub fn force_path_style(mut self, on: bool) -> Self {
        self.force_path_style = on;
        self
    }

    /// Attach a session token for temporary credentials.
    pub fn session_token(mut self, token: impl Into<String>) -> Self {
        self.session_token = Some(token.into());
        self
    }

    /// Toggle HTTPS (default on).
    pub fn use_https(mut self, on: bool) -> Self {
        self.use_https = on;
        self
    }

    /// Effective scheme (`https` or `http`).
    pub(crate) fn scheme(&self) -> &'static str {
        if self.use_https {
            "https"
        } else {
            "http"
        }
    }

    /// The endpoint host: the custom host when set, else the AWS default.
    pub(crate) fn endpoint_host(&self) -> String {
        match &self.endpoint {
            Some(e) => e.clone(),
            None => format!("s3.{}.amazonaws.com", self.region),
        }
    }
}