rust-web-server 17.63.0

A dependency-minimal Rust web platform: HTTP/1.1, HTTP/2, and HTTP/3 server, reverse proxy, and application framework with routing, middleware (auth, rate limiting, tracing), an async ORM, background jobs, object storage, and a mailer. Runs as a zero-code config-driven proxy or as a library crate. No third-party HTTP dependencies.
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

//! 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) or Azure Blob Storage in production.
//!
//! # Local disk (requires the `storage-local` feature)
//!
//! ```rust
//! # #[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
//! # #[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
//! # #[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(())
//! # }
//! ```

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

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

#[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};

// ── StorageError ─────────────────────────────────────────────────────────────

/// Error returned by all `Storage` operations.
#[derive(Debug)]
pub struct StorageError(pub String);

impl StorageError {
    pub fn new(msg: impl Into<String>) -> Self {
        StorageError(msg.into())
    }
}

impl std::fmt::Display for StorageError {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.write_str(&self.0)
    }
}

impl std::error::Error for StorageError {}

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

/// Backend-independent object storage.
///
/// Implement this trait to plug a custom backend (GCS, a database-backed
/// store, ...) into the same handler code that already works against
/// [`LocalStorage`], [`S3Storage`], and [`AzureBlobStorage`].
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;
}