runner-manager 0.4.8

// owner: f1-cli-auth-host-status
//
// ----------------------------------------------------------------------------
// `update` IS DRIVEN AGAINST A REAL COPY OF THE BINARY, REPLACING ITSELF.
// ----------------------------------------------------------------------------
// Every other suite here runs `Command::cargo_bin("runner-manager")`, which is
// `target/debug/runner-manager` -- a path this command classifies as a build in
// a checkout and refuses to touch, correctly and by design. So the happy path
// cannot be reached that way at all.
//
// What these tests do instead is copy the built binary into a temporary
// directory and run THAT, which is exactly the layout `install.sh` produces and
// is therefore the real thing rather than a stand-in for it. The copy then
// replaces its own file while it is running, on whichever operating system this
// leg of the matrix is -- which is the one property of this command that cannot
// be checked by reading it.
//
// The release it updates to is `common::build_release`, a3's synthetic release:
// five archives laid out the way the published ones are, with a `SHA256SUMS`
// generated by the same `release.sh` subcommand the release workflow calls. The
// assets are read from a directory rather than over HTTP, which is the same
// affordance `install.sh` has for an air-gapped mirror -- so no test here needs
// a network, and the digest check still runs against the document beside them.

mod common;

use std::path::{Path, PathBuf};
use std::process::Command;

use common::{FixtureRelease, build_release, substitute_payload};

/// The product's own mapping, transcribed by hand.
///
/// Deliberately a second copy rather than a call into the binary: this is the
/// oracle that says which archive this host is supposed to ask for, and one
/// derived from the answer under test would agree with whatever that answer is.
fn host_target() -> (&'static str, &'static str) {
    match (std::env::consts::OS, std::env::consts::ARCH) {
        ("windows", "x86_64") => ("x86_64-pc-windows-msvc", "runner-manager.exe"),
        ("macos", "aarch64") => ("aarch64-apple-darwin", "runner-manager"),
        ("macos", "x86_64") => ("x86_64-apple-darwin", "runner-manager"),
        ("linux", "x86_64") => ("x86_64-unknown-linux-gnu", "runner-manager"),
        ("linux", "aarch64") => ("aarch64-unknown-linux-gnu", "runner-manager"),
        (os, arch) => panic!(
            "this suite has no published archive for {os}/{arch}. If the project starts \
             publishing one, add it here and to `host_target` in `cli/update.rs`."
        ),
    }
}

/// This build's version, which is what `update` compares the release against.
const RUNNING: &str = env!("CARGO_PKG_VERSION");

/// `RUNNING` with its patch raised, so the fixture release is unambiguously
/// newer whatever version the workspace is on this week.
fn one_release_newer() -> String {
    let mut parts = RUNNING.split('.');
    let major: u64 = parts.next().expect("a major").parse().expect("a number");
    let minor: u64 = parts.next().expect("a minor").parse().expect("a number");
    let patch: u64 = parts.next().expect("a patch").parse().expect("a number");
    format!("{major}.{minor}.{}", patch + 1)
}

