qcli/

config.rs

//! Where qcli keeps its settings: `cli.conf` in the Quvyta ecosystem's folder, beside the
//! other Quvyta apps.
//!
//! ```text
//! ~/.config/quvyta/
//!     quvyta.conf     the language, theme and icons every Quvyta app shares
//!     cli.conf        qcli's settings: the provider it talks to
//! ```
//!
//! The provider is four keys: the address, the model, the file the key is in and the header the
//! key goes in. The key itself is never in this file, which people copy between machines and
//! paste into reports; only the path of the file that holds it.
//!
//! As a program of a QCode profile, qcli is told its provider by QCode instead, in two
//! environment variables: the address of QCode's relay inside the container and the model the
//! profile chose. The relay adds the key outside the container, so on that road qcli reads no key
//! and sends none, and the provider it was told is never written into this file.

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

use qframe::i18n::I18n;
use qframe::storage::{Ecosystem, Schema, Settings};

use crate::provider::{Endpoint, Key, KeyError};

/// The application's id in the ecosystem: its settings file is `cli.conf`.
pub const APP: &str = "cli";

/// The key of the address the Messages API lives under.
pub const ADDRESS: &str = "address";
/// The key of the model asked for.
pub const MODEL: &str = "model";
/// The key of the path of the file the key is read from.
pub const KEY_FILE: &str = "key-file";
/// The key of the header the key goes in.
pub const KEY_HEADER: &str = "key-header";

/// The header most servers of the Messages shape read the key from.
pub const DEFAULT_HEADER: &str = "x-api-key";

/// The variable a QCode profile names its relay's address in.
pub const ADDRESS_VARIABLE: &str = "QCLI_ADDRESS";
/// The variable a QCode profile names its model in.
pub const MODEL_VARIABLE: &str = "QCLI_MODEL";

/// What qcli's own keys may hold. Every value is text; an empty one is the same as none.
#[must_use]
pub fn schema() -> Schema {
    Schema::builtin().text(ADDRESS, "").text(MODEL, "").text(KEY_FILE, "").text(KEY_HEADER, DEFAULT_HEADER)
}

/// The settings from the ecosystem's folder, checked and healed.
#[must_use]
pub fn load() -> Settings {
    checked(Settings::load_member(&Ecosystem::QUVYTA, APP))
}

/// [`load`] from `folder` as the ecosystem's folder, so a test never touches the person's own
/// settings.
#[must_use]
pub fn load_in(folder: &Path) -> Settings {
    checked(Settings::open(folder.join(format!("{APP}.conf"))))
}

fn checked(settings: Settings) -> Settings {
    settings.member_of(&Ecosystem::QUVYTA).schema(schema()).self_heal(true)
}

/// The languages qcli speaks, for choosing the machine's one before the runtime is built.
#[must_use]
pub fn spoken() -> I18n {
    let mut i18n = I18n::builtin();
    for &(file, text) in crate::locales() {
        i18n.add_source(file, text);
    }
    i18n
}

/// Where the ecosystem's update notice reads its switch and remembers when it last asked.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct UpdateFolders {
    /// The ecosystem's configuration folder, whose shared file holds the switch.
    pub config: PathBuf,
    /// qcli's state folder, which remembers when the question was last asked.
    pub state: PathBuf,
}

impl UpdateFolders {
    /// This machine's folders, or `None` without a home folder, where nothing could remember the
    /// switch or the last question and so nothing is asked.
    #[must_use]
    pub fn here() -> Option<Self> {
        let ecosystem = Ecosystem::QUVYTA;
        ecosystem.config_dir().zip(ecosystem.state_dir(APP)).map(|(config, state)| Self { config, state })
    }
}

/// Where the provider was described.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum Source {
    /// In `cli.conf`, by the person, with the key in a file of theirs.
    #[default]
    Settings,
    /// By the QCode profile qcli runs in, in [`ADDRESS_VARIABLE`] and [`MODEL_VARIABLE`]. The
    /// address is QCode's relay on this machine, which adds the key itself, so there is no key
    /// file and no key; nothing of it is written into the settings, and it is changed in QCode.
    Profile,
}

/// Why the provider a QCode profile describes cannot be used. qcli does not open then: a tab that
/// went on with the settings file instead would talk to a provider the profile never chose.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum ProfileError {
    /// One variable is set and the other, named here, is not.
    Missing(&'static str),
    /// The address is not one of this machine. No key goes with a request on this road, so it is
    /// for a relay that adds one, never a way to reach a provider elsewhere. The address itself is
    /// not repeated: it was not written to be shown.
    Elsewhere,
}

