fundaia 0.26.0

//! Replacing this program with a newer one, in place.
//!
//! The release workflow already builds four binaries, tars each one and puts a
//! `.sha256` beside it, and `install.sh` already knows how to fetch them. This
//! is that same script, in the tool, so the version somebody is running catches
//! up on its own rather than after they read a notice and remember to act on it.
//!
//! Three decisions are worth knowing before changing anything here.
//!
//! - **The checksum is mandatory, unlike in `install.sh`.** That script runs
//!   because a person typed it and can see what it says; this runs by itself.
//!   A download nothing vouched for is not written over the binary that holds
//!   somebody's deploy credentials, so a missing `.sha256` fails the update.
//! - **The new binary is staged in the directory it will land in**, never in
//!   `/tmp`, because the swap has to be a `rename` and a rename does not cross
//!   filesystems. What is downloaded and unpacked lives in a scratch directory;
//!   only the finished file is copied next to its destination.
//! - **Nothing is written over the running binary.** `rename` replaces the
//!   directory entry and leaves this process on the old inode, which is what
//!   makes it safe to do halfway through a command. The alternative — opening
//!   the running file for writing — is `ETXTBSY` on Linux and a corrupt binary
//!   where it is not.

use std::fmt::Write as _;
use std::path::{Path, PathBuf};
use std::time::Duration;

use anyhow::{anyhow, bail, Context, Result};
use sha2::{Digest, Sha256};

/// Where the binaries are published. The crate is on crates.io and the compiled
/// artefacts are on GitHub, which is why the version is asked of one and
/// downloaded from the other.
const REPO: &str = "alex28042/fundaia-apps";

/// Generous next to the two seconds the check gets: by the time this runs,
/// there is a decision to download several megabytes and a line on screen
/// saying so.
const DOWNLOAD_TIMEOUT: Duration = Duration::from_secs(120);

/// Where the running commentary goes.
///
/// An update takes long enough to need one, and the two callers need it in
/// different places: the automatic check writes to stderr, because it is not
/// what anybody asked for, and `upgrade` writes to stdout, because it is. This
/// module knows what is happening and nothing about which stream that is —
/// including whether anybody is watching, which is why it hands out meters
/// rather than drawing anything itself.
pub trait Progress {
    fn say(&self, message: &str);

    /// A download about to start, carrying the size the server declared when it
    /// declared one. Without it there is no bar to fill, only a count going up.
    fn downloading(&self, bytes: Option<u64>) -> Box<dyn Meter>;

    /// Something long with nothing to measure: a compile. The message is what
    /// sits beside the spinner while it runs.
    fn working(&self, message: &str) -> Box<dyn Meter>;
}

/// One slow thing, while it is happening.
///
/// `finished` is called however it went, so the screen is left clean before the
/// caller says whether it worked — a bar frozen at 60% above the word "listo"
/// is worse than no bar at all.
pub trait Meter {
    fn advanced(&self, bytes: u64);
    fn finished(&self);
}

/// Everything the swap needs, resolved before a single byte is downloaded.
///
/// Built by `prepare`, which is where every reason this machine cannot update
/// itself is discovered — an unknown platform, a binary owned by root, a
/// directory that is read-only. Failing there costs nothing; failing after the
/// download costs the download.
pub struct SelfInstaller {
    version: String,
    target: &'static str,
    /// The file that gets replaced: this program, with symlinks followed.
    executable: PathBuf,
}

impl SelfInstaller {
    pub fn prepare(version: &str) -> Result<Self> {
        let target = target_triple().ok_or_else(|| {
            anyhow!(
                "no hay binario publicado para {}-{}",
                std::env::consts::ARCH,
                std::env::consts::OS
            )
        })?;

        // Canonical, so a symlinked install replaces what the link points at
        // rather than turning the link into a copy.
        let executable = std::env::current_exe()
            .and_then(|path| path.canonicalize())
            .context("no se ha podido localizar el propio ejecutable")?;

        let directory = executable
            .parent()
            .ok_or_else(|| anyhow!("el ejecutable no está dentro de ningún directorio"))?;

        // Asked by writing rather than by reading the permission bits: the
        // question is whether *this* process can write there, and the answer
        // involves the owner, the group, the mode and whether the filesystem is
        // mounted read-only.
        let probe = directory.join(format!(".fundaia-write-check-{}", std::process::id()));
        std::fs::OpenOptions::new()
            .write(true)
            .create_new(true)
            .open(&probe)
            .with_context(|| format!("{} no es escribible", directory.display()))?;
        let _ = std::fs::remove_file(&probe);

        Ok(Self {
            version: version.to_owned(),
            target,
            executable,
        })
    }