/// Run `command`, retrying briefly past `ETXTBSY`.
///
/// # Why a retry rather than a fix at the copy
///
/// Every test here copies the built binary into its own temporary `bin/` and
/// then executes it. On Linux, `execve` fails with `ETXTBSY` ("Text file busy")
/// while **any** file descriptor anywhere in the process still holds that file
/// open for writing — and the writer does not have to be this test. `cargo
/// test` runs the tests of one binary as threads of a single process, several
/// `Installed::new` calls overlap, and a `posix_spawn` issued by thread A
/// inherits the write descriptor thread B is at that instant using to copy
/// *its* binary. Closing our own file, which `fs::copy` already does before it
/// returns, cannot prevent that: the descriptor that blocks us belongs to
/// another test.
///
/// So the race is inherent to the shape of the suite rather than to any one
/// test, and the window is the microseconds between another thread's `copy` and
/// its `spawn`. A bounded retry closes it without serialising the suite behind a
/// mutex or giving every test its own process.
///
/// The retry is deliberately narrow: only `ETXTBSY`, only for about a second,
/// and any other spawn failure still panics with the original message. A blanket
/// "retry the spawn" would hide a binary that genuinely cannot run, which is a
/// thing these tests exist to catch.
fn spawn_past_etxtbsy(command: &mut Command) -> std::process::Output {
    // 50 * 20ms. Long enough for a concurrent copy to finish by orders of
    // magnitude, short enough that a real failure is not a slow failure.
    const ATTEMPTS: u32 = 50;
    const BACKOFF: std::time::Duration = std::time::Duration::from_millis(20);

    for _ in 0..ATTEMPTS {
        match command.output() {
            Ok(output) => return output,
            Err(error) if error.raw_os_error() == Some(TEXT_FILE_BUSY) => {
                std::thread::sleep(BACKOFF);
            }
            Err(error) => panic!("the copied binary must run: {error:?}"),
        }
    }

    panic!(
        "the copied binary was still reported busy after {:?}; that is far longer than a \
         concurrent copy in this suite can hold a write descriptor, so it is a real failure \
         rather than the race this retry exists for",
        ATTEMPTS * BACKOFF
    );
}

/// `ETXTBSY`. Zero on platforms that do not raise it, which never matches a
/// real `raw_os_error` and so leaves the retry inert on Windows and macOS.
#[cfg(target_os = "linux")]
const TEXT_FILE_BUSY: i32 = 26;
#[cfg(not(target_os = "linux"))]
const TEXT_FILE_BUSY: i32 = 0;

/// An installed copy of the binary, in the layout `install.sh` produces.
struct Installed {
    /// Held so the directory outlives the test.
    _root: tempfile::TempDir,
    /// The binary an operator would have on their PATH.
    binary: PathBuf,
    /// `--data-dir` for every invocation.
    data: PathBuf,
}

impl Installed {
    /// Copies the built binary into a temporary `bin/` and returns it.
    fn new() -> Self {
        let root = tempfile::tempdir().expect("a temporary directory");
        let bin = root.path().join("bin");
        std::fs::create_dir_all(&bin).expect("the install directory");
        let binary = bin.join(format!("runner-manager{}", std::env::consts::EXE_SUFFIX));
        std::fs::copy(env!("CARGO_BIN_EXE_runner-manager"), &binary)
            .expect("copying the built binary into place");
        #[cfg(unix)]
        {
            use std::os::unix::fs::PermissionsExt as _;
            std::fs::set_permissions(&binary, std::fs::Permissions::from_mode(0o755))
                .expect("making the copy executable");
        }
        let data = root.path().join("data");
        std::fs::create_dir_all(&data).expect("the data directory");
        Self {
            _root: root,
            binary,
            data,
        }
    }

    /// Runs the copied binary with the release assets pointed at `assets`.
    fn update(&self, assets: &Path, arguments: &[&str]) -> Outcome {
        let mut command = Command::new(&self.binary);
        // The developer's own exported variables must not change what this
        // measures, exactly as `support::runner_manager` argues.
        for variable in [
            "RUNNER_MANAGER_DATA_DIR",
            "RUNNER_MANAGER_GITHUB_BASE_URL",
            "RUST_LOG",
        ] {
            command.env_remove(variable);
        }
        command
            .env("RUNNER_MANAGER_UPDATE_BASE_URL", assets)
            .arg("--data-dir")
            .arg(&self.data)
            .arg("update")
            .args(arguments);
        let output = spawn_past_etxtbsy(&mut command);
        Outcome {
            code: output.status.code().unwrap_or(-1),
            stdout: String::from_utf8_lossy(&output.stdout).replace("\r\n", "\n"),
            stderr: String::from_utf8_lossy(&output.stderr).replace("\r\n", "\n"),
        }
    }

    fn bytes(&self) -> Vec<u8> {
        std::fs::read(&self.binary).expect("the installed binary must be readable")
    }
}

struct Outcome {
    code: i32,
    stdout: String,
    stderr: String,
}

