Crate garage_sdk

Crate garage_sdk 

Source
Expand description

§Garage SDK

An async SDK for Garage (S3-compatible) that uploads files from paths, URLs, or bytes and returns a stable public URL for CDN or proxy-fronted access.

§Features

  • Upload files from local paths, URLs, or raw bytes
  • Automatic content-type detection
  • Configurable key prefixes and file naming
  • Proper error handling with detailed error types
  • Builder pattern for flexible configuration

§Example

use garage_sdk::{GarageUploader, UploaderConfig};

#[tokio::main]
async fn main() -> Result<(), garage_sdk::Error> {
    let config = UploaderConfig::builder()
        .endpoint("https://s3.example.com")
        .bucket("my-bucket")
        .public_base_url("https://cdn.example.com")
        .credentials("access_key", "secret_key")
        .build()?;

    let uploader = GarageUploader::new(config)?;

    let result = uploader.upload_from_path("./image.png").await?;
    println!("Uploaded to: {}", result.public_url);

    Ok(())
}

§Download Buffering vs Streaming

upload_from_url buffers small downloads in memory and streams larger or unknown-size responses to avoid unbounded memory usage.

  • Default buffer threshold: 8 MB (max_buffered_bytes)
  • Hard size limit: 100 MB (max_file_size)

If Content-Length is present and below the threshold, the response is buffered. Otherwise, the response is streamed and the size cap is enforced during the read.

§Configuration Sources

  • Environment variables: UploaderConfig::from_env()
  • Secret files directory: UploaderConfig::from_secret_dir(...)
  • Env with file fallback: UploaderConfig::from_env_or_secret_dir(...)

For Kubernetes env injection, set: GARAGE_ENDPOINT, GARAGE_BUCKET, GARAGE_PUBLIC_URL, AWS_ACCESS_KEY_ID, and AWS_SECRET_ACCESS_KEY.

Re-exports§

pub use aws_sdk_s3;

Structs§

DownloadResult
Result of a download operation.
GarageUploader
The main uploader client for Garage S3-compatible storage.
ReqwestDownloader
Default downloader using reqwest.
S3Storage
Default storage client using aws-sdk-s3.
SecretFileNames
Secret file names used by UploaderConfig::from_secret_dir_with_names.
SecretFileNamesBuilder
Builder for custom secret file mappings.
StorageInput
Input payload for storage uploads.
StorageResult
Storage upload result.
UploadResult
Result of a successful upload operation.
UploaderConfig
Configuration for the Garage uploader.
UploaderConfigBuilder
Builder for UploaderConfig.
UuidKeyGenerator
Default key generator using UUID v4.

Enums§

DownloadBody
Body payload for a download.
Error
All possible errors that can occur when using the Garage SDK.

Traits§

Downloader
Downloader abstraction for fetching remote content.
KeyGenerator
Generates object keys for uploaded files.
StorageClient
Storage client abstraction for uploading content.

Type Aliases§

Result
Result type alias for Garage SDK operations.