Skip to main content

resopt/
batch.rs

1//! Policy-driven application of many reviewed candidates.
2//!
3//! Every file is applied as its own journaled transaction, so a batch can be
4//! cancelled or interrupted at any point: finished files stay individually
5//! restorable and unfinished ones are untouched.
6use crate::{
7    ImageCandidate, ResourceAnalysis,
8    analysis::WARNINGS,
9    filesystem::hash,
10    review::{Approvals, Review},
11};
12use anyhow::{Result, ensure};
13use serde::{Deserialize, Serialize};
14use std::{
15    path::PathBuf,
16    sync::{
17        Mutex,
18        atomic::{AtomicBool, Ordering},
19    },
20};
21
22/// What a batch may do. The defaults apply only verified lossless,
23/// same-format candidates.
24#[derive(Debug, Clone, Serialize, Deserialize)]
25#[serde(default, deny_unknown_fields)]
26pub struct BatchPolicy {
27    pub lossless: bool,
28    pub lossy: bool,
29    /// Allow conversions that change the file format (and migrate references).
30    pub cross_format: bool,
31    /// Extra floor for lossy candidates, on top of the analysis threshold.
32    pub min_score: Option<f64>,
33    /// Target formats to allow; empty allows every format.
34    pub formats: Vec<String>,
35    /// Warning kinds accepted for the whole batch. Empty skips warning candidates.
36    pub accept_warnings: Vec<String>,
37    /// Restrict the batch to these resource indexes (e.g. the filtered view).
38    pub resources: Option<Vec<usize>>,
39}
40
41impl Default for BatchPolicy {
42    fn default() -> Self {
43        Self {
44            lossless: true,
45            lossy: false,
46            cross_format: false,
47            min_score: None,
48            formats: vec![],
49            accept_warnings: vec![],
50            resources: None,
51        }
52    }
53}
54
55impl BatchPolicy {
56    pub fn validate(&self) -> Result<()> {
57        ensure!(
58            self.lossless || self.lossy,
59            "batch policy selects neither lossless nor lossy candidates"
60        );
61        ensure!(
62            self.min_score
63                .is_none_or(|s| s.is_finite() && (0.0..=100.0).contains(&s)),
64            "min_score must be 0..=100"
65        );
66        for warning in &self.accept_warnings {
67            ensure!(
68                WARNINGS.contains(&warning.as_str()),
69                "unknown warning kind: {warning}"
70            );
71        }
72        ensure!(
73            self.accept_warnings.is_empty() || self.lossy,
74            "warning candidates are lossy; enable lossy candidates to accept warnings"
75        );
76        Ok(())
77    }
78
79    fn approvals(&self) -> Approvals {
80        Approvals {
81            lossy: self.lossy,
82            warnings: self.accept_warnings.clone(),
83        }
84    }
85
86    fn allows(&self, resource: &ResourceAnalysis, candidate: &ImageCandidate) -> bool {
87        let accepted_warning = candidate.is_warning()
88            && candidate
89                .required_warnings()
90                .iter()
91                .all(|w| self.accept_warnings.contains(w));
92        let crossing =
93            candidate.format != resource.resource.format || resource.resource.extension_mismatch;
94        candidate.artifact.is_some()
95            && (candidate.valid || accepted_warning)
96            && (if candidate.lossy {
97                self.lossy
98            } else {
99                self.lossless
100            })
101            && (self.cross_format || !crossing)
102            && (!crossing || resource.resource.format_lock.is_none())
103            // Asset files are opened by path, and paths are often built at
104            // runtime. Renaming them is a per-file decision with its own
105            // reference preview, never a batch action.
106            && !(crossing
107                && resource
108                    .resource
109                    .android
110                    .as_ref()
111                    .is_some_and(|a| a.area == "assets"))
112            && (self.formats.is_empty() || self.formats.contains(&candidate.format))
113            && (!candidate.lossy
114                || self.min_score.is_none_or(|floor| {
115                    candidate
116                        .difference
117                        .as_ref()
118                        .and_then(|d| d.ssimulacra2)
119                        .is_some_and(|score| score >= floor)
120                }))
121    }
122}
123
124#[derive(Debug, Clone, Serialize)]
125pub struct BatchItem {
126    pub resource: usize,
127    pub candidate: usize,
128    pub path: PathBuf,
129    pub format: String,
130    pub quality: Option<u8>,
131    pub lossy: bool,
132    pub warning: Option<String>,
133    pub original_bytes: u64,
134    pub savings_bytes: u64,
135}
136
137#[derive(Debug, Clone, Serialize)]
138pub struct BatchPlan {
139    pub policy: BatchPolicy,
140    pub items: Vec<BatchItem>,
141    pub savings_bytes: u64,
142    pub lossy_items: usize,
143    pub warning_items: usize,
144    pub cross_format_items: usize,
145    /// Must accompany the apply request so the confirmed plan is the one run.
146    pub token: String,
147}
148
149/// Choose, per resource, the smallest candidate the policy allows. Resources
150/// with an existing operation are left alone.
151pub(crate) fn plan(review: &Review, policy: &BatchPolicy) -> Result<BatchPlan> {
152    policy.validate()?;
153    let states = review.states();
154    let missing = review.missing_resources()?;
155    let mut items = Vec::new();
156    for (index, resource) in review.report.resources.iter().enumerate() {
157        if policy
158            .resources
159            .as_ref()
160            .is_some_and(|r| !r.contains(&index))
161            || missing.binary_search(&index).is_ok()
162            || resource.status != "candidates_available"
163            || resource.resource.conversion_exclusion.is_some()
164            || states
165                .get(index.to_string())
166                .is_some_and(|s| s["state"] != "original")
167        {
168            continue;
169        }
170        let Some((candidate_index, candidate)) = resource
171            .candidates
172            .iter()
173            .enumerate()
174            .filter(|(_, c)| policy.allows(resource, c))
175            .min_by_key(|(_, c)| c.bytes)
176        else {
177            continue;
178        };
179        items.push(BatchItem {
180            resource: index,
181            candidate: candidate_index,
182            path: resource.resource.path.clone(),
183            format: candidate.format.clone(),
184            quality: candidate.quality,
185            lossy: candidate.lossy,
186            warning: candidate
187                .rejection
188                .clone()
189                .filter(|_| candidate.is_warning()),
190            original_bytes: resource.resource.bytes,
191            savings_bytes: candidate.savings_bytes,
192        });
193    }
194    // Largest savings first: a cancelled batch has already done the most useful work.
195    items.sort_by(|a, b| {
196        b.savings_bytes
197            .cmp(&a.savings_bytes)
198            .then(a.resource.cmp(&b.resource))
199    });
200    let selection: Vec<_> = items.iter().map(|i| (i.resource, i.candidate)).collect();
201    let token = hash(&serde_json::to_vec(&(policy, &selection))?);
202    Ok(BatchPlan {
203        policy: policy.clone(),
204        savings_bytes: items.iter().map(|i| i.savings_bytes).sum(),
205        lossy_items: items.iter().filter(|i| i.lossy).count(),
206        warning_items: items.iter().filter(|i| i.warning.is_some()).count(),
207        cross_format_items: items
208            .iter()
209            .filter(|i| {
210                let r = &review.report.resources[i.resource].resource;
211                i.format != r.format || r.extension_mismatch
212            })
213            .count(),
214        items,
215        token,
216    })
217}
218
219#[derive(Debug, Clone, Serialize)]
220pub struct BatchOutcome {
221    pub resource: usize,
222    pub path: PathBuf,
223    /// `applied`, `failed` or `cancelled`.
224    pub outcome: &'static str,
225    pub error: Option<String>,
226    pub savings_bytes: u64,
227}
228
229#[derive(Debug, Clone, Default, Serialize)]
230pub struct BatchStatus {
231    pub running: bool,
232    pub cancelled: bool,
233    pub total: usize,
234    pub outcomes: Vec<BatchOutcome>,
235    pub applied: usize,
236    pub failed: usize,
237    pub savings_bytes: u64,
238}
239
240/// Run a confirmed plan. `status` is updated after every file so callers can
241/// stream per-file outcomes; `cancel` stops before the next file.
242pub(crate) fn run(
243    review: &Review,
244    plan: &BatchPlan,
245    status: &Mutex<BatchStatus>,
246    cancel: &AtomicBool,
247) {
248    {
249        let mut status = status.lock().unwrap_or_else(|e| e.into_inner());
250        *status = BatchStatus {
251            running: true,
252            total: plan.items.len(),
253            ..Default::default()
254        };
255    }
256    let approvals = plan.policy.approvals();
257    for item in &plan.items {
258        let (outcome, error) = if cancel.load(Ordering::SeqCst) {
259            ("cancelled", None)
260        } else {
261            match review.apply_with_warnings(item.resource, item.candidate, &approvals, None, false)
262            {
263                Ok(()) => ("applied", None),
264                Err(error) => ("failed", Some(format!("{error:#}"))),
265            }
266        };
267        let mut status = status.lock().unwrap_or_else(|e| e.into_inner());
268        match outcome {
269            "applied" => {
270                status.applied += 1;
271                status.savings_bytes += item.savings_bytes;
272            }
273            "failed" => status.failed += 1,
274            _ => status.cancelled = true,
275        }
276        status.outcomes.push(BatchOutcome {
277            resource: item.resource,
278            path: item.path.clone(),
279            outcome,
280            error,
281            savings_bytes: if outcome == "applied" {
282                item.savings_bytes
283            } else {
284                0
285            },
286        });
287    }
288    status.lock().unwrap_or_else(|e| e.into_inner()).running = false;
289}
290
291/// Restore applied or partially applied operations, optionally limited to a
292/// caller-selected set of resource indexes. Operations sharing a file (one
293/// Contents.json, one reference file) must be undone newest-first; repeated
294/// passes find that order without trusting recorded timestamps.
295pub(crate) fn restore_many(
296    review: &Review,
297    resources: Option<&[usize]>,
298    cancel: &AtomicBool,
299) -> BatchStatus {
300    let selected = resources.map(|indexes| {
301        indexes
302            .iter()
303            .copied()
304            .collect::<std::collections::BTreeSet<_>>()
305    });
306    let mut pending: Vec<usize> = review
307        .states()
308        .as_object()
309        .into_iter()
310        .flatten()
311        .filter_map(|(index, state)| {
312            let index = index.parse().ok()?;
313            (state["state"] != "original"
314                && selected
315                    .as_ref()
316                    .is_none_or(|indexes| indexes.contains(&index)))
317            .then_some(index)
318        })
319        .collect();
320    pending.sort_unstable();
321    let mut status = BatchStatus {
322        total: pending.len(),
323        ..Default::default()
324    };
325    let mut last_errors = std::collections::BTreeMap::new();
326    loop {
327        let before = pending.len();
328        pending.retain(|&index| {
329            if cancel.load(Ordering::SeqCst) {
330                return true;
331            }
332            match review.restore(index) {
333                Ok(()) => {
334                    status.applied += 1;
335                    status.outcomes.push(BatchOutcome {
336                        resource: index,
337                        path: review.report.resources[index].resource.path.clone(),
338                        outcome: "applied",
339                        error: None,
340                        savings_bytes: 0,
341                    });
342                    false
343                }
344                Err(error) => {
345                    last_errors.insert(index, format!("{error:#}"));
346                    true
347                }
348            }
349        });
350        if pending.is_empty() || pending.len() == before || cancel.load(Ordering::SeqCst) {
351            break;
352        }
353    }
354    status.cancelled = cancel.load(Ordering::SeqCst);
355    for index in pending {
356        status.failed += 1;
357        status.outcomes.push(BatchOutcome {
358            resource: index,
359            path: review.report.resources[index].resource.path.clone(),
360            outcome: if status.cancelled {
361                "cancelled"
362            } else {
363                "failed"
364            },
365            error: last_errors.remove(&index),
366            savings_bytes: 0,
367        });
368    }
369    status
370}
371
372pub(crate) fn restore_all(review: &Review, cancel: &AtomicBool) -> BatchStatus {
373    restore_many(review, None, cancel)
374}
375
376/// Plan a batch for the report in `directory` without changing anything.
377pub fn plan_report(
378    directory: impl AsRef<std::path::Path>,
379    policy: &BatchPolicy,
380) -> Result<BatchPlan> {
381    plan(&Review::open(directory.as_ref())?, policy)
382}
383
384/// Apply every candidate the policy allows and return per-file outcomes.
385/// Interrupting the process is safe: each file is a separate journaled
386/// operation that `restore_report` (or the web UI) can undo.
387pub fn apply_report(
388    directory: impl AsRef<std::path::Path>,
389    policy: &BatchPolicy,
390) -> Result<BatchStatus> {
391    let review = Review::open(directory.as_ref())?;
392    let plan = plan(&review, policy)?;
393    let status = Mutex::new(BatchStatus::default());
394    run(&review, &plan, &status, &AtomicBool::new(false));
395    Ok(status.into_inner().unwrap_or_else(|e| e.into_inner()))
396}
397
398/// Restore every operation recorded in the report directory.
399pub fn restore_report(directory: impl AsRef<std::path::Path>) -> Result<BatchStatus> {
400    let review = Review::open(directory.as_ref())?;
401    Ok(restore_all(&review, &AtomicBool::new(false)))
402}