cargo/util/

progress.rs

//! Support for CLI progress bars.

use std::cmp;
use std::time::{Duration, Instant};

use crate::context::ProgressWhen;
use crate::util::{CargoResult, GlobalContext};
use anstyle_progress::TermProgress;
use cargo_util_terminal::Shell;
use unicode_width::UnicodeWidthChar;

/// CLI progress bar.
///
/// The `Progress` object can be in an enabled or disabled state. When
/// disabled, calling any of the methods to update it will not display
/// anything. Disabling is typically done by the user with options such as
/// `--quiet` or the `term.progress` config option.
///
/// There are several methods to update the progress bar and to cause it to
/// update its display.
///
/// The bar will be removed from the display when the `Progress` object is
/// dropped or [`Progress::clear`] is called.
///
/// The progress bar has built-in rate limiting to avoid updating the display
/// too fast. It should usually be fine to call [`Progress::tick`] as often as
/// needed, though be cautious if the tick rate is very high or it is
/// expensive to compute the progress value.
pub struct Progress<'gctx> {
    gctx: &'gctx GlobalContext,
    state: Option<State>,
}

impl<'gctx> Progress<'gctx> {
    /// Creates a new `Progress` with the [`ProgressStyle::Percentage`] style.
    ///
    /// See [`Progress::with_style`] for more information.
    pub fn new(name: &str, gctx: &'gctx GlobalContext) -> Progress<'gctx> {
        Self::with_style(name, ProgressStyle::Percentage, gctx)
    }

    /// Creates a new progress bar.
    ///
    /// The first parameter is the text displayed to the left of the bar, such
    /// as "Fetching".
    ///
    /// The progress bar is not displayed until explicitly updated with one if
    /// its methods.
    ///
    /// The progress bar may be created in a disabled state if the user has
    /// disabled progress display (such as with the `--quiet` option).
    pub fn with_style(
        name: &str,
        style: ProgressStyle,
        gctx: &'gctx GlobalContext,
    ) -> Progress<'gctx> {
        let progress_config = gctx.progress_config();
        let progress = match progress_config.when {
            ProgressWhen::Always => true,
            ProgressWhen::Never => false,
            ProgressWhen::Auto => gctx.shell().progress_supported(),
        };
        if progress {
            Progress::new_priv(name, style, gctx)
        } else {
            return Progress { gctx, state: None };
        }
    }

