Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

15.4 KB
Raw Blame
//! The host's log: `<home>/logs/pty-host-<instance>.log`, the owner's alone, kept to a size.
//!
//! The daemon starts the host with no stdio, so `log` records (and the host's own diagnostics) would
//! go nowhere without this. Each line goes to the file and to stderr, so a host run by hand in a
//! terminal still shows them. Past [`MAX_BYTES`] the file is moved to `pty-host-<instance>.log.1` (one older
//! file is kept) and a new one is started.
//!
//! One host per home and instance holds the home's lock (`host_lock`), but a host that lost the race for it, or the
//! Windows copy that left a job (`breakaway`), may append a line or two before it exits. Only the
//! lock's holder rotates (`own_rotation`, called once the lock is taken): a loser that rotated would
//! leave the winner writing to `.log.1`, and the winner's next rotation would replace those lines.
//!
//! A rotation that fails (on Windows, a reader holding the file without delete sharing) is not
//! tried again on every line, each with `files::rename`'s waits under the lock: the file grows by
//! another [`MAX_BYTES`] first.

use std::fs::File;
use std::io::{self, Write};
use std::path::{Path, PathBuf};
use std::sync::Mutex;
use std::sync::atomic::{AtomicBool, Ordering};

/// The size past which the log is rotated.
pub const MAX_BYTES: u64 = 5 * 1024 * 1024;

pub fn log_dir(home: &Path) -> PathBuf {
    home.join("logs")
}

pub fn log_path(home: &Path) -> PathBuf {
    crate::instance::log_path(home, &crate::instance::current())
}

/// The rotated file: `pty-host-<instance>.log.1`.
pub fn rotated_path(home: &Path) -> PathBuf {
    let mut rotated = log_path(home).into_os_string();
    rotated.push(".1");
    PathBuf::from(rotated)
}

pub struct FileLog {
    level: log::LevelFilter,
    max_bytes: u64,
    stderr: bool,
    /// Whether this process may rotate the file: the home lock's holder only.
    rotates: AtomicBool,
    state: Mutex<State>,
}

/// The installed logger, for `own_rotation`.
static INSTALLED: std::sync::OnceLock<&'static FileLog> = std::sync::OnceLock::new();

struct State {
    path: PathBuf,
    rotated: PathBuf,
    /// None once the file could not be opened: lines then go to stderr only.
    file: Option<File>,
    size: u64,
}

impl FileLog {
    /// Open (or create) the log under [home]. When the file cannot be opened, the logger still
    /// writes to stderr, and the error is returned alongside so the caller can report it.
    pub fn open(
        home: &Path,
        max_bytes: u64,
        stderr: bool,
        rotates: bool,
    ) -> (FileLog, Option<io::Error>) {
        let (path, rotated) = (log_path(home), rotated_path(home));
        let opened = open_log(home, &path);
        let (file, size, error) = match opened {
            Ok((file, size)) => (Some(file), size, None),
            Err(err) => (None, 0, Some(err)),
        };
        let level = std::env::var("HARNESS_PTY_LOG")
            .ok()
            .and_then(|v| v.parse().ok())
            .unwrap_or(log::LevelFilter::Info);
        let log = FileLog {
            level,
            max_bytes,
            stderr,
            rotates: AtomicBool::new(rotates),
            state: Mutex::new(State {
                path,
                rotated,
                file,
                size,
            }),
        };
        (log, error)
    }

    fn write_line(&self, line: &str) {
        if self.stderr {
            let _ = io::stderr().write_all(line.as_bytes());
        }
        let mut state = self.state.lock().unwrap_or_else(|e| e.into_inner());
        if state.file.is_none() {
            return;
        }
        if state.size > 0
            && state.size + line.len() as u64 > self.max_bytes
            && self.rotates.load(Ordering::Relaxed)
        {
            state.rotate();
        }
        let State { file, size, .. } = &mut *state;
        if let Some(file) = file
            && file.write_all(line.as_bytes()).is_ok()
        {
            *size += line.len() as u64;
        }
    }
}

