pub mod claim;
use std::path::{Path, PathBuf};
use serde::{Deserialize, Deserializer, Serialize};
use serde_json::{json, Value};
pub const PURPOSES: [&str; 2] = ["inference", "warmup"];
fn whole_gb<'de, D: Deserializer<'de>>(d: D) -> Result<u64, D::Error> {
let v = f64::deserialize(d)?;
Ok(if v.is_finite() && v > 0.0 {
v.floor() as u64
} else {
0
})
}
fn default_purpose() -> Vec<String> {
vec!["inference".to_string()]
}
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
pub struct HubAllocation {
pub enabled: bool,
#[serde(default, deserialize_with = "whole_gb")]
pub vram_gb: u64,
#[serde(default, deserialize_with = "whole_gb")]
pub ram_gb: u64,
#[serde(default, deserialize_with = "whole_gb")]
pub disk_gb: u64,
#[serde(default = "default_purpose")]
pub purpose: Vec<String>,
}
impl HubAllocation {
pub fn to_payload(&self) -> Value {
json!({
"enabled": self.enabled,
"vram_gb": self.vram_gb,
"ram_gb": self.ram_gb,
"disk_gb": self.disk_gb,
"purpose": self.purpose,
})
}
}
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct Machine {
pub vram_gb: u64,
pub ram_gb: u64,
pub disk_gb: u64,
}
impl Machine {
pub fn detect() -> Machine {
let gib = (1u64 << 30) as f64;
let vram = crate::bench_node::run::enumerate_with_timeout(
&std::sync::atomic::AtomicBool::new(false),
)
.map(|g| g.iter().map(|d| d.vram_bytes).sum::<u64>())
.unwrap_or(0);
Machine {
vram_gb: (vram as f64 / gib).floor() as u64,
ram_gb: crate::spaces::schedule::memory_gb().floor() as u64,
disk_gb: disk_total_gb(),
}
}
pub fn quarter(&self) -> (u64, u64, u64) {
(self.vram_gb / 4, self.ram_gb / 4, self.disk_gb / 4)
}
}
fn disk_total_gb() -> u64 {
let dir = crate::credentials::dir().unwrap_or_else(|| PathBuf::from("."));
let target = if dir.exists() {
dir
} else {
PathBuf::from("/")
};
std::process::Command::new("df")
.arg("-Pk")
.arg(target)
.output()
.ok()
.and_then(|o| parse_df_total_gb(&String::from_utf8_lossy(&o.stdout)))
.unwrap_or(0)
}
fn parse_df_total_gb(out: &str) -> Option<u64> {
let kb: u64 = out
.lines()
.nth(1)?
.split_whitespace()
.nth(1)?
.parse()
.ok()?;
Some(kb / 1024 / 1024)
}
pub fn config_path(dir: &Path) -> PathBuf {
dir.join("config.toml")
}
fn read_table(dir: &Path) -> toml::value::Table {
std::fs::read_to_string(config_path(dir))
.ok()
.and_then(|t| t.parse::<toml::Value>().ok())
.and_then(|v| match v {
toml::Value::Table(t) => Some(t),
_ => None,
})
.unwrap_or_default()
}
pub fn load(dir: &Path) -> Option<HubAllocation> {
read_table(dir)
.get("hub_allocation")?
.clone()
.try_into()
.ok()
}
pub fn save(dir: &Path, a: &HubAllocation) -> Result<(), String> {
let mut table = read_table(dir);
let v = toml::Value::try_from(a).map_err(|e| e.to_string())?;
table.insert("hub_allocation".to_string(), v);
std::fs::create_dir_all(dir).map_err(|e| e.to_string())?;
let text = toml::to_string_pretty(&toml::Value::Table(table)).map_err(|e| e.to_string())?;
let tmp = dir.join("config.toml.tmp");
std::fs::write(&tmp, text).map_err(|e| e.to_string())?;
std::fs::rename(&tmp, config_path(dir)).map_err(|e| e.to_string())
}
#[derive(Debug, Clone, PartialEq)]
pub enum Cmd {
Show,
Disable,
Enable {
vram_gb: Option<u64>,
ram_gb: Option<u64>,
disk_gb: Option<u64>,
purpose: Option<Vec<String>>,
},
}
pub fn parse_gb(s: &str) -> Result<u64, String> {
let t = s.trim().to_ascii_lowercase();
let t = t
.strip_suffix("gb")
.or_else(|| t.strip_suffix('g'))
.unwrap_or(&t);
t.trim()
.parse::<u64>()
.map_err(|_| format!("'{s}' is not a size in whole GB (e.g. 8G)"))
}
pub fn parse_purpose(s: &str) -> Result<Vec<String>, String> {
let mut out: Vec<String> = Vec::new();
for p in s.split(',').map(|p| p.trim().to_ascii_lowercase()) {
if !PURPOSES.contains(&p.as_str()) {
return Err(format!(
"unknown purpose '{p}' (choose from {})",
PURPOSES.join(", ")
));
}
if !out.contains(&p) {
out.push(p);
}
}
Ok(out)
}
pub fn parse_args(args: &[String]) -> Result<Cmd, String> {
let (mut enable, mut disable) = (false, false);
let (mut vram, mut ram, mut disk, mut purpose) = (None, None, None, None);
let mut it = args.iter();
while let Some(a) = it.next() {
let (flag, inline) = match a.split_once('=') {
Some((f, v)) => (f, Some(v.to_string())),
None => (a.as_str(), None),
};
let mut value = |name: &str| -> Result<String, String> {
inline
.clone()
.or_else(|| it.next().cloned())
.ok_or_else(|| format!("{name} needs a value"))
};
match flag {
"--enable" => enable = true,
"--disable" => disable = true,
"--vram" => vram = Some(parse_gb(&value("--vram")?)?),
"--ram" => ram = Some(parse_gb(&value("--ram")?)?),
"--disk" => disk = Some(parse_gb(&value("--disk")?)?),
"--purpose" => purpose = Some(parse_purpose(&value("--purpose")?)?),
other => return Err(format!("unknown argument '{other}'")),
}
}
let sized = vram.is_some() || ram.is_some() || disk.is_some() || purpose.is_some();
match (enable, disable) {
(true, true) => Err("--enable and --disable are mutually exclusive".to_string()),
(false, true) if sized => Err("--disable takes no size or purpose flags".to_string()),
(false, true) => Ok(Cmd::Disable),
(true, false) => Ok(Cmd::Enable {
vram_gb: vram,
ram_gb: ram,
disk_gb: disk,
purpose,
}),
(false, false) if sized => Err("size and purpose flags need --enable".to_string()),
(false, false) => Ok(Cmd::Show),
}
}
pub fn validate(a: &HubAllocation, m: &Machine) -> Result<(), String> {
if a.vram_gb > m.vram_gb {
return Err(format!(
"--vram {}G is more than this machine's GPU memory ({}G)",
a.vram_gb, m.vram_gb
));
}
if m.ram_gb > 0 && a.ram_gb > m.ram_gb {
return Err(format!(
"--ram {}G is more than this machine's memory ({}G)",
a.ram_gb, m.ram_gb
));
}
if m.disk_gb > 0 && a.disk_gb > m.disk_gb {
return Err(format!(
"--disk {}G is more than this machine's disk ({}G)",
a.disk_gb, m.disk_gb
));
}
if a.purpose.is_empty() {
return Err("purpose must name at least one of inference, warmup".to_string());
}
Ok(())
}
pub fn enabled_from(
existing: Option<&HubAllocation>,
cmd: &Cmd,
m: &Machine,
) -> Result<HubAllocation, String> {
let Cmd::Enable {
vram_gb,
ram_gb,
disk_gb,
purpose,
} = cmd
else {
return Err("not an --enable command".to_string());
};
let (qv, qr, qd) = m.quarter();
let a = HubAllocation {
enabled: true,
vram_gb: vram_gb.or(existing.map(|e| e.vram_gb)).unwrap_or(qv),
ram_gb: ram_gb.or(existing.map(|e| e.ram_gb)).unwrap_or(qr),
disk_gb: disk_gb.or(existing.map(|e| e.disk_gb)).unwrap_or(qd),
purpose: purpose
.clone()
.or_else(|| existing.map(|e| e.purpose.clone()))
.unwrap_or_else(default_purpose),
};
validate(&a, m)?;
Ok(a)
}
pub fn describe(a: Option<&HubAllocation>) -> String {
match a {
None => "Hub allocation: not set (lend capacity with `zc hub allocate --enable`)".into(),
Some(a) if !a.enabled => "Hub allocation: disabled".into(),
Some(a) => format!(
"Hub allocation: enabled\n vram: {}G\n ram: {}G\n disk: {}G\n purpose: {}",
a.vram_gb,
a.ram_gb,
a.disk_gb,
a.purpose.join(", ")
),
}
}
pub fn execute(dir: &Path, cmd: &Cmd, m: &Machine) -> Result<String, String> {
let existing = load(dir);
match cmd {
Cmd::Show => Ok(describe(existing.as_ref())),
Cmd::Disable => match existing {
None => Ok(describe(None)),
Some(mut a) => {
a.enabled = false;
save(dir, &a)?;
Ok("Hub allocation disabled. The hub is told on the next broker sync.".into())
}
},
Cmd::Enable { .. } => {
let a = enabled_from(existing.as_ref(), cmd, m)?;
save(dir, &a)?;
Ok(format!(
"{}\nThe hub is told on the next broker sync; restart the broker if it is not running.",
describe(Some(&a))
))
}
}
}
pub fn run_cli(args: &[String]) -> i32 {
if args.first().map(String::as_str) != Some("allocate") {
eprintln!("usage: zc hub allocate [--enable [--vram 8G] [--ram 16G] [--disk 50G] [--purpose inference,warmup] | --disable]");
return 2;
}
let cmd = match parse_args(&args[1..]) {
Ok(c) => c,
Err(e) => {
eprintln!("Error: {e}");
return 2;
}
};
let Some(dir) = crate::credentials::dir() else {
eprintln!("Error: no state directory (set HOME or ZAKURO_HOME)");
return 1;
};
let machine = if matches!(cmd, Cmd::Enable { .. }) {
Machine::detect()
} else {
Machine {
vram_gb: 0,
ram_gb: 0,
disk_gb: 0,
}
};
match execute(&dir, &cmd, &machine) {
Ok(t) => {
println!("{t}");
0
}
Err(e) => {
eprintln!("Error: {e}");
1
}
}
}
pub fn merge_from_hub(
local: Option<&HubAllocation>,
remote: &Value,
m: &Machine,
) -> Option<HubAllocation> {
let obj = remote.as_object()?;
let enabled = obj.get("enabled").and_then(Value::as_bool);
let purpose = obj
.get("purpose")
.and_then(Value::as_array)
.map(|a| {
a.iter()
.filter_map(Value::as_str)
.filter(|p| PURPOSES.contains(p))
.map(String::from)
.collect::<Vec<_>>()
})
.filter(|p| !p.is_empty());
let next = match local {
Some(l) => HubAllocation {
enabled: enabled.unwrap_or(l.enabled),
purpose: purpose.unwrap_or_else(|| l.purpose.clone()),
..l.clone()
},
None => {
let enabled = enabled?;
let (qv, qr, qd) = m.quarter();
let gb = |k: &str, d: u64| {
obj.get(k)
.and_then(Value::as_f64)
.map(|v| v.max(0.0).floor() as u64)
.unwrap_or(d)
};
HubAllocation {
enabled,
vram_gb: gb("vram_gb", qv),
ram_gb: gb("ram_gb", qr),
disk_gb: gb("disk_gb", qd),
purpose: purpose.unwrap_or_else(default_purpose),
}
}
};
if Some(&next) == local || validate(&next, m).is_err() {
return None;
}
Some(next)
}
pub fn apply_register_response(dir: &Path, body: &str) {
let Ok(v) = serde_json::from_str::<Value>(body) else {
return;
};
let Some(remote) = v.get("hub_allocation") else {
return;
};
let local = load(dir);
let machine = Machine::detect();
if let Some(next) = merge_from_hub(local.as_ref(), remote, &machine) {
match save(dir, &next) {
Ok(()) => println!(
" [HUB_ALLOC] hub changed the opt-in: {}",
if next.enabled { "enabled" } else { "disabled" }
),
Err(e) => eprintln!(" [HUB_ALLOC] could not save the hub's change: {e}"),
}
}
}
#[cfg(test)]
mod tests {
use super::*;
fn argv(a: &[&str]) -> Vec<String> {
a.iter().map(|s| s.to_string()).collect()
}
fn machine() -> Machine {
Machine {
vram_gb: 24,
ram_gb: 64,
disk_gb: 1000,
}
}
fn tmp() -> PathBuf {
let d = std::env::temp_dir().join(format!(
"zc-huballoc-{}-{}",
std::process::id(),
std::time::SystemTime::now()
.duration_since(std::time::UNIX_EPOCH)
.unwrap()
.as_nanos()
));
std::fs::create_dir_all(&d).unwrap();
d
}
#[test]
fn parses_sizes() {
assert_eq!(parse_gb("8G"), Ok(8));
assert_eq!(parse_gb("16gb"), Ok(16));
assert_eq!(parse_gb("50"), Ok(50));
assert!(parse_gb("1.5G").is_err());
assert!(parse_gb("8T").is_err());
}
#[test]
fn parses_commands() {
assert_eq!(parse_args(&[]), Ok(Cmd::Show));
assert_eq!(parse_args(&argv(&["--disable"])), Ok(Cmd::Disable));
assert_eq!(
parse_args(&argv(&[
"--enable",
"--vram",
"8G",
"--ram=16G",
"--purpose",
"inference,warmup"
])),
Ok(Cmd::Enable {
vram_gb: Some(8),
ram_gb: Some(16),
disk_gb: None,
purpose: Some(argv(&["inference", "warmup"])),
})
);
assert!(parse_args(&argv(&["--enable", "--disable"])).is_err());
assert!(parse_args(&argv(&["--vram", "8G"])).is_err());
assert!(parse_args(&argv(&["--disable", "--ram", "1G"])).is_err());
assert!(parse_args(&argv(&["--enable", "--purpose", "batch"])).is_err());
assert!(parse_args(&argv(&["--enable", "--vram"])).is_err());
assert!(parse_args(&argv(&["--bogus"])).is_err());
}
#[test]
fn first_enable_defaults_to_a_quarter_rounded_down() {
let m = Machine {
vram_gb: 10,
ram_gb: 66,
disk_gb: 999,
};
let cmd = parse_args(&argv(&["--enable"])).unwrap();
let a = enabled_from(None, &cmd, &m).unwrap();
assert_eq!((a.vram_gb, a.ram_gb, a.disk_gb), (2, 16, 249));
assert_eq!(a.purpose, vec!["inference"]);
assert!(a.enabled);
}
#[test]
fn re_enable_keeps_saved_sizes_unless_overridden() {
let saved = HubAllocation {
enabled: false,
vram_gb: 8,
ram_gb: 16,
disk_gb: 50,
purpose: argv(&["warmup"]),
};
let cmd = parse_args(&argv(&["--enable", "--ram", "32G"])).unwrap();
let a = enabled_from(Some(&saved), &cmd, &machine()).unwrap();
assert_eq!((a.vram_gb, a.ram_gb, a.disk_gb), (8, 32, 50));
assert_eq!(a.purpose, vec!["warmup"]);
}
#[test]
fn refuses_a_slice_larger_than_the_machine() {
for flags in [
["--enable", "--vram", "48G"],
["--enable", "--ram", "128G"],
["--enable", "--disk", "2000G"],
] {
let cmd = parse_args(&argv(&flags)).unwrap();
assert!(enabled_from(None, &cmd, &machine()).is_err(), "{flags:?}");
}
}
#[test]
fn config_round_trips_and_keeps_other_sections() {
let d = tmp();
std::fs::write(config_path(&d), "[broker]\nport = 7000\n").unwrap();
assert_eq!(load(&d), None);
let a = HubAllocation {
enabled: true,
vram_gb: 8,
ram_gb: 16,
disk_gb: 50,
purpose: argv(&["inference", "warmup"]),
};
save(&d, &a).unwrap();
assert_eq!(load(&d), Some(a));
let text = std::fs::read_to_string(config_path(&d)).unwrap();
assert!(
text.contains("[broker]") && text.contains("[hub_allocation]"),
"{text}"
);
let _ = std::fs::remove_dir_all(d);
}
#[test]
fn execute_enable_show_disable() {
let d = tmp();
let m = machine();
let out = execute(
&d,
&parse_args(&argv(&["--enable", "--vram", "8G"])).unwrap(),
&m,
)
.unwrap();
assert!(out.contains("enabled") && out.contains("8G"), "{out}");
assert!(load(&d).unwrap().enabled);
execute(&d, &Cmd::Disable, &m).unwrap();
let a = load(&d).unwrap();
assert!(!a.enabled);
assert_eq!(a.vram_gb, 8, "disable keeps the sizes");
assert!(execute(&d, &Cmd::Show, &m).unwrap().contains("disabled"));
let _ = std::fs::remove_dir_all(d);
}
#[test]
fn deserializes_decimal_sizes_by_rounding_down() {
let a: HubAllocation =
serde_json::from_str(r#"{"enabled":true,"vram_gb":8.9,"ram_gb":16}"#).unwrap();
assert_eq!((a.vram_gb, a.ram_gb, a.disk_gb), (8, 16, 0));
assert_eq!(a.purpose, vec!["inference"]);
}
#[test]
fn hub_change_flips_enabled_but_not_sizes() {
let local = HubAllocation {
enabled: true,
vram_gb: 8,
ram_gb: 16,
disk_gb: 50,
purpose: argv(&["inference"]),
};
let remote = json!({"enabled": false, "vram_gb": 20, "purpose": ["inference","warmup"]});
let n = merge_from_hub(Some(&local), &remote, &machine()).unwrap();
assert!(!n.enabled);
assert_eq!(n.vram_gb, 8);
assert_eq!(n.purpose, argv(&["inference", "warmup"]));
assert_eq!(
merge_from_hub(Some(&local), &json!({"enabled": true}), &machine()),
None
);
}
#[test]
fn hub_enable_without_local_section_uses_a_quarter() {
let n = merge_from_hub(None, &json!({"enabled": true}), &machine()).unwrap();
assert_eq!((n.vram_gb, n.ram_gb, n.disk_gb), (6, 16, 250));
assert_eq!(merge_from_hub(None, &json!({}), &machine()), None);
}
#[test]
fn df_output_is_parsed() {
let out =
"Filesystem 1024-blocks Used Available Capacity Mounted on\n/dev/x 976490576 1 2 3% /\n";
assert_eq!(parse_df_total_gb(out), Some(931));
}
}