Skip to main content

capy_storage/
lib.rs

1//! Private, bounded object storage for application services.
2#[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/// One validated application-controlled object identifier.
18#[derive(Clone, Debug, Eq, Hash, PartialEq)]
19pub struct StorageKey(String);
20impl StorageKey {
21    /// Accept relative slash-separated ASCII segments; reject traversal and path confusion.
22    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    /// Stable key text suitable for the configured backend.
42    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/// Errors avoid exposing object contents or credentials.
54#[derive(Debug, thiserror::Error)]
55pub enum StorageError {
56    /// Key is not an application-controlled relative identifier.
57    #[error("Invalid storage key")]
58    InvalidKey,
59    /// The object does not exist.
60    #[error("Storage object not found")]
61    NotFound,
62    /// The configured size bound would be exceeded.
63    #[error("Storage object exceeds configured size limit")]
64    TooLarge,
65    /// A path component would escape or alias the storage root.
66    #[error("Unsafe local storage path")]
67    UnsafePath,
68    /// Local backend operation failed.
69    #[error("Storage I/O failed")]
70    Io(#[source] std::io::Error),
71    /// Backend does not provide temporary download URLs.
72    #[error("Temporary download URLs are unsupported by this backend")]
73    Unsupported,
74    /// Backend configuration is invalid.
75    #[error("Invalid storage configuration: {0}")]
76    Configuration(&'static str),
77    /// S3 request or response failed; details are deliberately withheld.
78    #[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}
102/// Storage operation result.
103pub type Result<T> = std::result::Result<T, StorageError>;
104
105/// Small trusted metadata. A caller-supplied content type is only a hint.
106#[derive(Clone, Debug, Eq, PartialEq)]
107pub struct ObjectMetadata {
108    /// Object byte length.
109    pub length: u64,
110    /// Optional untrusted content type hint.
111    pub content_type: Option<String>,
112}
113
114/// Download handle whose reader can be consumed without buffering the whole object.
115pub struct StoredObject {
116    /// Byte stream; read with Tokio's `AsyncReadExt`.
117    pub reader: Box<dyn AsyncRead + Send + Unpin>,
118    /// Metadata available at opening time.
119    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/// Cloneable service; cloned handles share one backend, separate memories stay isolated.
134#[derive(Clone)]
135pub struct Storage {
136    backend: Arc<Backend>,
137    max_object_bytes: u64,
138}
139impl Storage {
140    /// Build from validated application settings; `none` leaves storage disabled.
141    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    /// Create isolated in-memory storage with a hard per-object byte limit.
166    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    /// Create a private local root, canonicalized before any object operation.
175    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    /// Stream an upload, aborting before more than the configured bound is stored.
201    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                // Recheck after writing, before the atomic rename.
239                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    /// Convenience for bounded in-memory input; useful for small files and tests.
257    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    /// Open an object as a stream with metadata.
271    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    /// Read a bounded complete object for tests or small application payloads.
305    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    /// Inspect object length and available metadata without downloading it.
316    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    /// Delete one object; deleting an absent key is idempotent.
329    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    /// Memory and local objects require authenticated application retrieval.
349    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}