stokehold 0.4.1

stokehold (formerly heavy): a machine-wide admission queue for heavy jobs (builds, tests, GPU work). Reserves cores, RAM, VRAM and disk, runs jobs when they fit, and prints what each one used.
//! The event log: `history-YYYY-MM.jsonl` (UTC) in the state dir. One JSON line per job event (queued, started,
//! finished) and per machine sample, read back by `stokehold history`. Five monthly files are kept.
//!
//! (`history.jsonl`, see `history.rs`, is separate: it holds the finished runs that set the default weights.)

use std::collections::BTreeMap;
use std::fs::{self, OpenOptions};
use std::io::Write;
use std::path::{Path, PathBuf};

use jiff::Timestamp;
use serde::{Deserialize, Serialize};

use crate::admit::Block;
use crate::error::Error;
use crate::job::Weights;

/// Monthly files kept.
pub const KEEP_FILES: usize = 5;
/// A line must stay well under the 4 KB that a single `write()` to an `O_APPEND` file keeps atomic.
const MAX_LINE: usize = 4000;
const MAX_COMMAND: usize = 80;
const MAX_CWD: usize = 512;

/// Who a job event is about.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct JobInfo {
    pub id: String,
    pub pid: u32,
    pub cwd: String,
    /// The git toplevel's basename, if the cwd is in a repo.
    pub repo: Option<String>,
    /// `argv[0..2]` joined, at most 80 characters.
    pub command: String,
    /// Requested cores and RAM.
    pub cpu: u32,
    pub mem: u64,
}

impl JobInfo {
    #[must_use]
    pub fn new(id: &str, pid: u32, cwd: &str, cmd: &[String], w: Weights) -> Self {
        Self { id: id.into(), pid, cwd: cwd.chars().take(MAX_CWD).collect(), repo: repo_of(Path::new(cwd)), command: short_command(cmd), cpu: w.cpu, mem: w.mem }
    }
}

/// Time spent blocked by one check.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
pub struct ReasonTime {
    pub reason: Block,
    pub ms: u64,
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(tag = "event", rename_all = "lowercase")]
pub enum Event {
    Queued {
        ts: Timestamp,
        #[serde(flatten)]
        job: JobInfo,
    },
    Started {
        ts: Timestamp,
        #[serde(flatten)]
        job: JobInfo,
        wait_ms: u64,
        reasons: Vec<ReasonTime>,
    },
    Finished {
        ts: Timestamp,
        #[serde(flatten)]
        job: JobInfo,
        exit: i32,
        wall_ms: u64,
        cpu_ms: u64,
        peak_rss: u64,
    },
    Sample {
        ts: Timestamp,
        cpu_pct: u64,
        mem_pct: u64,
        load1: f64,
        load5: f64,
        ncpu: u32,
        running: u32,
        waiting: u32,
        /// Waiting jobs by what blocks them right now.
        blocked: BTreeMap<String, u32>,
    },
}

impl Event {
    #[must_use]
    pub const fn ts(&self) -> Timestamp {
        match self {
            Self::Queued { ts, .. } | Self::Started { ts, .. } | Self::Finished { ts, .. } | Self::Sample { ts, .. } => *ts,
        }
    }
}

/// `argv[0..2]` joined with a space, cut to 80 characters.
#[must_use]
pub fn short_command(cmd: &[String]) -> String {
    cmd.iter().take(2).map(String::as_str).collect::<Vec<_>>().join(" ").chars().take(MAX_COMMAND).collect()
}

/// The basename of the nearest ancestor that holds a `.git` (a directory, or a file in a worktree).
#[must_use]
pub fn repo_of(cwd: &Path) -> Option<String> {
    cwd.ancestors().find(|d| d.join(".git").exists()).and_then(|d| d.file_name()).map(|n| n.to_string_lossy().into_owned())
}

/// `history-2026-11.jsonl`: the month in UTC.
#[must_use]
pub fn file_name(ts: Timestamp) -> String {
    format!("history-{}.jsonl", ts.strftime("%Y-%m"))
}

/// Appends one line: a single `write()` on an `O_APPEND` file, so concurrent processes never interleave.
///
/// # Errors
/// Fails on I/O or serialization errors.
pub fn append(dir: &Path, event: &Event) -> Result<(), Error> {
    fs::create_dir_all(dir)?;
    let mut line = serde_json::to_vec(event)?;
    if line.len() >= MAX_LINE {
        return Err(Error::Probe("history line too long".into()));
    }
    line.push(b'\n');
    OpenOptions::new().create(true).append(true).open(dir.join(file_name(event.ts())))?.write_all(&line)?;
    Ok(())
}

/// Records an event; a failure only warns (history must never fail a job).
pub fn record(dir: &Path, event: &Event) {
    if let Err(e) = append(dir, event) {
        eprintln!("stokehold: could not write history: {e}");
    }
}

fn monthly_files(dir: &Path) -> Vec<PathBuf> {
    let Ok(rd) = fs::read_dir(dir) else {
        return Vec::new();
    };
    let mut files: Vec<PathBuf> = rd
        .filter_map(Result::ok)
        .map(|e| e.path())
        .filter(|p| p.file_name().and_then(|n| n.to_str()).is_some_and(|n| n.starts_with("history-") && Path::new(n).extension().is_some_and(|x| x == "jsonl")))
        .collect();
    files.sort();
    files
}

/// Deletes all but the newest `KEEP_FILES` monthly files (the names sort by month).
pub fn prune(dir: &Path) {
    let files = monthly_files(dir);
    for old in files.iter().take(files.len().saturating_sub(KEEP_FILES)) {
        let _ = fs::remove_file(old);
    }
}

