ktstr/cli/
progress.rs

1//! Progress bars for kernel fetches (tarball download + git clone).
2//!
3//! Two bar types, both rendered through a single
4//! [`indicatif::MultiProgress`] so concurrent fetches (the parallel
5//! `cargo ktstr test --kernel A --kernel B` resolve) never garble
6//! each other's terminal output. Byte-download and build bars degrade
7//! to a no-op when stderr is not a TTY; clone progress instead emits
8//! throttled, escape-free phase/percentage heartbeats so a long pack
9//! receive or index is never silent in CI.
10//!
11//! - [`FetchProgress`] — the group handle. One per resolve operation,
12//!   shared across the rayon workers by `&` (the inner
13//!   [`indicatif::MultiProgress`] is `Send + Sync`). Hands out child
14//!   bars and replaces the single-instance [`crate::cli::Spinner`] the
15//!   download path previously wrapped (a `Spinner` cannot host
16//!   concurrent bars). The build phase renders through this group too:
17//!   `kernel_build_pipeline` takes a group and draws the configure /
18//!   build / `compile_commands.json` phases as `step_bar` spinners. So
19//!   no code path runs a standalone `Spinner` alongside a
20//!   live `MultiProgress`, and the parallel resolve's concurrent builds
21//!   share the one group rather than racing the process-global
22//!   `SPINNER_ACTIVE` guard. The only remaining `Spinner` is
23//!   `auto_download_kernel`'s brief version-fetch, which always finishes
24//!   before any group bar is created.
25//! - [`GroupBar`] — a determinate byte bar for tarball downloads:
26//!   transfer rate and ETA derived from `Content-Length`. Falls back
27//!   to a live byte counter (rate, no ETA) when the response carries
28//!   no `Content-Length`.
29//! - [`CloneProgress`] — a determinate object/file bar and heartbeat
30//!   bridge for gix/source network operations, driven by polling gix's
31//!   prodash progress tree via
32//!   `tree::Root::sorted_snapshot`. Shows a real bar + ETA whenever gix
33//!   reports a bounded total — resolving deltas and checkout files
34//!   always do; the receiving/read-pack phase does only when the server
35//!   advertises a pack size (often unknown for shallow smart-HTTP
36//!   clones) — and a spinner otherwise (negotiation, or an unadvertised
37//!   pack size). Single renderer (indicatif), zero new dependencies —
38//!   prodash's own line renderer is not compiled in this dependency
39//!   graph, so the tree is read rather than rendered by prodash.
40
41use std::sync::Arc;
42use std::sync::atomic::{AtomicBool, Ordering};
43use std::thread::JoinHandle;
44use std::time::{Duration, Instant};
45
46use gix::progress::prodash::progress::{Key, Task};
47use gix::progress::tree::{Item, Root};
48use indicatif::{MultiProgress, ProgressBar, ProgressDrawTarget, ProgressStyle};
49
50use crate::cli::stderr_color;
51
52/// Frame cadence shared by the bars' steady tick and the gix poll
53/// loop. The poll loop samples the prodash tree at this rate — a
54/// display ticker, not an evented wait: prodash exposes no
55/// "counter advanced" notification, only the pull-based
56/// `sorted_snapshot`, so a fixed-cadence sample (the same approach
57/// prodash's own renderer takes via `frames_per_second`) is the
58/// correct shape here.
59const TICK: Duration = Duration::from_millis(100);
60
61/// Determinate byte-download template: spinner, label, bar, bytes,
62/// rate, ETA. `bytes`/`total_bytes`/`bytes_per_sec` render in binary
63/// units (MiB/KiB); `eta` is `Content-Length`-derived.
64const DOWNLOAD_TEMPLATE: &str =
65    "{spinner:.green} {msg} [{wide_bar:.cyan/blue}] {bytes}/{total_bytes} ({bytes_per_sec}, {eta})";
66
67/// Byte-counter template for a download with no `Content-Length`: no
68/// total means no percent/ETA, but a live byte count + rate still
69/// shows real movement.
70const DOWNLOAD_TEMPLATE_NO_TOTAL: &str = "{spinner:.green} {msg} {bytes} ({bytes_per_sec})";
71
72/// Label-only spinner template for a non-quantifiable phase (kernel
73/// configure / build / compile_commands generation) — a moving spinner
74/// plus a message, with no byte/percent/ETA fields (there is nothing to
75/// count). Mirrors the cyan spinner the old build `Spinner` used.
76const STEP_TEMPLATE: &str = "{spinner:.cyan} {msg}";
77
78/// Determinate clone template: spinner, label/phase, bar, count,
79/// percent, ETA. Driven by gix's bounded object/file counts; the ETA
80/// is derived by indicatif from the count rate.
81const CLONE_TEMPLATE: &str =
82    "{spinner:.green} {msg} [{wide_bar:.cyan/blue}] {pos}/{len} ({percent}%, {eta})";
83
84/// Spinner template for the brief negotiation window before any
85/// bounded gix task exists (no total ⇒ nothing to estimate).
86const CLONE_TEMPLATE_SPINNER: &str = "{spinner:.green} {msg}";
87
88/// Maximum silence between non-TTY clone heartbeats. Phase changes and
89/// ten-percent progress boundaries are emitted sooner.
90const CLONE_HEARTBEAT: Duration = Duration::from_secs(10);
91
92/// Percent granularity for bounded non-TTY clone progress.
93const CLONE_PERCENT_STEP: usize = 10;
94
95/// Progress glyphs for the filled bar (filled, current, remaining).
96const PROGRESS_CHARS: &str = "##-";
97
98/// Shared owner of the concurrent fetch progress bars for one resolve
99/// operation.
100///
101/// Wraps an [`indicatif::MultiProgress`] (constructed against a hidden
102/// draw target off-TTY) and hands out child bars via `download_bar` /
103/// `clone_progress`. Created once per resolve and shared across the rayon
104/// `resolve_specs_parallel` workers by `&` reference — `MultiProgress`
105/// is `Send + Sync` and `add` is internally serialized on an
106/// `Arc<RwLock>`, so concurrent `download_bar`/`clone_progress` calls
107/// are safe.
108///
109/// Off-TTY (`!stderr_color()`) the group draws bars to a hidden target.
110/// Downloads/build steps remain no-op draws; clone progress still polls
111/// gix and emits throttled plain-text heartbeats to stderr.
112pub struct FetchProgress {
113    /// Hidden draw target off-TTY; stderr otherwise. Always present
114    /// (vs `Option`) so child-bar construction is unconditional and
115    /// the hidden/visible branch lives in one place: the draw target.
116    multi: MultiProgress,
117}
118
119impl FetchProgress {
120    /// Construct a fetch-progress group. On a TTY it renders to
121    /// stderr; otherwise (non-TTY / `NO_COLOR` / `TERM=dumb`) it uses
122    /// a hidden draw target so nothing reaches piped output.
123    ///
124    /// The `stderr_color()` gate mirrors [`crate::cli::Spinner`];
125    /// indicatif additionally auto-hides on a non-TTY, so the hidden
126    /// behavior is correct even if the two ever disagreed.
127    pub fn new() -> Self {
128        let multi = if stderr_color() {
129            MultiProgress::new()
130        } else {
131            MultiProgress::with_draw_target(ProgressDrawTarget::hidden())
132        };
133        Self { multi }
134    }
135
136    /// Whether the group draws to a hidden target (non-TTY / forced).
137    pub(crate) fn is_hidden(&self) -> bool {
138        self.multi.is_hidden()
139    }
140
141    /// Add a determinate byte-download bar. `total` is the response
142    /// `Content-Length`: `Some` ⇒ percent + ETA; `None` ⇒ a live byte
143    /// counter (rate, no ETA). `label` names the kernel being fetched
144    /// so concurrent bars are distinguishable. Off-TTY the returned
145    /// bar is hidden.
146    pub(crate) fn download_bar(&self, label: &str, total: Option<u64>) -> GroupBar {
147        let pb = match total {
148            Some(len) => ProgressBar::new(len),
149            None => ProgressBar::new_spinner(),
150        };
151        let pb = self.multi.add(pb);
152        let template = if total.is_some() {
153            DOWNLOAD_TEMPLATE
154        } else {
155            DOWNLOAD_TEMPLATE_NO_TOTAL
156        };
157        pb.set_style(
158            ProgressStyle::with_template(template)
159                .expect("valid download template")
160                .progress_chars(PROGRESS_CHARS),
161        );
162        pb.set_message(label.to_string());
163        // Skip the steady-tick ticker thread on the hidden path — it
164        // would redraw nothing yet still spawn a thread per bar (the
165        // exact CI/non-TTY case this module no-ops).
166        if !self.is_hidden() {
167            pb.enable_steady_tick(TICK);
168        }
169        GroupBar { pb }
170    }
171
172    /// Add a label-only spinner bar for a non-quantifiable build phase
173    /// (kernel configure / build / `compile_commands.json` generation).
174    /// Unlike [`Self::download_bar`] with `total = None`, it carries no
175    /// byte counter — the build phase has no bytes to count, only a
176    /// moving spinner and a message. Off-TTY it is hidden and the
177    /// steady-tick thread is skipped, matching [`Self::download_bar`].
178    ///
179    /// Routing the build phase through the group (rather than a
180    /// standalone [`crate::cli::Spinner`]) is what lets concurrent
181    /// builds in the parallel resolve render together without racing the
182    /// process-global `SPINNER_ACTIVE` guard.
183    pub(crate) fn step_bar(&self, label: &str) -> GroupBar {
184        let pb = self.multi.add(ProgressBar::new_spinner());
185        pb.set_style(ProgressStyle::with_template(STEP_TEMPLATE).expect("valid step template"));
186        pb.set_message(label.to_string());
187        if !self.is_hidden() {
188            pb.enable_steady_tick(TICK);
189        }
190        GroupBar { pb }
191    }
192
193    /// Add a git-clone progress bar and attempt to spawn the gix-tree →
194    /// indicatif poll bridge. A spawn failure is warned and nonfatal.
195    /// `label` names the clone (its git ref). The bar is
196    /// determinate (with ETA) whenever gix reports a bounded task and
197    /// a spinner otherwise; see [`CloneProgress`].
198    ///
199    /// Off-TTY (`is_hidden()`), the bar remains hidden but the poller
200    /// emits throttled plain-text updates instead.
201    pub(crate) fn clone_progress(&self, label: &str) -> CloneProgress {
202        self.operation_progress(label, "cloning", "clone")
203    }
204
205    /// Add a progress bridge for another network-backed git/source
206    /// operation. It intentionally uses the same prodash poller and
207    /// ten-second non-TTY heartbeat as a clone: ref discovery and
208    /// snapshot requests have the same potentially long, initially
209    /// unquantifiable network waits.
210    pub(crate) fn operation_progress(
211        &self,
212        label: &str,
213        active_verb: &str,
214        completion_noun: &str,
215    ) -> CloneProgress {
216        let root = Root::new();
217        let bar = self.multi.add(ProgressBar::new_spinner());
218        bar.set_style(
219            ProgressStyle::with_template(CLONE_TEMPLATE_SPINNER)
220                .expect("valid clone spinner template"),
221        );
222        bar.set_message(format!("{active_verb} {label}"));
223
224        let non_tty = self.is_hidden();
225        if !non_tty {
226            bar.enable_steady_tick(TICK);
227        }
228        CloneProgress::start(root, bar, label, completion_noun, non_tty, Instant::now())
229    }
230}
231
232impl CloneProgress {
233    /// Build the poll bridge around `root` and `bar`.
234    ///
235    /// Kept on `CloneProgress` so fetch paths without a surrounding
236    /// `FetchProgress` group can use the same heartbeat state machine
237    /// through [`CloneProgress::standalone_operation`].
238    fn start(
239        root: Arc<Root>,
240        bar: ProgressBar,
241        label: &str,
242        completion_noun: &str,
243        non_tty: bool,
244        started: Instant,
245    ) -> Self {
246        let stop = Arc::new(AtomicBool::new(false));
247        let poller = spawn_clone_poller(
248            Arc::clone(&root),
249            bar.clone(),
250            Arc::clone(&stop),
251            label.to_string(),
252            non_tty,
253        )
254        .map_err(|err| {
255            tracing::warn!(
256                %err,
257                operation = %label,
258                "could not start source-progress poller; acquisition will continue without it",
259            );
260        })
261        .ok();
262        CloneProgress {
263            root,
264            bar,
265            stop,
266            poller,
267            label: label.to_string(),
268            non_tty,
269            started,
270            completion_noun: completion_noun.to_string(),
271        }
272    }
273
274    /// A hidden, plain-text operation reporter for callers that do not
275    /// have a shared [`FetchProgress`] group. This keeps single-source
276    /// commands and internal mirror discovery from going silent during
277    /// a slow network wait; it does not create a renderer or serialize
278    /// the underlying operation.
279    pub(crate) fn standalone_operation(
280        label: &str,
281        active_verb: &str,
282        completion_noun: &str,
283    ) -> Self {
284        let root = Root::new();
285        let bar = ProgressBar::hidden();
286        bar.set_style(
287            ProgressStyle::with_template(CLONE_TEMPLATE_SPINNER)
288                .expect("valid clone spinner template"),
289        );
290        bar.set_message(format!("{active_verb} {label}"));
291        Self::start(root, bar, label, completion_noun, true, Instant::now())
292    }
293}
294
295#[cfg(test)]
296thread_local! {
297    static TEST_FAIL_NEXT_POLLER_SPAWN: std::cell::Cell<bool> = const {
298        std::cell::Cell::new(false)
299    };
300}
301
302fn spawn_clone_poller(
303    root: Arc<Root>,
304    bar: ProgressBar,
305    stop: Arc<AtomicBool>,
306    label: String,
307    non_tty: bool,
308) -> std::io::Result<JoinHandle<()>> {
309    #[cfg(test)]
310    {
311        let fail = TEST_FAIL_NEXT_POLLER_SPAWN.with(|flag| flag.replace(false));
312        if fail {
313            return Err(std::io::Error::other(
314                "injected progress-poller spawn failure",
315            ));
316        }
317    }
318    std::thread::Builder::new()
319        .name("ktstr-source-progress".to_string())
320        .spawn(move || poll_clone_tree(root, bar, stop, label, non_tty))
321}
322
323impl FetchProgress {
324    /// Print a status line that coordinates with the live bars.
325    ///
326    /// On a visible group this routes through
327    /// [`indicatif::MultiProgress::println`] so the line lands above
328    /// the bars without garbling them (a raw `eprintln!` while bars
329    /// are drawing corrupts their cursor accounting). On a hidden
330    /// group (non-TTY / CI) `MultiProgress::println` is a no-op draw
331    /// that would *swallow* the line, so it falls back to `eprintln!`
332    /// to preserve the status output piped/CI consumers rely on.
333    ///
334    /// Best-effort: a `println` error (e.g. broken pipe) is discarded
335    /// — a status line must never abort a fetch.
336    ///
337    /// Both arms lay the line out through
338    /// [`crate::cli::status_line`], so a fetch status printed between
339    /// bars keeps the same status column and label color as the lines
340    /// the CLI emits outside a progress group.
341    pub(crate) fn println(&self, line: &str) {
342        let line = super::util::status_line(line);
343        if self.is_hidden() {
344            eprintln!("{line}");
345        } else {
346            let _ = self.multi.println(line);
347        }
348    }
349
350    /// Remove all bars from the group. Best-effort: a clear failure is
351    /// discarded so it can never mask the resolve result the caller is
352    /// returning.
353    pub fn clear(&self) {
354        let _ = self.multi.clear();
355    }
356}
357
358impl Default for FetchProgress {
359    fn default() -> Self {
360        Self::new()
361    }
362}
363
364/// Poll the gix prodash tree at [`TICK`] cadence and mirror the most
365/// relevant task onto `bar` until `stop` is set.
366///
367/// Picks the deepest task that has a *bounded* counter (`done_at =
368/// Some` — a known total) so the bar shows a real position/length and
369/// indicatif can compute an ETA. Resolving deltas and checkout files
370/// are always bounded; receiving/read-pack is bounded only when the
371/// server advertises a pack size. Falls back to the deepest live task's
372/// name (spinner only) when no bounded task exists yet (negotiation, or
373/// an unadvertised pack size). The bar style is switched only on a
374/// determinate/indeterminate transition, not every tick.
375fn poll_clone_tree(
376    root: Arc<Root>,
377    bar: ProgressBar,
378    stop: Arc<AtomicBool>,
379    label: String,
380    non_tty: bool,
381) {
382    let mut snapshot: Vec<(Key, Task)> = Vec::new();
383    let mut determinate = false;
384    let mut reporter = NonTtyCloneReporter::new(Instant::now());
385    while !stop.load(Ordering::Relaxed) {
386        if non_tty {
387            root.sorted_snapshot(&mut snapshot);
388            if let Some(line) = reporter.update(&snapshot, Instant::now()) {
389                eprintln!("{}", super::util::status_line(&format!("{label}: {line}")));
390            }
391        } else {
392            poll_tick(&root, &bar, &mut determinate, &label, &mut snapshot);
393        }
394        std::thread::sleep(TICK);
395    }
396}
397
398/// State machine for escape-free non-TTY clone reporting.
399///
400/// Emits immediately when gix changes phase, at each ten-percent
401/// boundary for bounded work, and at least every [`CLONE_HEARTBEAT`]
402/// while a phase continues. `now` is injected so cadence behavior is
403/// deterministic in unit tests.
404struct NonTtyCloneReporter {
405    started: Instant,
406    phase: Option<String>,
407    percent_bucket: Option<usize>,
408    last_emit: Instant,
409}
410
411impl NonTtyCloneReporter {
412    fn new(now: Instant) -> Self {
413        Self {
414            started: now,
415            phase: None,
416            percent_bucket: None,
417            last_emit: now,
418        }
419    }
420
421    fn update(&mut self, snapshot: &[(Key, Task)], now: Instant) -> Option<String> {
422        let Some(task) = most_relevant_clone_task(snapshot) else {
423            let phase_changed = self.phase.as_deref() != Some("waiting for remote");
424            let heartbeat = now.saturating_duration_since(self.last_emit) >= CLONE_HEARTBEAT;
425            if !(phase_changed || heartbeat) {
426                return None;
427            }
428            self.phase = Some("waiting for remote".to_string());
429            self.percent_bucket = None;
430            self.last_emit = now;
431            return Some(format!(
432                "waiting for remote (elapsed {})",
433                human_elapsed(now.saturating_duration_since(self.started))
434            ));
435        };
436        let phase_changed = self.phase.as_deref() != Some(task.name.as_str());
437        let percent_bucket = task.progress.as_ref().and_then(|value| {
438            value.done_at.filter(|total| *total > 0).map(|total| {
439                let pos = value.step.load(Ordering::Relaxed);
440                ((pos.saturating_mul(100) / total) / CLONE_PERCENT_STEP) * CLONE_PERCENT_STEP
441            })
442        });
443        let progress_bucket_changed = percent_bucket != self.percent_bucket;
444        let heartbeat = now.saturating_duration_since(self.last_emit) >= CLONE_HEARTBEAT;
445        if !(phase_changed || progress_bucket_changed || heartbeat) {
446            return None;
447        }
448
449        self.phase = Some(task.name.clone());
450        self.percent_bucket = percent_bucket;
451        self.last_emit = now;
452        Some(format!(
453            "{} (elapsed {})",
454            format_clone_task(task),
455            human_elapsed(now.saturating_duration_since(self.started))
456        ))
457    }
458}
459
460/// Prefer the deepest bounded task, as the TTY bar does, then the
461/// deepest task carrying a counter, then the deepest named phase.
462fn most_relevant_clone_task(snapshot: &[(Key, Task)]) -> Option<&Task> {
463    snapshot
464        .iter()
465        .rev()
466        .find(|(_, task)| {
467            task.progress
468                .as_ref()
469                .and_then(|value| value.done_at)
470                .is_some()
471        })
472        .or_else(|| {
473            snapshot
474                .iter()
475                .rev()
476                .find(|(_, task)| task.progress.is_some())
477        })
478        .or_else(|| snapshot.last())
479        .map(|(_, task)| task)
480}
481
482fn format_clone_task(task: &Task) -> String {
483    let Some(value) = task.progress.as_ref() else {
484        return task.name.clone();
485    };
486    let pos = value.step.load(Ordering::Relaxed);
487    let rendered = match value.unit.as_ref() {
488        Some(unit) => unit.display(pos, value.done_at, None).to_string(),
489        None => match value.done_at {
490            Some(total) if total > 0 => {
491                format!("{pos}/{total} ({}%)", pos.saturating_mul(100) / total)
492            }
493            _ => pos.to_string(),
494        },
495    };
496    format!("{}: {rendered}", task.name)
497}
498
499fn human_elapsed(elapsed: Duration) -> String {
500    let seconds = elapsed.as_secs();
501    if seconds < 60 {
502        format!("{seconds}s")
503    } else if seconds < 3600 {
504        format!("{}m {:02}s", seconds / 60, seconds % 60)
505    } else {
506        format!(
507            "{}h {:02}m {:02}s",
508            seconds / 3600,
509            (seconds % 3600) / 60,
510            seconds % 60
511        )
512    }
513}
514
515/// One poll iteration: snapshot the tree and mirror the most relevant
516/// task onto `bar`. Extracted from [`poll_clone_tree`] so the
517/// snapshot→bar mapping is unit-testable without spawning a thread or
518/// running a real clone. `determinate` carries the determinate/spinner
519/// style state across calls so the style is switched only on a
520/// transition, not every tick. `snapshot` is a caller-owned scratch
521/// buffer reused across ticks to avoid a per-tick allocation.
522fn poll_tick(
523    root: &Root,
524    bar: &ProgressBar,
525    determinate: &mut bool,
526    label: &str,
527    snapshot: &mut Vec<(Key, Task)>,
528) {
529    root.sorted_snapshot(snapshot);
530
531    // Deepest bounded task (known total) if any; else deepest task with
532    // any live counter. `sorted_snapshot` orders by Key lexicographically
533    // (pre-order DFS over the tree); the clone is a single parent chain
534    // at any instant (root → "clone" → gix's active child), so the last
535    // matching entry is the deepest active task.
536    let bounded = snapshot
537        .iter()
538        .rev()
539        .find(|(_, t)| t.progress.as_ref().and_then(|v| v.done_at).is_some());
540    let any = snapshot.iter().rev().find(|(_, t)| t.progress.is_some());
541
542    if let Some((_, task)) = bounded {
543        // Safe: `bounded` only matched tasks whose progress is Some.
544        if let Some(value) = task.progress.as_ref() {
545            if !*determinate {
546                bar.set_style(
547                    ProgressStyle::with_template(CLONE_TEMPLATE)
548                        .expect("valid clone template")
549                        .progress_chars(PROGRESS_CHARS),
550                );
551                *determinate = true;
552            }
553            bar.set_length(value.done_at.unwrap_or(0) as u64);
554            bar.set_position(value.step.load(Ordering::SeqCst) as u64);
555            bar.set_message(format!("{label}: {}", task.name));
556        }
557    } else {
558        // No bounded task: spinner mode. This covers negotiation, an
559        // unadvertised pack size, AND a no-counter task (prodash gives
560        // `progress = None` when init is called with neither a max nor a
561        // unit, e.g. gix's "negotiate") — in all of which `any` may be
562        // None. Flip the style back on the determinate→spinner
563        // transition regardless, so the bar never stays stuck showing a
564        // stale determinate length; surface the deepest live task's name
565        // when one exists.
566        if *determinate {
567            bar.set_style(
568                ProgressStyle::with_template(CLONE_TEMPLATE_SPINNER)
569                    .expect("valid clone spinner template"),
570            );
571            *determinate = false;
572        }
573        if let Some((_, task)) = any {
574            bar.set_message(format!("{label}: {}", format_clone_task(task)));
575        }
576    }
577}
578
579/// A single bar within a [`FetchProgress`] group.
580///
581/// Backs two uses. A determinate (or byte-counter) download bar
582/// ([`FetchProgress::download_bar`]): its inner
583/// [`indicatif::ProgressBar`] is handed to
584/// `crate::fetch::DownloadStream::with_progress` via [`Self::bar`] and
585/// advanced with `inc(n)` beside the stream's own byte accounting — a
586/// single source of truth, so `position()` always equals the streamed
587/// `bytes_total`. And a label-only build-phase spinner
588/// ([`FetchProgress::step_bar`]) that only ever calls [`Self::finish`]
589/// (its [`Self::bar`] is unused — there is no stream to attach). Off-TTY
590/// the bar is hidden and every method is a no-op draw.
591pub(crate) struct GroupBar {
592    pb: ProgressBar,
593}
594
595impl GroupBar {
596    /// A clone of the inner bar to attach to the download stream
597    /// (download-bar use only). `ProgressBar` is `Arc`-backed, so the
598    /// clone drives the same bar.
599    pub(crate) fn bar(&self) -> ProgressBar {
600        self.pb.clone()
601    }
602
603    /// Finish and clear the bar. Idempotent.
604    pub(crate) fn finish(&self) {
605        self.pb.finish_and_clear();
606    }
607}
608
609impl Drop for GroupBar {
610    /// Clear the bar if it was not explicitly finished — covers the
611    /// download fns' extraction-error exit (bar already created, the
612    /// xz/gzip unpack fails via `?` before [`Self::finish`]) that
613    /// bails with a live, unfinished bar. HTTP failure and HTML reject
614    /// bail before the bar is constructed; a sha256 mismatch bails
615    /// after `finish()` has already run, so Drop is only a redundant
616    /// no-op there.
617    /// Idempotent with `finish`: a second `finish_and_clear` is a
618    /// no-op on an already-cleared bar.
619    fn drop(&mut self) {
620        self.pb.finish_and_clear();
621    }
622}
623
624/// Live gix/source-operation progress bridge.
625///
626/// Holds the prodash [`tree::Root`](Root), the indicatif bar, and the
627/// background poll thread spawned by
628/// [`FetchProgress::clone_progress`] or
629/// [`FetchProgress::operation_progress`]. [`Self::item_named`] yields
630/// fresh gix progress sinks
631/// ([`tree::Item`](Item)); all phases feed the one polled tree.
632///
633/// Shutdown is leak-proof: [`Self::finish`] (success path) and the
634/// [`Drop`] impl (a `git_clone` that bails via `?`) both signal the
635/// poll thread to stop and join it, then clear the bar — never detached,
636/// never leaked. Under the release profile's `panic = "abort"`, `Drop`
637/// does not run on a panic, but the whole process aborts so the poll
638/// thread cannot outlive it either.
639pub(crate) struct CloneProgress {
640    /// The prodash progress tree gix writes into. Shared (`Arc`) with
641    /// the poll thread, which snapshots it.
642    root: Arc<Root>,
643    /// The indicatif bar the poll thread drives. Cleared on shutdown.
644    bar: ProgressBar,
645    /// Set by [`Self::shutdown`] to stop the poll loop.
646    stop: Arc<AtomicBool>,
647    /// The poll thread handle. Present when spawning succeeded; `None`
648    /// after [`Self::shutdown`] takes it to join or when the operating
649    /// system rejected thread creation.
650    poller: Option<JoinHandle<()>>,
651    /// Human-readable clone label, also used by non-TTY completion.
652    label: String,
653    /// True when the bar is hidden and the poller emits plain text.
654    non_tty: bool,
655    /// Start time used in the non-TTY completion line.
656    started: Instant,
657    /// Noun used by the success-only completion line (`clone`, `ref
658    /// discovery`, `snapshot fetch`). Error paths only run `Drop` and
659    /// therefore never claim completion.
660    completion_noun: String,
661}
662
663impl CloneProgress {
664    /// A fresh progress sink with an explicit top-level phase name.
665    /// Ref discovery creates this before `connect`, so an empty gix
666    /// progress tree can never hide the first network wait; archive
667    /// fallback uses it to distinguish request and streaming/extract
668    /// phases.
669    pub(crate) fn item_named(&self, phase: &str) -> Item {
670        self.root.add_child(phase.to_string())
671    }
672
673    /// Stop the poll thread, join it, and clear the bar. Consuming
674    /// form for the success path; [`Drop`] performs the same work on
675    /// the error/panic path.
676    pub(crate) fn finish(mut self) {
677        self.shutdown();
678        if self.non_tty {
679            eprintln!(
680                "{}",
681                super::util::status_line(&format!(
682                    "{}: {} complete (elapsed {})",
683                    self.label,
684                    self.completion_noun,
685                    human_elapsed(self.started.elapsed())
686                ))
687            );
688        }
689    }
690
691    /// Idempotent teardown: signal stop, join the poll thread (if any
692    /// — `Option::take` makes a second call a no-op), then clear the
693    /// bar. The join happens after both gix calls have returned, so
694    /// the poll thread is never holding the snapshot lock across it.
695    fn shutdown(&mut self) {
696        self.stop.store(true, Ordering::Relaxed);
697        if let Some(handle) = self.poller.take() {
698            let _ = handle.join();
699        }
700        self.bar.finish_and_clear();
701    }
702}
703
704impl Drop for CloneProgress {
705    fn drop(&mut self) {
706        self.shutdown();
707    }
708}
709
710#[cfg(test)]
711mod tests {
712    use super::*;
713
714    /// A force-hidden group, independent of whether the test host has a
715    /// TTY. Constructs `FetchProgress` directly (white-box: the tests
716    /// are a child module of `progress`) so no production-only `hidden`
717    /// constructor is needed.
718    fn hidden_group() -> FetchProgress {
719        FetchProgress {
720            multi: MultiProgress::with_draw_target(ProgressDrawTarget::hidden()),
721        }
722    }
723
724    /// Under nextest, stderr is captured (not a TTY), so the default
725    /// group degrades to a hidden draw target — the arm CI runs.
726    #[test]
727    fn fetch_progress_new_is_hidden_under_non_tty() {
728        assert!(
729            FetchProgress::new().is_hidden(),
730            "a non-TTY FetchProgress must use a hidden draw target so piped/CI stderr stays clean",
731        );
732    }
733
734    /// A determinate download bar tracks `inc` exactly and exposes the
735    /// configured total — the contract `DownloadStream` relies on
736    /// (position advances by the bytes it streams).
737    #[test]
738    fn download_bar_determinate_tracks_inc() {
739        let fp = hidden_group();
740        let bar = fp.download_bar("6.14.2", Some(100));
741        bar.pb.inc(40);
742        bar.pb.inc(60);
743        assert_eq!(bar.pb.position(), 100);
744        assert_eq!(bar.pb.length(), Some(100));
745    }
746
747    /// With no Content-Length the bar is indeterminate (no total) but
748    /// still counts bytes — a live counter rather than a percent bar.
749    #[test]
750    fn download_bar_indeterminate_when_no_total() {
751        let fp = hidden_group();
752        let bar = fp.download_bar("6.15-rc3", None);
753        assert_eq!(bar.pb.length(), None);
754        bar.pb.inc(10);
755        assert_eq!(bar.pb.position(), 10);
756    }
757
758    /// `finish` is idempotent and the `Drop` impl also clears — neither
759    /// the explicit-finish nor the drop-without-finish path panics.
760    #[test]
761    fn download_bar_finish_and_drop_no_panic() {
762        let fp = hidden_group();
763        let bar = fp.download_bar("k", Some(10));
764        bar.finish();
765        bar.finish();
766        drop(bar);
767        // A bar dropped without an explicit finish (error path) clears
768        // via Drop without panic.
769        let bar2 = fp.download_bar("k2", Some(10));
770        bar2.pb.inc(5);
771        drop(bar2);
772    }
773
774    /// Adding and driving many bars concurrently from worker threads
775    /// (the rayon `resolve_specs_parallel` shape) must not panic or
776    /// deadlock — `MultiProgress` serializes `add` on its `RwLock`,
777    /// and `FetchProgress` is `Sync` so `&fp` shares across threads.
778    #[test]
779    fn fetch_progress_concurrent_bars_no_panic() {
780        let fp = hidden_group();
781        std::thread::scope(|s| {
782            for i in 0..16u32 {
783                let fp = &fp;
784                s.spawn(move || {
785                    let bar = fp.download_bar(&format!("k{i}"), Some(50));
786                    for _ in 0..50 {
787                        bar.pb.inc(1);
788                    }
789                    assert_eq!(bar.pb.position(), 50, "each bar accounts independently");
790                    bar.finish();
791                });
792            }
793        });
794        fp.clear();
795    }
796
797    /// A hidden group still polls the gix tree so CI receives
798    /// plain-text heartbeats, while its indicatif bar remains hidden.
799    #[test]
800    fn clone_progress_hidden_runs_plain_text_poller() {
801        let fp = hidden_group();
802        let cp = fp.clone_progress("for-next");
803        assert!(
804            cp.poller.is_some(),
805            "hidden group must poll gix for non-TTY heartbeats",
806        );
807        assert!(cp.non_tty);
808        let _item = cp.item_named("clone");
809        cp.finish();
810    }
811
812    #[test]
813    fn operation_progress_carries_explicit_phase_and_completion_labels() {
814        let fp = hidden_group();
815        let cp = fp.operation_progress(
816            "cargo ktstr: for-next",
817            "resolving git ref",
818            "ref discovery",
819        );
820        assert!(cp.non_tty);
821        assert_eq!(cp.completion_noun, "ref discovery");
822        let phase = cp.item_named("discovering refs");
823        let mut snapshot = Vec::new();
824        cp.root.sorted_snapshot(&mut snapshot);
825        assert!(
826            snapshot
827                .iter()
828                .any(|(_, task)| task.name == "discovering refs"),
829            "the phase created before connect must be visible to the heartbeat poller",
830        );
831        drop(phase);
832        drop(cp);
833    }
834
835    #[test]
836    fn poller_spawn_failure_is_nonfatal_and_drop_safe() {
837        TEST_FAIL_NEXT_POLLER_SPAWN.with(|flag| flag.set(true));
838        let cp = CloneProgress::standalone_operation("injected", "fetching", "fetch");
839        assert!(
840            cp.poller.is_none(),
841            "spawn failure must degrade to a reporter without a poll thread"
842        );
843        let _phase = cp.item_named("operation still usable");
844        drop(cp);
845    }
846
847    /// The poll thread shuts down and joins cleanly. Constructs a
848    /// `CloneProgress` over a real (unrendered) tree with the poller
849    /// running, then `finish` must stop + join within one tick without
850    /// hanging — pinning the leak-proof shutdown path.
851    #[test]
852    fn clone_progress_finish_joins_poll_thread() {
853        let root = Root::new();
854        let bar = ProgressBar::hidden();
855        let stop = Arc::new(AtomicBool::new(false));
856        let poller = std::thread::spawn({
857            let root = Arc::clone(&root);
858            let bar = bar.clone();
859            let stop = Arc::clone(&stop);
860            move || poll_clone_tree(root, bar, stop, "for-next".to_string(), false)
861        });
862        let cp = CloneProgress {
863            root,
864            bar,
865            stop,
866            poller: Some(poller),
867            label: "for-next".to_string(),
868            non_tty: false,
869            started: Instant::now(),
870            completion_noun: "clone".to_string(),
871        };
872        // Must not hang: sets stop, the loop exits within one TICK, join
873        // returns.
874        cp.finish();
875    }
876
877    /// A bounded gix task (known total) maps onto a determinate bar:
878    /// length = `done_at`, position = `step`. Deterministic — drives
879    /// the tree and runs one tick, no thread, no sleep.
880    #[test]
881    fn poll_tick_maps_bounded_task_to_determinate_bar() {
882        let root = Root::new();
883        let bar = ProgressBar::hidden();
884        let child = root.add_child("receiving objects");
885        child.init(Some(200), None);
886        child.set(80);
887
888        let mut determinate = false;
889        let mut snapshot = Vec::new();
890        poll_tick(&root, &bar, &mut determinate, "for-next", &mut snapshot);
891
892        assert!(
893            determinate,
894            "a bounded task must switch the bar to determinate"
895        );
896        assert_eq!(bar.length(), Some(200));
897        assert_eq!(bar.position(), 80);
898    }
899
900    /// An unbounded gix task (no total — e.g. the negotiation phase)
901    /// leaves the bar in spinner mode: `determinate` stays false and no
902    /// length is set.
903    #[test]
904    fn poll_tick_unbounded_task_stays_spinner() {
905        let root = Root::new();
906        let bar = ProgressBar::hidden();
907        let child = root.add_child("negotiate");
908        child.init(None, None);
909        child.set(3);
910
911        let mut determinate = false;
912        let mut snapshot = Vec::new();
913        poll_tick(&root, &bar, &mut determinate, "for-next", &mut snapshot);
914
915        assert!(
916            !determinate,
917            "an unbounded task must not flip the bar to determinate",
918        );
919        assert_eq!(bar.length(), None, "no total ⇒ no determinate length");
920    }
921
922    /// Once a bounded task has flipped the bar to determinate, a later
923    /// snapshot whose only live task is unbounded flips it back to
924    /// spinner mode — the bounded→unbounded transition branch in
925    /// `poll_tick` (gix can drop a bounded child before the next bounded
926    /// phase appears).
927    #[test]
928    fn poll_tick_flips_back_to_spinner_when_unbounded() {
929        let root = Root::new();
930        let bar = ProgressBar::hidden();
931        let mut snapshot = Vec::new();
932        let mut determinate = false;
933
934        let bounded = root.add_child("resolving deltas");
935        bounded.init(Some(50), None);
936        bounded.set(10);
937        poll_tick(&root, &bar, &mut determinate, "for-next", &mut snapshot);
938        assert!(determinate, "a bounded task must flip to determinate first");
939
940        // Drop the bounded task (gix removes a finished child from the
941        // tree) and leave only an unbounded one.
942        drop(bounded);
943        let unbounded = root.add_child("negotiate");
944        unbounded.init(None, None);
945        unbounded.set(1);
946        poll_tick(&root, &bar, &mut determinate, "for-next", &mut snapshot);
947        assert!(
948            !determinate,
949            "an unbounded-only snapshot must flip the bar back to spinner mode",
950        );
951    }
952
953    /// `println` on a hidden group selects the `eprintln!` arm (gated by
954    /// `is_hidden()`) rather than `multi.println` — which would swallow
955    /// the line on a hidden draw target — and does not panic. Pins
956    /// branch selection + no-panic; like the sibling `Spinner` tests it
957    /// does not capture stderr to assert the bytes are emitted (that is
958    /// std `eprintln!` behavior). The anti-swallow rationale is
959    /// documented on [`FetchProgress::println`] itself.
960    #[test]
961    fn fetch_progress_println_hidden_no_panic() {
962        let fp = hidden_group();
963        // is_hidden() == true selects the eprintln! arm inside println.
964        assert!(fp.is_hidden());
965        fp.println("cargo ktstr: downloading linux-6.14.2 (130.0 MiB)");
966    }
967
968    /// Several real poll threads created and shut down concurrently from
969    /// worker threads (the rayon multi-`git+URL` fan-out shape) must
970    /// neither panic nor hang — pins the concurrent clone-shutdown path
971    /// that the single-threaded `clone_progress_finish_joins_poll_thread`
972    /// test does not reach.
973    #[test]
974    fn concurrent_clone_progress_shutdown_no_panic() {
975        std::thread::scope(|s| {
976            for _ in 0..8 {
977                s.spawn(|| {
978                    let root = Root::new();
979                    let bar = ProgressBar::hidden();
980                    let stop = Arc::new(AtomicBool::new(false));
981                    let poller = std::thread::spawn({
982                        let root = Arc::clone(&root);
983                        let bar = bar.clone();
984                        let stop = Arc::clone(&stop);
985                        move || poll_clone_tree(root, bar, stop, "ref".to_string(), false)
986                    });
987                    let cp = CloneProgress {
988                        root,
989                        bar,
990                        stop,
991                        poller: Some(poller),
992                        label: "ref".to_string(),
993                        non_tty: false,
994                        started: Instant::now(),
995                        completion_noun: "clone".to_string(),
996                    };
997                    let _ = cp.item_named("clone");
998                    cp.finish();
999                });
1000            }
1001        });
1002    }
1003
1004    #[test]
1005    fn concurrent_hidden_clone_reporters_no_panic_or_deadlock() {
1006        let fp = hidden_group();
1007        let entered = std::sync::Barrier::new(9);
1008        let release = std::sync::Barrier::new(9);
1009        std::thread::scope(|scope| {
1010            for i in 0..8 {
1011                let fp = &fp;
1012                let entered = &entered;
1013                let release = &release;
1014                scope.spawn(move || {
1015                    let cp = fp.clone_progress(&format!("ci-ref-{i}"));
1016                    let item = cp.item_named("clone");
1017                    item.init(Some(1), gix::progress::count("objects"));
1018                    item.set(1);
1019                    entered.wait();
1020                    release.wait();
1021                    cp.finish();
1022                });
1023            }
1024            entered.wait();
1025            release.wait();
1026        });
1027    }
1028
1029    #[test]
1030    fn non_tty_clone_reporter_emits_percent_and_heartbeat_without_spam() {
1031        let root = Root::new();
1032        let task = root.add_child("indexing objects");
1033        task.init(Some(100), gix::progress::count("objects"));
1034        task.set(0);
1035        let start = Instant::now();
1036        let mut reporter = NonTtyCloneReporter::new(start);
1037        let mut snapshot = Vec::new();
1038
1039        root.sorted_snapshot(&mut snapshot);
1040        assert!(
1041            reporter
1042                .update(&snapshot, start)
1043                .expect("new phase")
1044                .contains("indexing objects"),
1045        );
1046        assert!(
1047            reporter
1048                .update(&snapshot, start + Duration::from_secs(1))
1049                .is_none(),
1050            "unchanged work before the heartbeat stays quiet",
1051        );
1052
1053        task.set(9);
1054        root.sorted_snapshot(&mut snapshot);
1055        assert!(
1056            reporter
1057                .update(&snapshot, start + Duration::from_secs(2))
1058                .is_none(),
1059            "work inside one ten-percent bucket stays quiet",
1060        );
1061        task.set(10);
1062        root.sorted_snapshot(&mut snapshot);
1063        assert!(
1064            reporter
1065                .update(&snapshot, start + Duration::from_secs(3))
1066                .expect("ten-percent boundary")
1067                .contains("10"),
1068        );
1069        assert!(
1070            reporter
1071                .update(&snapshot, start + Duration::from_secs(3) + CLONE_HEARTBEAT,)
1072                .expect("heartbeat")
1073                .contains("indexing objects"),
1074        );
1075    }
1076
1077    #[test]
1078    fn non_tty_clone_reporter_emits_unbounded_phase_changes() {
1079        let root = Root::new();
1080        let negotiate = root.add_child("negotiate");
1081        let start = Instant::now();
1082        let mut reporter = NonTtyCloneReporter::new(start);
1083        let mut snapshot = Vec::new();
1084        root.sorted_snapshot(&mut snapshot);
1085        assert_eq!(
1086            reporter.update(&snapshot, start).as_deref(),
1087            Some("negotiate (elapsed 0s)"),
1088        );
1089
1090        drop(negotiate);
1091        let receive = root.add_child("read pack");
1092        receive.init(None, gix::progress::bytes());
1093        receive.set(1024);
1094        root.sorted_snapshot(&mut snapshot);
1095        let line = reporter
1096            .update(&snapshot, start + Duration::from_millis(1))
1097            .expect("phase change");
1098        assert!(line.contains("read pack"));
1099        assert!(line.contains("KiB") || line.contains("KB") || line.contains("1024"));
1100    }
1101
1102    #[test]
1103    fn non_tty_clone_reporter_emits_when_same_phase_changes_boundedness() {
1104        let root = Root::new();
1105        let task = root.add_child("receiving objects");
1106        task.init(None, gix::progress::count("objects"));
1107        let start = Instant::now();
1108        let mut reporter = NonTtyCloneReporter::new(start);
1109        let mut snapshot = Vec::new();
1110        root.sorted_snapshot(&mut snapshot);
1111        assert!(
1112            reporter
1113                .update(&snapshot, start)
1114                .expect("initial unbounded phase")
1115                .contains("receiving objects"),
1116        );
1117
1118        task.init(Some(100), gix::progress::count("objects"));
1119        task.set(1);
1120        root.sorted_snapshot(&mut snapshot);
1121        let line = reporter
1122            .update(&snapshot, start + Duration::from_millis(1))
1123            .expect("unbounded-to-bounded transition emits immediately");
1124        assert!(line.contains("1/100") || line.contains("1 of 100"));
1125
1126        task.init(None, gix::progress::count("objects"));
1127        task.set(2);
1128        root.sorted_snapshot(&mut snapshot);
1129        let line = reporter
1130            .update(&snapshot, start + Duration::from_millis(2))
1131            .expect("bounded-to-unbounded transition emits immediately");
1132        assert!(line.contains('2'));
1133        assert!(!line.contains("/100") && !line.contains("of 100"));
1134    }
1135
1136    #[test]
1137    fn non_tty_clone_reporter_heartbeats_empty_tree_with_elapsed_time() {
1138        let start = Instant::now();
1139        let mut reporter = NonTtyCloneReporter::new(start);
1140        let snapshot = Vec::new();
1141        assert_eq!(
1142            reporter.update(&snapshot, start).as_deref(),
1143            Some("waiting for remote (elapsed 0s)"),
1144        );
1145        assert!(
1146            reporter
1147                .update(&snapshot, start + Duration::from_secs(9))
1148                .is_none(),
1149            "empty tree must not spam before the heartbeat",
1150        );
1151        assert_eq!(
1152            reporter
1153                .update(&snapshot, start + Duration::from_secs(10))
1154                .as_deref(),
1155            Some("waiting for remote (elapsed 10s)"),
1156        );
1157        assert_eq!(human_elapsed(Duration::from_secs(65)), "1m 05s");
1158        assert_eq!(human_elapsed(Duration::from_secs(3661)), "1h 01m 01s");
1159    }
1160
1161    /// A `step_bar` is a label-only spinner: no byte counter (length is
1162    /// `None`), and finish + drop-without-finish are both clean.
1163    #[test]
1164    fn step_bar_no_counter_no_panic() {
1165        let fp = hidden_group();
1166        let bar = fp.step_bar("Building kernel...");
1167        assert_eq!(
1168            bar.pb.length(),
1169            None,
1170            "a step bar has no quantifiable total"
1171        );
1172        bar.finish();
1173        // Drop-without-finish (the build error path) must also be clean.
1174        drop(fp.step_bar("Configuring kernel..."));
1175    }
1176
1177    /// Many build-phase `step_bar`s driven concurrently on one group
1178    /// (the parallel-resolve shape where multiple workers build at once)
1179    /// must not panic. Direct regression pin for the old
1180    /// concurrent-`Spinner` `SPINNER_ACTIVE` race that this change
1181    /// removes by routing the build phase through the group instead of a
1182    /// standalone `Spinner`.
1183    #[test]
1184    fn concurrent_step_bars_no_panic() {
1185        let fp = hidden_group();
1186        std::thread::scope(|s| {
1187            for i in 0..16u32 {
1188                let fp = &fp;
1189                s.spawn(move || {
1190                    let bar = fp.step_bar(&format!("Building kernel {i}..."));
1191                    bar.finish();
1192                });
1193            }
1194        });
1195        fp.clear();
1196    }
1197}