composer_install/progress.rs
1//! Install progress reporting — a caller-supplied seam.
2//!
3//! The downloader runs a two-phase parallel fan-out (download every dist,
4//! then extract every dist). It reports per-package progress through this
5//! trait so a CLI can drive a progress bar while a library consumer stays
6//! silent. The default [`NoProgress`] does nothing; this crate deliberately
7//! depends on no rendering library (`indicatif` etc.) — that's the caller's
8//! choice.
9
10use crate::downloader::DistOutcome;
11
12/// Per-package progress callbacks fired by the downloader. Both methods have
13/// no-op defaults, so an implementor overrides only the phase it cares about.
14/// Called from a rayon parallel iterator, so implementations must be `Sync`
15/// and cheap/non-blocking.
16pub trait Progress: Sync {
17 /// The downloader is about to fetch `dists` archives (cache hits
18 /// included). Fires once, before any other callback, so a bar can set its
19 /// length.
20 fn on_start(&self, dists: usize) {
21 let _ = dists;
22 }
23
24 /// One dist finished its download phase — either freshly fetched or a
25 /// cache hit (see [`DistOutcome`]). Fires once per package.
26 fn on_download(&self, package: &str, outcome: DistOutcome) {
27 let _ = (package, outcome);
28 }
29
30 /// One dist finished extracting into its `vendor/` destination. Fires
31 /// once per package, after every download has completed.
32 fn on_extract(&self, package: &str) {
33 let _ = package;
34 }
35
36 /// A fetch attempt for `package` failed and is about to be retried.
37 /// `attempt` counts the failures so far (1 on the first retry). Fired by
38 /// fetchers that retry, such as [`crate::ReqwestFetcher`]; a final
39 /// failure is returned as an error instead.
40 fn on_retry(&self, package: &str, attempt: u32, error: &eyre::Report) {
41 let _ = (package, attempt, error);
42 }
43}
44
45/// The silent default: reports nothing. Suitable for library use and for the
46/// non-interactive / `--quiet` / machine-output CLI paths.
47#[derive(Debug, Clone, Copy, Default)]
48pub struct NoProgress;
49
50impl Progress for NoProgress {}