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,
}
const GIB: u64 = 1 << 30;
fn cuda_vram_bytes(gpus: &[crate::bench_node::fingerprint::GpuId]) -> u64 {
gpus.iter()
.filter(|g| g.vendor.eq_ignore_ascii_case("nvidia"))
.map(|g| g.vram_bytes)
.sum()
}
fn tightest(limits: &[u64]) -> u64 {
limits.iter().copied().filter(|&l| l > 0).min().unwrap_or(0)
}
fn cgroup_memory_limit_bytes() -> u64 {
for path in [
"/sys/fs/cgroup/memory.max",
"/sys/fs/cgroup/memory/memory.limit_in_bytes",
] {
if let Ok(t) = std::fs::read_to_string(path) {
if let Ok(v) = t.trim().parse::<u64>() {
if v < (1u64 << 60) {
return v;
}
}
}
}
0
}
fn docker_memory_bytes() -> u64 {
use crate::broker::deploy::runtime::{run_bounded, CliOutcome, PROBE_TIMEOUT};
let (outcome, out) = run_bounded(
std::process::Command::new("docker").args(["info", "--format", "{{.MemTotal}}"]),
PROBE_TIMEOUT,
);
match outcome {
CliOutcome::Exited { success: true, .. } => out.trim().parse().unwrap_or(0),
_ => 0,
}
}
impl Machine {
pub fn detect() -> Machine {
let vram = crate::bench_node::run::enumerate_with_timeout(
&std::sync::atomic::AtomicBool::new(false),
)
.map(|g| cuda_vram_bytes(&g))
.unwrap_or(0);
let host_ram = (crate::spaces::schedule::memory_gb() * GIB as f64) as u64;
let ram = match tightest(&[cgroup_memory_limit_bytes(), docker_memory_bytes()]) {
0 => host_ram,
limit if host_ram > 0 => limit.min(host_ram),
limit => limit,
};
Machine {
vram_gb: vram / GIB,
ram_gb: ram / GIB,
disk_gb: disk_usable_gb(),
}
}
pub fn quarter(&self) -> (u64, u64, u64) {
(self.vram_gb / 4, self.ram_gb / 4, self.disk_gb / 4)
}
}
fn disk_usable_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_usable_gb(&String::from_utf8_lossy(&o.stdout)))
.unwrap_or(0)
}
fn parse_df_usable_gb(out: &str) -> Option<u64> {
let row = out.lines().nth(1)?;
let mut f = row.split_whitespace().skip(2);
let used: u64 = f.next()?.parse().ok()?;
let avail: u64 = f.next()?.parse().ok()?;
Some((used + avail) / 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 node can lend: GPU memory (CUDA VRAM) is {}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 node can lend: usable memory is {}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 node can lend: usable disk is {}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}");
if !matches!(cmd, Cmd::Show) {
if let Err(e) =
crate::policy::migrate::alias_hub_allocation(&dir, load(&dir).as_ref())
{
eprintln!("Error: policy.toml not updated: {e}");
}
}
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_usable_gb(out), Some(0));
let out = "Filesystem 1024-blocks Used Available Capacity Mounted on\n/dev/x 976490576 400000000 570000000 41% /\n";
assert_eq!(parse_df_usable_gb(out), Some(925));
}
fn gpu(vendor: &str, gib: u64) -> crate::bench_node::fingerprint::GpuId {
crate::bench_node::fingerprint::GpuId {
vendor: vendor.into(),
model: "m".into(),
uuid: "u".into(),
vram_bytes: gib * GIB,
}
}
#[test]
fn apple_unified_memory_is_not_vram() {
assert_eq!(cuda_vram_bytes(&[gpu("apple", 16)]), 0);
assert_eq!(
cuda_vram_bytes(&[gpu("apple", 16), gpu("nvidia", 24), gpu("nvidia", 8)]),
32 * GIB
);
assert_eq!(cuda_vram_bytes(&[]), 0);
}
#[test]
fn tightest_limit_ignores_unknowns() {
assert_eq!(tightest(&[0, 0]), 0);
assert_eq!(tightest(&[0, 3 * GIB]), 3 * GIB);
assert_eq!(tightest(&[8 * GIB, 3 * GIB]), 3 * GIB);
}
#[test]
fn no_gpu_node_defaults_vram_zero_and_refuses_explicit_vram() {
let m = Machine {
vram_gb: 0,
ram_gb: 3,
disk_gb: 170,
};
let cmd = Cmd::Enable {
vram_gb: None,
ram_gb: None,
disk_gb: None,
purpose: None,
};
let a = enabled_from(None, &cmd, &m).unwrap();
assert_eq!((a.vram_gb, a.ram_gb, a.disk_gb), (0, 0, 42));
let big = Cmd::Enable {
vram_gb: Some(2),
ram_gb: Some(4),
disk_gb: Some(231),
purpose: None,
};
let e = enabled_from(None, &big, &m).unwrap_err();
assert!(e.contains("--vram"), "{e}");
let e = enabled_from(
None,
&Cmd::Enable {
vram_gb: None,
ram_gb: Some(4),
disk_gb: None,
purpose: None,
},
&m,
)
.unwrap_err();
assert!(e.contains("--ram"), "{e}");
let e = enabled_from(
None,
&Cmd::Enable {
vram_gb: None,
ram_gb: None,
disk_gb: Some(231),
purpose: None,
},
&m,
)
.unwrap_err();
assert!(e.contains("--disk"), "{e}");
}
}