zc2 0.0.47

P2P compute broker with yen-denominated billing, WAL, and broker mesh support
//! Hosting settings: the owner's budget, which runner kinds and job sources
//! are on, and the image cleanup TTL.
//!
//! Since zc#514 this is a thin view over `policy.toml` (ZC-0017): the sections
//! and key names are the policy's, [`load_or_default`] reads the policy and
//! [`save`] writes the edited keys back under the policy lock (revision
//! bump included). An `agent/hosting.toml` from zc#575 is migrated into the
//! policy on its first load.

use crate::agent::runners::CatalogueEntry;
use crate::policy::{self, Atelier, Policy};
use crate::sandbox::{self, Amount, Gpus};
use serde::{Deserialize, Serialize};
use std::path::Path;
use std::time::Duration;

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct Hosting {
    pub budget: BudgetCfg,
    pub workloads: Workloads,
    pub sharing: Sharing,
    pub cleanup: Cleanup,
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct BudgetCfg {
    pub cpu: String,
    /// On Apple Silicon this covers RAM and GPU memory together.
    pub memory: String,
    pub gpu: bool,
    pub disk: String,
    /// Take jobs only on AC power.
    pub on_ac_only: bool,
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct Workloads {
    /// Enabled Atelier backends (`peft`, `ludwig`).
    pub atelier: Vec<String>,
    pub spaces: bool,
    pub environments: bool,
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct Sharing {
    /// `idle` | `always` | `schedule`.
    pub when: String,
    /// The squads served (`sharing.squads` of the policy).
    pub sources: Vec<String>,
    /// Windows for `when = "schedule"`, local time.
    #[serde(default)]
    pub schedule: Vec<String>,
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct Cleanup {
    /// Images unused for this long are removed (`7d`, `36h`, `90m`).
    pub idle_ttl: String,
}

/// The spec defaults as a view, with every runner kind `cat` supports
/// enabled. Tests build fixtures from it; the live defaults are the policy's
/// (ADR 0017 §3).
#[cfg(test)]
pub fn defaults(cat: &[CatalogueEntry]) -> Hosting {
    let on = |id: &str| cat.iter().any(|e| e.supported && e.kind.id() == id);
    Hosting {
        budget: BudgetCfg {
            cpu: "50%".into(),
            memory: "50%".into(),
            gpu: true,
            disk: "50G".into(),
            on_ac_only: true,
        },
        workloads: Workloads {
            atelier: cat
                .iter()
                .filter(|e| e.supported)
                .filter_map(|e| e.kind.atelier_backend())
                .map(String::from)
                .collect(),
            spaces: on("spaces"),
            environments: on("environments"),
        },
        sharing: Sharing {
            when: "idle".into(),
            sources: vec!["public".into()],
            schedule: Vec::new(),
        },
        cleanup: Cleanup {
            idle_ttl: "7d".into(),
        },
    }
}

fn supported_backends(cat: &[CatalogueEntry]) -> Vec<String> {
    cat.iter()
        .filter(|e| e.supported)
        .filter_map(|e| e.kind.atelier_backend())
        .map(String::from)
        .collect()
}

/// The hosting view of a policy.
pub fn from_policy(p: &Policy, cat: &[CatalogueEntry]) -> Hosting {
    Hosting {
        budget: BudgetCfg {
            cpu: p.budget.cpu.clone(),
            memory: p.budget.memory.clone(),
            gpu: p.budget.gpu,
            disk: p.budget.disk.clone(),
            on_ac_only: p.budget.on_ac_only,
        },
        workloads: Workloads {
            atelier: p.atelier_backends(&supported_backends(cat)),
            spaces: p.workloads.spaces,
            environments: p.workloads.environments,
        },
        sharing: Sharing {
            when: p.sharing.when.clone(),
            sources: p.sharing.squads.clone(),
            schedule: p.sharing.schedule.clone(),
        },
        cleanup: Cleanup {
            idle_ttl: p.cleanup.idle_ttl.clone(),
        },
    }
}

impl Hosting {
    /// Write this view's keys into `p`; a key the view did not change from
    /// what `p` already shows is left alone (the Atelier shorthand
    /// `true` / `"gpu-only"` stays as it is until the backend list moves).
    pub fn apply_to(&self, p: &mut Policy, cat: &[CatalogueEntry]) {
        let before = from_policy(p, cat);
        p.budget.cpu = self.budget.cpu.clone();
        p.budget.memory = self.budget.memory.clone();
        p.budget.gpu = self.budget.gpu;
        p.budget.disk = self.budget.disk.clone();
        p.budget.on_ac_only = self.budget.on_ac_only;
        p.workloads.spaces = self.workloads.spaces;
        p.workloads.environments = self.workloads.environments;
        if self.workloads.atelier != before.workloads.atelier {
            p.workloads.atelier = if self.workloads.atelier.is_empty() {
                Atelier::Off
            } else {
                Atelier::Backends(self.workloads.atelier.clone())
            };
        }
        p.sharing.when = self.sharing.when.clone();
        if self.sharing.sources != before.sharing.sources {
            p.sharing.squads = self.sharing.sources.clone();
        }
        p.sharing.schedule = self.sharing.schedule.clone();
        p.cleanup.idle_ttl = self.cleanup.idle_ttl.clone();
    }
}

/// The saved settings: `policy.toml`'s view (the policy of a new node is
/// generated on first load). An unreadable file is an error naming the
/// problem (an unknown key names the key), never a silent fallback.
pub fn load_or_default(home: &Path, cat: &[CatalogueEntry]) -> Result<Hosting, String> {
    policy::load(home).map(|p| from_policy(&p, cat))
}

/// Write `h` into the policy under its lock; the revision goes up when
/// something changed.
pub fn save(home: &Path, h: &Hosting, cat: &[CatalogueEntry]) -> Result<(), String> {
    policy::update(home, None, None, |p| {
        h.apply_to(p, cat);
        Ok(())
    })
    .map(|_| ())
    .map_err(|e| e.to_string())
}

impl Hosting {
    /// The `[budget]` section as the sandbox's [`sandbox::Budget`].
    pub fn budget(&self) -> Result<sandbox::Budget, String> {
        let disk_bytes = match sandbox::parse_memory(&self.budget.disk)
            .map_err(|e| format!("budget.disk: {e}"))?
        {
            Amount::Absolute(n) => n as u64,
            Amount::Percent(_) => {
                return Err("budget.disk: give a size such as 50G, not a percentage".into())
            }
        };
        Ok(sandbox::Budget {
            cpu: sandbox::parse_cpu(&self.budget.cpu).map_err(|e| format!("budget.cpu: {e}"))?,
            memory: sandbox::parse_memory(&self.budget.memory)
                .map_err(|e| format!("budget.memory: {e}"))?,
            gpu: if self.budget.gpu {
                Gpus::All
            } else {
                Gpus::None
            },
            disk_bytes,
        })
    }

    /// `cleanup.idle_ttl` as a duration (`7d`, `36h`, `90m`, `600s`).
    pub fn idle_ttl(&self) -> Result<Duration, String> {
        policy::parse_ttl(&self.cleanup.idle_ttl).map_err(|e| format!("cleanup.idle_ttl={e}"))
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::agent::runners::{catalogue, Hardware};
    use crate::sandbox::HostResources;

    fn mac_catalogue() -> Vec<CatalogueEntry> {
        catalogue(&Hardware {
            apple_silicon: true,
            nvidia: vec![],
            host: HostResources {
                logical_cpus: 10,
                memory_bytes: Some(16 << 30),
            },
        })
    }

    fn tmp() -> std::path::PathBuf {
        crate::policy::test_home()
    }

    #[test]
    fn defaults_enable_every_supported_runner() {
        let h = load_or_default(&tmp(), &mac_catalogue()).unwrap();
        assert_eq!(h.workloads.atelier, vec!["peft".to_string()]);
        assert!(h.workloads.spaces);
        assert!(h.workloads.environments);
    }

    #[test]
    fn defaults_match_the_policy_adr() {
        let h = load_or_default(&tmp(), &mac_catalogue()).unwrap();
        assert_eq!(h.budget.cpu, "50%");
        assert_eq!(h.budget.memory, "50%");
        assert!(
            h.budget.gpu,
            "design D2 (amends ZC-0017 §3): GPU sharing on by default"
        );
        assert_eq!(h.budget.disk, "50G");
        assert!(h.budget.on_ac_only);
        assert_eq!(h.sharing.when, "idle");
        assert_eq!(h.sharing.sources, vec!["public".to_string()]);
        assert_eq!(h.cleanup.idle_ttl, "7d");
    }

    #[test]
    fn an_old_hosting_toml_is_migrated_and_an_unknown_key_names_the_key() {
        let home = tmp();
        std::fs::create_dir_all(home.join("agent")).unwrap();
        std::fs::write(home.join("agent/hosting.toml"), "[budget]\nfoo = 1\n").unwrap();
        let err = load_or_default(&home, &mac_catalogue()).unwrap_err();
        assert!(err.contains("foo"), "{err}");

        let home = tmp();
        std::fs::create_dir_all(home.join("agent")).unwrap();
        std::fs::write(
            home.join("agent/hosting.toml"),
            "[budget]\ncpu = \"25%\"\nmemory = \"6g\"\ngpu = true\ndisk = \"80G\"\non_ac_only = false\n\
             [workloads]\natelier = [\"peft\"]\nspaces = false\nenvironments = true\n\
             [sharing]\nwhen = \"always\"\nsources = [\"hub\"]\n[cleanup]\nidle_ttl = \"3d\"\n",
        )
        .unwrap();
        let h = load_or_default(&home, &mac_catalogue()).unwrap();
        assert_eq!(h.budget.memory, "6g");
        assert!(h.budget.gpu && !h.budget.on_ac_only);
        assert!(!h.workloads.spaces);
        assert_eq!(h.sharing.when, "always");
        assert_eq!(
            h.sharing.sources,
            vec!["public".to_string()],
            "`hub` is the public squad"
        );
        assert_eq!(h.cleanup.idle_ttl, "3d");
        assert!(home.join("policy.toml").exists());
    }

    #[test]
    fn save_writes_through_to_policy_toml_and_bumps_the_revision() {
        let home = tmp();
        let cat = mac_catalogue();
        let mut h = load_or_default(&home, &cat).unwrap();
        let r0 = policy::load(&home).unwrap().revision;
        h.budget.memory = "6g".into();
        h.workloads.spaces = false;
        save(&home, &h, &cat).unwrap();
        assert_eq!(load_or_default(&home, &cat).unwrap(), h);
        let p = policy::load(&home).unwrap();
        assert_eq!(p.revision, r0 + 1);
        assert_eq!(p.budget.memory, "6g");
        assert!(!p.workloads.spaces);
        // Saving what is already there changes nothing.
        save(&home, &h, &cat).unwrap();
        assert_eq!(policy::load(&home).unwrap().revision, r0 + 1);
        #[cfg(unix)]
        {
            use std::os::unix::fs::PermissionsExt;
            let mode = std::fs::metadata(home.join("policy.toml"))
                .unwrap()
                .permissions()
                .mode();
            assert_eq!(mode & 0o777, 0o600);
        }
    }

    #[test]
    fn the_atelier_shorthand_survives_saving_an_unrelated_change() {
        let home = tmp();
        let cat = mac_catalogue();
        policy::update(&home, None, None, |p| {
            p.workloads.atelier = Atelier::GpuOnly;
            Ok(())
        })
        .unwrap();
        let mut h = load_or_default(&home, &cat).unwrap();
        h.cleanup.idle_ttl = "2d".into();
        save(&home, &h, &cat).unwrap();
        assert_eq!(
            policy::load(&home).unwrap().workloads.atelier,
            Atelier::GpuOnly,
            "the view lists backends, but the policy keeps `gpu-only`"
        );
        h.workloads.atelier = vec![];
        save(&home, &h, &cat).unwrap();
        assert_eq!(policy::load(&home).unwrap().workloads.atelier, Atelier::Off);
    }

    #[test]
    fn idle_ttl_parses_days() {
        let h = load_or_default(&tmp(), &mac_catalogue()).unwrap();
        assert_eq!(h.idle_ttl().unwrap().as_secs(), 604_800);
    }

    #[test]
    fn budget_converts_gpu_and_disk() {
        let mut h = load_or_default(&tmp(), &mac_catalogue()).unwrap();
        h.budget.gpu = true;
        let b = h.budget().unwrap();
        assert_eq!(b.gpu, crate::sandbox::Gpus::All);
        assert_eq!(b.disk_bytes, 50 << 30);
    }
}