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}