sail-rs 0.4.0

//! SDK configuration loaded from environment variables.
//!
//! Endpoints default to the Sail service and can be overridden individually
//! via `SAIL_API_URL`, `SAILBOX_API_URL`, `SAIL_IMAGEBUILDER_URL`, and
//! `SAILBOX_INGRESS_URL`.

use crate::error::SailError;

/// Resolved SDK configuration: credentials plus the three service endpoints.
///
/// Usually produced from the environment and `~/.sail` via
/// [`ClientBuilder`](crate::ClientBuilder) or [`Client::from_env`](crate::Client::from_env),
/// which also fill the derived fields consistently.
///
/// `Debug` redacts the API key, so a logged `Config` never leaks the
/// credential.
#[derive(Clone)]
pub struct Config {
    /// The environment mode these endpoints were resolved from, or `None` for
    /// the default. Retained so a caller that rebuilds a config from an explicit
    /// key can reselect the same environment (including its ingress scheme)
    /// rather than fall back to the default.
    pub mode: Option<String>,
    /// Bearer API key sent on every request (trimmed of surrounding whitespace).
    pub api_key: String,
    /// Base URL of the public Sail REST API (no trailing path).
    pub api_url: String,
    /// Base URL of the Sailbox lifecycle/exec API.
    pub sailbox_api_url: String,
    /// `host:port` endpoint that image builds are submitted to.
    pub imagebuilder_url: String,
    /// Base URL that listener URLs are built from when the server does not
    /// return one, e.g. `https://api.sailresearch.com`.
    pub ingress_base: String,
    /// How a listener's URL is addressed under [`ingress_base`](Config::ingress_base).
    pub ingress_scheme: IngressScheme,
}

impl std::fmt::Debug for Config {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("Config")
            .field("mode", &self.mode)
            .field("api_key", &redact_key(&self.api_key))
            .field("api_url", &self.api_url)
            .field("sailbox_api_url", &self.sailbox_api_url)
            .field("imagebuilder_url", &self.imagebuilder_url)
            .field("ingress_base", &self.ingress_base)
            .field("ingress_scheme", &self.ingress_scheme)
            .finish()
    }
}

/// The redacted `Debug` form of an API key: present-or-absent, never the value.
pub(crate) fn redact_key(api_key: &str) -> &'static str {
    if api_key.is_empty() {
        "<unset>"
    } else {
        "<redacted>"
    }
}

/// How the SDK addresses a listener's URL under the ingress base, the Sailbox
/// id, and the port, when the server does not return one.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum IngressScheme {
    /// One host, path-addressed: `<base>/_sailbox/{sailbox_id}/{guest_port}`
    /// (self-hosted stacks, or an explicit ingress URL).
    Path,
    /// Per-listener subdomain of the base: `<sailbox>-<port>.<base host>`
    /// (the Sail service, served by wildcard DNS).
    Subdomain,
}

#[derive(Debug)]
struct EnvDefaults {
    api_url: &'static str,
    sailbox_api_url: &'static str,
    imagebuilder_url: &'static str,
    ingress_base: &'static str,
    /// True when listeners are subdomain-addressed (deployed wildcard DNS);
    /// false for path-addressed (local). Built into [`IngressScheme`].
    ingress_subdomain: bool,
}

const PROD: EnvDefaults = EnvDefaults {
    api_url: "https://api.sailresearch.com",
    sailbox_api_url: "https://sailbox-api.sailresearch.com",
    imagebuilder_url: "sailbox-imagebuilder-dispatcher.sailresearch.com:443",
    ingress_base: "https://api.sailresearch.com",
    ingress_subdomain: true,
};

const DEV: EnvDefaults = EnvDefaults {
    api_url: "https://dev.sailresearch.com",
    sailbox_api_url: "https://sailbox-api.dev.sailresearch.com",
    imagebuilder_url: "sailbox-imagebuilder-dispatcher.dev.sailresearch.com:443",
    ingress_base: "https://dev.sailresearch.com",
    ingress_subdomain: true,
};

