exarch_core/
report.rs

1//! Extraction operation reporting.
2
3use std::path::Path;
4use std::time::Duration;
5
6/// Report of an archive extraction operation.
7///
8/// Contains statistics and metadata about the extraction process.
9#[derive(Debug, Clone, Default)]
10pub struct ExtractionReport {
11    /// Number of files successfully extracted.
12    pub files_extracted: usize,
13
14    /// Number of directories created.
15    pub directories_created: usize,
16
17    /// Number of symlinks created.
18    pub symlinks_created: usize,
19
20    /// Total bytes written to disk.
21    pub bytes_written: u64,
22
23    /// Duration of the extraction operation.
24    pub duration: Duration,
25
26    /// Number of files skipped due to security checks.
27    pub files_skipped: usize,
28
29    /// Warnings generated during extraction.
30    pub warnings: Vec<String>,
31}
32
33impl ExtractionReport {
34    /// Creates a new empty extraction report.
35    #[must_use]
36    pub fn new() -> Self {
37        Self::default()
38    }
39
40    /// Adds a warning message to the report.
41    pub fn add_warning(&mut self, message: String) {
42        self.warnings.push(message);
43    }
44
45    /// Returns total number of items processed.
46    #[must_use]
47    pub fn total_items(&self) -> usize {
48        self.files_extracted + self.directories_created + self.symlinks_created
49    }
50
51    /// Returns whether any warnings were generated.
52    #[must_use]
53    pub fn has_warnings(&self) -> bool {
54        !self.warnings.is_empty()
55    }
56}
57
58/// Callback trait for progress reporting during archive operations.
59///
60/// Implement this trait to receive progress updates during extraction or
61/// creation. The trait requires `Send` to allow use in multi-threaded contexts.
62///
63/// # Examples
64///
65/// ```
66/// use exarch_core::ProgressCallback;
67/// use std::path::Path;
68///
69/// struct SimpleProgress;
70///
71/// impl ProgressCallback for SimpleProgress {
72///     fn on_entry_start(&mut self, path: &Path, total: usize, current: usize) {
73///         println!("Processing {}/{}: {}", current, total, path.display());
74///     }
75///
76///     fn on_bytes_written(&mut self, bytes: u64) {
77///         // Track bytes written
78///     }
79///
80///     fn on_entry_complete(&mut self, path: &Path) {
81///         println!("Completed: {}", path.display());
82///     }
83///
84///     fn on_complete(&mut self) {
85///         println!("Operation complete");
86///     }
87/// }
88/// ```
89pub trait ProgressCallback: Send {
90    /// Called when starting to process an entry.
91    ///
92    /// # Arguments
93    ///
94    /// * `path` - Path of the entry being processed
95    /// * `total` - Total number of entries in the archive
96    /// * `current` - Current entry number (1-indexed)
97    fn on_entry_start(&mut self, path: &Path, total: usize, current: usize);
98
99    /// Called when bytes are written during extraction or read during creation.
100    ///
101    /// Granularity is per-entry: called once after the full entry is written.
102    /// Partial writes on failure are not reported. Not called for entries that
103    /// produce no output (directories, skipped entries).
104    ///
105    /// # Arguments
106    ///
107    /// * `bytes` - Number of bytes written/read in this update
108    fn on_bytes_written(&mut self, bytes: u64);
109
110    /// Called when an entry has been completely processed.
111    ///
112    /// Always called after [`on_entry_start`](Self::on_entry_start) for the
113    /// same entry, including when extraction of that entry fails. Callers can
114    /// rely on this pairing for cleanup or progress accounting.
115    ///
116    /// # Arguments
117    ///
118    /// * `path` - Path of the entry that was completed
119    fn on_entry_complete(&mut self, path: &Path);
120
121    /// Called when the entire operation completes successfully.
122    ///
123    /// Not called if the operation fails or results in a partial extraction.
124    /// Implementors must not rely on this method for cleanup — use `Drop`
125    /// instead.
126    fn on_complete(&mut self);
127}
128
129/// No-op implementation of `ProgressCallback` that does nothing.
130///
131/// Use this when you don't need progress reporting but the API requires
132/// a callback implementation.
133#[derive(Debug, Default)]
134pub struct NoopProgress;
135
136impl ProgressCallback for NoopProgress {
137    fn on_entry_start(&mut self, _path: &Path, _total: usize, _current: usize) {}
138
139    fn on_bytes_written(&mut self, _bytes: u64) {}
140
141    fn on_entry_complete(&mut self, _path: &Path) {}
142
143    fn on_complete(&mut self) {}
144}
145
146#[cfg(test)]
147mod tests {
148    use super::*;
149
150    #[test]
151    fn test_new_report() {
152        let report = ExtractionReport::new();
153        assert_eq!(report.files_extracted, 0);
154        assert_eq!(report.directories_created, 0);
155        assert_eq!(report.bytes_written, 0);
156        assert!(!report.has_warnings());
157    }
158
159    #[test]
160    fn test_add_warning() {
161        let mut report = ExtractionReport::new();
162        report.add_warning("Test warning".to_string());
163        assert!(report.has_warnings());
164        assert_eq!(report.warnings.len(), 1);
165    }
166
167    #[test]
168    fn test_total_items() {
169        let mut report = ExtractionReport::new();
170        report.files_extracted = 10;
171        report.directories_created = 5;
172        report.symlinks_created = 2;
173        assert_eq!(report.total_items(), 17);
174    }
175}
exarch_core/report.rs

exarch_core/
report.rs