impl std::fmt::Display for ProfileError {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            Self::Missing(name) => write!(
                f,
                "{name} is not set: a QCode profile tells qcli both {ADDRESS_VARIABLE} and {MODEL_VARIABLE}, or neither"
            ),
            Self::Elsewhere => write!(
                f,
                "{ADDRESS_VARIABLE} must be an address on this machine (localhost, 127.x or ::1): it is for the relay of a QCode profile, which adds the key, and no key is sent with it"
            ),
        }
    }
}

impl std::error::Error for ProfileError {}

/// The provider as the settings describe it. Every field is what the person wrote, trimmed.
#[derive(Debug, Clone, PartialEq, Eq, Default)]
pub struct Provider {
    /// The address the Messages API lives under.
    pub address: String,
    /// The model asked for.
    pub model: String,
    /// The path of the key file, as written: `~/` stands for the home folder.
    pub key_file: String,
    /// The header the key goes in.
    pub key_header: String,
    /// Where all this was described.
    pub source: Source,
}

/// Why the provider cannot be asked yet.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum Missing {
    /// One of the fields is empty; the key of the first one.
    Field(&'static str),
    /// The key file gave no key.
    Key(KeyError),
}

impl Provider {
    /// The provider in `settings`.
    #[must_use]
    pub fn from_settings(settings: &Settings) -> Self {
        let text = |key: &str| settings.get::<String>(key).unwrap_or_default().trim().to_owned();
        let header = text(KEY_HEADER);
        Self {
            address: text(ADDRESS),
            model: text(MODEL),
            key_file: text(KEY_FILE),
            key_header: if header.is_empty() { DEFAULT_HEADER.to_owned() } else { header },
            source: Source::Settings,
        }
    }

    /// The provider a QCode profile describes in the environment `read` gives, `None` when it
    /// describes none, which is qcli started anywhere but in a QCode tab.
    ///
    /// # Errors
    ///
    /// When only one of the two variables is set, or the address is not one of this machine.
    pub fn from_environment(read: impl Fn(&str) -> Option<String>) -> Result<Option<Self>, ProfileError> {
        let value = |name: &str| read(name).map(|value| value.trim().to_owned()).filter(|value| !value.is_empty());
        match (value(ADDRESS_VARIABLE), value(MODEL_VARIABLE)) {
            (None, None) => Ok(None),
            (None, Some(_)) => Err(ProfileError::Missing(ADDRESS_VARIABLE)),
            (Some(_), None) => Err(ProfileError::Missing(MODEL_VARIABLE)),
            (Some(address), Some(_)) if !on_this_machine(&address) => Err(ProfileError::Elsewhere),
            (Some(address), Some(model)) => Ok(Some(Self {
                address,
                model,
                key_file: String::new(),
                key_header: String::new(),
                source: Source::Profile,
            })),
        }
    }

    /// Writes the provider into `settings`. A header that is the default is not written, the
    /// way the ecosystem writes no default. A provider a QCode profile described is never
    /// written: it is the profile's, and the person's own settings stay as they wrote them.
    pub fn write(&self, settings: &mut Settings) {
        if self.source == Source::Profile {
            return;
        }
        settings.set(ADDRESS, self.address.trim().to_owned());
        settings.set(MODEL, self.model.trim().to_owned());
        settings.set(KEY_FILE, self.key_file.trim().to_owned());
        let header = self.key_header.trim();
        if header.is_empty() || header == DEFAULT_HEADER {
            settings.remove(KEY_HEADER);
        } else {
            settings.set(KEY_HEADER, header.to_owned());
        }
    }

    /// The first empty field, if any: the provider cannot be asked without all of them. A
    /// profile's provider has no key file to miss.
    #[must_use]
    pub fn missing_field(&self) -> Option<&'static str> {
        let key_file = (self.source == Source::Settings).then_some((KEY_FILE, &self.key_file));
        [(ADDRESS, &self.address), (MODEL, &self.model)]
            .into_iter()
            .chain(key_file)
            .find_map(|(key, value)| value.is_empty().then_some(key))
    }

    /// The key file's path, with `~/` read as the home folder.
    #[must_use]
    pub fn key_path(&self) -> PathBuf {
        expand_home(&self.key_file)
    }

    /// The endpoint to ask, with the key read from its file now; a profile's provider is asked
    /// with no key, which its relay adds.
    ///
    /// # Errors
    ///
    /// When a field is empty or the key file gives no key.
    pub fn endpoint(&self) -> Result<Endpoint, Missing> {
        if let Some(field) = self.missing_field() {
            return Err(Missing::Field(field));
        }
        let key = match self.source {
            Source::Settings => Some(Key::from_file(&self.key_path()).map_err(Missing::Key)?),
            Source::Profile => None,
        };
        Ok(Endpoint {
            address: self.address.clone(),
            model: self.model.clone(),
            key_header: self.key_header.clone(),
            key,
            silence: Endpoint::SILENCE,
        })
    }
}