const STAGING: EnvDefaults = EnvDefaults {
    api_url: "https://staging.sailresearch.com",
    sailbox_api_url: "https://sailbox-api.staging.sailresearch.com",
    imagebuilder_url: "sailbox-imagebuilder-dispatcher.staging.sailresearch.com:443",
    ingress_base: "https://beta.sailresearch.com",
    ingress_subdomain: true,
};

// Local backend nginx serves the public HTTP API on :8080 (see
// backend/docker-compose.yml NGINX_PORT). All sailbox lifecycle
// operations go through this endpoint; the imagebuilder dispatcher listens on
// :50061; listener ingress is served by path on :18080.
const LOCAL: EnvDefaults = EnvDefaults {
    api_url: "http://localhost:8080",
    sailbox_api_url: "http://localhost:8080",
    imagebuilder_url: "localhost:50061",
    ingress_base: "http://localhost:18080",
    ingress_subdomain: false,
};

fn env_or_empty(name: &str) -> String {
    std::env::var(name).unwrap_or_default()
}

fn env_trimmed(name: &str) -> String {
    env_or_empty(name).trim().to_string()
}

/// Resolve the env defaults for a SAIL_MODE value. Empty means "no mode
/// declared" and is treated as prod; any other unrecognized value raises.
fn mode_defaults(mode: &str) -> Result<&'static EnvDefaults, SailError> {
    match mode.trim().to_lowercase().as_str() {
        "" | "prod" => Ok(&PROD),
        "dev" => Ok(&DEV),
        "staging" => Ok(&STAGING),
        "local" => Ok(&LOCAL),
        other => Err(SailError::Config {
            message: format!(
                "SAIL_MODE={other} is not recognized; use SAIL_MODE=prod|dev|staging|local"
            ),
        }),
    }
}

/// The central public-API URL for a named mode (`prod`/`dev`/`staging`/`local`,
/// empty means prod), or `None` for an unrecognized mode. Lets bindings resolve
/// a mode's endpoint from this single source of truth instead of restating it.
#[doc(hidden)]
pub fn api_url_for_mode(mode: &str) -> Option<&'static str> {
    mode_defaults(mode).ok().map(|defaults| defaults.api_url)
}

impl Config {
    /// Resolve a config from a `mode` plus explicit overrides. `mode` selects
    /// the endpoint defaults (empty/None means prod); any non-empty override
    /// wins over its default. The API key is required and trimmed.
    pub(crate) fn resolve(
        mode: Option<&str>,
        api_key: String,
        api_url: Option<String>,
        sailbox_api_url: Option<String>,
        imagebuilder_url: Option<String>,
        sailbox_ingress_url: Option<String>,
    ) -> Result<Config, SailError> {
        let api_key = api_key.trim().to_string();
        if api_key.is_empty() {
            return Err(SailError::Config {
                message: "Set SAIL_API_KEY or run `sail auth login`.".to_string(),
            });
        }
        Config::build(
            mode,
            api_key,
            api_url,
            sailbox_api_url,
            imagebuilder_url,
            sailbox_ingress_url,
        )
    }

    /// Build a config, resolving each unset endpoint from the mode defaults. Does
    /// not require an API key; the caller decides whether an empty key is valid.
    fn build(
        mode: Option<&str>,
        api_key: String,
        api_url: Option<String>,
        sailbox_api_url: Option<String>,
        imagebuilder_url: Option<String>,
        sailbox_ingress_url: Option<String>,
    ) -> Result<Config, SailError> {
        let defaults = mode_defaults(mode.unwrap_or(""))?;
        fn or_default(override_value: Option<String>, default: &str) -> String {
            match override_value {
                Some(value) if !value.trim().is_empty() => value.trim().to_string(),
                _ => default.to_string(),
            }
        }
        // An explicit ingress URL is always addressed by path; the subdomain
        // scheme only applies to the deployed defaults.
        let has_override = sailbox_ingress_url
            .as_deref()
            .map(str::trim)
            .is_some_and(|value| !value.is_empty());
        let ingress_scheme = if !has_override && defaults.ingress_subdomain {
            IngressScheme::Subdomain
        } else {
            IngressScheme::Path
        };
        Ok(Config {
            mode: mode
                .map(str::trim)
                .filter(|value| !value.is_empty())
                .map(str::to_string),
            api_key,
            api_url: or_default(api_url, defaults.api_url),
            sailbox_api_url: or_default(sailbox_api_url, defaults.sailbox_api_url),
            imagebuilder_url: or_default(imagebuilder_url, defaults.imagebuilder_url),
            ingress_base: or_default(sailbox_ingress_url, defaults.ingress_base),
            ingress_scheme,
        })
    }

