1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
//! Module install - Streaming download of toolchain archives with progress reporting.
use super::{GoManager, archive};
use crate::{errors::GovmError, logging, version::GoVersion};
use futures_util::StreamExt;
use std::{
fs,
path::{Path, PathBuf},
time::Instant,
};
use tokio::io::AsyncWriteExt;
// ------------------------------------------ Types & Impls ------------------------------------- //
/// Lifecycle progress events emitted while a toolchain is being installed.
#[derive(Debug, Clone, Copy)]
pub(crate) enum InstallProgress {
/// A chunk of the archive finished downloading.
Downloading {
/// Number of bytes downloaded so far.
downloaded: u64,
/// Total archive size in bytes (0 if the server did not report it).
total: u64,
/// Smoothed download speed in bytes per second.
bytes_per_sec: f64,
},
/// The archive has finished downloading and is being unpacked to disk.
Extracting,
}
impl GoManager {
/// Asynchronously streams and extracts a target Go toolchain archive.
///
/// # Arguments
/// * `version` - The version metadata to install.
/// * `progress` - Callback invoked with [`InstallProgress`] events as the install advances.
///
/// # Errors
/// Returns [`GovmError`] on download failure, IO interruption, or extraction error.
pub(crate) async fn download_and_install<F>(
&self,
version: &GoVersion,
progress: F,
) -> Result<PathBuf, GovmError>
where
F: Fn(InstallProgress) + Send + 'static,
{
let download_path = self.downloads_dir.join(&version.filename);
let target_dir = self.versions_dir.join(format!("go{}", version.raw_version));
let expected_bytes = version.size;
// `size` is the manifest's own figure; when it is absent (0) say so
// rather than printing a misleading "0 B" as if it were measured.
let size_note = if expected_bytes > 0 {
format!(" size=\"{}\"", GoVersion::format_size(expected_bytes))
} else {
" size=unknown".to_string()
};
logging::info(&format!(
"install: started version={} url={} dest=\"{}\" bytes={expected_bytes}{size_note}",
version.raw_version,
version.url,
download_path.display()
));
let started_at = Instant::now();
let is_tar = version.filename.ends_with(".tar.gz");
self.download_archive(version, &download_path, is_tar, &progress)
.await?;
if target_dir.exists() {
fs::remove_dir_all(&target_dir)?;
}
fs::create_dir_all(&target_dir)?;
let dl_path_clone = download_path.clone();
let target_dir_clone = target_dir.clone();
// Measured before extraction deletes the archive, so the log records how
// much was on disk even when unpacking then fails halfway through.
let archive_bytes = fs::metadata(&download_path).map_or(0, |meta| meta.len());
// The archive is fully on disk, so the blocking extraction work moves
// onto the blocking pool instead of stalling the async runtime.
let extraction = tokio::task::spawn_blocking(move || {
archive::extract_archive(&dl_path_clone, &target_dir_clone, is_tar)
})
.await
.map_err(|e| GovmError::Extraction(e.to_string()))?;
// Deliberately not logged here: `handle_install_failed` owns the single
// `install: failed` line, and returning twice as loud is how one 404
// used to become two ERROR lines.
extraction?;
logging::info(&format!(
"install: complete version={} dest=\"{}\" archive_bytes={archive_bytes} elapsed_s={:.1}",
version.raw_version,
target_dir.display(),
started_at.elapsed().as_secs_f64()
));
Ok(target_dir)
}
/// Streams the archive for `version` to `download_path`, reporting live
/// progress, then validates the payload's magic bytes before extraction.
///
/// # Arguments
/// * `version` - The version metadata to install.
/// * `download_path` - Destination file the archive is streamed into.
/// * `is_tar` - Whether a `.tar.gz` (true) or `.zip` payload is expected.
/// * `progress` - Callback invoked with [`InstallProgress`] events.
///
/// # Errors
/// Returns [`GovmError`] on download failure, IO interruption, or an
/// unexpected (non-archive) payload.
async fn download_archive<F>(
&self,
version: &GoVersion,
download_path: &Path,
is_tar: bool,
progress: &F,
) -> Result<(), GovmError>
where
F: Fn(InstallProgress),
{
// Local timer for the transfer only; the install-wide duration (which also
// covers extraction) is measured by the caller.
let transfer_started_at = Instant::now();
let res = self.client.get(&version.url).send().await?;
let status = res.status();
let final_url = res.url().clone(); // where we *actually* ended up
logging::debug(&format!(
"download: response status={status} url={final_url} requested={}",
version.url
));
// No log line for a bad status: the `download response` DEBUG line above
// already carries status + final URL, and the handler logs the failure.
if !status.is_success() {
return Err(GovmError::HttpStatus {
status: status.as_u16(),
url: final_url.to_string(),
});
}
let total_size = res.content_length().unwrap_or(version.size);
let mut downloaded: u64 = 0;
let mut stream = res.bytes_stream();
// Throttling / speed estimation state.
let mut last_report = Instant::now();
let mut last_bytes: u64 = 0;
let mut smoothed_speed: f64 = 0.0;
let mut last_pct_reported: u8 = 0;
let mut file = tokio::fs::File::create(download_path).await?;
while let Some(chunk) = stream.next().await {
let chunk = chunk?;
file.write_all(&chunk).await?;
downloaded += chunk.len() as u64;
// Emit progress at most ~4x per second, or whenever a whole percent is crossed,
// so high-frequency chunk arrivals don't flood the UI.
let now = Instant::now();
let elapsed = now.duration_since(last_report).as_secs_f64();
if elapsed >= 0.25 || total_size == 0 {
// Byte deltas stay far below 2^53, so the f64 cast cannot lose
// precision for any realistic download.
#[allow(clippy::cast_precision_loss)]
let instant_speed = (downloaded - last_bytes) as f64 / elapsed.max(1e-3);
// Exponential moving average for a smoother speed readout.
smoothed_speed = if smoothed_speed == 0.0 {
instant_speed
} else {
smoothed_speed * 0.6 + instant_speed * 0.4
};
// The ratio is bounded to 0..=100 by construction, so the u8
// cast can neither truncate meaningfully nor flip the sign.
#[allow(
clippy::cast_precision_loss,
clippy::cast_possible_truncation,
clippy::cast_sign_loss
)]
let pct = if total_size > 0 {
((downloaded as f64 / total_size as f64) * 100.0) as u8
} else {
0
};
if elapsed >= 0.25 || pct > last_pct_reported || total_size == 0 {
progress(InstallProgress::Downloading {
downloaded,
total: total_size,
bytes_per_sec: smoothed_speed,
});
last_pct_reported = pct;
last_report = now;
last_bytes = downloaded;
}
}
}
file.flush().await?;
// Integer math keeps the figures exact and free of lossy float casts;
// `max(1)` guarantees the divide-by-zero case cannot happen.
let elapsed_ms = transfer_started_at.elapsed().as_millis().max(1);
let avg_bps = u64::try_from(u128::from(downloaded) * 1000 / elapsed_ms).unwrap_or(u64::MAX);
logging::info(&format!(
"download: complete version={} bytes={} dest=\"{}\" elapsed_ms={elapsed_ms} avg_bps={avg_bps}",
version.raw_version,
downloaded,
download_path.display()
));
if total_size > 0 && downloaded != total_size {
logging::warn(&format!(
"download: size mismatch expected_bytes={total_size} received_bytes={downloaded} url={final_url}"
));
}
// Final 100% report, then flip to the extraction phase.
progress(InstallProgress::Downloading {
downloaded,
total: total_size,
bytes_per_sec: smoothed_speed,
});
progress(InstallProgress::Extracting);
// Forensic breadcrumb: what did we ACTUALLY save? `1f 8b` = real gzip;
// `3c 68 74 6d` ("<htm") = HTML error page; plain tar bytes = something
// pre-decoded our stream. Read once and reuse the same head for the
// magic check — probing twice used to write the identical line twice.
let head = archive::read_head(download_path, 16);
if let Some(bytes) = &head {
let hex: Vec<String> = bytes.iter().map(|b| format!("{b:02x}")).collect();
logging::debug(&format!(
"archive: head path=\"{}\" bytes=\"{}\" expected=\"{}\"",
download_path.display(),
hex.join(" "),
if is_tar { "1f 8b" } else { "50 4b" }
));
}
archive::check_archive_magic(
head.as_deref().unwrap_or_default(),
is_tar,
final_url.as_str(),
)?;
Ok(())
}
}