rws-storage 18.29.0

Object storage for rust-web-server: local files, S3, Azure Blob and Google Cloud Storage backends. (internal: use the rust-web-server crate).
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136

//! File / object storage abstraction.
//!
//! `FormMultipartData::parse()` hands back raw bytes with no place to put
//! them. This module gives handlers a single `Storage` trait so the same
//! upload code works against local disk in development and an S3-compatible
//! bucket (AWS S3, Cloudflare R2, MinIO), Azure Blob Storage or Google Cloud
//! Storage in production.
//!
//! # Local disk (requires the `storage-local` feature)
//!
//! ```rust
//! # extern crate rws_storage as rust_web_server;
//! # #[cfg(feature = "storage-local")]
//! # fn example() -> Result<(), rust_web_server::storage::StorageError> {
//! use rust_web_server::storage::{LocalStorage, Storage};
//!
//! let dir = std::env::temp_dir().join("rws-storage-doctest");
//! let store = LocalStorage::new(dir.to_str().unwrap()).with_base_url("/uploads");
//!
//! let key = store.put("avatars/42.png", b"...png bytes...", "image/png")?;
//! assert_eq!("/uploads/avatars/42.png", store.url(&key));
//!
//! let bytes = store.get(&key)?;
//! store.delete(&key)?;
//! # std::fs::remove_dir_all(&dir).ok();
//! # Ok(())
//! # }
//! ```
//!
//! # S3-compatible object storage (requires the `storage-s3` feature)
//!
//! ```rust,no_run
//! # extern crate rws_storage as rust_web_server;
//! # #[cfg(feature = "storage-s3")]
//! # fn example() -> Result<(), rust_web_server::storage::StorageError> {
//! use rust_web_server::storage::{S3Storage, Storage};
//!
//! // Reads RWS_S3_BUCKET, RWS_S3_REGION, RWS_S3_ACCESS_KEY, RWS_S3_SECRET_KEY,
//! // and optionally RWS_S3_ENDPOINT (for R2 / MinIO / any S3-compatible host).
//! let store = S3Storage::from_env()?;
//!
//! store.put("avatars/42.png", b"...png bytes...", "image/png")?;
//! let bytes = store.get("avatars/42.png")?;
//! store.delete("avatars/42.png")?;
//! # Ok(())
//! # }
//! ```
//!
//! # Azure Blob Storage (requires the `storage-azure` feature)
//!
//! ```rust,no_run
//! # extern crate rws_storage as rust_web_server;
//! # #[cfg(feature = "storage-azure")]
//! # fn example() -> Result<(), rust_web_server::storage::StorageError> {
//! use rust_web_server::storage::{AzureBlobStorage, Storage};
//!
//! // Reads RWS_AZURE_ACCOUNT, RWS_AZURE_CONTAINER, and optionally
//! // RWS_AZURE_ACCOUNT_KEY (falls back to Managed Identity when unset) and
//! // RWS_AZURE_ENDPOINT (for Azurite / a private endpoint).
//! let store = AzureBlobStorage::from_env()?;
//!
//! store.put("avatars/42.png", b"...png bytes...", "image/png")?;
//! let bytes = store.get("avatars/42.png")?;
//! store.delete("avatars/42.png")?;
//! # Ok(())
//! # }
//! ```


// `StorageError` and the AWS / Azure credential helpers live in rws-server
// (`secrets` uses them too); the backends are here.
pub use rws_server::storage::*;

#[cfg(feature = "storage-azure")]
mod azure_blob;
#[cfg(feature = "storage-azure")]
mod azure_signature;

#[cfg(feature = "storage-gcs")]
mod gcs;
#[cfg(feature = "storage-gcs")]
mod gcs_credentials;

#[cfg(feature = "storage-local")]
mod local;
#[cfg(feature = "storage-s3")]
mod s3;

#[cfg(feature = "storage-local")]
pub use local::LocalStorage;
#[cfg(feature = "storage-s3")]
pub use s3::{S3Config, S3Storage};
#[cfg(feature = "storage-azure")]
pub use azure_blob::{AzureBlobConfig, AzureBlobStorage};
#[cfg(feature = "storage-gcs")]
pub use gcs::{GcsConfig, GcsStorage};


// ── Storage ──────────────────────────────────────────────────────────────────

/// Backend-independent object storage.
///
/// Implement this trait to plug a custom backend (a database-backed store,
/// ...) into the same handler code that already works against
/// [`LocalStorage`], [`S3Storage`], [`AzureBlobStorage`] and `GcsStorage`.
pub trait Storage: Send + Sync {
    /// Store `data` under `key`, overwriting any existing object at that key.
    /// Returns the key that was stored (backends that normalize or namespace
    /// keys may return a different string than the one passed in).
    fn put(&self, key: &str, data: &[u8], content_type: &str) -> Result<String, StorageError>;

    /// Retrieve the bytes stored under `key`.
    fn get(&self, key: &str) -> Result<Vec<u8>, StorageError>;

    /// Delete the object stored under `key`. Backends generally treat
    /// deleting a missing key as a no-op success, matching S3's semantics.
    fn delete(&self, key: &str) -> Result<(), StorageError>;

    /// A URL for retrieving `key`. For [`LocalStorage`] this is only
    /// meaningful if a base URL was configured (e.g. because the directory
    /// is also served as static files); for [`S3Storage`] it's the object's
    /// HTTPS URL. This performs no I/O and never fails.
    fn url(&self, key: &str) -> String;
    /// Store everything `reader` yields under `key` — for a body too large
    /// to hold in memory, e.g. a streamed upload ([`Request::body`] read as a
    /// stream, #31). [`LocalStorage`] writes as it reads and [`S3Storage`]
    /// uploads in parts (S3 multipart upload), so memory stays at one part;
    /// the default reads everything first and calls [`Storage::put`].
    ///
    /// [`Request::body`]: crate::request::Request::body
    fn put_stream(&self, key: &str, reader: &mut dyn std::io::Read, content_type: &str) -> Result<String, StorageError> {
        let mut data = Vec::new();
        reader.read_to_end(&mut data).map_err(|e| StorageError::new(format!("failed to read the data for '{key}': {e}")))?;
        self.put(key, &data, content_type)
    }
}