    /// Resolve a config from the environment, falling back to the stored
    /// `~/.sail` credential and settings for any value the environment does not
    /// set. Environment variables always win. The stored API key is applied only
    /// when its tagged target matches the resolved one, so a key minted for one
    /// environment is never sent to another. The key is trimmed so one sourced
    /// with a trailing newline can't produce a malformed bearer token.
    pub fn from_env() -> Result<Config, SailError> {
        Config::from_env_inner(/* require_api_key */ true)
    }

    /// Like [`from_env`](Self::from_env) but does not require an API key, for
    /// telemetry that degrades to a no-op when unauthenticated. Endpoints still
    /// resolve from the environment and `~/.sail`.
    #[doc(hidden)]
    pub fn from_env_optional_api_key() -> Result<Config, SailError> {
        Config::from_env_inner(/* require_api_key */ false)
    }

    fn from_env_inner(require_api_key: bool) -> Result<Config, SailError> {
        // Strict: a malformed config.toml or one with an unrecognized key is an
        // error here, so a typo'd setting fails loudly instead of being silently
        // dropped. Telemetry callers (voyage) catch this and degrade rather than
        // crash; see `_core_client.resolved_api_key`.
        let settings = crate::credentials::load_settings()?;
        let pick = |env_name: &str, stored_key: &str| -> String {
            pick_setting(std::env::var(env_name).ok(), settings.get(stored_key))
        };
        let mode = pick("SAIL_MODE", "mode");
        let api_url = pick("SAIL_API_URL", "api_url");
        let sailbox_api_url = pick("SAILBOX_API_URL", "sailbox_api_url");
        let imagebuilder_url = pick("SAIL_IMAGEBUILDER_URL", "imagebuilder_url");
        // Ingress is an env-only override; otherwise it follows the mode default.
        let sailbox_ingress_url = env_trimmed("SAILBOX_INGRESS_URL");

        let mut api_key = env_trimmed("SAIL_API_KEY");
        if api_key.is_empty() {
            let target = crate::credentials::resolve_target_api_url(&api_url, &mode);
            if crate::credentials::stored_key_matches_target(&settings, &target) {
                if let Some(stored) = crate::credentials::auth_key_best_effort() {
                    api_key = stored;
                }
            }
        }
        if require_api_key && api_key.is_empty() {
            return Err(SailError::Config {
                message: "Set SAIL_API_KEY or run `sail auth login`.".to_string(),
            });
        }

        Config::build(
            Some(&mode),
            api_key,
            opt(api_url),
            opt(sailbox_api_url),
            opt(imagebuilder_url),
            opt(sailbox_ingress_url),
        )
    }
}

fn opt(value: String) -> Option<String> {
    if value.is_empty() {
        None
    } else {
        Some(value)
    }
}

