1#[cfg(unix)]
3use std::os::unix::fs::PermissionsExt;
4use std::{
5 collections::HashMap,
6 io::Cursor,
7 path::{Path, PathBuf},
8 sync::{Arc, RwLock},
9};
10use tokio::{
11 fs::{self, File},
12 io::{AsyncRead, AsyncReadExt, AsyncWriteExt},
13};
14#[cfg(feature = "s3")]
15mod s3;
16
17#[derive(Clone, Debug, Eq, Hash, PartialEq)]
19pub struct StorageKey(String);
20impl StorageKey {
21 pub fn new(value: impl Into<String>) -> Result<Self> {
23 let value = value.into();
24 if value.is_empty()
25 || value.len() > 1024
26 || value.split('/').any(|segment| {
27 segment.is_empty()
28 || segment == "."
29 || segment == ".."
30 || segment == ".capy-tmp"
31 || segment.len() > 255
32 || !segment
33 .bytes()
34 .all(|c| c.is_ascii_alphanumeric() || b"_-.".contains(&c))
35 })
36 {
37 return Err(StorageError::InvalidKey);
38 }
39 Ok(Self(value))
40 }
41 pub fn as_str(&self) -> &str {
43 &self.0
44 }
45}
46impl TryFrom<&str> for StorageKey {
47 type Error = StorageError;
48 fn try_from(value: &str) -> Result<Self> {
49 Self::new(value)
50 }
51}
52
53#[derive(Debug, thiserror::Error)]
55pub enum StorageError {
56 #[error("Invalid storage key")]
58 InvalidKey,
59 #[error("Storage object not found")]
61 NotFound,
62 #[error("Storage object exceeds configured size limit")]
64 TooLarge,
65 #[error("Unsafe local storage path")]
67 UnsafePath,
68 #[error("Storage I/O failed")]
70 Io(#[source] std::io::Error),
71 #[error("Temporary download URLs are unsupported by this backend")]
73 Unsupported,
74 #[error("Invalid storage configuration: {0}")]
76 Configuration(&'static str),
77 #[error("S3 storage operation failed")]
79 Backend,
80}
81impl From<std::io::Error> for StorageError {
82 fn from(error: std::io::Error) -> Self {
83 Self::Io(error)
84 }
85}
86impl From<StorageError> for capy_core::AppError {
87 fn from(error: StorageError) -> Self {
88 match error {
89 StorageError::InvalidKey => Self::BadRequest("Invalid storage key.".into()),
90 StorageError::NotFound => Self::NotFound,
91 StorageError::TooLarge => Self::PayloadTooLarge,
92 StorageError::Configuration(message) => Self::Configuration(message.into()),
93 StorageError::Unsupported => {
94 Self::Configuration("Storage backend does not support temporary URLs.".into())
95 }
96 StorageError::UnsafePath | StorageError::Io(_) | StorageError::Backend => {
97 Self::Lifecycle
98 }
99 }
100 }
101}
102pub type Result<T> = std::result::Result<T, StorageError>;
104
105#[derive(Clone, Debug, Eq, PartialEq)]
107pub struct ObjectMetadata {
108 pub length: u64,
110 pub content_type: Option<String>,
112}
113
114pub struct StoredObject {
116 pub reader: Box<dyn AsyncRead + Send + Unpin>,
118 pub metadata: ObjectMetadata,
120}
121
122struct MemoryObject {
123 bytes: Vec<u8>,
124 content_type: Option<String>,
125}
126enum Backend {
127 Memory(RwLock<HashMap<StorageKey, MemoryObject>>),
128 Local(PathBuf),
129 #[cfg(feature = "s3")]
130 S3(s3::S3),
131}
132
133#[derive(Clone)]
135pub struct Storage {
136 backend: Arc<Backend>,
137 max_object_bytes: u64,
138}
139impl Storage {
140 pub fn from_config(settings: &capy_core::StorageSettings) -> Result<Option<Self>> {
142 match settings.driver.as_str() {
143 "none" => Ok(None),
144 "memory" => Self::memory(settings.max_object_bytes).map(Some),
145 "local" => Self::local(&settings.root, settings.max_object_bytes).map(Some),
146 "s3" => {
147 #[cfg(feature = "s3")]
148 {
149 let backend = s3::S3::new(settings)?;
150 Ok(Some(Self {
151 backend: Arc::new(Backend::S3(backend)),
152 max_object_bytes: settings.max_object_bytes,
153 }))
154 }
155 #[cfg(not(feature = "s3"))]
156 {
157 Err(StorageError::Configuration(
158 "S3 support is not enabled in this build",
159 ))
160 }
161 }
162 _ => Err(StorageError::Configuration("unknown storage driver")),
163 }
164 }
165 pub fn memory(max_object_bytes: u64) -> Result<Self> {
167 validate_limit(max_object_bytes)?;
168 Ok(Self {
169 backend: Arc::new(Backend::Memory(RwLock::new(HashMap::new()))),
170 max_object_bytes,
171 })
172 }
173
174 pub fn local(root: impl AsRef<Path>, max_object_bytes: u64) -> Result<Self> {
176 validate_limit(max_object_bytes)?;
177 let root = root.as_ref();
178 std::fs::create_dir_all(root)?;
179 let root = root.canonicalize()?;
180 if !root.is_dir() {
181 return Err(StorageError::Configuration(
182 "local root must be a directory",
183 ));
184 }
185 let temporary = root.join(".capy-tmp");
186 reject_symlink(&temporary)?;
187 std::fs::create_dir_all(&temporary)?;
188 reject_symlink(&temporary)?;
189 #[cfg(unix)]
190 {
191 std::fs::set_permissions(&root, std::fs::Permissions::from_mode(0o700))?;
192 std::fs::set_permissions(&temporary, std::fs::Permissions::from_mode(0o700))?;
193 }
194 Ok(Self {
195 backend: Arc::new(Backend::Local(root)),
196 max_object_bytes,
197 })
198 }
199
200 pub async fn put<R: AsyncRead + Unpin + Send>(
202 &self,
203 key: &StorageKey,
204 reader: &mut R,
205 content_type: Option<&str>,
206 ) -> Result<ObjectMetadata> {
207 if content_type.is_some_and(|value| value.len() > 255 || value.contains(['\r', '\n'])) {
208 return Err(StorageError::Configuration("invalid content type hint"));
209 }
210 let metadata = ObjectMetadata {
211 length: 0,
212 content_type: content_type.map(str::to_owned),
213 };
214 match self.backend.as_ref() {
215 Backend::Memory(objects) => {
216 let mut bytes = Vec::new();
217 let length = read_bounded(reader, &mut bytes, self.max_object_bytes).await?;
218 objects.write().unwrap().insert(
219 key.clone(),
220 MemoryObject {
221 bytes,
222 content_type: metadata.content_type.clone(),
223 },
224 );
225 Ok(ObjectMetadata { length, ..metadata })
226 }
227 Backend::Local(root) => {
228 let parent = prepare_parent(root, key).await?;
229 let destination = parent.join(key.as_str().rsplit('/').next().unwrap());
230 reject_symlink(&destination)?;
231 let temporary = tempfile::NamedTempFile::new_in(root.join(".capy-tmp"))?;
232 let path = temporary.path().to_owned();
233 let mut file = File::from_std(temporary.reopen()?);
234 let length = read_bounded(reader, &mut file, self.max_object_bytes).await?;
235 file.flush().await?;
236 file.sync_all().await?;
237 drop(file);
238 let current_parent = prepare_parent(root, key).await?;
240 if current_parent != parent {
241 return Err(StorageError::UnsafePath);
242 }
243 reject_symlink(&destination)?;
244 fs::rename(path, destination).await?;
245 Ok(ObjectMetadata { length, ..metadata })
246 }
247 #[cfg(feature = "s3")]
248 Backend::S3(backend) => {
249 backend
250 .put(key, reader, content_type, self.max_object_bytes)
251 .await
252 }
253 }
254 }
255
256 pub async fn put_bytes(
258 &self,
259 key: &StorageKey,
260 bytes: &[u8],
261 content_type: Option<&str>,
262 ) -> Result<ObjectMetadata> {
263 if bytes.len() as u64 > self.max_object_bytes {
264 return Err(StorageError::TooLarge);
265 }
266 let mut reader = Cursor::new(bytes.to_vec());
267 self.put(key, &mut reader, content_type).await
268 }
269
270 pub async fn get(&self, key: &StorageKey) -> Result<StoredObject> {
272 match self.backend.as_ref() {
273 Backend::Memory(objects) => {
274 let objects = objects.read().unwrap();
275 let object = objects.get(key).ok_or(StorageError::NotFound)?;
276 Ok(StoredObject {
277 reader: Box::new(Cursor::new(object.bytes.clone())),
278 metadata: ObjectMetadata {
279 length: object.bytes.len() as u64,
280 content_type: object.content_type.clone(),
281 },
282 })
283 }
284 Backend::Local(root) => {
285 let path = object_path(root, key)?;
286 let file = File::open(path).await.map_err(missing)?;
287 let metadata = file.metadata().await?;
288 if !metadata.is_file() {
289 return Err(StorageError::UnsafePath);
290 }
291 Ok(StoredObject {
292 reader: Box::new(file),
293 metadata: ObjectMetadata {
294 length: metadata.len(),
295 content_type: None,
296 },
297 })
298 }
299 #[cfg(feature = "s3")]
300 Backend::S3(backend) => backend.get(key).await,
301 }
302 }
303
304 pub async fn read(&self, key: &StorageKey) -> Result<Vec<u8>> {
306 let mut object = self.get(key).await?;
307 if object.metadata.length > self.max_object_bytes {
308 return Err(StorageError::TooLarge);
309 }
310 let mut bytes = Vec::new();
311 read_bounded(&mut object.reader, &mut bytes, self.max_object_bytes).await?;
312 Ok(bytes)
313 }
314
315 pub async fn head(&self, key: &StorageKey) -> Result<Option<ObjectMetadata>> {
317 #[cfg(feature = "s3")]
318 if let Backend::S3(backend) = self.backend.as_ref() {
319 return backend.head(key).await;
320 }
321 match self.get(key).await {
322 Ok(object) => Ok(Some(object.metadata)),
323 Err(StorageError::NotFound) => Ok(None),
324 Err(error) => Err(error),
325 }
326 }
327
328 pub async fn delete(&self, key: &StorageKey) -> Result<()> {
330 match self.backend.as_ref() {
331 Backend::Memory(objects) => {
332 objects.write().unwrap().remove(key);
333 Ok(())
334 }
335 Backend::Local(root) => {
336 let path = object_path(root, key)?;
337 match fs::remove_file(path).await {
338 Ok(()) => Ok(()),
339 Err(error) if error.kind() == std::io::ErrorKind::NotFound => Ok(()),
340 Err(error) => Err(error.into()),
341 }
342 }
343 #[cfg(feature = "s3")]
344 Backend::S3(backend) => backend.delete(key).await,
345 }
346 }
347
348 pub async fn temporary_get_url(
350 &self,
351 key: &StorageKey,
352 duration: std::time::Duration,
353 ) -> Result<String> {
354 match self.backend.as_ref() {
355 #[cfg(feature = "s3")]
356 Backend::S3(backend) => backend.temporary_get_url(key, duration),
357 _ => {
358 let _ = (key, duration);
359 Err(StorageError::Unsupported)
360 }
361 }
362 }
363}
364
365fn validate_limit(limit: u64) -> Result<()> {
366 if !(1..=1_073_741_824).contains(&limit) {
367 return Err(StorageError::Configuration(
368 "max_object_bytes must be 1..=1073741824",
369 ));
370 }
371 Ok(())
372}
373
374async fn read_bounded<R: AsyncRead + Unpin, W: tokio::io::AsyncWrite + Unpin>(
375 reader: &mut R,
376 writer: &mut W,
377 limit: u64,
378) -> Result<u64> {
379 let mut buffer = [0u8; 16 * 1024];
380 let mut total = 0;
381 loop {
382 let count = reader.read(&mut buffer).await?;
383 if count == 0 {
384 return Ok(total);
385 }
386 total += count as u64;
387 if total > limit {
388 return Err(StorageError::TooLarge);
389 }
390 writer.write_all(&buffer[..count]).await?;
391 }
392}
393
394async fn prepare_parent(root: &Path, key: &StorageKey) -> Result<PathBuf> {
395 let mut parent = root.to_owned();
396 let segments = key.as_str().split('/').collect::<Vec<_>>();
397 for segment in &segments[..segments.len() - 1] {
398 parent.push(segment);
399 reject_symlink(&parent)?;
400 fs::create_dir(&parent).await.or_else(|error| {
401 if error.kind() == std::io::ErrorKind::AlreadyExists {
402 Ok(())
403 } else {
404 Err(error)
405 }
406 })?;
407 reject_symlink(&parent)?;
408 #[cfg(unix)]
409 fs::set_permissions(&parent, std::fs::Permissions::from_mode(0o700)).await?;
410 }
411 let canonical = parent.canonicalize()?;
412 if !canonical.starts_with(root) {
413 return Err(StorageError::UnsafePath);
414 }
415 Ok(canonical)
416}
417fn object_path(root: &Path, key: &StorageKey) -> Result<PathBuf> {
418 let mut path = root.to_owned();
419 for segment in key.as_str().split('/') {
420 path.push(segment);
421 reject_symlink(&path)?;
422 }
423 Ok(path)
424}
425fn reject_symlink(path: &Path) -> Result<()> {
426 match std::fs::symlink_metadata(path) {
427 Ok(metadata) if metadata.file_type().is_symlink() => Err(StorageError::UnsafePath),
428 Ok(_) => Ok(()),
429 Err(error) if error.kind() == std::io::ErrorKind::NotFound => Ok(()),
430 Err(error) => Err(error.into()),
431 }
432}
433fn missing(error: std::io::Error) -> StorageError {
434 if error.kind() == std::io::ErrorKind::NotFound {
435 StorageError::NotFound
436 } else {
437 StorageError::Io(error)
438 }
439}
440
441#[cfg(test)]
442mod tests {
443 use super::*;
444
445 fn key(value: &str) -> StorageKey {
446 StorageKey::new(value).unwrap()
447 }
448
449 #[test]
450 fn keys_reject_traversal_and_path_confusion() {
451 for value in [
452 "",
453 "/absolute",
454 "../escape",
455 "a/../b",
456 "a//b",
457 "a/./b",
458 ".capy-tmp/object",
459 "a\\b",
460 "a\0b",
461 "a%2fb",
462 ] {
463 assert!(StorageKey::new(value).is_err(), "{value:?}");
464 }
465 assert_eq!(key("avatars/user-1.png").as_str(), "avatars/user-1.png");
466 }
467
468 async fn lifecycle(storage: Storage) {
469 let object = key("avatars/user-1.png");
470 assert!(storage.head(&object).await.unwrap().is_none());
471 assert_eq!(
472 storage
473 .put_bytes(&object, b"hello", Some("image/png"))
474 .await
475 .unwrap()
476 .length,
477 5
478 );
479 assert_eq!(storage.read(&object).await.unwrap(), b"hello");
480 assert_eq!(storage.head(&object).await.unwrap().unwrap().length, 5);
481 assert!(matches!(
482 storage
483 .temporary_get_url(&object, std::time::Duration::from_secs(60))
484 .await,
485 Err(StorageError::Unsupported)
486 ));
487 storage.delete(&object).await.unwrap();
488 storage.delete(&object).await.unwrap();
489 assert!(storage.head(&object).await.unwrap().is_none());
490 }
491
492 #[tokio::test]
493 async fn memory_is_isolated_and_bounded() {
494 lifecycle(Storage::memory(16).unwrap()).await;
495 let first = Storage::memory(4).unwrap();
496 let second = Storage::memory(4).unwrap();
497 let object = key("export.txt");
498 first.put_bytes(&object, b"1234", None).await.unwrap();
499 assert!(matches!(
500 first.put_bytes(&object, b"12345", None).await,
501 Err(StorageError::TooLarge)
502 ));
503 assert_eq!(first.read(&object).await.unwrap(), b"1234");
504 assert!(second.head(&object).await.unwrap().is_none());
505 }
506
507 #[tokio::test]
508 async fn local_is_private_atomic_and_rejects_symlinks() {
509 let root = tempfile::tempdir().unwrap();
510 let storage = Storage::local(root.path(), 8).unwrap();
511 #[cfg(unix)]
512 assert_eq!(
513 std::fs::metadata(root.path()).unwrap().permissions().mode() & 0o777,
514 0o700
515 );
516 lifecycle(storage.clone()).await;
517 let object = key("a/file.txt");
518 storage.put_bytes(&object, b"good", None).await.unwrap();
519 #[cfg(unix)]
520 assert_eq!(
521 std::fs::metadata(root.path().join("a"))
522 .unwrap()
523 .permissions()
524 .mode()
525 & 0o777,
526 0o700
527 );
528 assert!(matches!(
529 storage.put_bytes(&object, b"too-long!", None).await,
530 Err(StorageError::TooLarge)
531 ));
532 assert_eq!(storage.read(&object).await.unwrap(), b"good");
533 #[cfg(unix)]
534 {
535 let outside = tempfile::tempdir().unwrap();
536 std::os::unix::fs::symlink(outside.path(), root.path().join("escape")).unwrap();
537 assert!(matches!(
538 storage.put_bytes(&key("escape/file"), b"x", None).await,
539 Err(StorageError::UnsafePath)
540 ));
541 assert!(matches!(
542 storage.get(&key("escape/file")).await,
543 Err(StorageError::UnsafePath)
544 ));
545 let unsafe_root = tempfile::tempdir().unwrap();
546 std::os::unix::fs::symlink(outside.path(), unsafe_root.path().join(".capy-tmp"))
547 .unwrap();
548 assert!(matches!(
549 Storage::local(unsafe_root.path(), 8),
550 Err(StorageError::UnsafePath)
551 ));
552 }
553 }
554}