saturnus 0.4.0

Command-line front end of the saturnus emulator: run ROMs headless, script keys, dump screens, serve the serial port and the control API
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105

//! ROM images: loading with a size check, and `rom fetch` from hpcalc.org
//! (kb: docs/clean-room-rule). ROMs are never bundled; the user downloads
//! them after a confirmation prompt.

use std::io::{BufRead, Write};
use std::path::{Path, PathBuf};

use anyhow::{Context, Result, bail};
use saturnus_core::Model;
use saturnus_drive::fetch::{self, Fetched, Wanted};
use saturnus_host::romid::{self, KnownRom};

pub use saturnus_drive::rom::load;

/// The revision of a known image by SHA-256; the one list of known images,
/// with where hpcalc.org offers them, is `saturnus_host::romid::KNOWN`,
/// which the pages and the app share.
pub use saturnus_host::romid::revision;

/// `saturnus rom fetch`: download, unzip and verify the ROM into `dir`
/// (`saturnus_drive::fetch`). An existing file that verifies is kept
/// without downloading.
pub fn fetch(model: Model, dir: &Path, yes: bool) -> Result<PathBuf> {
    let Some(known) = romid::download(model) else {
        bail!(
            "there is no download for the {}: HP never published its ROM. Read the ROM \
             out of your own calculator and pass the file with --rom",
            model.name().to_uppercase()
        );
    };
    let wanted = Wanted::from(known);
    let target = dir.join(known.file);
    // Asked only when there is something to download.
    let present =
        saturnus_drive::files::read_capped(&target, saturnus_drive::files::max_rom_file())
            .is_ok_and(|d| fetch::verify(&wanted, &d).is_ok());
    if !present && target.exists() {
        bail!(
            "{} is not the expected ROM file (wrong size or SHA-256); delete it and \
             run this again",
            target.display()
        );
    }
    if !present && !yes && !confirm(known, dir)? {
        bail!("download cancelled");
    }
    let got = fetch::fetch(&wanted, dir, false)
        .map_err(anyhow::Error::msg)
        .with_context(|| {
            format!(
                "cannot download the {} ROM; download it yourself from {}",
                model.name().to_uppercase(),
                known.page
            )
        })?;
    let what = match got {
        Fetched::Present(_) => "is present and verified",
        Fetched::Downloaded(_) => "downloaded and verified",
    };
    println!("{} {what} (SHA-256 {})", got.path().display(), known.sha256);
    Ok(got.path().to_path_buf())
}

fn confirm(known: &KnownRom, dir: &Path) -> Result<bool> {
    print!(
        "Download {} into {}?\nThe ROM is HP's copyrighted software, hosted by hpcalc.org with \
         HP's permission for use with emulators; it is not part of saturnus. [y/N] ",
        known.url,
        dir.display()
    );
    std::io::stdout().flush().context("cannot write prompt")?;
    let mut answer = String::new();
    std::io::stdin()
        .lock()
        .read_line(&mut answer)
        .context("cannot read the answer")?;
    Ok(matches!(answer.trim(), "y" | "Y" | "yes" | "YES" | "Yes"))
}

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

    #[test]
    fn the_pioneers_have_no_download() {
        for m in [Model::Hp27s, Model::Hp17bii, Model::Hp17b, Model::Hp28s] {
            let e = fetch(m, Path::new("unused"), true).unwrap_err().to_string();
            assert!(e.contains("your own calculator"), "{e}");
        }
        let e = fetch(Model::Hp42s, Path::new("unused"), true).unwrap_err();
        assert!(e.to_string().contains("--rom"), "{e}");
    }

    /// An existing file that does not verify is refused before anything
    /// is downloaded or asked.
    #[test]
    fn a_bad_existing_file_is_refused() {
        let dir = std::env::temp_dir().join(format!("saturnus-cli-rom-{}", std::process::id()));
        std::fs::create_dir_all(&dir).unwrap();
        std::fs::write(dir.join("sxrom-j"), [0u8; 10]).unwrap();
        let e = fetch(Model::Hp48sx, &dir, false).unwrap_err();
        assert!(e.to_string().contains("delete it"), "{e}");
        std::fs::remove_dir_all(&dir).unwrap();
    }
}