    /// Where the finished binary will end up. Shown after a successful update,
    /// because "installed" without a path is the sentence that leaves somebody
    /// wondering which of their two copies moved.
    pub fn destination(&self) -> &Path {
        &self.executable
    }

    /// Installs the newer version by whichever of the two routes works, and
    /// leaves the binary exactly as it was if neither does.
    pub async fn install(&self, progress: &dyn Progress) -> Result<()> {
        let scratch = private_scratch_directory(&self.version)?;

        let outcome = self.take_a_route(&scratch, progress).await;

        // However it went: an aborted update must not leave a half-unpacked
        // binary in a temporary directory nobody ever looks at.
        let _ = std::fs::remove_dir_all(&scratch);

        outcome
    }

    /// The published binary if it can be had, and the crate if it cannot.
    ///
    /// Both routes end at the same version; they differ in what they need from
    /// the machine and in how long they take. The binary is seconds and needs
    /// no toolchain, so it is tried first — but the assets hang off a **private**
    /// repository, and GitHub serves those to nobody without a credential. So
    /// today the first route answers 404 in a fifth of a second and the second
    /// one is what actually installs. The order stays this way because the day
    /// that repository is public, the fast route starts working with no change
    /// here.
    ///
    /// Only an archive that could not be *obtained* falls through. One that
    /// arrives and fails its checksum stops everything: that is the difference
    /// between "not available" and "not to be trusted", and quietly building
    /// from source after a failed signature check would turn a red flag into a
    /// retry.
    async fn take_a_route(&self, scratch: &Path, progress: &dyn Progress) -> Result<()> {
        let http = reqwest::Client::builder()
            .timeout(DOWNLOAD_TIMEOUT)
            .user_agent(concat!("fundaia/", env!("CARGO_PKG_VERSION")))
            .build()?;

        let url = self.asset_url();
        let Ok(archive) = download(&http, &url, progress).await else {
            progress.say("el binario publicado no está a la vista; compilando desde crates.io…");
            return self.build_from_the_crate(progress).await;
        };

        let published = fetch(&http, &format!("{url}.sha256"))
            .await
            .context("la release no publica checksum para este binario")?;
        let published = String::from_utf8(published).context("el checksum no es texto")?;

        progress.say("comprobando la descarga…");
        verify(&archive, &published)?;

        let packed = scratch.join("fundaia.tar.gz");
        std::fs::write(&packed, &archive).context("no se ha podido guardar la descarga")?;
        unpack(&packed, scratch).await?;

        let fresh = scratch.join("fundaia");
        if !fresh.is_file() {
            bail!("el archivo descargado no contiene fundaia");
        }

        self.swap(&fresh)
    }

    /// `cargo install`, which needs no swapping of our own: cargo writes the
    /// finished binary into place itself, and does it the same careful way.
    ///
    /// `--root` so it lands on the copy that is running rather than on
    /// whichever one `~/.cargo/bin` holds. `--locked` so it builds against the
    /// dependencies the release was tested with. `--version` because "newest"
    /// is decided up in `update`, and a crate that gained a version in the last
    /// four seconds must not change what this installs.
    async fn build_from_the_crate(&self, progress: &dyn Progress) -> Result<()> {
        let mut cargo = tokio::process::Command::new("cargo");
        cargo
            .arg("install")
            .arg("fundaia")
            .arg("--version")
            .arg(&self.version)
            .arg("--locked")
            .arg("--force")
            .arg("--quiet");

        if let Some(root) = cargo_root(&self.executable) {
            cargo.arg("--root").arg(root);
        }

        // The one place in this module where the wait has no size at all:
        // `--quiet` was chosen so cargo's own wall of progress lines does not
        // land in the middle of a command's output, and the cost of that is two
        // hundred crates compiling behind a screen that says nothing.
        let meter = progress.working(&format!("compilando {} desde crates.io", self.version));
        let built = cargo.output().await;
        meter.finished();

        let built =
            built.context("no se ha podido ejecutar cargo — instálalo o actualiza a mano")?;

        if !built.status.success() {
            let complaint = String::from_utf8_lossy(&built.stderr);
            bail!("cargo install ha fallado: {}", last_line(&complaint));
        }

        progress.say("compilada e instalada");

        Ok(())
    }