impl Outcome {
    fn both(&self) -> String {
        format!("{}{}", self.stdout, self.stderr)
    }
}

/// The bytes the fixture release carries for this host.
fn payload_of(release: &FixtureRelease) -> Vec<u8> {
    let (target, binary) = host_target();
    std::fs::read(release.staged(target).join(binary)).expect("the fixture payload")
}

// ---------------------------------------------------------------------------

/// The whole point of the command: a newer release replaces the binary that is
/// running, and says so.
#[test]
fn a_newer_release_replaces_the_running_binary() {
    let fixtures = tempfile::tempdir().expect("a temporary directory");
    let release = build_release(fixtures.path(), &one_release_newer());
    let installed = Installed::new();
    let before = installed.bytes();

    let outcome = installed.update(&release.assets, &[]);
    assert_eq!(
        outcome.code,
        0,
        "update must succeed; output was:\n{}",
        outcome.both()
    );
    assert!(
        outcome.stdout.contains(&format!(
            "Installed runner-manager {} to",
            one_release_newer()
        )),
        "update must name the version it installed; output was:\n{}",
        outcome.both()
    );
    assert!(
        outcome.stdout.contains("SHA-256 OK:"),
        "update must report the digest it checked; output was:\n{}",
        outcome.both()
    );

    let after = installed.bytes();
    assert_ne!(before, after, "the binary on disk must have been replaced");
    assert_eq!(
        after,
        payload_of(&release),
        "the installed file must be the binary the release archive carried"
    );
}

/// A release that is not newer changes nothing, and says nothing was done.
///
/// A `update` that reinstalled the same version on every run would restart the
/// service every time it was called -- the daemon watches this file -- which
/// turns a harmless habit into an interrupted job.
#[test]
fn the_same_version_is_not_reinstalled() {
    let fixtures = tempfile::tempdir().expect("a temporary directory");
    let release = build_release(fixtures.path(), RUNNING);
    let installed = Installed::new();
    let before = installed.bytes();

    let outcome = installed.update(&release.assets, &[]);
    assert_eq!(
        outcome.code,
        0,
        "being up to date is not a failure; output was:\n{}",
        outcome.both()
    );
    assert!(
        outcome
            .stdout
            .contains("is the newest release. Nothing to do."),
        "output was:\n{}",
        outcome.both()
    );
    assert_eq!(installed.bytes(), before, "nothing may be written");
}

/// The published archive is verified before it is installed, and a substituted
/// one is refused with the binary in place untouched.
///
/// `substitute_payload` rebuilds a well-formed archive whose contents are not
/// the ones the digest was published for, which is the threat
/// `07-security.md` names -- an artifact tampered with in transit. Nothing but
/// the SHA-256 comparison can tell.
#[test]
fn a_substituted_archive_is_refused_and_nothing_is_installed() {
    let fixtures = tempfile::tempdir().expect("a temporary directory");
    let release = build_release(fixtures.path(), &one_release_newer());
    let (target, _) = host_target();
    substitute_payload(&release, target);

    let installed = Installed::new();
    let before = installed.bytes();

    let outcome = installed.update(&release.assets, &[]);
    assert_eq!(
        outcome.code,
        20,
        "a digest mismatch is `unusable_response`; output was:\n{}",
        outcome.both()
    );
    assert!(
        outcome.stderr.contains("CHECKSUM MISMATCH"),
        "the refusal must say what happened; output was:\n{}",
        outcome.both()
    );
    assert_eq!(
        installed.bytes(),
        before,
        "a refused update must leave the binary that was working in place"
    );
}