/// Whether `address` is an `http://` or `https://` address of this machine: `localhost`, `127.x`
/// or `::1`. An address that names a user before its host is not, whatever the host: it is not
/// what a relay is given, and it makes the host easy to misread.
#[must_use]
pub fn on_this_machine(address: &str) -> bool {
    let address = address.trim();
    let scheme = |name: &str| address.get(..name.len()).is_some_and(|start| start.eq_ignore_ascii_case(name));
    let rest = if scheme("http://") {
        &address[7..]
    } else if scheme("https://") {
        &address[8..]
    } else {
        return false;
    };
    let authority = rest.split(['/', '?', '#']).next().unwrap_or_default();
    !authority.contains('@') && loopback(host(authority))
}

/// The host of an address's authority (`host`, `host:port`, `[v6]:port`), with any user part
/// before an `@` left out.
pub(crate) fn host(authority: &str) -> &str {
    let host = authority.rsplit_once('@').map_or(authority, |(_, host)| host);
    if let Some(bracketed) = host.strip_prefix('[') {
        bracketed.split(']').next().unwrap_or_default()
    } else {
        host.split(':').next().unwrap_or_default()
    }
}

/// Whether `host` is this machine: `localhost`, or a loopback address.
pub(crate) fn loopback(host: &str) -> bool {
    host.eq_ignore_ascii_case("localhost") || host.parse::<std::net::IpAddr>().is_ok_and(|ip| ip.is_loopback())
}

/// `path` with a leading `~/` replaced by the home folder.
///
/// Without a home folder there is nothing to replace it with, so the path is used as it was
/// written and the key file under it is then reported as the system reports it.
fn expand_home(path: &str) -> PathBuf {
    expand_home_in(path, std::env::var_os("HOME"))
}

