Skip to main content

qualia_client_core/api/
q42_volumes.rs

1//! List, inspect, verify, magnet, and compact unified Q42 volumes in the vault.
2
3use std::fs;
4use std::path::{Path, PathBuf};
5
6use qualia_core_db::q42_volume::{
7    compact_volume_set, is_unified_volume, verify_volume_set_from_root, Q42InspectReport,
8    Q42Magnet, Q42VerifySetReport, Q42VolumeSetMagnets, VerifyLevel,
9};
10use serde::{Deserialize, Serialize};
11
12const SCAN_ROOTS: &[&str] = &["Index", "Chats", "wellfair", "runtime"];
13
14#[derive(Debug, Clone, Serialize, Deserialize)]
15pub struct Q42VolumeListItem {
16    pub path: String,
17    pub relative: String,
18    pub display_name: String,
19    pub file_bytes: u64,
20    pub version: u16,
21    pub flags: u16,
22    pub flag_names: Vec<String>,
23    pub block_count: u64,
24    pub lexicon_entries: Option<u64>,
25    pub has_bidx: bool,
26    pub has_field_ranges: bool,
27    pub has_field_postings: bool,
28    pub is_volume_root: bool,
29    pub publication_class: String,
30    pub publication_transport: String,
31    pub may_public_magnet: bool,
32    pub open_error: Option<String>,
33}
34
35#[derive(Debug, Clone, Serialize, Deserialize)]
36pub struct Q42VolumeWorkspace {
37    pub storage_path: String,
38    pub volumes: Vec<Q42VolumeListItem>,
39    pub total_bytes: u64,
40    pub volume_count: usize,
41    pub unreadable: usize,
42}
43
44#[derive(Debug, Clone, Serialize)]
45pub struct Q42MagnetResult {
46    pub root: Q42Magnet,
47    pub children: Vec<Q42Magnet>,
48}
49
50#[derive(Debug, Clone, Serialize, Deserialize)]
51pub struct Q42CompactResult {
52    pub source: String,
53    pub output: String,
54}
55
56fn storage_root() -> Result<PathBuf, String> {
57    let state = crate::state::APP_STATE
58        .get()
59        .ok_or_else(|| "App state is not initialised".to_string())?;
60    let path = state
61        .config
62        .lock()
63        .map_err(|e| format!("config lock poisoned: {e}"))?
64        .storage_path
65        .clone();
66    Ok(PathBuf::from(path))
67}
68
69/// Lists q42 volumes.
70pub fn list_q42_volumes() -> Result<Q42VolumeWorkspace, String> {
71    list_q42_volumes_under(&storage_root()?)
72}
73
74/// Lists q42 volumes under a path.
75pub fn list_q42_volumes_under(storage: &Path) -> Result<Q42VolumeWorkspace, String> {
76    let mut volumes = Vec::new();
77    if storage.is_dir() {
78        scan_dir(storage, storage, 0, &mut volumes)?;
79        for name in SCAN_ROOTS {
80            let child = storage.join(name);
81            if child.is_dir() {
82                scan_dir(&child, storage, 0, &mut volumes)?;
83            }
84        }
85    }
86    volumes.sort_by(|a, b| a.relative.cmp(&b.relative));
87    volumes.dedup_by(|a, b| a.path == b.path);
88    let total_bytes = volumes.iter().map(|v| v.file_bytes).sum();
89    let unreadable = volumes.iter().filter(|v| v.open_error.is_some()).count();
90    Ok(Q42VolumeWorkspace {
91        storage_path: storage.display().to_string(),
92        volume_count: volumes.len(),
93        unreadable,
94        total_bytes,
95        volumes,
96    })
97}
98
99fn scan_dir(
100    dir: &Path,
101    storage: &Path,
102    depth: usize,
103    out: &mut Vec<Q42VolumeListItem>,
104) -> Result<(), String> {
105    if depth > 6 {
106        return Ok(());
107    }
108    let entries = match fs::read_dir(dir) {
109        Ok(entries) => entries,
110        Err(_) => return Ok(()),
111    };
112    for entry in entries.filter_map(Result::ok) {
113        let path = entry.path();
114        if path.is_dir() {
115            if depth == 0 && dir == storage {
116                continue;
117            }
118            scan_dir(&path, storage, depth + 1, out)?;
119            continue;
120        }
121        let Some(name) = path.file_name().and_then(|n| n.to_str()) else {
122            continue;
123        };
124        if !name.ends_with(".q42") || name.ends_with(".c.q42") {
125            continue;
126        }
127        out.push(item_from_path(&path, storage));
128    }
129    Ok(())
130}
131
132fn item_from_path(path: &Path, storage: &Path) -> Q42VolumeListItem {
133    let display_name = path
134        .file_name()
135        .and_then(|n| n.to_str())
136        .unwrap_or("volume.q42")
137        .to_string();
138    let relative = path
139        .strip_prefix(storage)
140        .map(|p| p.to_string_lossy().replace('\\', "/"))
141        .unwrap_or_else(|_| path.display().to_string());
142    let file_bytes = fs::metadata(path).map(|m| m.len()).unwrap_or(0);
143    match Q42InspectReport::from_path(path) {
144        Ok(report) => Q42VolumeListItem {
145            path: path.display().to_string(),
146            relative,
147            display_name,
148            file_bytes: report.file_bytes,
149            version: report.version,
150            flags: report.flags,
151            flag_names: report.flag_names.iter().map(|s| (*s).to_string()).collect(),
152            block_count: report.block_count,
153            lexicon_entries: report.lexicon_entries,
154            has_bidx: report.has_bidx,
155            has_field_ranges: report.has_field_ranges,
156            has_field_postings: report.has_field_postings,
157            is_volume_root: report.is_volume_root,
158            publication_class: report.publication_class,
159            publication_transport: report.publication_transport,
160            may_public_magnet: report.may_public_magnet,
161            open_error: None,
162        },
163        Err(err) => Q42VolumeListItem {
164            path: path.display().to_string(),
165            relative,
166            display_name,
167            file_bytes,
168            version: 0,
169            flags: 0,
170            flag_names: Vec::new(),
171            block_count: 0,
172            lexicon_entries: None,
173            has_bidx: false,
174            has_field_ranges: false,
175            has_field_postings: false,
176            is_volume_root: false,
177            publication_class: "unreadable".into(),
178            publication_transport: String::new(),
179            may_public_magnet: false,
180            open_error: Some(err.to_string()),
181        },
182    }
183}
184
185/// Inspects a q42 volume.
186pub fn inspect_q42_volume(path: String) -> Result<Q42InspectReport, String> {
187    let path = require_q42_file(&path)?;
188    Q42InspectReport::from_path(&path).map_err(|e| e.to_string())
189}
190
191/// Verifies a q42 volume.
192pub fn verify_q42_volume(
193    path: String,
194    level: Option<String>,
195) -> Result<Q42VerifySetReport, String> {
196    let path = require_q42_file(&path)?;
197    let level = match level.as_deref() {
198        None | Some("") => VerifyLevel::Full,
199        Some(raw) => VerifyLevel::parse(raw).map_err(|e| e.to_string())?,
200    };
201    verify_volume_set_from_root(&path, level).map_err(|e| e.to_string())
202}
203
204/// Magnet link for a q42 volume.
205pub fn magnet_q42_volume(path: String) -> Result<Q42MagnetResult, String> {
206    let path = require_q42_file(&path)?;
207    let webseed = Some("http://127.0.0.1:4242/torrent/webseed/{hash}");
208    if is_unified_volume(&path).ok() == Some(true) {
209        if let Ok(set) = Q42VolumeSetMagnets::for_root(&path, webseed) {
210            return Ok(Q42MagnetResult {
211                root: set.root,
212                children: set.children,
213            });
214        }
215    }
216    let root = Q42Magnet::for_path(&path, webseed).map_err(|e| e.to_string())?;
217    Ok(Q42MagnetResult {
218        root,
219        children: Vec::new(),
220    })
221}
222
223/// Compacts a q42 volume.
224pub fn compact_q42_volume(path: String) -> Result<Q42CompactResult, String> {
225    let path = require_q42_file(&path)?;
226    let stem = path
227        .file_stem()
228        .and_then(|s| s.to_str())
229        .unwrap_or("volume");
230    let out_dir = path
231        .parent()
232        .unwrap_or_else(|| Path::new("."))
233        .join(format!("{stem}-compacted"));
234    let output = compact_volume_set(&path, &out_dir).map_err(|e| e.to_string())?;
235    Ok(Q42CompactResult {
236        source: path.display().to_string(),
237        output: output.display().to_string(),
238    })
239}
240
241fn require_q42_file(raw: &str) -> Result<PathBuf, String> {
242    let path = PathBuf::from(raw.trim());
243    if !path.is_file() {
244        return Err(format!("Q42 file not found: {}", path.display()));
245    }
246    let name = path
247        .file_name()
248        .and_then(|n| n.to_str())
249        .unwrap_or_default();
250    if !name.ends_with(".q42") {
251        return Err("path must be a .q42 volume".into());
252    }
253    Ok(path)
254}
255
256#[cfg(test)]
257mod tests {
258    use super::*;
259    use qualia_core_db::q42_volume::write_sorted_quins_volume;
260    use qualia_core_db::NQuin;
261
262    fn quin(object: u64) -> NQuin {
263        NQuin {
264            subject: 1,
265            predicate: 2,
266            object,
267            context: 3,
268            metadata: 0,
269            parity: NQuin::calculate_parity(1, 2, object, 3, 0),
270        }
271    }
272
273    #[test]
274    fn list_inspect_verify_and_compact_a_vault_volume() {
275        let dir = tempfile::tempdir().unwrap();
276        let index = dir.path().join("Index");
277        fs::create_dir_all(&index).unwrap();
278        let path = index.join("session.q42");
279        write_sorted_quins_volume(&path, &[quin(9), quin(1)]).unwrap();
280
281        let workspace = list_q42_volumes_under(dir.path()).unwrap();
282        assert_eq!(workspace.volume_count, 1);
283        assert_eq!(workspace.volumes[0].display_name, "session.q42");
284        assert_eq!(workspace.volumes[0].block_count, 1);
285        assert!(workspace.volumes[0].has_field_postings);
286        assert!(workspace.volumes[0].open_error.is_none());
287
288        let inspect = inspect_q42_volume(path.display().to_string()).unwrap();
289        assert_eq!(inspect.version, 4);
290        assert_eq!(inspect.block_count, 1);
291
292        let verify = verify_q42_volume(path.display().to_string(), Some("full".into())).unwrap();
293        assert_eq!(verify.members.len(), 1);
294        assert_ne!(
295            verify.overall,
296            qualia_core_db::q42_volume::CheckStatus::Fail,
297            "{}",
298            verify.to_text()
299        );
300        assert!(verify.members[0].checks.iter().any(|check| {
301            check.name == "blocks.decode"
302                && check.status == qualia_core_db::q42_volume::CheckStatus::Pass
303        }));
304
305        let compacted = compact_q42_volume(path.display().to_string()).unwrap();
306        assert!(PathBuf::from(&compacted.output).is_file());
307        let again = verify_q42_volume(compacted.output, None).unwrap();
308        assert_ne!(
309            again.overall,
310            qualia_core_db::q42_volume::CheckStatus::Fail,
311            "{}",
312            again.to_text()
313        );
314    }
315
316    #[test]
317    fn unmarked_personal_volume_cannot_mint_a_public_magnet() {
318        let dir = tempfile::tempdir().unwrap();
319        let path = dir.path().join("chat.q42");
320        write_sorted_quins_volume(&path, &[quin(4)]).unwrap();
321        let err = magnet_q42_volume(path.display().to_string()).unwrap_err();
322        assert!(
323            err.to_ascii_lowercase().contains("permissive commons")
324                || err.to_ascii_lowercase().contains("denied")
325                || err.to_ascii_lowercase().contains("unmarked"),
326            "deny text was: {err}"
327        );
328    }
329}