    fn new_priv(name: &str, style: ProgressStyle, gctx: &'gctx GlobalContext) -> Progress<'gctx> {
        let progress_config = gctx.progress_config();
        let width = progress_config
            .width
            .or_else(|| gctx.shell().err_width().progress_max_width());

        Progress {
            gctx,
            state: width.map(|n| State {
                format: Format {
                    style,
                    max_width: n,
                    // 50 gives some space for text after the progress bar,
                    // even on narrow (e.g. 80 char) terminals.
                    max_print: 50,
                    term_integration: TerminalIntegration::from_config(gctx),
                    unicode: gctx.shell().err_unicode(),
                },
                name: name.to_string(),
                done: false,
                throttle: Throttle::new(),
                last_line: None,
                fixed_width: progress_config.width,
            }),
        }
    }

    /// Disables the progress bar, ensuring it won't be displayed.
    pub fn disable(&mut self) {
        self.state = None;
    }

    /// Returns whether or not the progress bar is allowed to be displayed.
    pub fn is_enabled(&self) -> bool {
        self.state.is_some()
    }

    /// Updates the state of the progress bar.
    ///
    /// * `cur` should be how far along the progress is.
    /// * `max` is the maximum value for the progress bar.
    /// * `msg` is a small piece of text to display at the end of the progress
    ///   bar. It will be truncated with `…` if it does not fit on the terminal.
    ///
    /// This may not actually update the display if `tick` is being called too
    /// quickly.
    pub fn tick(&mut self, cur: usize, max: usize, msg: &str) -> CargoResult<()> {
        let Some(s) = &mut self.state else {
            return Ok(());
        };

        let mut shell = self.gctx.shell();

        // Don't update too often as it can cause excessive performance loss
        // just putting stuff onto the terminal. We also want to avoid
        // flickering by not drawing anything that goes away too quickly. As a
        // result we've got two branches here:
        //
        // 1. If we haven't drawn anything, we wait for a period of time to
        //    actually start drawing to the console. This ensures that
        //    short-lived operations don't flicker on the console. Currently
        //    there's a 500ms delay to when we first draw something.
        // 2. If we've drawn something, then we rate limit ourselves to only
        //    draw to the console every so often. Currently there's a 100ms
        //    delay between updates.
        if !s.throttle.allowed() {
            return Ok(());
        }

        s.tick(cur, max, msg, &mut shell)
    }

    /// Updates the state of the progress bar.
    ///
    /// This is the same as [`Progress::tick`], but ignores rate throttling
    /// and forces the display to be updated immediately.
    ///
    /// This may be useful for situations where you know you aren't calling
    /// `tick` too fast, and accurate information is more important than
    /// limiting the console update rate.
    pub fn tick_now(&mut self, cur: usize, max: usize, msg: &str) -> CargoResult<()> {
        let mut shell = self.gctx.shell();

        match self.state {
            Some(ref mut s) => s.tick(cur, max, msg, &mut shell),
            None => Ok(()),
        }
    }

    /// Returns whether or not updates are currently being throttled.
    ///
    /// This can be useful if computing the values for calling the
    /// [`Progress::tick`] function may require some expensive work.
    pub fn update_allowed(&mut self) -> bool {
        match &mut self.state {
            Some(s) => s.throttle.allowed(),
            None => false,
        }
    }

    /// Displays progress without a bar.
    ///
    /// The given `msg` is the text to display after the status message.
    ///
    /// Example: `Downloading 61 crates, remaining bytes: 28.0 MB`
    ///
    /// This does not have any rate limit throttling, so be careful about
    /// calling it too often.
    pub fn print_now(&mut self, msg: &str) -> CargoResult<()> {
        let mut shell = self.gctx.shell();

        match &mut self.state {
            Some(s) => s.print(ProgressOutput::PrintNow, msg, &mut shell),
            None => Ok(()),
        }
    }

    /// Clears the progress bar from the console.
    pub fn clear(&mut self) {
        let mut shell = self.gctx.shell();

        if let Some(ref mut s) = self.state {
            s.clear(&mut shell);
        }
    }

    /// Sets the progress reporter to the error state.
    pub fn indicate_error(&mut self) {
        if let Some(s) = &mut self.state {
            s.format.term_integration.error()
        }
    }
}

impl<'gctx> Drop for Progress<'gctx> {
    fn drop(&mut self) {
        self.clear();
    }
}

/// Indicates the style of information for displaying the amount of progress.
///
/// See also [`Progress::print_now`] for displaying progress without a bar.
pub enum ProgressStyle {
    /// Displays progress as a percentage.
    ///
    /// Example: `Fetch [=====================>   ]  88.15%`
    ///
    /// This is good for large values like number of bytes downloaded.
    Percentage,
    /// Displays progress as a ratio.
    ///
    /// Example: `Building [===>                      ] 35/222`
    ///
    /// This is good for smaller values where the exact number is useful to see.
    Ratio,
    /// Does not display an exact value of how far along it is.
    ///
    /// Example: `Fetch [===========>                     ]`
    ///
    /// This is good for situations where the exact value is an approximation,
    /// and thus there isn't anything accurate to display to the user.
    Indeterminate,
}

struct State {
    format: Format,
    name: String,
    done: bool,
    throttle: Throttle,
    last_line: Option<String>,
    fixed_width: Option<usize>,
}

impl State {
    fn tick(&mut self, cur: usize, max: usize, msg: &str, shell: &mut Shell) -> CargoResult<()> {
        if self.done {
            write!(shell.err(), "{}", self.format.term_integration.remove())?;
            return Ok(());
        }

        if max > 0 && cur == max {
            self.done = true;
        }

        // Write out a pretty header, then the progress bar itself, and then
        // return back to the beginning of the line for the next print.
        self.try_update_max_width(shell);
        if let Some(pbar) = self.format.progress(cur, max) {
            self.print(pbar, msg, shell)?;
        }
        Ok(())
    }

    fn print(&mut self, progress: ProgressOutput, msg: &str, shell: &mut Shell) -> CargoResult<()> {
        self.throttle.update();
        self.try_update_max_width(shell);

        let (mut line, report) = match progress {
            ProgressOutput::PrintNow => (String::new(), None),
            ProgressOutput::TextAndReport(prefix, report) => (prefix, Some(report)),
            ProgressOutput::Report(report) => (String::new(), Some(report)),
        };

        // make sure we have enough room for the header
        if self.format.max_width < 15 {
            // even if we don't have space we can still output progress report
            if let Some(tb) = report {
                write!(shell.err(), "{tb}\r")?;
            }
            return Ok(());
        }

        self.format.render(&mut line, msg);
        while line.len() < self.format.max_width - 15 {
            line.push(' ');
        }

        // Only update if the line has changed.
        if shell.is_cleared() || self.last_line.as_ref() != Some(&line) {
            shell.set_needs_clear(false);
            shell.transient_status(&self.name)?;
            if let Some(tb) = report {
                write!(shell.err(), "{line}{tb}\r")?;
            } else {
                write!(shell.err(), "{line}\r")?;
            }
            self.last_line = Some(line);
            shell.set_needs_clear(true);
        }

        Ok(())
    }