    /// Copy next door, make it executable, and move it over the old one. The
    /// three steps are in this order so the only irreversible one is last and
    /// atomic.
    fn swap(&self, fresh: &Path) -> Result<()> {
        let staged = self
            .executable
            .with_file_name(format!(".fundaia-{}.new", self.version));

        // `create_new` rather than `copy`: a file already there under this name
        // was not written by this process, and following it — or a symlink
        // planted there — would hand the swap somebody else's bytes.
        let copied = std::fs::OpenOptions::new()
            .write(true)
            .create_new(true)
            .open(&staged)
            .and_then(|mut target| std::io::copy(&mut std::fs::File::open(fresh)?, &mut target));
        if let Err(error) = copied {
            let _ = std::fs::remove_file(&staged);
            return Err(error)
                .with_context(|| format!("no se ha podido escribir en {}", staged.display()));
        }

        if let Err(error) = make_executable(&staged) {
            let _ = std::fs::remove_file(&staged);
            return Err(error);
        }

        if let Err(error) = std::fs::rename(&staged, &self.executable) {
            let _ = std::fs::remove_file(&staged);
            return Err(error).with_context(|| {
                format!("no se ha podido reemplazar {}", self.executable.display())
            });
        }

        Ok(())
    }

    fn asset_url(&self) -> String {
        format!(
            "https://github.com/{REPO}/releases/download/{tag}/{asset}",
            tag = tag_of(&self.version),
            asset = asset_name(&self.version, self.target),
        )
    }
}

async fn fetch(http: &reqwest::Client, url: &str) -> Result<Vec<u8>> {
    let response = http.get(url).send().await?.error_for_status()?;
    Ok(response.bytes().await?.to_vec())
}

/// The same request, read a chunk at a time so somebody can watch it arrive.
///
/// `bytes()` would be one line and would also be a program that prints
/// "descargando…" and then says nothing for however long several megabytes take
/// over whatever connection this is. The size comes from `Content-Length` when
/// the server sends one — GitHub does for a release asset — and its absence
/// costs the bar and nothing else: the count and the rate still move.
///
/// The body is still assembled in memory rather than streamed to the scratch
/// file. It is a handful of megabytes that has to be hashed in one piece before
/// anything is written, and a checksum is only a guarantee if it is checked
/// before the bytes reach a path with `fundaia` in the name.
async fn download(http: &reqwest::Client, url: &str, progress: &dyn Progress) -> Result<Vec<u8>> {
    let mut response = http.get(url).send().await?.error_for_status()?;

    let declared = response.content_length();
    let meter = progress.downloading(declared);

    let mut body = Vec::with_capacity(declared.unwrap_or(0) as usize);

    // Collected rather than propagated, so the meter is cleared before the
    // error surfaces and the failure is not printed underneath a live bar.
    let mut interrupted = None;
    loop {
        match response.chunk().await {
            Ok(Some(chunk)) => {
                body.extend_from_slice(&chunk);
                meter.advanced(chunk.len() as u64);
            }
            Ok(None) => break,
            Err(error) => {
                interrupted = Some(error);
                break;
            }
        }
    }

    meter.finished();

    match interrupted {
        Some(error) => Err(error).context("la descarga se ha cortado"),
        None => Ok(body),
    }
}

/// A directory in the temporary space that this process created and owns.
///
/// The name used to be the version and the pid, both guessable, and
/// `create_dir_all` was happy to adopt a directory that already existed — so
/// anyone on the machine could create it first and swap the unpacked binary
/// between the checksum and the copy. The name carries a nonce, the mode
/// keeps everyone else out, and `create` (not `create_all`) refuses one that
/// is already there rather than moving in.
fn private_scratch_directory(version: &str) -> Result<PathBuf> {
    let nonce = std::time::SystemTime::now()
        .duration_since(std::time::UNIX_EPOCH)
        .map(|since| since.as_nanos())
        .unwrap_or(0);
    let scratch = std::env::temp_dir().join(format!(
        "fundaia-{version}-{}-{nonce:x}",
        std::process::id()
    ));

    let mut builder = std::fs::DirBuilder::new();
    #[cfg(unix)]
    {
        use std::os::unix::fs::DirBuilderExt;
        builder.mode(0o700);
    }
    builder
        .create(&scratch)
        .with_context(|| format!("no se ha podido crear {}", scratch.display()))?;

    Ok(scratch)
}