impl State {
    /// `pty-host-<instance>.log` → `pty-host-<instance>.log.1` (replacing it), then a new, empty
    /// `pty-host-<instance>.log`. When the rename fails the same file is reopened, and its size
    /// counted from zero: the next try is another cap's worth of lines away.
    fn rotate(&mut self) {
        self.file = None;
        let renamed = crate::files::rename(&self.path, &self.rotated).is_ok();
        let home = self
            .path
            .parent()
            .and_then(Path::parent)
            .map(Path::to_path_buf);
        if let Some(home) = home
            && let Ok((file, size)) = open_log(&home, &self.path)
        {
            self.file = Some(file);
            self.size = if renamed { size } else { 0 };
        }
    }
}

impl log::Log for FileLog {
    fn enabled(&self, metadata: &log::Metadata) -> bool {
        metadata.level() <= self.level
    }

    fn log(&self, record: &log::Record) {
        if !self.enabled(record.metadata()) {
            return;
        }
        let line = format!(
            "{} pid {} {} {}: {}\n",
            utc_now(),
            std::process::id(),
            record.level(),
            record.target(),
            record.args()
        );
        self.write_line(&line);
    }

    fn flush(&self) {
        let mut state = self.state.lock().unwrap_or_else(|e| e.into_inner());
        if let Some(file) = state.file.as_mut() {
            let _ = file.flush();
        }
    }
}

/// Install the host's logger for [home] (once per process; a second call changes nothing). A log
/// file that cannot be opened is reported, on stderr, and the host carries on without one.
pub fn install(home: &Path) {
    let (log, error) = FileLog::open(home, MAX_BYTES, true, false);
    let level = log.level;
    // Leaked: the logger lives as long as the process.
    let log: &'static FileLog = Box::leak(Box::new(log));
    if log::set_logger(log).is_ok() {
        log::set_max_level(level);
        let _ = INSTALLED.set(log);
    }
    if let Some(err) = error {
        log::warn!("no log file under {}: {err}", log_dir(home).display());
    }
}

/// This process holds the home's lock: from now on it rotates the log (the module comment).
pub fn own_rotation() {
    if let Some(log) = INSTALLED.get() {
        log.rotates.store(true, Ordering::Relaxed);
    }
}

/// `<home>/logs/`, the owner's alone (0700 on Unix, the run directory's user-only DACL on Windows),
/// then the log in it, opened to append: created 0600 on Unix (and made so, whatever an older file
/// had), on Windows with the user-only DACL from its creation, and shared, so it can be read (and
/// rotated) while it is open.
fn open_log(home: &Path, path: &Path) -> io::Result<(File, u64)> {
    let dir = log_dir(home);
    #[cfg(unix)]
    let file = {
        use std::os::unix::fs::{DirBuilderExt, OpenOptionsExt, PermissionsExt};
        std::fs::DirBuilder::new()
            .recursive(true)
            .mode(0o700)
            .create(&dir)?;
        std::fs::set_permissions(&dir, std::fs::Permissions::from_mode(0o700))?;
        let file = std::fs::OpenOptions::new()
            .append(true)
            .create(true)
            .mode(0o600)
            .open(path)?;
        file.set_permissions(std::fs::Permissions::from_mode(0o600))?;
        file
    };
    #[cfg(windows)]
    let file = {
        std::fs::create_dir_all(home)?;
        crate::transport::windows::secure_dir(&dir)?;
        crate::transport::windows::open_private_append(path)?
    };
    let size = file.metadata()?.len();
    Ok((file, size))
}

/// `YYYY-MM-DDTHH:MM:SS.mmmZ`, with no date crate.
fn utc_now() -> String {
    let now = std::time::SystemTime::now()
        .duration_since(std::time::UNIX_EPOCH)
        .unwrap_or_default();
    format_utc(now.as_secs(), now.subsec_millis())
}