    fn clear(&mut self, shell: &mut Shell) {
        // Always clear the progress report
        let _ = write!(shell.err(), "{}", self.format.term_integration.remove());
        // No need to clear if the progress is not currently being displayed.
        if self.last_line.is_some() && !shell.is_cleared() {
            shell.err_erase_line();
            self.last_line = None;
        }
    }

    fn try_update_max_width(&mut self, shell: &mut Shell) {
        if self.fixed_width.is_none() {
            if let Some(n) = shell.err_width().progress_max_width() {
                self.format.max_width = n;
            }
        }
    }
}

struct Format {
    style: ProgressStyle,
    max_width: usize,
    max_print: usize,
    term_integration: TerminalIntegration,
    unicode: bool,
}

impl Format {
    fn progress(&self, cur: usize, max: usize) -> Option<ProgressOutput> {
        assert!(cur <= max);
        // Render the percentage at the far right and then figure how long the
        // progress bar is
        let pct = (cur as f64) / (max as f64);
        let pct = if !pct.is_finite() { 0.0 } else { pct };
        let stats = match self.style {
            ProgressStyle::Percentage => format!(" {:6.02}%", pct * 100.0),
            ProgressStyle::Ratio => format!(" {cur}/{max}"),
            ProgressStyle::Indeterminate => String::new(),
        };
        let report = match self.style {
            ProgressStyle::Percentage | ProgressStyle::Ratio => {
                let pct = (pct * 100.0) as u8;
                let pct = pct.clamp(0, 100);
                self.term_integration.value(pct)
            }
            ProgressStyle::Indeterminate => self.term_integration.indeterminate(),
        };

        let extra_len = stats.len() + 2 /* [ and ] */ + 15 /* status header */;
        let Some(display_width) = self.width().checked_sub(extra_len) else {
            if self.term_integration.enabled {
                return Some(ProgressOutput::Report(report));
            }
            return None;
        };

        let mut string = String::with_capacity(self.max_width);
        string.push('[');
        let hashes = display_width as f64 * pct;
        let hashes = hashes as usize;

        // Draw the `===>`
        if hashes > 0 {
            for _ in 0..hashes - 1 {
                string.push('=');
            }
            if cur == max {
                string.push('=');
            } else {
                string.push('>');
            }
        }

        // Draw the empty space we have left to do
        for _ in 0..(display_width - hashes) {
            string.push(' ');
        }
        string.push(']');
        string.push_str(&stats);

        Some(ProgressOutput::TextAndReport(string, report))
    }

    fn render(&self, string: &mut String, msg: &str) {
        let mut avail_msg_len = self.max_width - string.len() - 15;
        let mut ellipsis_pos = 0;

        let (ellipsis, ellipsis_width) = if self.unicode { ("…", 1) } else { ("...", 3) };

        if avail_msg_len <= ellipsis_width {
            return;
        }
        for c in msg.chars() {
            let display_width = c.width().unwrap_or(0);
            if avail_msg_len >= display_width {
                avail_msg_len -= display_width;
                string.push(c);
                if avail_msg_len >= ellipsis_width {
                    ellipsis_pos = string.len();
                }
            } else {
                string.truncate(ellipsis_pos);
                string.push_str(ellipsis);
                break;
            }
        }
    }

    #[cfg(test)]
    fn progress_status(&self, cur: usize, max: usize, msg: &str) -> Option<String> {
        let mut ret = match self.progress(cur, max)? {
            // Check only the variant that contains text.
            ProgressOutput::TextAndReport(text, _) => text,
            _ => return None,
        };
        self.render(&mut ret, msg);
        Some(ret)
    }

    fn width(&self) -> usize {
        cmp::min(self.max_width, self.max_print)
    }
}

struct Throttle {
    first: bool,
    last_update: Instant,
}

impl Throttle {
    fn new() -> Throttle {
        Throttle {
            first: true,
            last_update: Instant::now(),
        }
    }

    fn allowed(&mut self) -> bool {
        if self.first {
            let delay = Duration::from_millis(500);
            if self.last_update.elapsed() < delay {
                return false;
            }
        } else {
            let interval = Duration::from_millis(100);
            if self.last_update.elapsed() < interval {
                return false;
            }
        }
        self.update();
        true
    }

