Skip to main content

capy_core/
storage_config.rs

1use crate::{AppError, Result};
2use serde::{Deserialize, Serialize};
3
4/// Optional private object-store configuration (`config/storage.toml`, `STORAGE_*`).
5#[derive(Clone, Deserialize, Serialize)]
6#[serde(default, deny_unknown_fields)]
7pub struct StorageSettings {
8    /// `none`, `memory`, `local`, or `s3`.
9    pub driver: String,
10    /// Local filesystem root, relative to the application working directory if needed.
11    pub root: String,
12    /// Hard per-object size bound for uploads and buffered test reads.
13    pub max_object_bytes: u64,
14    /// S3 bucket.
15    pub bucket: Option<String>,
16    /// S3 signing region.
17    pub region: Option<String>,
18    /// Optional S3-compatible endpoint override.
19    pub endpoint: Option<String>,
20    /// Use path-style addressing, commonly required by MinIO.
21    pub path_style: bool,
22    /// Optional explicit S3 access key; environment credentials are also supported.
23    pub access_key_id: Option<String>,
24    /// Optional explicit S3 secret; never printed by Debug.
25    pub secret_access_key: Option<String>,
26    /// Optional temporary credential token; never printed by Debug.
27    pub session_token: Option<String>,
28}
29impl Default for StorageSettings {
30    fn default() -> Self {
31        Self {
32            driver: "none".into(),
33            root: ".capy/storage".into(),
34            max_object_bytes: 32 * 1024 * 1024,
35            bucket: None,
36            region: None,
37            endpoint: None,
38            path_style: true,
39            access_key_id: None,
40            secret_access_key: None,
41            session_token: None,
42        }
43    }
44}
45impl std::fmt::Debug for StorageSettings {
46    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
47        f.debug_struct("StorageSettings")
48            .field("driver", &self.driver)
49            .field("root", &self.root)
50            .field("max_object_bytes", &self.max_object_bytes)
51            .field("bucket", &self.bucket)
52            .field("region", &self.region)
53            .field("endpoint", &self.endpoint)
54            .field("path_style", &self.path_style)
55            .field(
56                "access_key_id",
57                &self.access_key_id.as_ref().map(|_| "[redacted]"),
58            )
59            .field(
60                "secret_access_key",
61                &self.secret_access_key.as_ref().map(|_| "[redacted]"),
62            )
63            .field(
64                "session_token",
65                &self.session_token.as_ref().map(|_| "[redacted]"),
66            )
67            .finish()
68    }
69}
70impl StorageSettings {
71    /// Reject obviously unsafe settings without a network connection.
72    pub fn validate(&self, production: bool) -> Result<()> {
73        if !(1..=1_073_741_824).contains(&self.max_object_bytes) {
74            return Err(AppError::Configuration(
75                "Storage max_object_bytes must be 1..=1073741824.".into(),
76            ));
77        }
78        match self.driver.as_str() {
79            "none" => Ok(()),
80            "memory" if production => Err(AppError::Configuration(
81                "In-memory storage is unavailable in production.".into(),
82            )),
83            "memory" => Ok(()),
84            "local" => {
85                let root = std::path::Path::new(&self.root);
86                if self.root.trim().is_empty()
87                    || self.root == "/"
88                    || root
89                        .components()
90                        .any(|component| matches!(component, std::path::Component::ParentDir))
91                {
92                    return Err(AppError::Configuration("Storage local root must be a dedicated directory without parent traversal.".into()));
93                }
94                if let Ok(metadata) = std::fs::symlink_metadata(root) {
95                    if !metadata.is_dir() || metadata.file_type().is_symlink() {
96                        return Err(AppError::Configuration(
97                            "Storage local root must be a real directory.".into(),
98                        ));
99                    }
100                }
101                Ok(())
102            }
103            "s3" => {
104                if self.bucket.as_deref().is_none_or(str::is_empty)
105                    || self.region.as_deref().is_none_or(str::is_empty)
106                {
107                    return Err(AppError::Configuration(
108                        "S3 storage requires bucket and region.".into(),
109                    ));
110                }
111                if self.access_key_id.is_some() != self.secret_access_key.is_some() {
112                    return Err(AppError::Configuration(
113                        "S3 access key and secret must be configured together.".into(),
114                    ));
115                }
116                if let Some(endpoint) = &self.endpoint {
117                    let parsed = url::Url::parse(endpoint)
118                        .map_err(|_| AppError::Configuration("Invalid S3 endpoint URL.".into()))?;
119                    let secure = parsed.scheme() == "https";
120                    let local = parsed.scheme() == "http"
121                        && matches!(parsed.host_str(), Some("127.0.0.1" | "localhost"));
122                    if parsed.host_str().is_none()
123                        || !parsed.username().is_empty()
124                        || parsed.password().is_some()
125                        || parsed.query().is_some()
126                        || parsed.fragment().is_some()
127                    {
128                        return Err(AppError::Configuration("Invalid S3 endpoint URL.".into()));
129                    }
130                    if !(secure || local && !production) {
131                        return Err(AppError::Configuration(
132                            "S3 endpoint must use HTTPS, except localhost in development/test."
133                                .into(),
134                        ));
135                    }
136                }
137                Ok(())
138            }
139            _ => Err(AppError::Configuration(
140                "Storage driver must be none, memory, local, or s3.".into(),
141            )),
142        }
143    }
144}