fn expand_home_in(path: &str, home: Option<std::ffi::OsString>) -> PathBuf {
    match (path.strip_prefix("~/"), home) {
        (Some(rest), Some(home)) => PathBuf::from(home).join(rest),
        _ => PathBuf::from(path),
    }
}

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

    fn folder(name: &str) -> PathBuf {
        let folder = std::env::temp_dir().join(format!("qcli-config-{name}-{}", std::process::id()));
        let _ = std::fs::remove_dir_all(&folder);
        std::fs::create_dir_all(&folder).expect("folder");
        folder
    }

    #[test]
    fn the_provider_is_written_and_read_back_and_the_default_header_is_not_written() {
        let folder = folder("round");
        let mut settings = load_in(&folder);
        let provider = Provider {
            address: " http://127.0.0.1:9/anthropic ".into(),
            model: "some-model".into(),
            key_file: "~/keys/made-up".into(),
            key_header: DEFAULT_HEADER.into(),
            source: Source::Settings,
        };
        provider.write(&mut settings);
        settings.save().expect("saved");
        let text = std::fs::read_to_string(folder.join("cli.conf")).expect("the file");
        assert!(text.contains("address = \"http://127.0.0.1:9/anthropic\""), "{text}");
        assert!(!text.contains(KEY_HEADER), "the default header is not written: {text}");

        let read = Provider::from_settings(&load_in(&folder));
        assert_eq!(read.address, "http://127.0.0.1:9/anthropic");
        assert_eq!(read.key_header, DEFAULT_HEADER);

        let mut settings = load_in(&folder);
        Provider { key_header: "api-key".into(), ..read }.write(&mut settings);
        settings.save().expect("saved");
        assert_eq!(Provider::from_settings(&load_in(&folder)).key_header, "api-key");
        std::fs::remove_dir_all(&folder).expect("clean up");
    }

    #[test]
    fn an_endpoint_needs_every_field_and_a_key_in_the_file() {
        let folder = folder("endpoint");
        let key_file = folder.join("key");
        let mut provider = Provider {
            address: "http://127.0.0.1:9".into(),
            model: String::new(),
            key_file: key_file.display().to_string(),
            key_header: "api-key".into(),
            source: Source::Settings,
        };
        assert_eq!(provider.endpoint().expect_err("no model"), Missing::Field(MODEL));
        provider.model = "m".into();
        assert!(matches!(provider.endpoint(), Err(Missing::Key(KeyError::Unreadable { .. }))));
        std::fs::write(&key_file, "not-a-real-key-0000-wxyz\n").expect("key");
        let endpoint = provider.endpoint().expect("an endpoint");
        assert_eq!((endpoint.model.as_str(), endpoint.key_header.as_str()), ("m", "api-key"));
        std::fs::remove_dir_all(&folder).expect("clean up");
    }

    #[test]
    fn a_home_path_is_read_from_the_home_folder() {
        let home = std::env::var_os("HOME").map(PathBuf::from).expect("a home in tests");
        assert_eq!(expand_home("~/a/b"), home.join("a/b"));
        assert_eq!(expand_home("/a/b"), PathBuf::from("/a/b"));
    }

    #[test]
    fn a_home_path_with_no_home_folder_is_the_path_as_it_was_written() {
        // Nothing to stand for `~`, so the path is left as it is and the key file under it is
        // then reported as the system reports it, never as a key.
        let path = expand_home_in("~/.config/quvyta/key", None);
        assert_eq!(path, PathBuf::from("~/.config/quvyta/key"));
        let provider = Provider {
            address: "http://127.0.0.1:9".into(),
            model: "m".into(),
            key_file: "~/.config/quvyta/key".into(),
            key_header: DEFAULT_HEADER.into(),
            source: Source::Settings,
        };
        assert!(matches!(provider.endpoint(), Err(Missing::Key(KeyError::Unreadable { .. }))));
    }

    #[test]
    fn a_settings_file_that_is_a_folder_leaves_the_provider_unset_and_says_why() {
        let folder = folder("a-folder");
        std::fs::create_dir(folder.join(format!("{APP}.conf"))).expect("the settings file is a folder");
        let settings = load_in(&folder);
        let said: Vec<_> = settings.diagnostics().iter().map(|problem| problem.message.clone()).collect();
        assert!(
            said.iter().any(|line| line.contains("cli.conf") && line.contains("os error 21")),
            "the file is named and what the system said is quoted: {said:?}"
        );
        assert!(
            std::fs::metadata(folder.join(format!("{APP}.conf"))).expect("still there").is_dir(),
            "nothing was written over it"
        );
        assert_eq!(Provider::from_settings(&settings).missing_field(), Some(ADDRESS), "the form opens for the address");
        std::fs::remove_dir_all(&folder).expect("clean up");
    }

    #[test]
    fn an_unknown_key_is_dropped_and_a_value_of_the_wrong_type_is_replaced_by_the_default() {
        let folder = folder("healed");
        let file = folder.join(format!("{APP}.conf"));
        std::fs::write(&file, "address = 5\nmodel = \"kept\"\nkey-file = \"~/k\"\ncolour = \"green\"\n")
            .expect("write");
        let settings = load_in(&folder);
        let provider = Provider::from_settings(&settings);
        assert_eq!(
            (provider.address.as_str(), provider.model.as_str(), provider.key_file.as_str()),
            ("", "kept", "~/k")
        );
        let healed = std::fs::read_to_string(&file).expect("the healed file");
        assert!(healed.contains("model = \"kept\""), "what was right is kept: {healed}");
        assert!(healed.contains("address = \"\""), "what was wrong became the default: {healed}");
        assert!(!healed.contains("colour"), "what qcli has no use for is gone: {healed}");
        assert!(load_in(&folder).diagnostics().is_empty(), "the file is whole now, so nothing is said about it");
        std::fs::remove_dir_all(&folder).expect("clean up");
    }

    #[test]
    fn a_key_file_that_is_a_folder_or_is_not_there_never_becomes_an_endpoint() {
        let folder = folder("bad-key-path");
        std::fs::create_dir(folder.join("a-folder")).expect("folder");
        let mut provider = Provider {
            address: "http://127.0.0.1:9".into(),
            model: "m".into(),
            key_file: folder.join("a-folder").display().to_string(),
            key_header: DEFAULT_HEADER.into(),
            source: Source::Settings,
        };
        let Err(Missing::Key(KeyError::Unreadable { path, .. })) = provider.endpoint() else {
            panic!("a folder is not a key file, got {:?}", provider.endpoint());
        };
        assert_eq!(path, folder.join("a-folder"), "the file it could not read is named");

        provider.key_file = folder.join("not-there").display().to_string();
        assert!(
            matches!(provider.endpoint(), Err(Missing::Key(KeyError::Unreadable { .. }))),
            "a file that is not there is named too"
        );
        std::fs::remove_dir_all(&folder).expect("clean up");
    }

    fn environment(address: Option<&'static str>, model: Option<&'static str>) -> impl Fn(&str) -> Option<String> {
        move |name| match name {
            ADDRESS_VARIABLE => address.map(str::to_owned),
            MODEL_VARIABLE => model.map(str::to_owned),
            _ => None,
        }
    }

    #[test]
    fn a_profile_that_names_both_variables_gives_a_provider_with_no_key_file() {
        let read = |name: &str| match name {
            ADDRESS_VARIABLE => Some("http://127.0.0.1:41417".to_owned()),
            MODEL_VARIABLE => Some("relay-model-7".to_owned()),
            _ => None,
        };
        let provider = Provider::from_environment(read).expect("no error").expect("a provider");
        assert_eq!(provider.source, Source::Profile);
        assert_eq!(provider.address, "http://127.0.0.1:41417");
        assert_eq!(provider.model, "relay-model-7");
        assert_eq!(provider.missing_field(), None, "a profile's provider never misses the key file");
        let endpoint = provider.endpoint().expect("an endpoint with no key read");
        assert!(endpoint.key.is_none(), "no key goes with a profile's request");
        assert_eq!(endpoint.model, "relay-model-7");

        assert_eq!(Provider::from_environment(environment(None, None)), Ok(None), "neither set is no profile");
        assert_eq!(Provider::from_environment(environment(Some("  "), Some(" "))), Ok(None), "spaces are not set");
    }

    #[test]
    fn only_one_of_the_two_variables_stops_qcli_and_names_the_missing_one() {
        let only_address = Provider::from_environment(environment(Some("http://127.0.0.1:41417"), None));
        assert_eq!(only_address, Err(ProfileError::Missing(MODEL_VARIABLE)));
        let only_model = Provider::from_environment(environment(None, Some("relay-model-7")));
        assert_eq!(only_model, Err(ProfileError::Missing(ADDRESS_VARIABLE)));

        let said = only_address.expect_err("missing").to_string();
        assert!(said.contains(MODEL_VARIABLE), "the missing name is said: {said}");
        let said = only_model.expect_err("missing").to_string();
        assert!(said.contains(ADDRESS_VARIABLE), "the missing name is said: {said}");
    }

    #[test]
    fn an_address_off_this_machine_is_refused_without_being_repeated() {
        let refused = [
            "https://api.example.com/anthropic",
            "http://127.0.0.1@evil.example.com",
            "http://localhost.evil.example:41417",
            "ftp://127.0.0.1",
            "127.0.0.1:41417",
            "http://10.0.0.5:41417",
        ];
        for address in refused {
            let error = Provider::from_environment(environment(Some(address), Some("m"))).expect_err(address);
            assert_eq!(error, ProfileError::Elsewhere, "{address}");
            let said = error.to_string();
            for word in ["example", "evil", "10.0.0.5"] {
                assert!(!said.contains(word), "{address}: the address is not repeated: {said}");
            }
        }
        let local = ["http://localhost:41417", "http://[::1]:41417/", "https://127.0.0.2", "HTTP://127.0.0.1:41417"];
        for address in local {
            let result = Provider::from_environment(environment(Some(address), Some("m")));
            assert!(matches!(result, Ok(Some(_))), "{address} is this machine: {result:?}");
        }
    }

    #[test]
    fn a_profile_provider_is_never_written_into_the_settings() {
        let folder = folder("profile-write");
        let mut settings = load_in(&folder);
        Provider {
            address: "http://127.0.0.1:9/mine".into(),
            model: "mine-model".into(),
            key_file: "~/keys/mine".into(),
            key_header: DEFAULT_HEADER.into(),
            source: Source::Settings,
        }
        .write(&mut settings);
        settings.save().expect("saved");

        let profile = Provider::from_environment(environment(Some("http://127.0.0.1:41417"), Some("relay-model-7")))
            .expect("no error")
            .expect("a provider");
        let mut settings = load_in(&folder);
        profile.write(&mut settings);
        settings.save().expect("saved");

        let read = Provider::from_settings(&load_in(&folder));
        assert_eq!(read.address, "http://127.0.0.1:9/mine", "the person's address stays");
        assert_eq!(read.model, "mine-model", "the profile's model is not written");
        std::fs::remove_dir_all(&folder).expect("clean up");
    }
}