    fn update(&mut self) {
        self.first = false;
        self.last_update = Instant::now();
    }
}

/// Controls terminal progress integration via OSC sequences.
struct TerminalIntegration {
    enabled: bool,
    error: bool,
}

impl TerminalIntegration {
    #[cfg(test)]
    fn new(enabled: bool) -> Self {
        Self {
            enabled,
            error: false,
        }
    }

    /// Creates a `TerminalIntegration` from Cargo's configuration.
    /// Autodetect support if not explicitly enabled or disabled.
    fn from_config(gctx: &GlobalContext) -> Self {
        let enabled = gctx
            .progress_config()
            .term_integration
            .unwrap_or_else(|| gctx.shell().is_err_term_integration_available());

        Self {
            enabled,
            error: false,
        }
    }

    fn progress_state(&self, value: StatusValue) -> StatusValue {
        match (self.enabled, self.error) {
            (true, false) => value,
            (true, true) => match value {
                StatusValue::Value(v) => StatusValue::Error(v),
                _ => StatusValue::Error(100),
            },
            (false, _) => StatusValue::None,
        }
    }

    pub fn remove(&self) -> StatusValue {
        self.progress_state(StatusValue::Remove)
    }

    pub fn value(&self, percent: u8) -> StatusValue {
        self.progress_state(StatusValue::Value(percent))
    }

    pub fn indeterminate(&self) -> StatusValue {
        self.progress_state(StatusValue::Indeterminate)
    }

    pub fn error(&mut self) {
        self.error = true;
    }
}

enum ProgressOutput {
    /// Print progress without a message
    PrintNow,
    /// Progress, message and progress report
    TextAndReport(String, StatusValue),
    /// Only progress report, no message and no text progress
    Report(StatusValue),
}

/// A progress status value printable as an ANSI OSC 9;4 escape code.
#[cfg_attr(test, derive(PartialEq, Debug))]
enum StatusValue {
    /// No output.
    None,
    /// Remove progress.
    Remove,
    /// Progress value (0-100).
    Value(u8),
    /// Indeterminate state (no bar, just animation)
    Indeterminate,
    /// Progress value in an error state (0-100).
    Error(u8),
}

impl std::fmt::Display for StatusValue {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        let progress = match self {
            Self::None => TermProgress::none(),
            Self::Remove => TermProgress::remove(),
            Self::Value(v) => TermProgress::start().percent(*v),
            Self::Indeterminate => TermProgress::start(),
            Self::Error(v) => TermProgress::error().percent(*v),
        };

        progress.fmt(f)
    }
}