/// `tar` rather than a Rust decompressor, deliberately: every platform this
/// publishes for has it, `install.sh` already depends on it, and two crates of
/// build time is a poor trade for unpacking one file.
async fn unpack(archive: &Path, into: &Path) -> Result<()> {
    let status = tokio::process::Command::new("tar")
        .arg("-xzf")
        .arg(archive)
        .arg("-C")
        .arg(into)
        .status()
        .await
        .context("no se ha podido ejecutar tar")?;

    if !status.success() {
        bail!("tar no ha podido descomprimir la descarga");
    }

    Ok(())
}

/// What the release says the archive should hash to, against what it does.
fn verify(archive: &[u8], published: &str) -> Result<()> {
    let expected = expected_digest(published)
        .ok_or_else(|| anyhow!("el checksum publicado está vacío o mal formado"))?;
    let actual = digest_of(archive);

    if actual != expected {
        bail!("el checksum no coincide: la descarga se descarta");
    }

    Ok(())
}

/// `sha256sum` writes `<hash>  <filename>`, and `shasum -a 256` writes the same
/// with one space fewer on some platforms. Only the first field is ours.
fn expected_digest(published: &str) -> Option<String> {
    let digest = published.split_whitespace().next()?;

    if digest.len() != 64 || !digest.chars().all(|c| c.is_ascii_hexdigit()) {
        return None;
    }

    Some(digest.to_ascii_lowercase())
}

fn digest_of(bytes: &[u8]) -> String {
    let digest = Sha256::digest(bytes);

    digest
        .iter()
        .fold(String::with_capacity(64), |mut text, byte| {
            let _ = write!(text, "{byte:02x}");
            text
        })
}

/// The tag the release workflow lays down, which is also what the asset is
/// named after.
fn tag_of(version: &str) -> String {
    format!("cli-v{version}")
}

fn asset_name(version: &str, target: &str) -> String {
    format!("fundaia-{tag}-{target}.tar.gz", tag = tag_of(version))
}

/// What to hand `cargo install --root`, so it writes over the copy that is
/// running rather than over whatever `~/.cargo/bin` holds.
///
/// Cargo appends `bin/` to the root itself, so this is the parent of the
/// directory the executable sits in — and only when that directory is called
/// `bin`, because anywhere else the two would not agree on the final path.
/// `None` means "let cargo decide", which is `~/.cargo/bin` and is the right
/// answer for the installs that came from there in the first place.
fn cargo_root(executable: &Path) -> Option<&Path> {
    let directory = executable.parent()?;

    if directory.file_name()? != "bin" {
        return None;
    }

    directory.parent()
}

/// The last thing a failed build complained about. Cargo's stderr is a wall of
/// progress lines and the reason is at the bottom of it.
fn last_line(complaint: &str) -> &str {
    complaint
        .lines()
        .map(str::trim)
        .rfind(|line| !line.is_empty())
        .unwrap_or("sin explicación")
}

/// Which of the four published binaries this machine runs.
///
/// Worked out from what the standard library already knows rather than from a
/// build script exporting `TARGET`: there are four of them, they are listed in
/// `cli.yml`, and anything else has to be told there is no binary for it rather
/// than handed the closest guess.
fn target_triple() -> Option<&'static str> {
    triple_for(std::env::consts::ARCH, std::env::consts::OS)
}

fn triple_for(arch: &str, os: &str) -> Option<&'static str> {
    match (arch, os) {
        ("aarch64", "macos") => Some("aarch64-apple-darwin"),
        ("x86_64", "macos") => Some("x86_64-apple-darwin"),
        ("x86_64", "linux") => Some("x86_64-unknown-linux-gnu"),
        ("aarch64", "linux") => Some("aarch64-unknown-linux-gnu"),
        _ => None,
    }
}

