multibucket 0.2.1

A unified async object-storage trait with a from-scratch Qiniu Kodo backend (upload / download / delete / stat / list / signed URLs).
Documentation
//! The backend-agnostic [`ObjectStorage`] trait.

use std::time::Duration;

use async_trait::async_trait;
use bytes::Bytes;

use crate::error::Result;
use crate::types::{ListOutcome, ObjectMetadata, PutBody, PutOptions};

/// Options for a listing request.
#[derive(Debug, Clone, Default)]
pub struct ListOptions {
    /// Continue from this marker (returned by a previous page).
    pub marker: Option<String>,
    /// Maximum number of keys returned per page.
    pub limit: Option<u32>,
    /// Group keys sharing this delimiter (Qiniu supports `"/"` etc.).
    pub delimiter: Option<String>,
}

impl ListOptions {
    /// List one page with at most `limit` entries.
    pub fn with_limit(limit: u32) -> Self {
        ListOptions {
            limit: Some(limit),
            ..Default::default()
        }
    }
}

/// A unified asynchronous object-storage interface.
///
/// Every backend (Qiniu today, S3/OSS tomorrow) implements this trait, so
/// application code can be written once and pointed at any bucket — the idea
/// behind the `multibucket` name.
#[async_trait]
pub trait ObjectStorage: Send + Sync {
    /// Human-readable backend name, e.g. `"qiniu"`.
    fn backend(&self) -> &'static str;

    /// The bucket this instance operates on.
    fn bucket(&self) -> &str;

    /// Upload (create or overwrite) an object.
    async fn put(&self, key: &str, body: PutBody, opts: &PutOptions) -> Result<ObjectMetadata>;

    /// Upload an object using a resumable / multipart strategy, splitting the
    /// body into `part_size` chunks.
    ///
    /// Backends without native multipart support simply fall back to
    /// [`put`](Self::put). A `part_size` of `0` means "use the backend default".
    async fn put_resumable(
        &self,
        key: &str,
        body: PutBody,
        part_size: usize,
        opts: &PutOptions,
    ) -> Result<ObjectMetadata> {
        let _ = part_size;
        self.put(key, body, opts).await
    }

    /// Download an object into memory.
    async fn get(&self, key: &str) -> Result<Bytes>;

    /// Delete an object. Missing keys are reported via [`crate::Error::Api`].
    async fn delete(&self, key: &str) -> Result<()>;

    /// Whether an object exists.
    async fn exists(&self, key: &str) -> Result<bool>;

    /// Fetch an object's metadata.
    async fn stat(&self, key: &str) -> Result<ObjectMetadata>;

    /// List objects under `prefix`, one page at a time.
    async fn list(&self, prefix: &str, opts: &ListOptions) -> Result<ListOutcome>;

    /// Produce a time-limited, pre-signed download URL.
    ///
    /// For public buckets this is usually just the plain URL; for private
    /// buckets a download token (`e` + `token`) is appended.
    fn presign_get(&self, key: &str, expires: Duration) -> Result<String>;
}