lash_local_store/
lib.rs

1use std::collections::HashMap;
2use std::fs;
3use std::path::{Path, PathBuf};
4use std::sync::Mutex;
5
6use lash_core::{
7    AttachmentCreateMeta, AttachmentId, AttachmentMeta, AttachmentRef, AttachmentStore,
8    AttachmentStoreError, AttachmentStorePersistence, StoredAttachment,
9};
10
11pub struct FileAttachmentStore {
12    root: PathBuf,
13    meta: Mutex<HashMap<AttachmentId, AttachmentMeta>>,
14}
15
16impl FileAttachmentStore {
17    pub fn new(root: impl Into<PathBuf>) -> Self {
18        Self {
19            root: root.into(),
20            meta: Mutex::new(HashMap::new()),
21        }
22    }
23
24    pub fn root(&self) -> &Path {
25        &self.root
26    }
27
28    /// Lock the in-memory metadata cache, recovering from a poisoned lock
29    /// rather than panicking. The cache is a best-effort fast path backed by
30    /// the on-disk `.json` sidecars, so a prior panic while it was held must
31    /// not permanently brick the store — `get`/`put` simply fall back to disk.
32    fn meta_cache(&self) -> std::sync::MutexGuard<'_, HashMap<AttachmentId, AttachmentMeta>> {
33        self.meta
34            .lock()
35            .unwrap_or_else(|poisoned| poisoned.into_inner())
36    }
37
38    fn path_for_id(&self, id: &AttachmentId) -> PathBuf {
39        let id = id.as_str();
40        let prefix = id.get(..2).unwrap_or(id);
41        self.root.join("sha256").join(prefix).join(id)
42    }
43
44    fn meta_path_for_id(&self, id: &AttachmentId) -> PathBuf {
45        self.path_for_id(id).with_extension("json")
46    }
47}
48
49/// Write `bytes` to `final_path` crash-atomically: stage into a sibling
50/// `<final>.tmp`, flush it, then `rename` into place. A `rename` within the
51/// same directory is atomic on POSIX, so a reader (or a crash) ever sees either
52/// the old contents or the complete new contents — never a half-written file.
53/// The temp file is removed on any failure so a crashed write leaves no
54/// `.tmp` litter behind.
55fn write_atomic(final_path: &Path, bytes: &[u8]) -> Result<(), AttachmentStoreError> {
56    let mut tmp_os = final_path.as_os_str().to_os_string();
57    tmp_os.push(".tmp");
58    let tmp_path = PathBuf::from(tmp_os);
59
60    let io_err = |path: &Path, source: std::io::Error| AttachmentStoreError::Io {
61        path: path.to_path_buf(),
62        source,
63    };
64
65    let write_result = (|| {
66        let mut file = fs::File::create(&tmp_path).map_err(|source| io_err(&tmp_path, source))?;
67        std::io::Write::write_all(&mut file, bytes).map_err(|source| io_err(&tmp_path, source))?;
68        // Best-effort durability for the staged bytes before the rename.
69        file.sync_all()
70            .map_err(|source| io_err(&tmp_path, source))?;
71        fs::rename(&tmp_path, final_path).map_err(|source| io_err(final_path, source))
72    })();
73
74    if write_result.is_err() {
75        // Never leave a partial temp file behind.
76        let _ = fs::remove_file(&tmp_path);
77    }
78    write_result
79}
80
81impl AttachmentStore for FileAttachmentStore {
82    fn persistence(&self) -> AttachmentStorePersistence {
83        AttachmentStorePersistence::Durable
84    }
85
86    fn put(
87        &self,
88        bytes: Vec<u8>,
89        meta: AttachmentCreateMeta,
90    ) -> Result<AttachmentRef, AttachmentStoreError> {
91        let meta = AttachmentMeta::new(
92            lash_core::attachments::content_id(&bytes),
93            meta.media_type,
94            bytes.len() as u64,
95            meta.width,
96            meta.height,
97            meta.label,
98        );
99        let path = self.path_for_id(&meta.id);
100        if let Some(parent) = path.parent() {
101            fs::create_dir_all(parent).map_err(|source| AttachmentStoreError::Io {
102                path: parent.to_path_buf(),
103                source,
104            })?;
105        }
106        if !path.exists() {
107            write_atomic(&path, &bytes)?;
108        }
109        let meta_path = self.meta_path_for_id(&meta.id);
110        let meta_bytes = serde_json::to_vec_pretty(&meta).expect("attachment metadata serializes");
111        write_atomic(&meta_path, &meta_bytes)?;
112        let reference = meta.as_ref();
113        self.meta_cache().insert(reference.id.clone(), meta);
114        Ok(reference)
115    }
116
117    fn get(&self, id: &AttachmentId) -> Result<StoredAttachment, AttachmentStoreError> {
118        let path = self.path_for_id(id);
119        let bytes = fs::read(&path).map_err(|source| {
120            if source.kind() == std::io::ErrorKind::NotFound {
121                AttachmentStoreError::NotFound(id.clone())
122            } else {
123                AttachmentStoreError::Io {
124                    path: path.clone(),
125                    source,
126                }
127            }
128        })?;
129        let meta = if let Some(meta) = self.meta_cache().get(id).cloned() {
130            meta
131        } else {
132            let meta_path = self.meta_path_for_id(id);
133            let meta_bytes = fs::read(&meta_path).map_err(|source| {
134                if source.kind() == std::io::ErrorKind::NotFound {
135                    AttachmentStoreError::MissingMeta(id.clone())
136                } else {
137                    AttachmentStoreError::Io {
138                        path: meta_path.clone(),
139                        source,
140                    }
141                }
142            })?;
143            serde_json::from_slice(&meta_bytes).map_err(|source| AttachmentStoreError::Io {
144                path: meta_path,
145                source: std::io::Error::new(std::io::ErrorKind::InvalidData, source),
146            })?
147        };
148        Ok(StoredAttachment { meta, bytes })
149    }
150}
151
152#[cfg(test)]
153mod tests {
154    use super::*;
155    use lash_core::{ImageMediaType, MediaType};
156
157    fn meta() -> AttachmentCreateMeta {
158        AttachmentCreateMeta::new(
159            MediaType::Image(ImageMediaType::Png),
160            Some(1),
161            Some(1),
162            Some("pixel".to_string()),
163        )
164    }
165
166    #[test]
167    fn file_store_round_trips_bytes_and_metadata() {
168        let temp = tempfile::tempdir().expect("tempdir");
169        let store = FileAttachmentStore::new(temp.path());
170        let reference = store.put(vec![1, 2, 3], meta()).expect("put");
171        let stored = store.get(&reference.id).expect("get");
172
173        assert_eq!(stored.bytes, vec![1, 2, 3]);
174        assert_eq!(stored.meta.id, reference.id);
175        assert_eq!(stored.meta.byte_len, 3);
176    }
177
178    // Finding 4: `put` must write crash-atomically (stage into `<final>.tmp`,
179    // then rename). After a successful put there must be no leftover `.tmp`
180    // files in the content directory — proof that the temp file was renamed
181    // into place rather than written in situ.
182    #[test]
183    fn file_store_writes_atomically_without_temp_litter() {
184        let temp = tempfile::tempdir().expect("tempdir");
185        let store = FileAttachmentStore::new(temp.path());
186        let reference = store.put(vec![9, 8, 7, 6], meta()).expect("put");
187
188        let final_path = store.path_for_id(&reference.id);
189        let meta_path = store.meta_path_for_id(&reference.id);
190        assert!(final_path.exists(), "content file must be in place");
191        assert!(meta_path.exists(), "metadata file must be in place");
192
193        let mut tmp_files = Vec::new();
194        let dir = final_path.parent().expect("content dir");
195        for entry in fs::read_dir(dir).expect("read content dir") {
196            let path = entry.expect("dir entry").path();
197            if path.extension().and_then(|ext| ext.to_str()) == Some("tmp") {
198                tmp_files.push(path);
199            }
200        }
201        assert!(
202            tmp_files.is_empty(),
203            "atomic write must not leave .tmp files behind: {tmp_files:?}"
204        );
205
206        // The bytes round-trip in full (no truncation from a partial write).
207        let stored = store.get(&reference.id).expect("get");
208        assert_eq!(stored.bytes, vec![9, 8, 7, 6]);
209    }
210
211    // A stale `<final>.tmp` left by a crashed prior write must not block a
212    // subsequent successful put — the temp file is recreated/truncated.
213    #[test]
214    fn file_store_overwrites_stale_temp_file() {
215        let temp = tempfile::tempdir().expect("tempdir");
216        let store = FileAttachmentStore::new(temp.path());
217        let content_id = lash_core::attachments::content_id(&[1, 1, 1]);
218        let id = AttachmentId::new(content_id.to_string());
219        let final_path = store.path_for_id(&id);
220        let parent = final_path.parent().expect("parent");
221        fs::create_dir_all(parent).expect("mkdir");
222        let mut tmp_os = final_path.as_os_str().to_os_string();
223        tmp_os.push(".tmp");
224        fs::write(PathBuf::from(tmp_os), b"stale partial write").expect("seed stale tmp");
225
226        let reference = store
227            .put(vec![1, 1, 1], meta())
228            .expect("put over stale tmp");
229        let stored = store.get(&reference.id).expect("get");
230        assert_eq!(stored.bytes, vec![1, 1, 1]);
231    }
232}
lash_local_store/lib.rs

lash_local_store/
lib.rs