fn format_utc(secs: u64, millis: u32) -> String {
    let (days, rem) = (secs / 86_400, secs % 86_400);
    // Howard Hinnant's civil_from_days.
    let z = days as i64 + 719_468;
    let era = z.div_euclid(146_097);
    let doe = z.rem_euclid(146_097);
    let yoe = (doe - doe / 1460 + doe / 36_524 - doe / 146_096) / 365;
    let doy = doe - (365 * yoe + yoe / 4 - yoe / 100);
    let mp = (5 * doy + 2) / 153;
    let day = doy - (153 * mp + 2) / 5 + 1;
    let month = if mp < 10 { mp + 3 } else { mp - 9 };
    let year = yoe + era * 400 + i64::from(month <= 2);
    format!(
        "{year:04}-{month:02}-{day:02}T{:02}:{:02}:{:02}.{millis:03}Z",
        rem / 3600,
        rem % 3600 / 60,
        rem % 60
    )
}

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

    fn record(log: &FileLog, level: log::Level, message: &str) {
        log.log(
            &log::Record::builder()
                .level(level)
                .target("harness_pty::test")
                .args(format_args!("{message}"))
                .build(),
        );
    }

    #[test]
    fn formats_utc_times() {
        assert_eq!(format_utc(0, 0), "1970-01-01T00:00:00.000Z");
        assert_eq!(format_utc(951_782_400, 7), "2000-02-29T00:00:00.007Z");
        assert_eq!(format_utc(1_791_893_045, 999), "2026-10-13T12:04:05.999Z");
    }

    #[test]
    fn writes_lines_to_an_owner_only_file_and_appends_across_opens() {
        let home = tempfile::tempdir().unwrap();
        let (log, error) = FileLog::open(home.path(), MAX_BYTES, false, true);
        assert!(error.is_none(), "{error:?}");
        record(&log, log::Level::Info, "first");
        record(&log, log::Level::Debug, "not at info");
        drop(log);
        let (log, _) = FileLog::open(home.path(), MAX_BYTES, false, true);
        record(&log, log::Level::Error, "second");
        let text = std::fs::read_to_string(log_path(home.path())).unwrap();
        let lines: Vec<&str> = text.lines().collect();
        assert_eq!(lines.len(), 2, "{text}");
        assert!(
            lines[0].ends_with("INFO harness_pty::test: first"),
            "{text}"
        );
        assert!(
            lines[1].ends_with("ERROR harness_pty::test: second"),
            "{text}"
        );
        assert!(lines[1].contains(&format!(" pid {} ", std::process::id())));
        #[cfg(unix)]
        {
            use std::os::unix::fs::PermissionsExt;
            let mode = |p: &Path| std::fs::metadata(p).unwrap().permissions().mode() & 0o777;
            assert_eq!(mode(&log_dir(home.path())), 0o700);
            assert_eq!(mode(&log_path(home.path())), 0o600);
        }
        #[cfg(windows)]
        {
            use crate::transport::windows::file_dacl;
            file_dacl(&log_dir(home.path())).assert_users_alone(true);
            file_dacl(&log_path(home.path())).assert_only_user_entries();
        }
    }

    #[cfg(unix)]
    #[test]
    fn an_older_log_readable_by_others_is_made_the_owners_alone() {
        use std::os::unix::fs::PermissionsExt;
        let home = tempfile::tempdir().unwrap();
        std::fs::create_dir_all(log_dir(home.path())).unwrap();
        std::fs::write(log_path(home.path()), "old\n").unwrap();
        std::fs::set_permissions(
            log_path(home.path()),
            std::fs::Permissions::from_mode(0o644),
        )
        .unwrap();
        let (_log, error) = FileLog::open(home.path(), MAX_BYTES, false, true);
        assert!(error.is_none());
        let mode = std::fs::metadata(log_path(home.path()))
            .unwrap()
            .permissions()
            .mode();
        assert_eq!(mode & 0o777, 0o600);
    }

    #[test]
    fn rotates_at_the_cap_and_keeps_one_older_file() {
        let home = tempfile::tempdir().unwrap();
        // Lines of 101 to 150 bytes (the pid's digits vary): two fit under the cap, three do not.
        let (log, _) = FileLog::open(home.path(), 300, false, true);
        let message = "x".repeat(60);
        for _ in 0..3 {
            record(&log, log::Level::Info, &message);
        }
        // The third did not fit beside the first two: they were moved aside.
        let older = std::fs::read_to_string(rotated_path(home.path())).unwrap();
        let current = std::fs::read_to_string(log_path(home.path())).unwrap();
        assert_eq!(older.lines().count(), 2, "{older}");
        assert_eq!(current.lines().count(), 1, "{current}");
        for _ in 0..2 {
            record(&log, log::Level::Info, &message);
        }
        // Rotated again: the oldest file is replaced, not kept beside.
        assert_eq!(
            std::fs::read_to_string(rotated_path(home.path()))
                .unwrap()
                .lines()
                .count(),
            2
        );
        assert_eq!(
            std::fs::read_to_string(log_path(home.path()))
                .unwrap()
                .lines()
                .count(),
            1
        );
        let names: Vec<_> = std::fs::read_dir(log_dir(home.path()))
            .unwrap()
            .map(|e| e.unwrap().file_name().into_string().unwrap())
            .collect();
        assert_eq!(names.len(), 2, "{names:?}");
        #[cfg(unix)]
        {
            use std::os::unix::fs::PermissionsExt;
            let mode = std::fs::metadata(log_path(home.path()))
                .unwrap()
                .permissions()
                .mode();
            assert_eq!(mode & 0o777, 0o600);
        }
    }

    #[test]
    fn a_process_that_does_not_hold_the_lock_never_rotates() {
        let home = tempfile::tempdir().unwrap();
        let (log, _) = FileLog::open(home.path(), 300, false, false);
        for _ in 0..5 {
            record(&log, log::Level::Info, &"x".repeat(60));
        }
        assert!(!rotated_path(home.path()).exists());
        let text = std::fs::read_to_string(log_path(home.path())).unwrap();
        assert_eq!(text.lines().count(), 5);
        // Once it holds it, it does.
        log.rotates.store(true, Ordering::Relaxed);
        record(&log, log::Level::Info, "next");
        assert!(rotated_path(home.path()).exists());
    }

    #[test]
    fn a_rotation_that_fails_is_tried_again_only_a_cap_later() {
        let home = tempfile::tempdir().unwrap();
        let (log, _) = FileLog::open(home.path(), 300, false, true);
        // `.log.1` is a directory with something in it: the file cannot be renamed over it.
        std::fs::create_dir_all(rotated_path(home.path()).join("held")).unwrap();
        let message = "x".repeat(60);
        for _ in 0..3 {
            record(&log, log::Level::Info, &message);
        }
        // The third line went in, to the same file.
        assert_eq!(
            std::fs::read_to_string(log_path(home.path()))
                .unwrap()
                .lines()
                .count(),
            3
        );
        // Free to rotate now, but not yet tried again: the count started over at the failure.
        std::fs::remove_dir_all(rotated_path(home.path())).unwrap();
        record(&log, log::Level::Info, &message);
        assert!(!rotated_path(home.path()).exists());
        // The next line would take it over the cap again: the rotation is made.
        record(&log, log::Level::Info, &message);
        assert!(rotated_path(home.path()).is_file());
        assert_eq!(
            std::fs::read_to_string(log_path(home.path()))
                .unwrap()
                .lines()
                .count(),
            1
        );
    }

    #[test]
    fn a_log_that_cannot_be_opened_leaves_stderr() {
        let home = tempfile::tempdir().unwrap();
        // `logs` is a file: no directory can be made there.
        std::fs::write(log_dir(home.path()), "").unwrap();
        let (log, error) = FileLog::open(home.path(), MAX_BYTES, false, true);
        assert!(error.is_some());
        record(&log, log::Level::Error, "still fine");
    }
}