/// Every parseable event at or after `since`, oldest first. Damaged lines are skipped.
#[must_use]
pub fn read_since(dir: &Path, since: Timestamp) -> Vec<Event> {
    let mut events: Vec<Event> = monthly_files(dir)
        .iter()
        .filter_map(|p| fs::read_to_string(p).ok())
        .flat_map(|t| t.lines().filter_map(|l| serde_json::from_str::<Event>(l).ok()).collect::<Vec<_>>())
        .filter(|e| e.ts() >= since)
        .collect();
    events.sort_by_key(Event::ts);
    events
}

/// Adds up how long a waiter was blocked by each check.
#[derive(Debug, Default)]
pub struct WaitTally {
    current: Option<(Block, i64)>,
    totals: BTreeMap<Block, u64>,
}

impl WaitTally {
    /// At `now_ms` the waiter is blocked by `next` (or by nothing). The time since the last note goes to the
    /// check that blocked then.
    pub fn note(&mut self, now_ms: i64, next: Option<Block>) {
        if let Some((block, since)) = self.current {
            *self.totals.entry(block).or_default() += u64::try_from(now_ms - since).unwrap_or(0);
        }
        self.current = next.map(|b| (b, now_ms));
    }

    #[must_use]
    pub fn reasons(&self) -> Vec<ReasonTime> {
        self.totals.iter().map(|(reason, ms)| ReasonTime { reason: *reason, ms: *ms }).collect()
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    fn info(id: &str) -> JobInfo {
        JobInfo { id: id.into(), pid: 7, cwd: "/w".into(), repo: Some("r".into()), command: "cargo test".into(), cpu: 4, mem: 1 << 30 }
    }

    fn ts(s: &str) -> Timestamp {
        s.parse().unwrap()
    }

    #[test]
    fn lines_are_written_and_parsed() {
        let t = tempfile::tempdir().unwrap();
        let when = ts("2026-11-19T10:00:00Z");
        let events = vec![
            Event::Queued { ts: when, job: info("a") },
            Event::Started { ts: when, job: info("a"), wait_ms: 1500, reasons: vec![ReasonTime { reason: Block::Ramp, ms: 1500 }] },
            Event::Finished { ts: when, job: info("a"), exit: 0, wall_ms: 9000, cpu_ms: 30_000, peak_rss: 1 << 20 },
            Event::Sample { ts: when, cpu_pct: 42, mem_pct: 50, load1: 3.5, load5: 2.0, ncpu: 16, running: 1, waiting: 2, blocked: BTreeMap::from([("cpu".to_string(), 2)]) },
        ];
        for e in &events {
            append(t.path(), e).unwrap();
        }
        let text = fs::read_to_string(t.path().join("history-2026-11.jsonl")).unwrap();
        assert_eq!(text.lines().count(), 4);
        let first: serde_json::Value = serde_json::from_str(text.lines().next().unwrap()).unwrap();
        assert_eq!(first["event"], "queued");
        assert_eq!(first["repo"], "r");
        assert_eq!(first["command"], "cargo test");
        assert_eq!(read_since(t.path(), ts("2026-11-19T00:00:00Z")), events);
        assert_eq!(read_since(t.path(), ts("2026-11-20T00:00:00Z")).len(), 0);
    }

    #[test]
    fn command_and_cwd_are_cut_and_lines_stay_small() {
        let long = "x".repeat(500);
        let cmd = vec!["cargo".to_string(), long.clone(), "ignored".to_string()];
        let c = short_command(&cmd);
        assert_eq!(c.chars().count(), 80);
        assert!(c.starts_with("cargo xx"));
        let j = JobInfo::new("id", 1, &"/y".repeat(1000), &cmd, Weights::default());
        let line = serde_json::to_string(&Event::Queued { ts: Timestamp::UNIX_EPOCH, job: j }).unwrap();
        assert!(line.len() < 1000, "{}", line.len());
    }

    #[test]
    fn months_split_by_utc_and_only_five_are_kept() {
        let t = tempfile::tempdir().unwrap();
        assert_eq!(file_name(ts("2026-11-30T23:59:59Z")), "history-2026-11.jsonl");
        assert_eq!(file_name(ts("2026-12-01T00:00:00Z")), "history-2026-12.jsonl");
        for m in 1..=7 {
            fs::write(t.path().join(format!("history-2026-{m:02}.jsonl")), "").unwrap();
        }
        fs::write(t.path().join("history.jsonl"), "").unwrap();
        prune(t.path());
        let mut names: Vec<String> = fs::read_dir(t.path()).unwrap().map(|e| e.unwrap().file_name().to_string_lossy().into_owned()).collect();
        names.sort();
        assert_eq!(names, ["history-2026-03.jsonl", "history-2026-04.jsonl", "history-2026-05.jsonl", "history-2026-06.jsonl", "history-2026-07.jsonl", "history.jsonl"]);
    }

    #[test]
    fn repo_is_the_git_toplevel_basename() {
        let t = tempfile::tempdir().unwrap();
        let repo = t.path().join("my-repo");
        fs::create_dir_all(repo.join(".git")).unwrap();
        fs::create_dir_all(repo.join("a/b")).unwrap();
        assert_eq!(repo_of(&repo.join("a/b")).as_deref(), Some("my-repo"));
    }

    #[test]
    fn wait_tally_attributes_time_to_the_blocking_check() {
        let mut w = WaitTally::default();
        w.note(1000, Some(Block::Queue));
        w.note(1400, Some(Block::Ramp));
        w.note(1500, Some(Block::Queue));
        w.note(2500, None);
        assert_eq!(w.reasons(), vec![ReasonTime { reason: Block::Queue, ms: 1400 }, ReasonTime { reason: Block::Ramp, ms: 100 }]);
    }
}