/// `--check` reports the available version and writes nothing.
#[test]
fn check_reports_the_new_version_and_changes_nothing() {
    let fixtures = tempfile::tempdir().expect("a temporary directory");
    let release = build_release(fixtures.path(), &one_release_newer());
    let installed = Installed::new();
    let before = installed.bytes();

    let outcome = installed.update(&release.assets, &["--check"]);
    assert_eq!(outcome.code, 0, "output was:\n{}", outcome.both());
    assert!(
        outcome.stdout.contains(&format!(
            "published                 {}",
            one_release_newer()
        )),
        "output was:\n{}",
        outcome.both()
    );
    assert!(
        outcome
            .stdout
            .contains("Nothing has been changed, because --check was given."),
        "output was:\n{}",
        outcome.both()
    );
    assert!(
        outcome
            .stdout
            .contains("Install it with: runner-manager update"),
        "an updatable copy must be told the command that does it; output was:\n{}",
        outcome.both()
    );
    assert_eq!(installed.bytes(), before, "nothing may be written");
}

/// The report names the channel and the file, because "which of my three
/// installs did this update" is the first question an operator asks.
#[test]
fn the_report_names_the_channel_and_the_file_it_would_replace() {
    let fixtures = tempfile::tempdir().expect("a temporary directory");
    let release = build_release(fixtures.path(), &one_release_newer());
    let installed = Installed::new();

    let outcome = installed.update(&release.assets, &["--check"]);
    assert!(
        outcome
            .stdout
            .contains("installed by              release archive ("),
        "output was:\n{}",
        outcome.both()
    );
    assert!(
        outcome
            .stdout
            .contains(&format!("installed                 {RUNNING}")),
        "output was:\n{}",
        outcome.both()
    );
}

/// A build in a checkout is refused, and refused with its own exit code so a
/// script can tell it from a failed download.
///
/// This one runs the binary cargo built, in place, which is exactly the layout
/// being refused.
#[test]
fn a_build_in_a_checkout_is_refused() {
    let fixtures = tempfile::tempdir().expect("a temporary directory");
    let release = build_release(fixtures.path(), &one_release_newer());
    let data = tempfile::tempdir().expect("a temporary directory");

    let output = Command::new(env!("CARGO_BIN_EXE_runner-manager"))
        .env_remove("RUNNER_MANAGER_DATA_DIR")
        .env("RUNNER_MANAGER_UPDATE_BASE_URL", &release.assets)
        .arg("--data-dir")
        .arg(data.path())
        .arg("update")
        .output()
        .expect("the binary must run");
    let stderr = String::from_utf8_lossy(&output.stderr).replace("\r\n", "\n");

    assert_eq!(
        output.status.code(),
        Some(22),
        "a checkout build is `update_unsupported`; stderr was:\n{stderr}"
    );
    assert!(
        stderr.contains("build in a checkout"),
        "stderr was:\n{stderr}"
    );
    assert!(
        stderr.contains("cargo build --release"),
        "the refusal must name what to run instead; stderr was:\n{stderr}"
    );
}

/// `--check` on a copy that cannot be updated must not end by recommending the
/// command that would refuse.
#[test]
fn check_says_when_this_copy_could_not_be_updated() {
    let fixtures = tempfile::tempdir().expect("a temporary directory");
    let release = build_release(fixtures.path(), &one_release_newer());
    let data = tempfile::tempdir().expect("a temporary directory");

    let output = Command::new(env!("CARGO_BIN_EXE_runner-manager"))
        .env_remove("RUNNER_MANAGER_DATA_DIR")
        .env("RUNNER_MANAGER_UPDATE_BASE_URL", &release.assets)
        .arg("--data-dir")
        .arg(data.path())
        .arg("update")
        .arg("--check")
        .output()
        .expect("the binary must run");
    let stdout = String::from_utf8_lossy(&output.stdout).replace("\r\n", "\n");

    assert_eq!(output.status.code(), Some(0), "stdout was:\n{stdout}");
    assert!(
        stdout.contains("`runner-manager update` would refuse here:"),
        "stdout was:\n{stdout}"
    );
    assert!(
        !stdout.contains("Install it with: runner-manager update"),
        "a dry run must not recommend a command that refuses; stdout was:\n{stdout}"
    );
}