#[cfg(unix)]
fn make_executable(path: &Path) -> Result<()> {
    use std::os::unix::fs::PermissionsExt;

    std::fs::set_permissions(path, std::fs::Permissions::from_mode(0o755)).with_context(|| {
        format!(
            "no se han podido ajustar los permisos de {}",
            path.display()
        )
    })
}

/// There is no published binary for a platform without Unix permissions, so
/// this exists to keep the module compiling rather than to be reached.
#[cfg(not(unix))]
fn make_executable(_path: &Path) -> Result<()> {
    Ok(())
}

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

    #[test]
    fn it_should_name_the_asset_the_way_the_release_workflow_does() {
        assert_eq!(
            asset_name("0.4.0", "aarch64-apple-darwin"),
            "fundaia-cli-v0.4.0-aarch64-apple-darwin.tar.gz",
        );
    }

    #[test]
    fn it_should_name_the_tag_the_way_the_release_workflow_does() {
        assert_eq!(tag_of("0.4.0"), "cli-v0.4.0");
    }

    #[test]
    fn it_should_know_the_binary_an_apple_silicon_mac_runs() {
        assert_eq!(triple_for("aarch64", "macos"), Some("aarch64-apple-darwin"));
    }

    #[test]
    fn it_should_know_the_binary_the_home_server_runs() {
        assert_eq!(
            triple_for("x86_64", "linux"),
            Some("x86_64-unknown-linux-gnu")
        );
    }

    #[test]
    fn it_should_refuse_a_platform_nothing_is_published_for() {
        assert!(triple_for("x86_64", "windows").is_none());
    }

    #[test]
    fn it_should_read_the_digest_out_of_what_sha256sum_writes() {
        let line = format!("{}  fundaia.tar.gz", "a".repeat(64));
        assert_eq!(expected_digest(&line), Some("a".repeat(64)));
    }

    #[test]
    fn it_should_read_a_digest_that_arrived_on_its_own() {
        assert_eq!(expected_digest(&"b".repeat(64)), Some("b".repeat(64)));
    }

    #[test]
    fn it_should_read_an_uppercase_digest_as_the_same_digest() {
        assert_eq!(expected_digest(&"A".repeat(64)), Some("a".repeat(64)));
    }

    #[test]
    fn it_should_refuse_a_checksum_file_that_is_empty() {
        assert!(expected_digest("   \n").is_none());
    }

    #[test]
    fn it_should_refuse_a_digest_of_the_wrong_length() {
        assert!(expected_digest("deadbeef  fundaia.tar.gz").is_none());
    }

    #[test]
    fn it_should_refuse_a_digest_that_is_not_hexadecimal() {
        assert!(expected_digest(&"z".repeat(64)).is_none());
    }

    #[test]
    fn it_should_hash_the_way_sha256sum_does() {
        assert_eq!(
            digest_of(b"fundaia"),
            "2973701beace145a932d249fbf716f25802a722be3ca41476b59e666597a83d4"
        );
    }

    #[test]
    fn it_should_accept_an_archive_whose_digest_matches() {
        let published = format!("{}  fundaia.tar.gz", digest_of(b"fundaia"));
        assert!(verify(b"fundaia", &published).is_ok());
    }

    #[test]
    fn it_should_refuse_an_archive_whose_digest_does_not_match() {
        let published = format!("{}  fundaia.tar.gz", digest_of(b"fundaia"));
        assert!(verify(b"something else entirely", &published).is_err());
    }

    #[test]
    fn it_should_refuse_an_archive_with_no_checksum_at_all() {
        assert!(verify(b"fundaia", "").is_err());
    }

    #[test]
    fn it_should_point_cargo_at_the_prefix_the_binary_lives_under() {
        assert_eq!(
            cargo_root(Path::new("/home/alex/.local/bin/fundaia")),
            Some(Path::new("/home/alex/.local")),
        );
    }

    #[test]
    fn it_should_let_cargo_decide_when_the_binary_is_not_in_a_bin_directory() {
        assert!(cargo_root(Path::new("/opt/tools/fundaia")).is_none());
    }

    #[test]
    fn it_should_report_what_cargo_complained_about_last() {
        assert_eq!(
            last_line("   Compiling fundaia\nerror: could not compile\n\n"),
            "error: could not compile",
        );
    }

    #[test]
    fn it_should_say_something_when_cargo_failed_without_a_word() {
        assert_eq!(last_line("  \n\n"), "sin explicación");
    }
}