gglib_core/

settings.rs

//! Settings domain types and validation.
//!
//! This module contains the core settings types used across the application.
//! These are pure domain types with no infrastructure dependencies.

use serde::{Deserialize, Serialize};

use crate::domain::{InferenceConfig, InferenceProfile};

/// Default port for the OpenAI-compatible proxy server.
pub const DEFAULT_PROXY_PORT: u16 = 8080;

/// Default base port for llama-server instance allocation.
pub const DEFAULT_LLAMA_BASE_PORT: u16 = 9000;

/// Default context size for models when not specified by the user.
pub const DEFAULT_CONTEXT_SIZE: u64 = 4096;

/// Application settings structure.
///
/// All fields are optional to support partial updates and graceful defaults.
#[derive(Debug, Clone, Default, Serialize, Deserialize, PartialEq)]
#[serde(default)]
pub struct Settings {
    /// Default directory for downloading models.
    pub default_download_path: Option<String>,

    /// Default context size for models (e.g., 4096, 8192).
    pub default_context_size: Option<u64>,

    /// Port for the OpenAI-compatible proxy server.
    pub proxy_port: Option<u16>,

    /// Base port for llama-server instance allocation (first port in range).
    /// Note: The OpenAI-compatible proxy listens on `proxy_port`.
    pub llama_base_port: Option<u16>,

    /// Maximum number of downloads that can be queued (1-50).
    pub max_download_queue_size: Option<u32>,

    /// Whether to show memory fit indicators in `HuggingFace` browser.
    pub show_memory_fit_indicators: Option<bool>,

    /// Maximum iterations for tool calling agentic loop.
    pub max_tool_iterations: Option<u32>,

    /// Maximum stagnation steps before stopping agent loop.
    pub max_stagnation_steps: Option<u32>,

    /// Default model ID for commands that support a default model.
    pub default_model_id: Option<i64>,

    /// Global inference parameter defaults.
    ///
    /// Applied when neither request nor per-model defaults are specified.
    /// If not set, hardcoded defaults are used as final fallback.
    #[serde(default)]
    pub inference_defaults: Option<InferenceConfig>,

    /// Named sampling profiles, selectable per request as `{model}:{profile}`.
    ///
    /// Global rather than per-model: one `coding` profile applies to every
    /// model, and its sparse fields fall through to that model's own
    /// `inference_defaults` for anything it does not set. See
    /// [`crate::domain::inference_profile`].
    #[serde(default)]
    pub inference_profiles: Option<Vec<InferenceProfile>>,

    // ── Setup wizard ────────────────────────────────────────────────
    /// Whether the first-run setup wizard has been completed.
    pub setup_completed: Option<bool>,

    /// Custom prompt template for generating chat titles.
    pub title_generation_prompt: Option<String>,

    // ── Network binding ─────────────────────────────────────────────
    /// Override the bind host for `gglib web`.
    ///
    /// `None` → use the compiled-in default (`127.0.0.1`). The `--host` flag
    /// takes precedence for a single run without changing this value.
    pub bind_host: Option<String>,

    /// Whether `gglib web` binds all LAN interfaces and broadcasts over mDNS.
    ///
    /// `None`/`Some(false)` → localhost-only. The `--share-lan` flag can turn
    /// this on for a single run, but cannot turn it off — clear it here.
    pub share_lan: Option<bool>,

    // ── Sampling authority ──────────────────────────────────────────
    /// Whether a client's own sampling parameters (`temperature`, `top_p`,
    /// `top_k`, `presence_penalty`, `repeat_penalty`, `min_p`) are honoured
    /// by the proxy at all.
    ///
    /// `None`/`Some(false)` → the client's sampling opinions are dropped from
    /// the resolution hierarchy entirely; the request falls straight through
    /// to the profile / per-model / global / floor layers as if the client
    /// had sent none of them. `max_tokens` is unaffected either way — it is
    /// a budget, not a taste, and a client that names one still gets it
    /// honoured; ignoring it would silently truncate that client's own
    /// turns.
    ///
    /// Defaults to distrust because most clients that talk to this proxy
    /// send fixed sampling values with no user-facing control behind them —
    /// boilerplate the client always sends, not a deliberate choice by
    /// whoever is using it (VS Code Copilot's LLM Gateway hardcodes
    /// `temperature: 0` on every request, for one). Letting that boilerplate
    /// silently outrank a model's own tuned defaults and this server's
    /// global settings defeats the point of configuring either. Set `true`
    /// for a client that does expose real sampling controls to its user
    /// (`OpenWebUI`'s sliders, for instance).
    pub trust_client_sampling: Option<bool>,
}