/// Resolve one endpoint/mode setting, trimmed. The environment wins whenever the
/// variable is present, including when it is empty: an explicit empty value masks
/// any stored override, which is how `sail --mode <env>` forces that mode's
/// endpoint defaults instead of inheriting a stored `~/.sail` endpoint. Only a
/// fully unset variable falls back to the stored value.
fn pick_setting(env_value: Option<String>, stored: Option<&String>) -> String {
    match env_value {
        Some(value) => value.trim().to_string(),
        None => stored
            .map(|value| value.trim().to_string())
            .unwrap_or_default(),
    }
}

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

    #[test]
    fn known_modes_resolve() {
        assert_eq!(mode_defaults("").unwrap().api_url, PROD.api_url);
        assert_eq!(mode_defaults(" PROD ").unwrap().api_url, PROD.api_url);
        assert_eq!(mode_defaults("dev").unwrap().api_url, DEV.api_url);
        assert_eq!(mode_defaults("local").unwrap().api_url, LOCAL.api_url);
    }

    #[test]
    fn unknown_mode_is_config_error() {
        match mode_defaults("production") {
            Err(SailError::Config { message }) => {
                assert!(message.contains("not recognized"), "message={message}");
            }
            other => panic!("expected Config error, got {other:?}"),
        }
    }

    #[test]
    fn pick_setting_present_env_masks_stored() {
        let stored = "https://stored.example".to_string();
        // A present env var wins, even empty: an empty value masks the stored
        // override (how `--mode` forces mode defaults), rather than falling back.
        assert_eq!(
            pick_setting(Some("https://env.example".to_string()), Some(&stored)),
            "https://env.example"
        );
        assert_eq!(pick_setting(Some(String::new()), Some(&stored)), "");
        assert_eq!(pick_setting(Some("  ".to_string()), Some(&stored)), "");
        // Only a fully unset var falls back to the stored value.
        assert_eq!(
            pick_setting(/* env_value */ None, Some(&stored)),
            "https://stored.example"
        );
        assert_eq!(pick_setting(/* env_value */ None, /* stored */ None), "");
    }

    #[test]
    fn override_wins_blank_falls_back_to_mode_default() {
        let config = Config::resolve(
            Some("dev"),
            "k".to_string(),
            Some("https://override.example".to_string()),
            /* sailbox_api_url */ None, // unset → mode default
            /* imagebuilder_url */ Some("   ".to_string()), // blank → mode default
            /* sailbox_ingress_url */ None,
        )
        .unwrap();
        assert_eq!(config.api_url, "https://override.example");
        assert_eq!(config.sailbox_api_url, DEV.sailbox_api_url);
        assert_eq!(config.imagebuilder_url, DEV.imagebuilder_url);
    }

    #[test]
    fn api_key_is_required_and_trimmed() {
        assert!(matches!(
            Config::resolve(
                /* mode */ None,
                "   ".to_string(),
                /* api_url */ None,
                /* sailbox_api_url */ None,
                /* imagebuilder_url */ None,
                /* sailbox_ingress_url */ None,
            ),
            Err(SailError::Config { .. })
        ));
        let config = Config::resolve(
            /* mode */ None,
            "  sk_k  ".to_string(),
            /* api_url */ None,
            /* sailbox_api_url */ None,
            /* imagebuilder_url */ None,
            /* sailbox_ingress_url */ None,
        )
        .unwrap();
        assert_eq!(config.api_key, "sk_k");
        // No mode declared resolves to the prod defaults.
        assert_eq!(config.api_url, PROD.api_url);
    }

    #[test]
    fn ingress_defaults_per_mode_and_override_forces_path() {
        // Deployed modes default to a subdomain-addressed ingress.
        let prod = Config::resolve(
            /* mode */ None,
            "k".to_string(),
            /* api_url */ None,
            /* sailbox_api_url */ None,
            /* imagebuilder_url */ None,
            /* sailbox_ingress_url */ None,
        )
        .unwrap();
        assert_eq!(prod.ingress_scheme, IngressScheme::Subdomain);
        assert_eq!(prod.ingress_base, PROD.ingress_base);
        // Local defaults to path-addressed ingress.
        let local = Config::resolve(
            Some("local"),
            "k".to_string(),
            /* api_url */ None,
            /* sailbox_api_url */ None,
            /* imagebuilder_url */ None,
            /* sailbox_ingress_url */ None,
        )
        .unwrap();
        assert_eq!(local.ingress_scheme, IngressScheme::Path);
        // An explicit ingress URL is always path-addressed.
        let overridden = Config::resolve(
            /* mode */ None,
            "k".to_string(),
            /* api_url */ None,
            /* sailbox_api_url */ None,
            /* imagebuilder_url */ None,
            Some("https://ingress.example".to_string()),
        )
        .unwrap();
        assert_eq!(overridden.ingress_scheme, IngressScheme::Path);
        assert_eq!(overridden.ingress_base, "https://ingress.example");
    }
}