#[test]
fn test_progress_status() {
    let format = Format {
        style: ProgressStyle::Ratio,
        max_print: 40,
        max_width: 60,
        term_integration: TerminalIntegration::new(false),
        unicode: true,
    };
    assert_eq!(
        format.progress_status(0, 4, ""),
        Some("[                   ] 0/4".to_string())
    );
    assert_eq!(
        format.progress_status(1, 4, ""),
        Some("[===>               ] 1/4".to_string())
    );
    assert_eq!(
        format.progress_status(2, 4, ""),
        Some("[========>          ] 2/4".to_string())
    );
    assert_eq!(
        format.progress_status(3, 4, ""),
        Some("[=============>     ] 3/4".to_string())
    );
    assert_eq!(
        format.progress_status(4, 4, ""),
        Some("[===================] 4/4".to_string())
    );

    assert_eq!(
        format.progress_status(3999, 4000, ""),
        Some("[===========> ] 3999/4000".to_string())
    );
    assert_eq!(
        format.progress_status(4000, 4000, ""),
        Some("[=============] 4000/4000".to_string())
    );

    assert_eq!(
        format.progress_status(3, 4, ": short message"),
        Some("[=============>     ] 3/4: short message".to_string())
    );
    assert_eq!(
        format.progress_status(3, 4, ": msg thats just fit"),
        Some("[=============>     ] 3/4: msg thats just fit".to_string())
    );
    assert_eq!(
        format.progress_status(3, 4, ": msg that's just fit"),
        Some("[=============>     ] 3/4: msg that's just f…".to_string())
    );

    // combining diacritics have width zero and thus can fit max_width.
    let zalgo_msg = "z̸̧̢̗͉̝̦͍̱ͧͦͨ̑̅̌ͥ́͢a̢ͬͨ̽ͯ̅̑ͥ͋̏̑ͫ̄͢͏̫̝̪̤͎̱̣͍̭̞̙̱͙͍̘̭͚l̶̡̛̥̝̰̭̹̯̯̞̪͇̱̦͙͔̘̼͇͓̈ͨ͗ͧ̓͒ͦ̀̇ͣ̈ͭ͊͛̃̑͒̿̕͜g̸̷̢̩̻̻͚̠͓̞̥͐ͩ͌̑ͥ̊̽͋͐̐͌͛̐̇̑ͨ́ͅo͙̳̣͔̰̠̜͕͕̞̦̙̭̜̯̹̬̻̓͑ͦ͋̈̉͌̃ͯ̀̂͠ͅ ̸̡͎̦̲̖̤̺̜̮̱̰̥͔̯̅̏ͬ̂ͨ̋̃̽̈́̾̔̇ͣ̚͜͜h̡ͫ̐̅̿̍̀͜҉̛͇̭̹̰̠͙̞ẽ̶̙̹̳̖͉͎̦͂̋̓ͮ̔ͬ̐̀͂̌͑̒͆̚͜͠ ͓͓̟͍̮̬̝̝̰͓͎̼̻ͦ͐̾̔͒̃̓͟͟c̮̦͍̺͈͚̯͕̄̒͐̂͊̊͗͊ͤͣ̀͘̕͝͞o̶͍͚͍̣̮͌ͦ̽̑ͩ̅ͮ̐̽̏͗́͂̅ͪ͠m̷̧͖̻͔̥̪̭͉͉̤̻͖̩̤͖̘ͦ̂͌̆̂ͦ̒͊ͯͬ͊̉̌ͬ͝͡e̵̹̣͍̜̺̤̤̯̫̹̠̮͎͙̯͚̰̼͗͐̀̒͂̉̀̚͝͞s̵̲͍͙͖̪͓͓̺̱̭̩̣͖̣ͤͤ͂̎̈͗͆ͨͪ̆̈͗͝͠";
    assert_eq!(
        format.progress_status(3, 4, zalgo_msg),
        Some("[=============>     ] 3/4".to_string() + zalgo_msg)
    );

    // some non-ASCII ellipsize test
    assert_eq!(
        format.progress_status(3, 4, "_123456789123456e\u{301}\u{301}8\u{301}90a"),
        Some("[=============>     ] 3/4_123456789123456e\u{301}\u{301}8\u{301}9…".to_string())
    );
    assert_eq!(
        format.progress_status(3, 4, "：每個漢字佔據了兩個字元"),
        Some("[=============>     ] 3/4：每個漢字佔據了兩…".to_string())
    );
    assert_eq!(
        // handle breaking at middle of character
        format.progress_status(3, 4, "：-每個漢字佔據了兩個字元"),
        Some("[=============>     ] 3/4：-每個漢字佔據了兩…".to_string())
    );
}

#[test]
fn test_progress_status_percentage() {
    let format = Format {
        style: ProgressStyle::Percentage,
        max_print: 40,
        max_width: 60,
        term_integration: TerminalIntegration::new(false),
        unicode: true,
    };
    assert_eq!(
        format.progress_status(0, 77, ""),
        Some("[               ]   0.00%".to_string())
    );
    assert_eq!(
        format.progress_status(1, 77, ""),
        Some("[               ]   1.30%".to_string())
    );
    assert_eq!(
        format.progress_status(76, 77, ""),
        Some("[=============> ]  98.70%".to_string())
    );
    assert_eq!(
        format.progress_status(77, 77, ""),
        Some("[===============] 100.00%".to_string())
    );
}

#[test]
fn test_progress_status_too_short() {
    let format = Format {
        style: ProgressStyle::Percentage,
        max_print: 25,
        max_width: 25,
        term_integration: TerminalIntegration::new(false),
        unicode: true,
    };
    assert_eq!(
        format.progress_status(1, 1, ""),
        Some("[] 100.00%".to_string())
    );

    let format = Format {
        style: ProgressStyle::Percentage,
        max_print: 24,
        max_width: 24,
        term_integration: TerminalIntegration::new(false),
        unicode: true,
    };
    assert_eq!(format.progress_status(1, 1, ""), None);
}

#[test]
fn test_term_integration_disabled() {
    let report = TerminalIntegration::new(false);
    let mut out = String::new();
    out.push_str(&report.remove().to_string());
    out.push_str(&report.value(10).to_string());
    out.push_str(&report.indeterminate().to_string());
    assert!(out.is_empty());
}

#[test]
fn test_term_integration_error_state() {
    let mut report = TerminalIntegration::new(true);
    assert_eq!(report.value(10), StatusValue::Value(10));
    report.error();
    assert_eq!(report.value(50), StatusValue::Error(50));
}