impl Settings {
    /// Create settings with sensible defaults.
    #[must_use]
    pub const fn with_defaults() -> Self {
        Self {
            default_download_path: None,
            default_context_size: Some(DEFAULT_CONTEXT_SIZE),
            proxy_port: Some(DEFAULT_PROXY_PORT),
            llama_base_port: Some(DEFAULT_LLAMA_BASE_PORT),
            max_download_queue_size: Some(10),
            show_memory_fit_indicators: Some(true),
            #[allow(clippy::cast_possible_truncation)] // compile-time constants, always < u32::MAX
            max_tool_iterations: Some(crate::domain::agent::DEFAULT_MAX_ITERATIONS as u32),
            #[allow(clippy::cast_possible_truncation)]
            max_stagnation_steps: Some(crate::domain::agent::DEFAULT_MAX_STAGNATION_STEPS as u32),
            default_model_id: None,
            inference_defaults: None,
            inference_profiles: None,
            setup_completed: None,
            title_generation_prompt: None,
            bind_host: None,
            share_lan: None,
            trust_client_sampling: None,
        }
    }

    /// Get the effective proxy port (with default fallback).
    #[must_use]
    pub const fn effective_proxy_port(&self) -> u16 {
        match self.proxy_port {
            Some(port) => port,
            None => DEFAULT_PROXY_PORT,
        }
    }

    /// Get the effective llama-server base port (with default fallback).
    #[must_use]
    pub const fn effective_llama_base_port(&self) -> u16 {
        match self.llama_base_port {
            Some(port) => port,
            None => DEFAULT_LLAMA_BASE_PORT,
        }
    }

    /// Merge another settings into this one, only updating fields that are Some.
    pub fn merge(&mut self, other: &SettingsUpdate) {
        if let Some(ref path) = other.default_download_path {
            self.default_download_path.clone_from(path);
        }
        if let Some(ref ctx_size) = other.default_context_size {
            self.default_context_size = *ctx_size;
        }
        if let Some(ref port) = other.proxy_port {
            self.proxy_port = *port;
        }
        if let Some(ref port) = other.llama_base_port {
            self.llama_base_port = *port;
        }
        if let Some(ref queue_size) = other.max_download_queue_size {
            self.max_download_queue_size = *queue_size;
        }
        if let Some(ref show_fit) = other.show_memory_fit_indicators {
            self.show_memory_fit_indicators = *show_fit;
        }
        if let Some(ref iters) = other.max_tool_iterations {
            self.max_tool_iterations = *iters;
        }
        if let Some(ref steps) = other.max_stagnation_steps {
            self.max_stagnation_steps = *steps;
        }
        if let Some(ref model_id) = other.default_model_id {
            self.default_model_id = *model_id;
        }
        if let Some(ref inference_defaults) = other.inference_defaults {
            self.inference_defaults.clone_from(inference_defaults);
        }
        if let Some(ref inference_profiles) = other.inference_profiles {
            self.inference_profiles.clone_from(inference_profiles);
        }
        if let Some(ref v) = other.setup_completed {
            self.setup_completed = *v;
        }
        if let Some(ref v) = other.title_generation_prompt {
            self.title_generation_prompt.clone_from(v);
        }
        if let Some(ref v) = other.bind_host {
            self.bind_host.clone_from(v);
        }
        if let Some(ref v) = other.share_lan {
            self.share_lan = *v;
        }
        if let Some(ref v) = other.trust_client_sampling {
            self.trust_client_sampling = *v;
        }
    }
}

