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
//! [`QiniuConfig`] — everything needed to talk to one Qiniu Kodo bucket.

use super::region::Region;

/// Configuration for a single [`QiniuClient`](super::QiniuClient).
///
/// Construct with [`QiniuConfig::new`] and chain the optional setters:
///
/// ```
/// use multibucket::backends::qiniu::{QiniuConfig, Region};
///
/// let cfg = QiniuConfig::new("ak", "sk", "my-bucket")
///     .region(Region::Z2)
///     .private_bucket("cdn.example.com");
/// ```
#[derive(Debug, Clone)]
pub struct QiniuConfig {
    /// Qiniu AccessKey.
    pub access_key: String,
    /// Qiniu SecretKey.
    pub secret_key: String,
    /// Target bucket (空间) name.
    pub bucket: String,
    /// Region; determines the default service hosts.
    pub region: Region,
    /// Download domain. When `None`, the region's `io` host is used.
    pub download_domain: Option<String>,
    /// Whether the bucket is private (requires signed download URLs).
    pub private_bucket: bool,
    /// Added to the local clock when computing token deadlines (`e`).
    ///
    /// Qiniu rejects tokens whose `e` is too far from *its* server clock with
    /// `RequestExpiresTooSkewed`. If the client machine's clock is skewed
    /// (e.g. a test/sandbox whose date does not match the real world), set this
    /// to `server_time - local_time` so deadlines are computed against the
    /// server's notion of "now". Most real deployments leave this at `0` and
    /// instead call [`QiniuClient::sync_clock`], which derives this offset
    /// automatically from Qiniu's `Date` response header.
    pub deadline_offset_secs: i64,
    /// Use HTTPS for all requests (recommended, default `true`).
    pub use_https: bool,
    /// Override the upload host (`up-<region>.qiniup.com`).
    pub up_host: Option<String>,
    /// Override the management host (`rs-<region>.qiniuapi.com`).
    pub rs_host: Option<String>,
    /// Override the listing host (`rsf-<region>.qiniuapi.com`).
    pub rsf_host: Option<String>,
}

impl QiniuConfig {
    /// 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 {
        QiniuConfig {
            access_key: access_key.into(),
            secret_key: secret_key.into(),
            bucket: bucket.into(),
            region: Region::default(),
            download_domain: None,
            private_bucket: false,
            deadline_offset_secs: 0,
            use_https: true,
            up_host: None,
            rs_host: None,
            rsf_host: None,
        }
    }

    /// Set the region.
    pub fn region(mut self, region: Region) -> Self {
        self.region = region;
        self
    }

    /// Mark the bucket as private and set its public download `domain`.
    ///
    /// Download URLs will be signed with an expiry token.
    pub fn private_bucket(mut self, domain: impl Into<String>) -> Self {
        self.private_bucket = true;
        self.download_domain = Some(domain.into());
        self
    }

    /// Mark the bucket as private **without** binding a custom download domain.
    ///
    /// The region's default `io` host (`iovip-<region>.qiniuio.com`) is signed
    /// with an expiry token instead — this is Qiniu's standard private-download
    /// mechanism and works for any private bucket that has not yet bound a
    /// custom CDN domain. (Use [`private_bucket`](Self::private_bucket) when you
    /// do have a dedicated download domain.)
    pub fn private(mut self) -> Self {
        self.private_bucket = true;
        self
    }

    /// Compensate for a skewed client clock when minting token deadlines.
    ///
    /// `e = (local_now + offset) + ttl`. Set `offset = server_time - local_time`
    /// in environments whose wall clock disagrees with Qiniu's servers (Qiniu
    /// answers a skewed `e` with `RequestExpiresTooSkewed`). Leave at `0` when
    /// the machine clock is accurate.
    pub fn deadline_offset_secs(mut self, offset: i64) -> Self {
        self.deadline_offset_secs = offset;
        self
    }

    /// Set a public download domain without enabling private signing.
    pub fn download_domain(mut self, domain: impl Into<String>) -> Self {
        self.download_domain = Some(domain.into());
        self
    }

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

    /// Override the upload host.
    pub fn up_host(mut self, host: impl Into<String>) -> Self {
        self.up_host = Some(host.into());
        self
    }

    /// Override the resource-management host.
    pub fn rs_host(mut self, host: impl Into<String>) -> Self {
        self.rs_host = Some(host.into());
        self
    }

    /// Override the listing host.
    pub fn rsf_host(mut self, host: impl Into<String>) -> Self {
        self.rsf_host = Some(host.into());
        self
    }

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

    pub(crate) fn up_host_resolved(&self) -> &str {
        self.up_host
            .as_deref()
            .unwrap_or_else(|| self.region.up_host())
    }

    pub(crate) fn rs_host_resolved(&self) -> &str {
        self.rs_host
            .as_deref()
            .unwrap_or_else(|| self.region.rs_host())
    }

    pub(crate) fn rsf_host_resolved(&self) -> &str {
        self.rsf_host
            .as_deref()
            .unwrap_or_else(|| self.region.rsf_host())
    }

    pub(crate) fn download_host(&self) -> &str {
        self.download_domain
            .as_deref()
            .unwrap_or_else(|| self.region.io_host())
    }
}