Skip to main content

rskit_bench/
run_storage.rs

1//! Storage trait and file-based implementation for bench results.
2
3use crate::result::{BenchRunResult, BenchRunSummary};
4use rskit_errors::{AppError, AppResult, ErrorCode};
5use rskit_fs::{
6    confine_path,
7    sync_io::{dir, file},
8};
9use std::path::{Path, PathBuf};
10
11/// Options for listing stored results.
12pub struct ListOptions {
13    pub limit: usize,
14    pub tag: Option<String>,
15    pub dataset: Option<String>,
16}
17
18impl Default for ListOptions {
19    fn default() -> Self {
20        Self {
21            limit: 100,
22            tag: None,
23            dataset: None,
24        }
25    }
26}
27
28impl ListOptions {
29    #[must_use]
30    pub fn with_limit(mut self, n: usize) -> Self {
31        self.limit = n;
32        self
33    }
34
35    #[must_use]
36    pub fn with_tag(mut self, tag: impl Into<String>) -> Self {
37        self.tag = Some(tag.into());
38        self
39    }
40
41    #[must_use]
42    pub fn with_dataset(mut self, dataset: impl Into<String>) -> Self {
43        self.dataset = Some(dataset.into());
44        self
45    }
46}
47
48/// Abstraction for storing/retrieving benchmark results.
49pub trait RunStorage: Send + Sync {
50    fn save(&self, result: &BenchRunResult) -> AppResult<String>;
51    fn load(&self, run_id: &str) -> AppResult<BenchRunResult>;
52    fn latest(&self) -> AppResult<BenchRunResult>;
53    fn list(&self, opts: ListOptions) -> AppResult<Vec<BenchRunSummary>>;
54}
55
56/// File-based storage implementation.
57pub struct FileRunStorage {
58    dir: PathBuf,
59}
60
61impl FileRunStorage {
62    pub fn new(dir: impl Into<PathBuf>) -> Self {
63        Self { dir: dir.into() }
64    }
65}
66
67impl RunStorage for FileRunStorage {
68    fn save(&self, result: &BenchRunResult) -> AppResult<String> {
69        dir::create_all(&self.dir)?;
70        let path = run_result_path(&self.dir, &result.id)?;
71        let json = serde_json::to_string_pretty(result)
72            .map_err(|e| AppError::new(ErrorCode::Internal, format!("serialize: {e}")))?;
73        file::write(&path, json)?;
74        Ok(result.id.clone())
75    }
76
77    fn load(&self, run_id: &str) -> AppResult<BenchRunResult> {
78        let path = run_result_path(&self.dir, run_id)?;
79        let content = file::read_string(&path).map_err(|e| {
80            AppError::new(
81                ErrorCode::NotFound,
82                format!("Run not found: {run_id} ({e})"),
83            )
84        })?;
85        serde_json::from_str(&content)
86            .map_err(|e| AppError::new(ErrorCode::Internal, format!("deserialize: {e}")))
87    }
88
89    fn latest(&self) -> AppResult<BenchRunResult> {
90        let summaries = self.list(ListOptions::default().with_limit(1))?;
91        if summaries.is_empty() {
92            return Err(AppError::new(ErrorCode::NotFound, "No runs found"));
93        }
94        self.load(&summaries[0].id)
95    }
96
97    fn list(&self, opts: ListOptions) -> AppResult<Vec<BenchRunSummary>> {
98        if !dir::exists(&self.dir)? {
99            return Ok(Vec::new());
100        }
101        let mut summaries = Vec::new();
102        for entry in dir::list(&self.dir)? {
103            if !entry.is_file || entry.path.extension().is_none_or(|e| e != "json") {
104                continue;
105            }
106            let Ok(content) = file::read_string(&entry.path) else {
107                tracing::warn!(path = %entry.path.display(), "skipping unreadable bench run result");
108                continue;
109            };
110            let Ok(result) = serde_json::from_str::<BenchRunResult>(&content) else {
111                tracing::warn!(path = %entry.path.display(), "skipping invalid bench run result");
112                continue;
113            };
114            if let Some(ref tag) = opts.tag
115                && result.tag != *tag
116            {
117                continue;
118            }
119            if let Some(ref ds) = opts.dataset
120                && result.dataset.name != *ds
121            {
122                continue;
123            }
124            let f1 = result
125                .metrics
126                .iter()
127                .find_map(|m| m.values.get("f1").copied())
128                .unwrap_or(0.0);
129            summaries.push(BenchRunSummary {
130                id: result.id,
131                timestamp: result.timestamp,
132                tag: result.tag,
133                dataset: result.dataset.name,
134                f1,
135            });
136        }
137        summaries.sort_by(|a, b| b.timestamp.cmp(&a.timestamp));
138        if opts.limit > 0 && summaries.len() > opts.limit {
139            summaries.truncate(opts.limit);
140        }
141        Ok(summaries)
142    }
143}
144
145fn run_result_path(root: &Path, run_id: &str) -> AppResult<PathBuf> {
146    if run_id.contains(['/', '\\']) {
147        return Err(AppError::new(
148            ErrorCode::InvalidInput,
149            format!("run id must not contain path separators: {run_id}"),
150        ));
151    }
152    confine_path(root, Path::new(&format!("{run_id}.json")))
153}
154
155#[cfg(test)]
156mod tests {
157    use std::collections::HashMap;
158
159    use crate::result::{BenchRunResult, DatasetInfo};
160
161    use super::{FileRunStorage, ListOptions, RunStorage};
162
163    fn result(id: &str) -> BenchRunResult {
164        BenchRunResult {
165            id: id.to_string(),
166            schema: crate::schema::schema_url(),
167            version: crate::schema::version(),
168            timestamp: "2026-01-01T00:00:00Z".to_string(),
169            tag: "main".to_string(),
170            duration_ms: 10,
171            dataset: DatasetInfo {
172                name: "dataset".to_string(),
173                version: "1".to_string(),
174                sample_count: 1,
175                label_distribution: HashMap::new(),
176            },
177            metrics: Vec::new(),
178            branches: HashMap::new(),
179            samples: Vec::new(),
180            curves: HashMap::new(),
181        }
182    }
183
184    #[test]
185    fn list_skips_invalid_run_result_files() {
186        let dir = tempfile::tempdir().expect("tempdir");
187        let storage = FileRunStorage::new(dir.path());
188
189        storage.save(&result("valid")).expect("save valid result");
190        std::fs::write(dir.path().join("partial.json"), "{").expect("write invalid json");
191
192        let summaries = storage
193            .list(ListOptions::default())
194            .expect("list should skip invalid files");
195
196        assert_eq!(summaries.len(), 1);
197        assert_eq!(summaries[0].id, "valid");
198    }
199
200    #[test]
201    fn save_rejects_run_ids_with_path_separators() {
202        let dir = tempfile::tempdir().expect("tempdir");
203        let storage = FileRunStorage::new(dir.path());
204        let mut result = result("../escaped");
205
206        let error = storage
207            .save(&result)
208            .expect_err("path separator should fail");
209
210        assert_eq!(error.code(), rskit_errors::ErrorCode::InvalidInput);
211        result.id = "nested/path".to_string();
212        let error = storage.save(&result).expect_err("nested path should fail");
213        assert_eq!(error.code(), rskit_errors::ErrorCode::InvalidInput);
214    }
215}