/// Partial settings update.
///
/// Each field is `Option<Option<T>>`:
/// - `None` = don't change this field
/// - `Some(None)` = set field to None/null
/// - `Some(Some(value))` = set field to value
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
pub struct SettingsUpdate {
    pub default_download_path: Option<Option<String>>,
    pub default_context_size: Option<Option<u64>>,
    pub proxy_port: Option<Option<u16>>,
    pub llama_base_port: Option<Option<u16>>,
    pub max_download_queue_size: Option<Option<u32>>,
    pub show_memory_fit_indicators: Option<Option<bool>>,
    pub max_tool_iterations: Option<Option<u32>>,
    pub max_stagnation_steps: Option<Option<u32>>,
    pub default_model_id: Option<Option<i64>>,
    pub inference_defaults: Option<Option<InferenceConfig>>,
    pub inference_profiles: Option<Option<Vec<InferenceProfile>>>,
    pub setup_completed: Option<Option<bool>>,
    pub title_generation_prompt: Option<Option<String>>,
    pub bind_host: Option<Option<String>>,
    pub share_lan: Option<Option<bool>>,
    pub trust_client_sampling: Option<Option<bool>>,
}

/// Settings validation error.
#[derive(Debug, Clone, thiserror::Error)]
pub enum SettingsError {
    #[error("Context size must be between 512 and 1,000,000, got {0}")]
    InvalidContextSize(u64),

    #[error("Port should be >= 1024 (privileged ports require root), got {0}")]
    InvalidPort(u16),

    #[error("Max download queue size must be between 1 and 50, got {0}")]
    InvalidQueueSize(u32),

    #[error("Download path cannot be empty")]
    EmptyDownloadPath,

    #[error("Invalid inference parameter: {0}")]
    InvalidInferenceConfig(String),

    #[error("Invalid inference profile: {0}")]
    InvalidInferenceProfile(String),

    #[error("Bind host must be an IP address (e.g. 127.0.0.1 or 0.0.0.0), got '{0}'")]
    InvalidBindHost(String),
}

/// Validate settings values.
pub fn validate_settings(settings: &Settings) -> Result<(), SettingsError> {
    // Validate context size
    if let Some(ctx_size) = settings.default_context_size
        && !(512..=1_000_000).contains(&ctx_size)
    {
        return Err(SettingsError::InvalidContextSize(ctx_size));
    }

    // Validate proxy port
    if let Some(port) = settings.proxy_port
        && port < 1024
    {
        return Err(SettingsError::InvalidPort(port));
    }

    // Validate llama-server base port
    if let Some(port) = settings.llama_base_port
        && port < 1024
    {
        return Err(SettingsError::InvalidPort(port));
    }

    // Validate max download queue size
    if let Some(queue_size) = settings.max_download_queue_size
        && !(1..=50).contains(&queue_size)
    {
        return Err(SettingsError::InvalidQueueSize(queue_size));
    }

    // Validate download path if specified
    if settings
        .default_download_path
        .as_ref()
        .is_some_and(|p| p.trim().is_empty())
    {
        return Err(SettingsError::EmptyDownloadPath);
    }

    // Validate the bind host if specified. Requiring a literal IP (rather than
    // accepting a name) keeps the value unambiguous for both the TCP bind and
    // the mDNS address record.
    if let Some(ref host) = settings.bind_host
        && host.parse::<std::net::IpAddr>().is_err()
    {
        return Err(SettingsError::InvalidBindHost(host.clone()));
    }

    // Validate inference defaults if specified
    if let Some(ref inference_config) = settings.inference_defaults {
        validate_inference_config(inference_config)
            .map_err(SettingsError::InvalidInferenceConfig)?;
    }

    // Validate inference profiles if specified
    if let Some(ref profiles) = settings.inference_profiles {
        validate_inference_profiles(profiles).map_err(SettingsError::InvalidInferenceProfile)?;
    }

    Ok(())
}

