Skip to main content

shaul_core/
finalizer.rs

1use std::path::{Path, PathBuf};
2use std::sync::{Arc, OnceLock};
3
4use async_trait::async_trait;
5
6use crate::archive::ExtractorRegistry;
7use crate::backend::FileOutcome;
8use crate::cache::ContentCache;
9use crate::checksum::compute_file_checksum;
10use crate::config::ResolvedOptions;
11use crate::error::{Error, Result};
12use crate::event::{EventKind, EventSink};
13use crate::task::{TaskId, VerifyMode};
14use crate::telemetry::metrics;
15
16/// Outcome accumulated by a finalizer or by a whole pipeline.
17#[derive(Clone, Debug, Default)]
18pub struct FinalizeResult {
19    /// Whether the file's checksum was verified.
20    pub checksum_verified: bool,
21    /// Directory the archive was extracted into, if extraction ran.
22    pub extracted_to: Option<PathBuf>,
23}
24
25/// Read-only inputs available to each finalizer.
26pub struct FinalizeContext<'a> {
27    /// Task that produced the file.
28    pub task_id: TaskId,
29    /// Directory the task was asked to download into.
30    pub destination: &'a Path,
31    /// The completed file and how it was written.
32    pub file: &'a FileOutcome,
33    /// Resolved options controlling verification and extraction.
34    pub options: &'a ResolvedOptions,
35    /// Sink for verification, extraction and warning events.
36    pub events: &'a EventSink,
37}
38
39/// A single post-download step, run once all bytes have been written.
40#[async_trait]
41pub trait Finalizer: Send + Sync {
42    /// Stable name used in diagnostics.
43    fn name(&self) -> &'static str;
44    /// Runs this step for the completed file.
45    async fn finalize(&self, context: &FinalizeContext<'_>) -> Result<FinalizeResult>;
46}
47
48/// Fixed order: verify before extraction. A corrupt archive is never
49/// unpacked.
50pub struct FinalizerPipeline {
51    finalizers: Vec<Arc<dyn Finalizer>>,
52}
53
54impl Default for FinalizerPipeline {
55    fn default() -> Self {
56        Self {
57            finalizers: vec![Arc::new(VerifyFinalizer), Arc::new(ExtractFinalizer)],
58        }
59    }
60}
61
62impl FinalizerPipeline {
63    /// Builds a pipeline that runs the given finalizers in order.
64    pub fn new(finalizers: Vec<Arc<dyn Finalizer>>) -> Self {
65        Self { finalizers }
66    }
67
68    /// Builds the default verification step plus extraction through a custom
69    /// [`ExtractorRegistry`].
70    pub fn with_extractor_registry(registry: Arc<ExtractorRegistry>) -> Self {
71        Self::new(vec![
72            Arc::new(VerifyFinalizer),
73            Arc::new(ExtractorFinalizer::new(registry)),
74        ])
75    }
76
77    /// Runs every finalizer in order and merges their results, stopping at the
78    /// first error.
79    pub async fn run(&self, context: &FinalizeContext<'_>) -> Result<FinalizeResult> {
80        let mut result = FinalizeResult::default();
81        for finalizer in &self.finalizers {
82            let step = finalizer.finalize(context).await?;
83            result.checksum_verified |= step.checksum_verified;
84            if step.extracted_to.is_some() {
85                result.extracted_to = step.extracted_to;
86            }
87        }
88        Ok(result)
89    }
90}
91
92/// Verifies the downloaded file against the expected checksum, honoring
93/// [`VerifyMode`].
94pub struct VerifyFinalizer;
95
96#[async_trait]
97impl Finalizer for VerifyFinalizer {
98    fn name(&self) -> &'static str {
99        "verify"
100    }
101
102    async fn finalize(&self, context: &FinalizeContext<'_>) -> Result<FinalizeResult> {
103        if context.file.checksum_verified {
104            return Ok(FinalizeResult {
105                checksum_verified: true,
106                extracted_to: None,
107            });
108        }
109        let expected = context
110            .options
111            .checksum
112            .clone()
113            .or_else(|| context.file.checksum.clone());
114
115        match (context.options.verify, expected) {
116            (VerifyMode::Disabled, _) => Ok(FinalizeResult::default()),
117            (VerifyMode::Require, None) => Err(Error::ChecksumMissing),
118            (VerifyMode::Auto, None) => Ok(FinalizeResult::default()),
119            (_, Some(expected)) => {
120                context.events.emit(EventKind::VerificationStarted {
121                    task_id: context.task_id,
122                    file: context.file.relative_path.clone(),
123                    algorithm: expected.algorithm.to_string(),
124                    expected: expected.hex.clone(),
125                });
126                let actual =
127                    compute_file_checksum(context.file.path.clone(), expected.algorithm).await?;
128                let ok = expected.matches(&actual);
129                context.events.emit(EventKind::VerificationCompleted {
130                    task_id: context.task_id,
131                    file: context.file.relative_path.clone(),
132                    ok,
133                    actual: actual.hex.clone(),
134                });
135                if !ok {
136                    return Err(Error::Verification {
137                        expected: expected.hex,
138                        actual: actual.hex,
139                    });
140                }
141                cache_verified_file(context, &expected).await;
142                Ok(FinalizeResult {
143                    checksum_verified: true,
144                    extracted_to: None,
145                })
146            }
147        }
148    }
149}
150
151async fn cache_verified_file(context: &FinalizeContext<'_>, checksum: &crate::checksum::Checksum) {
152    if !context.options.content_cache {
153        return;
154    }
155    let cache = match ContentCache::new(&context.options.content_cache_dir) {
156        Ok(cache) => cache,
157        Err(error) => {
158            context.events.emit(EventKind::Warning {
159                task_id: Some(context.task_id),
160                message: format!("could not open content cache: {error}"),
161            });
162            return;
163        }
164    };
165    match cache
166        .insert(checksum, &context.file.path, context.file.size)
167        .await
168    {
169        Ok(_) => context
170            .events
171            .telemetry()
172            .counter(metrics::CACHE_INSERTS, 1, &[]),
173        Err(error) => context.events.emit(EventKind::Warning {
174            task_id: Some(context.task_id),
175            message: format!("could not populate content cache: {error}"),
176        }),
177    }
178}
179
180/// Extracts supported archives according to the resolved extraction options
181/// using the built-in [`ExtractorRegistry::default`] formats.
182pub struct ExtractFinalizer;
183
184#[async_trait]
185impl Finalizer for ExtractFinalizer {
186    fn name(&self) -> &'static str {
187        "extract"
188    }
189
190    async fn finalize(&self, context: &FinalizeContext<'_>) -> Result<FinalizeResult> {
191        static REGISTRY: OnceLock<Arc<ExtractorRegistry>> = OnceLock::new();
192        let registry = REGISTRY
193            .get_or_init(|| Arc::new(ExtractorRegistry::default()))
194            .clone();
195        run_extraction(context, registry).await
196    }
197}
198
199/// Extracts archives with a caller-supplied [`ExtractorRegistry`].
200pub struct ExtractorFinalizer {
201    registry: Arc<ExtractorRegistry>,
202}
203
204impl ExtractorFinalizer {
205    /// Creates a finalizer that chooses extractors from `registry`.
206    pub fn new(registry: Arc<ExtractorRegistry>) -> Self {
207        Self { registry }
208    }
209}
210
211#[async_trait]
212impl Finalizer for ExtractorFinalizer {
213    fn name(&self) -> &'static str {
214        "extract"
215    }
216
217    async fn finalize(&self, context: &FinalizeContext<'_>) -> Result<FinalizeResult> {
218        run_extraction(context, self.registry.clone()).await
219    }
220}
221
222async fn run_extraction(
223    context: &FinalizeContext<'_>,
224    registry: Arc<ExtractorRegistry>,
225) -> Result<FinalizeResult> {
226    if !context.options.extract {
227        return Ok(FinalizeResult::default());
228    }
229    if !registry.supports(&context.file.path)? {
230        context.events.emit(EventKind::Warning {
231            task_id: Some(context.task_id),
232            message: format!(
233                "extraction requested but {} is not a supported archive",
234                context.file.path.display()
235            ),
236        });
237        return Ok(FinalizeResult::default());
238    }
239
240    let extract_root = context
241        .options
242        .extract_dir
243        .clone()
244        .unwrap_or_else(|| context.destination.to_path_buf());
245    context.events.emit(EventKind::ExtractionStarted {
246        task_id: context.task_id,
247        file: context.file.relative_path.clone(),
248        target: extract_root.clone(),
249    });
250
251    let archive_path = context.file.path.clone();
252    let extract_root_for_task = extract_root.clone();
253    let overwrite = context.options.overwrite;
254    let report = tokio::task::spawn_blocking(move || {
255        registry.extract(&archive_path, &extract_root_for_task, overwrite)
256    })
257    .await
258    .map_err(|error| Error::Extraction(format!("extract task failed: {error}")))??;
259
260    let Some(report) = report else {
261        context.events.emit(EventKind::Warning {
262            task_id: Some(context.task_id),
263            message: format!(
264                "extraction requested but {} is no longer supported",
265                context.file.path.display()
266            ),
267        });
268        return Ok(FinalizeResult::default());
269    };
270
271    for warning in &report.warnings {
272        context.events.emit(EventKind::Warning {
273            task_id: Some(context.task_id),
274            message: warning.clone(),
275        });
276    }
277
278    if context.options.delete_archive
279        && let Err(error) = tokio::fs::remove_file(&context.file.path).await
280    {
281        context.events.emit(EventKind::Warning {
282            task_id: Some(context.task_id),
283            message: format!(
284                "could not delete archive {}: {error}",
285                context.file.path.display()
286            ),
287        });
288    }
289
290    context.events.emit(EventKind::ExtractionCompleted {
291        task_id: context.task_id,
292        file: context.file.relative_path.clone(),
293        target: report.target.clone(),
294        files_extracted: report.files_extracted,
295    });
296
297    Ok(FinalizeResult {
298        checksum_verified: false,
299        extracted_to: Some(report.target),
300    })
301}
302
303#[cfg(test)]
304mod tests {
305    use super::*;
306    use crate::archive::{ArchiveExtractor, ExtractReport, ExtractorRequest};
307    use crate::config::Config;
308    use crate::task::TaskOptions;
309
310    struct DemoExtractor;
311
312    impl ArchiveExtractor for DemoExtractor {
313        fn name(&self) -> &'static str {
314            "demo"
315        }
316
317        fn supports(&self, path: &Path) -> Result<bool> {
318            Ok(path.extension().and_then(|extension| extension.to_str()) == Some("demo"))
319        }
320
321        fn extract(&self, request: &ExtractorRequest<'_>) -> Result<ExtractReport> {
322            let target = request.extract_root.join("demo-out");
323            std::fs::create_dir_all(&target)?;
324            std::fs::write(target.join("hello.txt"), b"hello")?;
325            Ok(ExtractReport {
326                target,
327                files_extracted: 1,
328                warnings: Vec::new(),
329            })
330        }
331    }
332
333    #[tokio::test]
334    async fn extractor_finalizer_uses_the_registry() {
335        let dir = tempfile::tempdir().unwrap();
336        let archive = dir.path().join("payload.demo");
337        std::fs::write(&archive, b"payload").unwrap();
338        let destination = dir.path().join("dest");
339        std::fs::create_dir_all(&destination).unwrap();
340
341        let task_options = TaskOptions {
342            extract: Some(true),
343            ..TaskOptions::default()
344        };
345        let options = Config::default()
346            .resolve(&destination, &task_options)
347            .unwrap();
348        let (events, _receiver) = EventSink::channel(16);
349        let file = FileOutcome::new(archive, "payload.demo".to_string(), 7, None, false);
350        let context = FinalizeContext {
351            task_id: uuid::Uuid::new_v4(),
352            destination: &destination,
353            file: &file,
354            options: &options,
355            events: &events,
356        };
357
358        let registry = ExtractorRegistry::default().with(Arc::new(DemoExtractor));
359        let result = ExtractorFinalizer::new(Arc::new(registry))
360            .finalize(&context)
361            .await
362            .unwrap();
363
364        let extracted = result.extracted_to.expect("extracted path");
365        assert_eq!(extracted, destination.join("demo-out"));
366        assert_eq!(
367            std::fs::read_to_string(extracted.join("hello.txt")).unwrap(),
368            "hello"
369        );
370    }
371}