use serde::Serialize;
use std::io::{Read, Write};
use std::path::{Path, PathBuf};
use std::sync::atomic::{AtomicBool, Ordering};
use std::sync::{Arc, Mutex};
use std::time::{Duration, Instant};
#[derive(Debug, PartialEq, Eq)]
pub struct BaseImage {
pub url: &'static str,
pub sha256: &'static str,
pub arch: &'static str,
}
pub const IMAGES: &[BaseImage] = &[
BaseImage {
url: "https://cloud-images.ubuntu.com/releases/resolute/release-20261016/ubuntu-26.04-server-cloudimg-arm64.img",
sha256: "8eb876c2ccc4b6ff89e4a65d511815923b285e04503ba465809bf587f763da24",
arch: "aarch64",
},
BaseImage {
url: "https://cloud-images.ubuntu.com/releases/resolute/release-20261016/ubuntu-26.04-server-cloudimg-amd64.img",
sha256: "5645d0318ad21f643ebb1ac4567514620e9893380b07b0201fda163baa5b7eb5",
arch: "x86_64",
},
];
pub fn image_for(arch: &str) -> Option<&'static BaseImage> {
IMAGES.iter().find(|i| i.arch == arch)
}
pub fn cache_dir() -> Option<PathBuf> {
crate::credentials::dir().map(|d| d.join("lima-cache"))
}
pub fn cached_path(dir: &Path, img: &BaseImage) -> PathBuf {
dir.join(format!("ubuntu-{}-{}.img", img.arch, &img.sha256[..16]))
}
pub fn cached_image() -> Option<(PathBuf, &'static BaseImage)> {
let img = image_for(std::env::consts::ARCH)?;
let p = cached_path(&cache_dir()?, img);
p.is_file().then_some((p, img))
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
#[serde(rename_all = "lowercase")]
pub enum Phase {
Idle,
Downloading,
Verifying,
Starting,
Ready,
Failed,
}
#[derive(Debug, Clone, PartialEq, Serialize)]
pub struct State {
pub phase: Phase,
pub done: u64,
pub total: Option<u64>,
#[serde(skip_serializing_if = "Option::is_none")]
pub reason: Option<String>,
#[serde(skip_serializing_if = "Option::is_none")]
pub diagnostics: Option<String>,
}
impl State {
pub fn at(phase: Phase) -> Self {
Self {
phase,
done: 0,
total: None,
reason: None,
diagnostics: None,
}
}
fn failed(reason: &str, diagnostics: String) -> Self {
Self {
reason: Some(reason.to_string()),
diagnostics: Some(diagnostics),
..Self::at(Phase::Failed)
}
}
}
#[derive(Debug, PartialEq, Eq)]
pub enum Fetch {
Done,
Gone,
}
pub fn download(
url: &str,
sha256: &str,
dest: &Path,
progress: &mut dyn FnMut(u64, Option<u64>),
verifying: &mut dyn FnMut(),
) -> Result<Fetch, String> {
if let Some(d) = dest.parent() {
std::fs::create_dir_all(d).map_err(|e| format!("cannot create {}: {e}", d.display()))?;
}
let part = dest.with_extension("part");
let agent = ureq::Agent::new_with_config(
ureq::Agent::config_builder()
.http_status_as_error(false)
.timeout_connect(Some(Duration::from_secs(30)))
.timeout_recv_response(Some(ATTEMPT_CAP))
.build(),
);
let mut idle = 0;
loop {
let before = std::fs::metadata(&part).map(|m| m.len()).unwrap_or(0);
match attempt(&agent, url, &part, progress)? {
Some(fetch) => {
if fetch == Fetch::Gone {
return Ok(Fetch::Gone);
}
break;
}
None => {
let after = std::fs::metadata(&part).map(|m| m.len()).unwrap_or(0);
idle = if after > before { 0 } else { idle + 1 };
if idle >= IDLE_ATTEMPTS {
return Err(format!(
"download stopped making progress after {after} bytes ({IDLE_ATTEMPTS} attempts)"
));
}
}
}
}
verifying();
let got = sha256_file(&part)?;
if got != sha256 {
let _ = std::fs::remove_file(&part);
return Err(format!(
"{url}: sha256 {got} does not match the pinned {sha256}"
));
}
std::fs::rename(&part, dest).map_err(|e| format!("cannot move the image into place: {e}"))?;
Ok(Fetch::Done)
}
const ATTEMPT_CAP: Duration = Duration::from_secs(15 * 60);
const IDLE_ATTEMPTS: u32 = 3;
fn attempt(
agent: &ureq::Agent,
url: &str,
part: &Path,
progress: &mut dyn FnMut(u64, Option<u64>),
) -> Result<Option<Fetch>, String> {
let have = std::fs::metadata(part).map(|m| m.len()).unwrap_or(0);
let mut req = agent.get(url);
if have > 0 {
req = req.header("Range", format!("bytes={have}-"));
}
let mut resp = match req.call() {
Ok(r) => r,
Err(_) => return Ok(None),
};
let status = resp.status().as_u16();
let len = resp
.headers()
.get("content-length")
.and_then(|v| v.to_str().ok())
.and_then(|v| v.parse::<u64>().ok());
let (start, total, append) = match status {
404 | 410 => return Ok(Some(Fetch::Gone)),
206 => (have, len.map(|l| l + have), true),
200 => (0, len, false),
416 => return Ok(Some(Fetch::Done)),
s => return Err(format!("GET {url}: HTTP {s}")),
};
let mut done = start;
progress(done, total);
let mut f = std::fs::OpenOptions::new()
.create(true)
.write(true)
.append(append)
.truncate(!append)
.open(part)
.map_err(|e| format!("cannot write {}: {e}", part.display()))?;
let mut body = resp.body_mut().with_config().limit(u64::MAX).reader();
let mut buf = vec![0u8; 1 << 20];
while let Ok(n) = body.read(&mut buf) {
if n == 0 {
break;
}
f.write_all(&buf[..n])
.map_err(|e| format!("cannot write {}: {e}", part.display()))?;
done += n as u64;
progress(done, total);
}
f.sync_all().ok();
Ok(match total {
Some(t) if done < t => None,
_ => Some(Fetch::Done),
})
}
fn sha256_file(p: &Path) -> Result<String, String> {
let mut f = std::fs::File::open(p).map_err(|e| format!("cannot read {}: {e}", p.display()))?;
let mut ctx = ring::digest::Context::new(&ring::digest::SHA256);
let mut buf = vec![0u8; 1 << 20];
loop {
let n = f
.read(&mut buf)
.map_err(|e| format!("cannot read {}: {e}", p.display()))?;
if n == 0 {
break;
}
ctx.update(&buf[..n]);
}
Ok(hex::encode(ctx.finish().as_ref()))
}
pub trait Steps {
fn unsupported(&self) -> Option<String>;
fn missing_image(&self) -> Option<(&'static BaseImage, PathBuf)>;
fn download(
&self,
img: &BaseImage,
dest: &Path,
progress: &mut dyn FnMut(u64, Option<u64>),
verifying: &mut dyn FnMut(),
) -> Result<Fetch, String>;
fn ensure_vm(&self) -> Result<(), String>;
}
pub fn run(steps: &dyn Steps, emit: &mut dyn FnMut(State)) {
if let Some(why) = steps.unsupported() {
return emit(State::failed("This Mac can't run Zakuro's sandbox", why));
}
if let Some((img, dest)) = steps.missing_image() {
let mut last = (Instant::now(), u64::MAX);
let mut on_progress = |done: u64, total: Option<u64>| {
let pct = total.map_or(done >> 26, |t| done * 100 / t.max(1));
if pct != last.1 || last.0.elapsed() >= Duration::from_millis(500) {
last = (Instant::now(), pct);
emit(State {
done,
total,
..State::at(Phase::Downloading)
});
}
};
let mut verified = false;
let r = steps.download(img, &dest, &mut on_progress, &mut || verified = true);
if verified {
emit(State::at(Phase::Verifying));
}
match r {
Ok(_) => {}
Err(e) => {
return emit(State::failed(
"Zakuro couldn't download its sandbox; check the internet connection and retry",
e,
))
}
}
}
emit(State::at(Phase::Starting));
match steps.ensure_vm() {
Ok(()) => emit(State::at(Phase::Ready)),
Err(e) => emit(State::failed("Zakuro couldn't start its sandbox", e)),
}
}
pub const MIN_MACOS: (u32, u32) = (13, 5);
pub fn parse_macos_version(s: &str) -> Option<(u32, u32)> {
let mut it = s.trim().split('.');
let major = it.next()?.parse().ok()?;
let minor = it.next().map_or(Some(0), |m| m.parse().ok())?;
Some((major, minor))
}
pub fn macos_version() -> Option<(u32, u32)> {
if !cfg!(target_os = "macos") {
return None;
}
let out = std::process::Command::new("/usr/sbin/sysctl")
.args(["-n", "kern.osproductversion"])
.output()
.ok()?;
parse_macos_version(&String::from_utf8_lossy(&out.stdout))
}
pub fn too_old(version: Option<(u32, u32)>) -> Option<String> {
let v = version?;
(v < MIN_MACOS).then(|| {
format!(
"macOS {}.{} is too old for Lima's vz VMs: {}.{} or newer is needed",
v.0, v.1, MIN_MACOS.0, MIN_MACOS.1
)
})
}
pub struct Host;
impl Steps for Host {
fn unsupported(&self) -> Option<String> {
if !cfg!(target_os = "macos") {
return Some("the Lima sandbox is macOS only".into());
}
too_old(macos_version())
}
fn missing_image(&self) -> Option<(&'static BaseImage, PathBuf)> {
let img = image_for(std::env::consts::ARCH)?;
let p = cached_path(&cache_dir()?, img);
(!p.is_file()).then_some((img, p))
}
fn download(
&self,
img: &BaseImage,
dest: &Path,
progress: &mut dyn FnMut(u64, Option<u64>),
verifying: &mut dyn FnMut(),
) -> Result<Fetch, String> {
download(img.url, img.sha256, dest, progress, verifying)
}
fn ensure_vm(&self) -> Result<(), String> {
let rt = super::lima::LimaRuntime::shell();
match rt.ensure() {
Ok(()) => Ok(()),
Err(e) if rt.broken()? => {
rt.delete()?;
rt.ensure()
.map_err(|e2| format!("{e}; after recreating: {e2}"))
}
Err(e) => Err(e),
}
}
}
pub struct Provisioner {
state: Mutex<State>,
running: AtomicBool,
}
impl Default for Provisioner {
fn default() -> Self {
Self {
state: Mutex::new(State::at(Phase::Idle)),
running: AtomicBool::new(false),
}
}
}
impl Provisioner {
pub fn state(&self) -> State {
self.state.lock().unwrap_or_else(|p| p.into_inner()).clone()
}
pub fn start(
self: &Arc<Self>,
steps: Arc<dyn Steps + Send + Sync>,
publish: Arc<dyn Fn(&State) + Send + Sync>,
) -> State {
if self.running.swap(true, Ordering::SeqCst) {
return self.state();
}
*self.state.lock().unwrap_or_else(|p| p.into_inner()) = State::at(Phase::Idle);
let me = self.clone();
std::thread::spawn(move || {
run(steps.as_ref(), &mut |s| {
*me.state.lock().unwrap_or_else(|p| p.into_inner()) = s.clone();
publish(&s);
});
me.running.store(false, Ordering::SeqCst);
});
self.state()
}
}
#[cfg(test)]
mod tests {
use super::*;
struct Fake {
unsupported: Option<String>,
missing: bool,
fetch: Result<Fetch, String>,
vm: Result<(), String>,
}
impl Steps for Fake {
fn unsupported(&self) -> Option<String> {
self.unsupported.clone()
}
fn missing_image(&self) -> Option<(&'static BaseImage, PathBuf)> {
self.missing
.then(|| (&IMAGES[0], PathBuf::from("/nowhere")))
}
fn download(
&self,
_: &BaseImage,
_: &Path,
progress: &mut dyn FnMut(u64, Option<u64>),
verifying: &mut dyn FnMut(),
) -> Result<Fetch, String> {
for i in 0..=1000u64 {
progress(i * 1000, Some(1_000_000));
}
verifying();
match &self.fetch {
Ok(Fetch::Done) => Ok(Fetch::Done),
Ok(Fetch::Gone) => Ok(Fetch::Gone),
Err(e) => Err(e.clone()),
}
}
fn ensure_vm(&self) -> Result<(), String> {
self.vm.clone()
}
}
fn phases(f: &Fake) -> Vec<State> {
let mut out = vec![];
run(f, &mut |s| out.push(s));
out
}
#[test]
fn a_fresh_mac_downloads_verifies_starts_and_is_ready() {
let s = phases(&Fake {
unsupported: None,
missing: true,
fetch: Ok(Fetch::Done),
vm: Ok(()),
});
let names: Vec<Phase> = s.iter().map(|s| s.phase).collect();
assert_eq!(names.first(), Some(&Phase::Downloading));
assert_eq!(
&names[names.len() - 3..],
&[Phase::Verifying, Phase::Starting, Phase::Ready]
);
let downloads = names.iter().filter(|p| **p == Phase::Downloading).count();
assert!((100..=102).contains(&downloads), "{downloads}");
let last = s.iter().rfind(|s| s.phase == Phase::Downloading).unwrap();
assert_eq!((last.done, last.total), (1_000_000, Some(1_000_000)));
}
#[test]
fn a_cached_image_goes_straight_to_starting() {
let s = phases(&Fake {
unsupported: None,
missing: false,
fetch: Err("not called".into()),
vm: Ok(()),
});
assert_eq!(
s.iter().map(|s| s.phase).collect::<Vec<_>>(),
vec![Phase::Starting, Phase::Ready]
);
}
#[test]
fn an_expired_image_url_falls_back_to_limas_own_download() {
let s = phases(&Fake {
unsupported: None,
missing: true,
fetch: Ok(Fetch::Gone),
vm: Ok(()),
});
assert_eq!(s.last().unwrap().phase, Phase::Ready);
}
#[test]
fn failures_say_one_plain_sentence_and_keep_the_cause() {
let s = phases(&Fake {
unsupported: None,
missing: true,
fetch: Err("GET x: HTTP 500".into()),
vm: Ok(()),
});
let last = s.last().unwrap();
assert_eq!(last.phase, Phase::Failed);
assert!(last
.reason
.as_deref()
.unwrap()
.starts_with("Zakuro couldn't download"));
assert_eq!(last.diagnostics.as_deref(), Some("GET x: HTTP 500"));
let s = phases(&Fake {
unsupported: None,
missing: false,
fetch: Ok(Fetch::Done),
vm: Err("limactl start zakuro failed: boom".into()),
});
assert_eq!(
s.last().unwrap().reason.as_deref(),
Some("Zakuro couldn't start its sandbox")
);
let s = phases(&Fake {
unsupported: too_old(Some((12, 7))),
missing: true,
fetch: Ok(Fetch::Done),
vm: Ok(()),
});
assert_eq!(s.len(), 1);
assert!(s[0]
.diagnostics
.as_deref()
.unwrap()
.contains("macOS 12.7 is too old"));
}
#[test]
fn one_run_at_a_time_and_every_state_is_published() {
struct Slow(Mutex<std::sync::mpsc::Receiver<()>>);
impl Steps for Slow {
fn unsupported(&self) -> Option<String> {
None
}
fn missing_image(&self) -> Option<(&'static BaseImage, PathBuf)> {
None
}
fn download(
&self,
_: &BaseImage,
_: &Path,
_: &mut dyn FnMut(u64, Option<u64>),
_: &mut dyn FnMut(),
) -> Result<Fetch, String> {
unreachable!()
}
fn ensure_vm(&self) -> Result<(), String> {
self.0.lock().unwrap().recv().unwrap();
Ok(())
}
}
let (go, wait) = std::sync::mpsc::channel();
let steps: Arc<dyn Steps + Send + Sync> = Arc::new(Slow(Mutex::new(wait)));
let p = Arc::new(Provisioner::default());
let seen = Arc::new(Mutex::new(vec![]));
let s2 = seen.clone();
let publish: Arc<dyn Fn(&State) + Send + Sync> =
Arc::new(move |s| s2.lock().unwrap().push(s.phase));
assert_eq!(p.state().phase, Phase::Idle);
p.start(steps.clone(), publish.clone());
while p.state().phase != Phase::Starting {
std::thread::sleep(Duration::from_millis(5));
}
assert_eq!(p.start(steps, publish).phase, Phase::Starting);
go.send(()).unwrap();
while p.state().phase != Phase::Ready {
std::thread::sleep(Duration::from_millis(5));
}
assert_eq!(*seen.lock().unwrap(), vec![Phase::Starting, Phase::Ready]);
}
#[test]
fn macos_versions() {
assert_eq!(parse_macos_version("12.7.6\n"), Some((12, 7)));
assert_eq!(parse_macos_version("14"), Some((14, 0)));
assert_eq!(parse_macos_version(""), None);
assert!(too_old(Some((13, 4))).is_some());
assert_eq!(too_old(Some((13, 5))), None);
assert_eq!(too_old(Some((26, 1))), None);
assert_eq!(too_old(None), None);
}
#[test]
fn the_pinned_images_cover_both_mac_architectures() {
for arch in ["aarch64", "x86_64"] {
let i = image_for(arch).unwrap();
assert_eq!(i.sha256.len(), 64);
assert!(i
.url
.starts_with("https://cloud-images.ubuntu.com/releases/"));
}
}
fn serve(body: Vec<u8>, hits: Arc<Mutex<Vec<String>>>) -> String {
let l = std::net::TcpListener::bind("127.0.0.1:0").unwrap();
let addr = l.local_addr().unwrap();
std::thread::spawn(move || {
for conn in l.incoming() {
let mut c = conn.unwrap();
let mut req = vec![0u8; 4096];
let n = c.read(&mut req).unwrap();
let req = String::from_utf8_lossy(&req[..n]).to_string();
let range = req
.lines()
.find_map(|l| {
let (k, v) = l.split_once(':')?;
k.eq_ignore_ascii_case("range")
.then(|| v.trim().strip_prefix("bytes="))
.flatten()
})
.and_then(|r| r.trim_end_matches('-').parse::<usize>().ok());
hits.lock()
.unwrap()
.push(req.lines().next().unwrap_or("").into());
let (status, slice) = match range {
Some(from) => ("206 Partial Content", &body[from..]),
None => ("200 OK", &body[..]),
};
let head = format!(
"HTTP/1.1 {status}\r\nContent-Length: {}\r\nConnection: close\r\n\r\n",
slice.len()
);
c.write_all(head.as_bytes()).unwrap();
c.write_all(slice).unwrap();
}
});
format!("http://{addr}/img")
}
fn scratch(name: &str) -> PathBuf {
let d = std::env::temp_dir().join(format!("zc-provision-{name}-{}", std::process::id()));
let _ = std::fs::remove_dir_all(&d);
std::fs::create_dir_all(&d).unwrap();
d
}
#[test]
fn a_partial_download_resumes_and_is_verified() {
let body: Vec<u8> = (0..3_000_000u32).map(|i| (i % 251) as u8).collect();
let sha = hex::encode(ring::digest::digest(&ring::digest::SHA256, &body).as_ref());
let hits = Arc::new(Mutex::new(vec![]));
let url = serve(body.clone(), hits.clone());
let dir = scratch("resume");
let dest = dir.join("img");
std::fs::write(dest.with_extension("part"), &body[..1_000_000]).unwrap();
let mut seen = vec![];
let r = download(&url, &sha, &dest, &mut |d, t| seen.push((d, t)), &mut || {});
assert_eq!(r, Ok(Fetch::Done));
assert_eq!(std::fs::read(&dest).unwrap(), body);
assert!(!dest.with_extension("part").exists());
assert_eq!(seen.first(), Some(&(1_000_000, Some(3_000_000))));
assert_eq!(seen.last(), Some(&(3_000_000, Some(3_000_000))));
assert!(hits.lock().unwrap()[0].starts_with("GET /img"));
let _ = std::fs::remove_dir_all(&dir);
}
#[test]
fn a_dropped_connection_resumes_in_the_same_download() {
let body: Vec<u8> = (0..2_000_000u32).map(|i| (i % 249) as u8).collect();
let sha = hex::encode(ring::digest::digest(&ring::digest::SHA256, &body).as_ref());
let l = std::net::TcpListener::bind("127.0.0.1:0").unwrap();
let url = format!("http://{}/img", l.local_addr().unwrap());
let served = body.clone();
let ranges = Arc::new(Mutex::new(vec![]));
let seen = ranges.clone();
std::thread::spawn(move || {
for (i, conn) in l.incoming().enumerate() {
let mut c = conn.unwrap();
let mut req = vec![0u8; 4096];
let n = c.read(&mut req).unwrap();
let req = String::from_utf8_lossy(&req[..n]).to_lowercase();
let from = req
.lines()
.find_map(|l| l.strip_prefix("range: bytes="))
.and_then(|r| r.trim().trim_end_matches('-').parse::<usize>().ok())
.unwrap_or(0);
seen.lock().unwrap().push(from);
let slice = &served[from..];
let status = if from > 0 {
"206 Partial Content"
} else {
"200 OK"
};
let head = format!(
"HTTP/1.1 {status}\r\nContent-Length: {}\r\nConnection: close\r\n\r\n",
slice.len()
);
c.write_all(head.as_bytes()).unwrap();
let cut = if i == 0 { 700_000 } else { slice.len() };
let _ = c.write_all(&slice[..cut]);
}
});
let dir = scratch("dropped");
let dest = dir.join("img");
let mut checked = 0;
let r = download(&url, &sha, &dest, &mut |_, _| {}, &mut || checked += 1);
assert_eq!(r, Ok(Fetch::Done));
assert_eq!(std::fs::read(&dest).unwrap(), body);
assert_eq!(*ranges.lock().unwrap(), vec![0, 700_000]);
assert_eq!(checked, 1, "checked once, when whole");
let _ = std::fs::remove_dir_all(&dir);
}
#[test]
fn a_corrupt_download_is_deleted_not_kept() {
let body = vec![7u8; 10_000];
let url = serve(body, Arc::new(Mutex::new(vec![])));
let dir = scratch("corrupt");
let dest = dir.join("img");
let r = download(&url, &"0".repeat(64), &dest, &mut |_, _| {}, &mut || {});
assert!(r.unwrap_err().contains("does not match the pinned"));
assert!(!dest.exists() && !dest.with_extension("part").exists());
let _ = std::fs::remove_dir_all(&dir);
}
}