/// Validate a set of inference profiles.
///
/// Checks each profile's name against [`crate::domain::validate_name`], rejects
/// duplicate names (they would make `{model}:{profile}` ambiguous), and reuses
/// [`validate_inference_config`] for the numeric ranges so profile parameters
/// and global defaults can never drift apart on what counts as valid.
///
/// # Errors
///
/// Returns a human-readable description of the first problem found.
pub fn validate_inference_profiles(profiles: &[InferenceProfile]) -> Result<(), String> {
    let mut seen: Vec<&str> = Vec::with_capacity(profiles.len());

    for profile in profiles {
        profile.validate().map_err(|e| e.to_string())?;

        if seen.contains(&profile.name.as_str()) {
            return Err(format!("duplicate profile name '{}'", profile.name));
        }
        seen.push(&profile.name);

        validate_inference_config(&profile.config)
            .map_err(|e| format!("profile '{}': {e}", profile.name))?;
    }

    Ok(())
}

/// Validate inference configuration parameters.
///
/// Checks that all specified parameters are within valid ranges.
pub fn validate_inference_config(config: &InferenceConfig) -> Result<(), String> {
    // Validate temperature (0.0 - 2.0)
    if let Some(temp) = config.temperature
        && !(0.0..=2.0).contains(&temp)
    {
        return Err(format!(
            "Temperature must be between 0.0 and 2.0, got {temp}"
        ));
    }

    // Validate top_p (0.0 - 1.0)
    if let Some(top_p) = config.top_p
        && !(0.0..=1.0).contains(&top_p)
    {
        return Err(format!("Top P must be between 0.0 and 1.0, got {top_p}"));
    }

    // Validate top_k (must be positive)
    if let Some(top_k) = config.top_k
        && top_k <= 0
    {
        return Err(format!("Top K must be positive, got {top_k}"));
    }

    // Validate max_tokens (must be positive)
    if let Some(max_tokens) = config.max_tokens
        && max_tokens == 0
    {
        return Err("Max tokens must be positive".to_string());
    }

    // Validate repeat_penalty (must be positive)
    if let Some(repeat_penalty) = config.repeat_penalty
        && repeat_penalty <= 0.0
    {
        return Err(format!(
            "Repeat penalty must be positive, got {repeat_penalty}"
        ));
    }

    // Validate presence_penalty (0.0 - 2.0)
    if let Some(pp) = config.presence_penalty
        && !(0.0..=2.0).contains(&pp)
    {
        return Err(format!(
            "Presence penalty must be between 0.0 and 2.0, got {pp}"
        ));
    }

    // Validate min_p (0.0 - 1.0)
    if let Some(mp) = config.min_p
        && !(0.0..=1.0).contains(&mp)
    {
        return Err(format!("Min P must be between 0.0 and 1.0, got {mp}"));
    }

    Ok(())
}

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

    #[test]
    fn test_default_settings() {
        let settings = Settings::with_defaults();
        assert_eq!(settings.default_context_size, Some(4096));
        assert_eq!(settings.proxy_port, Some(DEFAULT_PROXY_PORT));
        assert_eq!(settings.llama_base_port, Some(DEFAULT_LLAMA_BASE_PORT));
        assert_eq!(settings.default_download_path, None);
        assert_eq!(settings.max_download_queue_size, Some(10));
        assert_eq!(settings.show_memory_fit_indicators, Some(true));
    }

    #[test]
    fn test_validate_settings_valid() {
        let settings = Settings::with_defaults();
        assert!(validate_settings(&settings).is_ok());
    }

    #[test]
    fn test_validate_context_size_too_small() {
        let settings = Settings {
            default_context_size: Some(100),
            ..Default::default()
        };
        assert!(matches!(
            validate_settings(&settings),
            Err(SettingsError::InvalidContextSize(100))
        ));
    }

    #[test]
    fn test_validate_context_size_too_large() {
        let settings = Settings {
            default_context_size: Some(2_000_000),
            ..Default::default()
        };
        assert!(matches!(
            validate_settings(&settings),
            Err(SettingsError::InvalidContextSize(2_000_000))
        ));
    }

    #[test]
    fn test_validate_port_too_low() {
        let settings = Settings {
            proxy_port: Some(80),
            ..Default::default()
        };
        assert!(matches!(
            validate_settings(&settings),
            Err(SettingsError::InvalidPort(80))
        ));
    }

    #[test]
    fn test_validate_empty_path() {
        let settings = Settings {
            default_download_path: Some(String::new()),
            ..Default::default()
        };
        assert!(matches!(
            validate_settings(&settings),
            Err(SettingsError::EmptyDownloadPath)
        ));
    }

    #[test]
    fn test_validate_inference_config_valid() {
        let config = InferenceConfig {
            temperature: Some(0.7),
            top_p: Some(0.9),
            top_k: Some(40),
            max_tokens: Some(2048),
            repeat_penalty: Some(1.1),
            presence_penalty: Some(0.0),
            min_p: Some(0.0),
        };
        assert!(validate_inference_config(&config).is_ok());
    }

    #[test]
    fn test_validate_inference_config_temperature_out_of_range() {
        let config = InferenceConfig {
            temperature: Some(2.5),
            ..Default::default()
        };
        assert!(validate_inference_config(&config).is_err());

        let config = InferenceConfig {
            temperature: Some(-0.1),
            ..Default::default()
        };
        assert!(validate_inference_config(&config).is_err());
    }

    #[test]
    fn test_validate_inference_config_top_p_out_of_range() {
        let config = InferenceConfig {
            top_p: Some(1.5),
            ..Default::default()
        };
        assert!(validate_inference_config(&config).is_err());

        let config = InferenceConfig {
            top_p: Some(-0.1),
            ..Default::default()
        };
        assert!(validate_inference_config(&config).is_err());
    }

    #[test]
    fn test_validate_inference_config_negative_values() {
        let config = InferenceConfig {
            top_k: Some(-1),
            ..Default::default()
        };
        assert!(validate_inference_config(&config).is_err());

        let config = InferenceConfig {
            repeat_penalty: Some(0.0),
            ..Default::default()
        };
        assert!(validate_inference_config(&config).is_err());
    }

    #[test]
    fn test_settings_with_valid_inference_defaults() {
        let settings = Settings {
            inference_defaults: Some(InferenceConfig {
                temperature: Some(0.8),
                top_p: Some(0.95),
                ..Default::default()
            }),
            ..Settings::with_defaults()
        };
        assert!(validate_settings(&settings).is_ok());
    }

    #[test]
    fn test_settings_with_invalid_inference_defaults() {
        let settings = Settings {
            inference_defaults: Some(InferenceConfig {
                temperature: Some(3.0), // Invalid
                ..Default::default()
            }),
            ..Settings::with_defaults()
        };
        assert!(validate_settings(&settings).is_err());
    }

    #[test]
    fn test_validate_queue_size_too_small() {
        let settings = Settings {
            max_download_queue_size: Some(0),
            ..Default::default()
        };
        assert!(matches!(
            validate_settings(&settings),
            Err(SettingsError::InvalidQueueSize(0))
        ));
    }

    #[test]
    fn test_validate_queue_size_too_large() {
        let settings = Settings {
            max_download_queue_size: Some(100),
            ..Default::default()
        };
        assert!(matches!(
            validate_settings(&settings),
            Err(SettingsError::InvalidQueueSize(100))
        ));
    }

    #[test]
    fn test_merge_settings() {
        let mut settings = Settings::with_defaults();
        let update = SettingsUpdate {
            default_context_size: Some(Some(8192)),
            proxy_port: Some(None), // Clear proxy port
            ..Default::default()
        };
        settings.merge(&update);

        assert_eq!(settings.default_context_size, Some(8192));
        assert_eq!(settings.proxy_port, None);
        assert_eq!(settings.llama_base_port, Some(DEFAULT_LLAMA_BASE_PORT)); // Unchanged
    }

    #[test]
    fn test_trust_client_sampling_defaults_to_none_and_merges_like_any_bool_setting() {
        let defaults = Settings::with_defaults();
        assert_eq!(defaults.trust_client_sampling, None);

        let mut settings = Settings::with_defaults();
        settings.merge(&SettingsUpdate {
            trust_client_sampling: Some(Some(true)),
            ..Default::default()
        });
        assert_eq!(settings.trust_client_sampling, Some(true));

        settings.merge(&SettingsUpdate {
            trust_client_sampling: Some(None),
            ..Default::default()
        });
        assert_eq!(settings.trust_client_sampling, None);
    }

    #[test]
    fn test_effective_ports() {
        let settings = Settings::with_defaults();
        assert_eq!(settings.effective_proxy_port(), DEFAULT_PROXY_PORT);
        assert_eq!(
            settings.effective_llama_base_port(),
            DEFAULT_LLAMA_BASE_PORT
        );

        let settings_none = Settings::default();
        assert_eq!(settings_none.effective_proxy_port(), DEFAULT_PROXY_PORT);
        assert_eq!(
            settings_none.effective_llama_base_port(),
            DEFAULT_LLAMA_BASE_PORT
        );
    }

    // ── Inference profiles ──────────────────────────────────────────────

    fn profile(name: &str, temperature: f32) -> InferenceProfile {
        InferenceProfile {
            name: name.to_owned(),
            description: None,
            config: InferenceConfig {
                temperature: Some(temperature),
                ..Default::default()
            },
            list_in_models: false,
        }
    }

    #[test]
    fn test_builtin_templates_pass_settings_validation() {
        let settings = Settings {
            inference_profiles: Some(crate::domain::builtin_templates()),
            ..Settings::with_defaults()
        };
        assert!(validate_settings(&settings).is_ok());
    }

    #[test]
    fn test_validate_profiles_rejects_duplicate_names() {
        let err = validate_inference_profiles(&[profile("coding", 0.2), profile("coding", 0.9)])
            .expect_err("duplicates must be rejected");
        assert!(err.contains("duplicate"), "unexpected message: {err}");
        assert!(err.contains("coding"), "message should name the profile");
    }

    #[test]
    fn test_validate_profiles_rejects_invalid_name() {
        let err = validate_inference_profiles(&[profile("Not_A_Slug", 0.5)])
            .expect_err("invalid slug must be rejected");
        assert!(err.contains("Not_A_Slug"), "unexpected message: {err}");
    }

    /// Profile parameters go through the same range checks as global
    /// defaults, and the failure names which profile was at fault.
    #[test]
    fn test_validate_profiles_reuses_inference_config_ranges() {
        let err = validate_inference_profiles(&[profile("coding", 5.0)])
            .expect_err("out-of-range temperature must be rejected");
        assert!(err.contains("coding"), "message should name the profile");
        assert!(err.contains("Temperature"), "unexpected message: {err}");
    }

    #[test]
    fn test_settings_with_invalid_profile_fails_validation() {
        let settings = Settings {
            inference_profiles: Some(vec![profile("coding", 5.0)]),
            ..Settings::with_defaults()
        };
        assert!(matches!(
            validate_settings(&settings),
            Err(SettingsError::InvalidInferenceProfile(_))
        ));
    }

    #[test]
    fn test_merge_replaces_and_clears_profiles() {
        let mut settings = Settings {
            inference_profiles: Some(vec![profile("coding", 0.2)]),
            ..Settings::with_defaults()
        };

        settings.merge(&SettingsUpdate {
            inference_profiles: Some(Some(vec![profile("chat", 0.7)])),
            ..Default::default()
        });
        let profiles = settings.inference_profiles.as_ref().expect("still set");
        assert_eq!(profiles.len(), 1);
        assert_eq!(profiles[0].name, "chat");

        settings.merge(&SettingsUpdate {
            inference_profiles: Some(None),
            ..Default::default()
        });
        assert_eq!(settings.inference_profiles, None);

        // An absent field must leave the current value alone.
        settings.inference_profiles = Some(vec![profile("coding", 0.2)]);
        settings.merge(&SettingsUpdate::default());
        assert!(settings.inference_profiles.is_some());
    }

    /// The repository stores one KV row per serde field and rebuilds
    /// `Settings` from whatever rows exist, so an older row set (no profiles
    /// row) must still deserialize.
    #[test]
    fn test_profiles_round_trip_through_json_and_default_when_absent() {
        let settings = Settings {
            inference_profiles: Some(vec![profile("coding", 0.2)]),
            ..Settings::with_defaults()
        };
        let value = serde_json::to_value(&settings).expect("serializes");
        assert!(value.get("inference_profiles").is_some());

        let restored: Settings = serde_json::from_value(value).expect("round-trips");
        assert_eq!(restored.inference_profiles, settings.inference_profiles);

        let absent: Settings = serde_json::from_str("{}").expect("deserializes without the field");
        assert_eq!(absent.inference_profiles, None);
    }
}