/// The override that redirects where a replacement executable comes from
/// accepts only this machine.
///
/// This is the security property of the whole seam: an http(s) origin that is
/// not loopback would make an exported variable a remote-code-execution
/// primitive aimed at whoever runs `update` next.
#[test]
fn an_http_asset_source_that_is_not_this_machine_is_refused() {
    let data = tempfile::tempdir().expect("a temporary directory");
    let output = Command::new(env!("CARGO_BIN_EXE_runner-manager"))
        .env_remove("RUNNER_MANAGER_DATA_DIR")
        .env(
            "RUNNER_MANAGER_UPDATE_BASE_URL",
            "https://releases.example.com/download",
        )
        .arg("--data-dir")
        .arg(data.path())
        .arg("update")
        .arg("--check")
        .output()
        .expect("the binary must run");
    let stderr = String::from_utf8_lossy(&output.stderr).replace("\r\n", "\n");

    assert_eq!(
        output.status.code(),
        Some(9),
        "an untrusted origin is `invalid_argument`; stderr was:\n{stderr}"
    );
    assert!(
        stderr.contains("which is not this machine"),
        "stderr was:\n{stderr}"
    );
}

/// A release that publishes no archive for this host is a different failure
/// from a release that could not be read, and must not be reported as one.
#[test]
fn a_release_without_this_platform_says_so() {
    let fixtures = tempfile::tempdir().expect("a temporary directory");
    let release = build_release(fixtures.path(), &one_release_newer());
    let (target, _) = host_target();

    // Drop every line naming this host's archive, leaving the other four.
    let sums = std::fs::read_to_string(release.sums()).expect("the fixture SHA256SUMS");
    let kept: Vec<&str> = sums.lines().filter(|line| !line.contains(target)).collect();
    std::fs::write(release.sums(), format!("{}\n", kept.join("\n"))).expect("the trimmed sums");

    let installed = Installed::new();
    let outcome = installed.update(&release.assets, &["--check"]);
    assert_eq!(
        outcome.code,
        15,
        "a missing platform is `unsupported_host`; output was:\n{}",
        outcome.both()
    );
    assert!(
        outcome.stderr.contains("publishes no archive for"),
        "output was:\n{}",
        outcome.both()
    );
}

// ---------------------------------------------------------------------------
// What the update means for the service
// ---------------------------------------------------------------------------

/// An install record in the shape `service install` writes, transcribed by hand.
///
/// ----------------------------------------------------------------------------
/// WRITTEN OUT RATHER THAN BUILT FROM `InstallRecord`, ON PURPOSE.
/// ----------------------------------------------------------------------------
/// `crates/app` has no library target, so `tests/` sees dev-dependencies only
/// and cannot reach `runner-manager-platform` -- but even where it could, a
/// fixture serialised from the very struct `update` deserialises would agree
/// with whatever that struct says, which is the one thing a fixture must not
/// do. This is an independent statement of the file `service install` leaves in
/// `config/`, and a schema change that stops `update` reporting the hand-over
/// must fail here rather than pass quietly. Same reasoning as the hand-copied
/// command list in `cli_command_surface.rs`.
fn write_install_record(data: &Path, source_binary: Option<&Path>) {
    let config = data.join("config");
    std::fs::create_dir_all(&config).expect("the config directory");
    let source_line = match source_binary {
        Some(path) => format!("source_binary = {}\n", toml_path(path)),
        None => String::new(),
    };
    let record = format!(
        "schema_version = 1\n\
         service_name = \"com.example.runner-manager\"\n\
         manager = \"launchd\"\n\
         start_mode = \"boot\"\n\
         account = \"root\"\n\
         binary = {binary}\n\
         {source_line}\
         arguments = [\"daemon\", \"run\"]\n\
         restart_delay_secs = 5\n\
         restart_reset_secs = 60\n\
         log_file = {log}\n\
         starts_on_demand = false\n\
         definition_path = \"/Library/LaunchDaemons/com.example.runner-manager.plist\"\n\
         installed_at = \"2026-09-01T00:00:00Z\"\n\
         installed_by_version = \"0.0.1\"\n\
         \n\
         [directories]\n\
         config = {config_dir}\n\
         state = {state}\n\
         runtime = {runtime}\n\
         logs = {logs}\n",
        binary = toml_path(&data.join("state").join("bin").join("runner-manager")),
        log = toml_path(&data.join("logs").join("runner-manager")),
        config_dir = toml_path(&config),
        state = toml_path(&data.join("state")),
        runtime = toml_path(&data.join("runtime")),
        logs = toml_path(&data.join("logs")),
    );
    std::fs::write(config.join("service.toml"), record).expect("the install record");
}

