feat: callback-based progress tracking for uploads and downloads

[assafvayner]

Summary

• Adds a ProgressHandler trait and structured ProgressEvent types (UploadEvent, DownloadEvent) that allow callers to receive real-time progress callbacks during file transfers
• Upload events carry phase information (Preparing → CheckingUploadMode → Uploading → Committing) plus aggregate byte progress
• Download events carry per-file byte progress (Started → InProgress → Complete) and aggregate xet progress
• All five transfer params structs gain an optional progress: Progress field (Option<Arc<dyn ProgressHandler>>) that defaults to None — existing callers are unaffected
• The hfrs CLI wires up an indicatif-based handler (CliProgressHandler) that renders multi-progress bars, respects --quiet and HF_HUB_DISABLE_PROGRESS_BARS
• Xet uploads emit progress before/after commit via GroupProgressReport
• Removes the polling-based progress tracking design spec (superseded by the callback approach)

New files

File	Purpose
huggingface_hub/src/types/progress.rs	Core types: ProgressHandler, ProgressEvent, UploadEvent, DownloadEvent, FileProgress, FileStatus, UploadPhase, Progress, emit()
huggingface_hub/src/bin/hfrs/progress.rs	CliProgressHandler with indicatif MultiProgress

Key design decisions

• Nested enum (ProgressEvent::Upload(UploadEvent)) separates upload/download concerns at the type level
• Phase on every upload event so consumers always know the current phase from any single event — no state tracking needed
• Delta-only download progress — only files whose state changed since last event
• Progress type alias (Option<Arc<dyn ProgressHandler>>) keeps params structs clean
• Blocking API unaffected — progress passes through as part of the params struct via existing sync_api! macros

Test plan

• Unit tests in types/progress.rs — event recording, phase progression, batched file complete, None handler is no-op, Send+Sync compile check (6 tests)
• Integration tests in tests/download_test.rs — download with progress to local dir, download with progress to cache, download without progress handler (3 tests)
• cargo +nightly fmt --check passes
• cargo clippy --all-features -D warnings passes
• cargo test -p huggingface-hub --lib — 67 tests pass
• cargo build --release succeeds
• CI runs cargo test -p huggingface-hub --all-features which picks up all new unit and integration tests automatically

[assafvayner]

poll not push

[assafvayner]

push, not poll

[assafvayner]

Code review

Found 2 issues:

1. download_file emits Start { total_bytes: 0 } before the HEAD request, so the CLI bytes progress bar is never created for single-file non-xet downloads. CliProgressHandler only creates the bar when total_bytes > 0 && total_files == 1, which never holds. The design spec says total_bytes should be known at Start (from the HEAD response).

huggingface_hub_rust/huggingface_hub/src/api/files.rs

Lines 111 to 120 in b340113

	pub async fn download_file(&self, params: &RepoDownloadFileParams) -> Result<PathBuf> {
	progress::emit(
	&params.progress,
	ProgressEvent::Download(DownloadEvent::Start {
	total_files: 1,
	total_bytes: 0,
	}),
	);
	let result = self.download_file_inner(params).await;
	if result.is_ok() {

2. For inline (non-xet/non-LFS) uploads, the bytes_bar is created in the Start handler but never updated. bytes_bar.set_position() is only called when phase == UploadPhase::Uploading (line 213), but inline uploads skip the Uploading phase entirely -- they go Preparing -> CheckingUploadMode -> Committing. The bar stays at position 0 for the entire upload.

huggingface_hub_rust/huggingface_hub/src/bin/hfrs/progress.rs

Lines 212 to 218 in b340113

	if *phase == UploadPhase::Uploading
	&& let Some(ref bar) = state.bytes_bar
	{
	bar.set_length(*total_bytes);
	bar.set_position(*bytes_completed);
	}

🤖 Generated with Claude Code

_{- If this code review was useful, please react with 👍. Otherwise, react with 👎.}