garage_sdk/lib.rs
1//! # Garage SDK
2//!
3//! An async SDK for Garage (S3-compatible) that uploads files from paths, URLs,
4//! or bytes and returns a stable public URL for CDN or proxy-fronted access.
5//!
6//! ## Features
7//!
8//! - Upload files from local paths, URLs, or raw bytes
9//! - Automatic content-type detection
10//! - Configurable key prefixes and file naming
11//! - Proper error handling with detailed error types
12//! - Builder pattern for flexible configuration
13//!
14//! ## Example
15//!
16//! ```rust,no_run
17//! use garage_sdk::{GarageUploader, UploaderConfig};
18//!
19//! #[tokio::main]
20//! async fn main() -> Result<(), garage_sdk::Error> {
21//! let config = UploaderConfig::builder()
22//! .endpoint("https://s3.example.com")
23//! .bucket("my-bucket")
24//! .public_base_url("https://cdn.example.com")
25//! .credentials("access_key", "secret_key")
26//! .build()?;
27//!
28//! let uploader = GarageUploader::new(config)?;
29//!
30//! let result = uploader.upload_from_path("./image.png").await?;
31//! println!("Uploaded to: {}", result.public_url);
32//!
33//! Ok(())
34//! }
35//! ```
36//!
37//! ## Download Buffering vs Streaming
38//!
39//! `upload_from_url` buffers small downloads in memory and streams larger or
40//! unknown-size responses to avoid unbounded memory usage.
41//!
42//! - Default buffer threshold: 8 MB (`max_buffered_bytes`)
43//! - Hard size limit: 100 MB (`max_file_size`)
44//!
45//! If `Content-Length` is present and below the threshold, the response is
46//! buffered. Otherwise, the response is streamed and the size cap is enforced
47//! during the read.
48//!
49//! ## Configuration Sources
50//!
51//! - Environment variables: `UploaderConfig::from_env()`
52//! - Secret files directory: `UploaderConfig::from_secret_dir(...)`
53//! - Env with file fallback: `UploaderConfig::from_env_or_secret_dir(...)`
54//!
55//! For Kubernetes env injection, set:
56//! `GARAGE_ENDPOINT`, `GARAGE_BUCKET`, `GARAGE_PUBLIC_URL`,
57//! `AWS_ACCESS_KEY_ID`, and `AWS_SECRET_ACCESS_KEY`.
58
59mod config;
60mod download;
61mod error;
62mod keygen;
63mod storage;
64mod types;
65mod uploader;
66
67pub use aws_sdk_s3;
68pub use config::{SecretFileNames, SecretFileNamesBuilder, UploaderConfig, UploaderConfigBuilder};
69pub use download::{DownloadBody, DownloadResult, Downloader, ReqwestDownloader};
70pub use error::{Error, Result};
71pub use keygen::{KeyGenerator, UuidKeyGenerator};
72pub use storage::{S3Storage, StorageClient, StorageInput, StorageResult};
73pub use types::UploadResult;
74pub use uploader::GarageUploader;