/// A path as a TOML string. Windows separators are escapes in a basic string,
/// so the literal form is the one that survives them.
fn toml_path(path: &Path) -> String {
    format!("'{}'", path.display())
}

/// The step an operator upgrading by hand forgets: the service runs a copy, so
/// the hand-over happens by itself and takes as long as the jobs in flight.
#[test]
fn a_service_running_a_copy_is_told_it_will_hand_over_by_itself() {
    let fixtures = tempfile::tempdir().expect("a temporary directory");
    let release = build_release(fixtures.path(), &one_release_newer());
    let installed = Installed::new();
    write_install_record(&installed.data, Some(&installed.binary));

    let outcome = installed.update(&release.assets, &[]);
    assert_eq!(outcome.code, 0, "output was:\n{}", outcome.both());
    assert!(
        outcome
            .stdout
            .contains("The service runs its own copy of this binary."),
        "output was:\n{}",
        outcome.both()
    );
    assert!(
        outcome.stdout.contains("Nothing else is needed."),
        "output was:\n{}",
        outcome.both()
    );
}

/// A registration made before the service ran a copy of its own names the
/// binary directly, and that layout cannot pick the new version up by itself.
#[test]
fn a_registration_with_no_recorded_source_is_told_to_reinstall() {
    let fixtures = tempfile::tempdir().expect("a temporary directory");
    let release = build_release(fixtures.path(), &one_release_newer());
    let installed = Installed::new();
    write_install_record(&installed.data, None);

    let outcome = installed.update(&release.assets, &[]);
    assert_eq!(outcome.code, 0, "output was:\n{}", outcome.both());
    assert!(
        outcome.stdout.contains("names a binary directly"),
        "output was:\n{}",
        outcome.both()
    );
    assert!(
        outcome.stdout.contains("runner-manager service install"),
        "the report must name the command that fixes it; output was:\n{}",
        outcome.both()
    );
}

/// A host with two copies of this program: the service was installed from one
/// of them and `update` was run from the other. Saying "it will hand over" here
/// would be false, and it is the case an operator is least likely to spot.
#[test]
fn a_service_installed_from_another_binary_is_named_rather_than_assumed() {
    let fixtures = tempfile::tempdir().expect("a temporary directory");
    let release = build_release(fixtures.path(), &one_release_newer());
    let installed = Installed::new();
    let elsewhere = installed.data.join("another").join("runner-manager");
    write_install_record(&installed.data, Some(&elsewhere));

    let outcome = installed.update(&release.assets, &[]);
    assert_eq!(outcome.code, 0, "output was:\n{}", outcome.both());
    assert!(
        outcome.stdout.contains("The service was installed from"),
        "output was:\n{}",
        outcome.both()
    );
    assert!(
        outcome.stdout.contains(&elsewhere.display().to_string()),
        "the report must name the other binary; output was:\n{}",
        outcome.both()
    );
}

/// A host with no service at all gets no paragraph about one.
#[test]
fn a_host_with_no_service_is_told_nothing_about_one() {
    let fixtures = tempfile::tempdir().expect("a temporary directory");
    let release = build_release(fixtures.path(), &one_release_newer());
    let installed = Installed::new();

    let outcome = installed.update(&release.assets, &[]);
    assert_eq!(outcome.code, 0, "output was:\n{}", outcome.both());
    assert!(
        !outcome.stdout.contains("The service"),
        "output was:\n{}",
        outcome.both()
    );
}