Skip to main content

qualia_vision/
media_store.rs

1//! Content-addressed media store (Phase 2 / V2) — pure Rust, no Python.
2//!
3//! Layout under `root`:
4//! ```text
5//! media/
6//!   by-hash/
7//!     ab/cd/<hex>.bin     # raw bytes
8//!   index/
9//!     <hex>.json          # MediaRecord
10//! ```
11
12use std::fs;
13use std::io::Write;
14use std::path::{Path, PathBuf};
15
16use crate::semantic::media_digest;
17use crate::types::VisionError;
18
19/// Retention / sensitivity class for media (mirrors graph sensitivity language).
20#[derive(Debug, Clone, Copy, PartialEq, Eq)]
21#[repr(u8)]
22pub enum RetentionClass {
23    Public = 0,
24    Restricted = 1,
25    Classified = 2,
26}
27
28impl RetentionClass {
29    /// `&str` form.
30    pub fn as_str(self) -> &'static str {
31        match self {
32            RetentionClass::Public => "public",
33            RetentionClass::Restricted => "restricted",
34            RetentionClass::Classified => "classified",
35        }
36    }
37
38    /// Parses.
39    pub fn parse(s: &str) -> Option<Self> {
40        match s.trim().to_ascii_lowercase().as_str() {
41            "public" => Some(Self::Public),
42            "restricted" => Some(Self::Restricted),
43            "classified" => Some(Self::Classified),
44            _ => None,
45        }
46    }
47}
48
49#[derive(Debug, Clone, PartialEq, Eq)]
50pub struct MediaRecord {
51    pub digest_hex: String,
52    pub byte_len: u64,
53    pub mime: String,
54    pub width: u32,
55    pub height: u32,
56    pub retention: RetentionClass,
57    pub imported_unix: u64,
58    /// FNV digest hash (u64) for quin linking.
59    pub digest_u64: u64,
60}
61
62pub struct MediaStore {
63    root: PathBuf,
64}
65
66impl MediaStore {
67    /// Opens.
68    pub fn open(root: impl Into<PathBuf>) -> Result<Self, String> {
69        let root = root.into();
70        fs::create_dir_all(root.join("media/by-hash")).map_err(|e| e.to_string())?;
71        fs::create_dir_all(root.join("media/index")).map_err(|e| e.to_string())?;
72        Ok(Self { root })
73    }
74
75    /// Root.
76    pub fn root(&self) -> &Path {
77        &self.root
78    }
79
80    fn blob_path(&self, digest_hex: &str) -> PathBuf {
81        let a = digest_hex.get(0..2).unwrap_or("00");
82        let b = digest_hex.get(2..4).unwrap_or("00");
83        self.root
84            .join("media/by-hash")
85            .join(a)
86            .join(b)
87            .join(format!("{digest_hex}.bin"))
88    }
89
90    fn index_path(&self, digest_hex: &str) -> PathBuf {
91        self.root
92            .join("media/index")
93            .join(format!("{digest_hex}.json"))
94    }
95
96    /// Import raw bytes. Same content → same digest (dedupe). Partial writes never leave an index.
97    pub fn import_bytes(
98        &self,
99        bytes: &[u8],
100        mime: &str,
101        width: u32,
102        height: u32,
103        retention: RetentionClass,
104        now_unix: u64,
105    ) -> Result<MediaRecord, String> {
106        if bytes.is_empty() {
107            return Err("empty media".into());
108        }
109        let d = media_digest(bytes);
110        let digest_hex = format!("{:016x}", d.hash);
111        let blob = self.blob_path(&digest_hex);
112        let idx = self.index_path(&digest_hex);
113
114        if blob.is_file() && idx.is_file() {
115            return self.read_record(&digest_hex);
116        }
117
118        if let Some(parent) = blob.parent() {
119            fs::create_dir_all(parent).map_err(|e| e.to_string())?;
120        }
121        let tmp = blob.with_extension("bin.tmp");
122        {
123            let mut f = fs::File::create(&tmp).map_err(|e| e.to_string())?;
124            f.write_all(bytes).map_err(|e| e.to_string())?;
125            f.sync_all().map_err(|e| e.to_string())?;
126        }
127        fs::rename(&tmp, &blob).map_err(|e| e.to_string())?;
128
129        let rec = MediaRecord {
130            digest_hex: digest_hex.clone(),
131            byte_len: bytes.len() as u64,
132            mime: mime.into(),
133            width,
134            height,
135            retention,
136            imported_unix: now_unix,
137            digest_u64: d.hash,
138        };
139        let json = format!(
140            "{{\n  \"digest_hex\": \"{}\",\n  \"byte_len\": {},\n  \"mime\": \"{}\",\n  \"width\": {},\n  \"height\": {},\n  \"retention\": \"{}\",\n  \"imported_unix\": {},\n  \"digest_u64\": {}\n}}\n",
141            rec.digest_hex,
142            rec.byte_len,
143            escape_json(&rec.mime),
144            rec.width,
145            rec.height,
146            rec.retention.as_str(),
147            rec.imported_unix,
148            rec.digest_u64
149        );
150        let idx_tmp = idx.with_extension("json.tmp");
151        fs::write(&idx_tmp, json.as_bytes()).map_err(|e| e.to_string())?;
152        fs::rename(&idx_tmp, &idx).map_err(|e| e.to_string())?;
153        Ok(rec)
154    }
155
156    /// Reads record.
157    pub fn read_record(&self, digest_hex: &str) -> Result<MediaRecord, String> {
158        let s = fs::read_to_string(self.index_path(digest_hex)).map_err(|e| e.to_string())?;
159        parse_record_json(&s)
160    }
161
162    /// Reads bytes.
163    pub fn read_bytes(&self, digest_hex: &str) -> Result<Vec<u8>, String> {
164        fs::read(self.blob_path(digest_hex)).map_err(|e| e.to_string())
165    }
166
167    /// `true` when it exists.
168    pub fn exists(&self, digest_hex: &str) -> bool {
169        self.blob_path(digest_hex).is_file() && self.index_path(digest_hex).is_file()
170    }
171}
172
173fn escape_json(s: &str) -> String {
174    s.replace('\\', "\\\\").replace('"', "\\\"")
175}
176
177fn parse_record_json(s: &str) -> Result<MediaRecord, String> {
178    // Minimal hand parser for our fixed schema (no serde dep on vision crate).
179    fn field<'a>(s: &'a str, key: &str) -> Result<&'a str, String> {
180        let pat = format!("\"{key}\"");
181        let i = s.find(&pat).ok_or_else(|| format!("missing {key}"))?;
182        let rest = &s[i + pat.len()..];
183        let rest = rest.trim_start_matches(|c: char| c == ' ' || c == ':' || c == '\t');
184        if rest.starts_with('"') {
185            let rest = &rest[1..];
186            let end = rest.find('"').ok_or_else(|| format!("bad string {key}"))?;
187            Ok(&rest[..end])
188        } else {
189            let end = rest
190                .find(|c: char| c == ',' || c == '}' || c == '\n')
191                .unwrap_or(rest.len());
192            Ok(rest[..end].trim())
193        }
194    }
195    let digest_hex = field(s, "digest_hex")?.to_string();
196    let byte_len: u64 = field(s, "byte_len")?
197        .parse()
198        .map_err(|e| format!("byte_len: {e}"))?;
199    let mime = field(s, "mime")?.to_string();
200    let width: u32 = field(s, "width")?
201        .parse()
202        .map_err(|e| format!("width: {e}"))?;
203    let height: u32 = field(s, "height")?
204        .parse()
205        .map_err(|e| format!("height: {e}"))?;
206    let retention =
207        RetentionClass::parse(field(s, "retention")?).ok_or_else(|| "bad retention".to_string())?;
208    let imported_unix: u64 = field(s, "imported_unix")?
209        .parse()
210        .map_err(|e| format!("imported_unix: {e}"))?;
211    let digest_u64: u64 = field(s, "digest_u64")?
212        .parse()
213        .map_err(|e| format!("digest_u64: {e}"))?;
214    Ok(MediaRecord {
215        digest_hex,
216        byte_len,
217        mime,
218        width,
219        height,
220        retention,
221        imported_unix,
222        digest_u64,
223    })
224}
225
226/// Map store errors into VisionError when used at ABI edge.
227pub fn map_store_err(e: String) -> VisionError {
228    let _ = e;
229    VisionError::BackendUnavailable
230}
231
232#[cfg(test)]
233mod tests {
234    use super::*;
235    use std::time::{SystemTime, UNIX_EPOCH};
236
237    #[test]
238    fn import_dedupes() {
239        let dir = std::env::temp_dir().join(format!(
240            "qv-media-{}",
241            SystemTime::now()
242                .duration_since(UNIX_EPOCH)
243                .unwrap()
244                .as_nanos()
245        ));
246        let _ = fs::remove_dir_all(&dir);
247        let store = MediaStore::open(&dir).unwrap();
248        let bytes = b"\x00\xff\x00hello-vision-fixture";
249        let r1 = store
250            .import_bytes(
251                bytes,
252                "application/octet-stream",
253                1,
254                1,
255                RetentionClass::Public,
256                1,
257            )
258            .unwrap();
259        let r2 = store
260            .import_bytes(
261                bytes,
262                "application/octet-stream",
263                1,
264                1,
265                RetentionClass::Public,
266                2,
267            )
268            .unwrap();
269        assert_eq!(r1.digest_hex, r2.digest_hex);
270        assert!(store.exists(&r1.digest_hex));
271        assert_eq!(store.read_bytes(&r1.digest_hex).unwrap(), bytes);
272        let _ = fs::remove_dir_all(&dir);
273    }
274
275    #[test]
276    fn digest_matches_semantic() {
277        let b = [1u8, 2, 3, 4];
278        let d = media_digest(&b);
279        assert_eq!(d.byte_len, 4);
280        assert_ne!(d.hash, 0);
281    }
282}