use std::collections::HashMap;
use std::path::{Path, PathBuf};
use std::sync::OnceLock;
use serde::Deserialize;
const FILE: &str = "llmman.conf";
#[derive(Deserialize, Default, Debug)]
#[serde(deny_unknown_fields)]
pub struct Conf {
#[serde(default)]
pub aliases: HashMap<String, String>,
#[serde(default)]
providers: HashMap<String, ProviderConf>,
#[serde(default)]
pub verify: VerifyConf,
#[serde(default)]
pub aggregation: AggregationConf,
}
#[derive(Deserialize, Default, Debug, Clone)]
#[serde(deny_unknown_fields)]
pub struct AggregationConf {
#[serde(default)]
pub peers: Option<String>,
}
#[derive(Deserialize)]
#[serde(deny_unknown_fields)]
struct ProviderConf {
#[serde(default)]
api_key: Option<String>,
#[serde(default)]
base_url: Option<String>,
#[serde(default)]
wire: Option<crate::providers::Wire>,
#[serde(default)]
api_key_env: Option<String>,
#[serde(default)]
name: Option<String>,
}
impl std::fmt::Debug for ProviderConf {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
f.debug_struct("ProviderConf")
.field("api_key", &self.api_key.as_ref().map(|_| "<redacted>"))
.field("base_url", &self.base_url)
.field("wire", &self.wire)
.field("api_key_env", &self.api_key_env)
.field("name", &self.name)
.finish()
}
}
impl ProviderConf {
fn defines(&self) -> bool {
self.base_url.is_some()
}
fn definition_only_fields(&self) -> Vec<&'static str> {
let mut set = Vec::new();
if self.wire.is_some() {
set.push("wire");
}
if self.api_key_env.is_some() {
set.push("api_key_env");
}
if self.name.is_some() {
set.push("name");
}
set
}
}
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct ConfiguredProvider {
pub id: String,
pub name: String,
pub base_url: String,
pub wire: crate::providers::Wire,
pub key_env: Option<String>,
}
#[derive(Deserialize, Default, Debug, Clone)]
#[serde(deny_unknown_fields)]
pub struct VerifyConf {
#[serde(default)]
pub default: Option<String>,
#[serde(default)]
pub trust: Vec<TrustConf>,
}
#[derive(Deserialize, Debug, Clone)]
#[serde(deny_unknown_fields)]
pub struct TrustConf {
pub pattern: String,
#[serde(default)]
pub keys: Vec<String>,
#[serde(default)]
pub mode: Option<String>,
}
impl Conf {
fn provider_keys(&self) -> HashMap<String, String> {
self.providers
.iter()
.filter_map(|(id, p)| Some((id.clone(), p.api_key.as_deref()?.trim().to_string())))
.collect()
}
}
#[derive(Debug)]
pub struct File {
pub path: PathBuf,
pub dir: PathBuf,
pub conf: Conf,
}
pub fn search_paths() -> Vec<PathBuf> {
let mut paths = vec![system_dir().join(FILE)];
paths.extend(user_dir().map(|d| d.join(FILE)));
paths
}
#[cfg(not(windows))]
fn system_dir() -> PathBuf {
PathBuf::from("/etc/llmman")
}
#[cfg(windows)]
fn system_dir() -> PathBuf {
let drive = std::env::var("SystemDrive").unwrap_or_else(|_| "C:".to_string());
PathBuf::from(format!("{drive}\\etc\\llmman"))
}
fn user_dir() -> Option<PathBuf> {
dirs::home_dir().map(|h| h.join(".config").join("llmman"))
}
pub fn user_path() -> Option<PathBuf> {
user_dir().map(|d| d.join(FILE))
}
pub fn system_path() -> PathBuf {
system_dir().join(FILE)
}
pub fn user_path_display() -> String {
user_path()
.map(|p| p.display().to_string())
.unwrap_or_else(|| FILE.to_string())
}
pub fn files() -> Result<&'static [File], &'static str> {
cache().as_deref().map_err(String::as_str)
}
fn cache() -> &'static Result<Vec<File>, String> {
static CACHE: OnceLock<Result<Vec<File>, String>> = OnceLock::new();
CACHE.get_or_init(|| {
let loaded = load();
if let Err(e) = &loaded {
eprintln!("[llmman] warning: {e}");
}
loaded
})
}
fn load() -> Result<Vec<File>, String> {
if cfg!(test) {
return Ok(Vec::new());
}
let mut files = Vec::new();
for path in search_paths() {
let text = match std::fs::read_to_string(&path) {
Ok(text) => text,
Err(e) if e.kind() == std::io::ErrorKind::NotFound => continue,
Err(e) => return Err(format!("ignoring {}: {e}", path.display())),
};
let conf = parse(&text).map_err(|e| format!("ignoring {}: {e}", path.display()))?;
let dir = path.parent().unwrap_or(Path::new(".")).to_path_buf();
files.push(File { path, dir, conf });
}
Ok(files)
}
pub(crate) fn parse(text: &str) -> Result<Conf, String> {
let conf: Conf = toml::from_str(text).map_err(|e| e.to_string())?;
validate(&conf)?;
Ok(conf)
}
fn validate(conf: &Conf) -> Result<(), String> {
for (id, p) in &conf.providers {
if id.is_empty() || id.contains('/') {
return Err(format!(
"[providers.{id:?}]: a provider id cannot be empty or contain '/'"
));
}
match &p.base_url {
Some(url) => {
base_url_of(url).map_err(|e| format!("[providers.{id}] base_url: {e}"))?;
}
None => {
let only_on_definition = p.definition_only_fields();
if !only_on_definition.is_empty() {
return Err(format!(
"[providers.{id}] sets {} but no base_url, so it only keys the catalog \
provider {id:?}",
only_on_definition.join(", ")
));
}
}
}
}
Ok(())
}
fn base_url_of(url: &str) -> Result<String, String> {
let url = url.trim();
let parsed = reqwest::Url::parse(url).map_err(|e| format!("{url:?}: {e}"))?;
match parsed.scheme() {
"http" | "https" => {}
other => {
return Err(format!(
"{url:?}: scheme must be http or https, not {other}"
))
}
}
if parsed.host_str().is_none() {
return Err(format!("{url:?}: no host"));
}
if !parsed.username().is_empty() || parsed.password().is_some() {
return Err(format!(
"{url:?}: a base URL cannot carry a username or password; use api_key"
));
}
if parsed.query().is_some() || parsed.fragment().is_some() {
return Err(format!("{url:?}: a base URL has no query or fragment"));
}
Ok(parsed.as_str().trim_end_matches('/').to_string())
}
pub fn configured_providers() -> &'static [ConfiguredProvider] {
static CACHE: OnceLock<Vec<ConfiguredProvider>> = OnceLock::new();
CACHE.get_or_init(|| configured_from(files().unwrap_or_default()))
}
fn configured_from(files: &[File]) -> Vec<ConfiguredProvider> {
let mut merged: HashMap<&str, ConfiguredProvider> = HashMap::new();
for file in files {
for (id, p) in file.conf.providers.iter().filter(|(_, p)| p.defines()) {
let base_url = p
.base_url
.as_deref()
.and_then(|u| base_url_of(u).ok())
.expect("validated at parse");
let entry = merged.entry(id).or_insert_with(|| ConfiguredProvider {
id: id.clone(),
name: id.clone(),
base_url: String::new(),
wire: crate::providers::Wire::OpenAi,
key_env: None,
});
entry.base_url = base_url;
if let Some(wire) = p.wire {
entry.wire = wire;
}
if let Some(var) = p.api_key_env.as_deref().map(str::trim) {
entry.key_env = (!var.is_empty()).then(|| var.to_string());
}
if let Some(name) = p.name.as_deref().map(str::trim).filter(|n| !n.is_empty()) {
entry.name = name.to_string();
}
}
}
let mut out: Vec<ConfiguredProvider> = merged.into_values().collect();
out.sort_by(|a, b| a.id.cmp(&b.id));
out
}
pub fn provider_api_key(provider_id: &str) -> Option<&'static str> {
static CACHE: OnceLock<HashMap<String, String>> = OnceLock::new();
CACHE
.get_or_init(load_provider_keys)
.get(provider_id)
.map(String::as_str)
}
fn load_provider_keys() -> HashMap<String, String> {
let mut accepted = Vec::new();
for file in files().unwrap_or_default() {
let keys = file.conf.provider_keys();
if !keys.values().all(String::is_empty) {
if let Err(e) = owner_readable_only(&file.path) {
eprintln!(
"[llmman] warning: ignoring the API keys in {}: {e}",
file.path.display()
);
continue;
}
}
accepted.push(keys);
}
merge_keys(accepted)
}
fn merge_keys(per_file: Vec<HashMap<String, String>>) -> HashMap<String, String> {
let mut merged: HashMap<String, String> = HashMap::new();
for keys in per_file {
merged.extend(keys);
}
merged.retain(|_, key| !key.is_empty());
merged
}
pub fn peers() -> Vec<String> {
peers_from(
std::env::var("LLMMAN_PEERS").ok().as_deref(),
files().unwrap_or_default(),
)
}
fn peers_from(env: Option<&str>, files: &[File]) -> Vec<String> {
env.or_else(|| {
files
.iter()
.rev()
.find_map(|f| f.conf.aggregation.peers.as_deref())
})
.unwrap_or_default()
.split(',')
.map(str::trim)
.filter(|s| !s.is_empty())
.map(str::to_string)
.collect()
}
#[cfg(unix)]
pub(crate) fn owner_readable_only(path: &Path) -> Result<(), String> {
use std::os::unix::fs::PermissionsExt;
let mode = std::fs::metadata(path)
.map_err(|e| e.to_string())?
.permissions()
.mode();
if mode & 0o077 != 0 {
return Err(format!(
"mode {:04o} lets other users read it. Run: chmod 600 {}",
mode & 0o7777,
path.display()
));
}
Ok(())
}
#[cfg(not(unix))]
pub(crate) fn owner_readable_only(_path: &Path) -> Result<(), String> {
Ok(())
}
#[cfg(test)]
mod tests {
use super::*;
fn conf(text: &str) -> Conf {
parse(text).expect("valid conf")
}
#[test]
fn debug_output_never_carries_a_key() {
let c = conf("[providers.openai]\napi_key = \"sk-secret-value\"");
let rendered = format!("{c:?}");
assert!(!rendered.contains("sk-secret-value"), "{rendered}");
assert!(rendered.contains("redacted"), "{rendered}");
}
#[test]
fn parses_every_section_of_one_file() {
let c = conf(
r#"
[aliases]
gemma4 = "docker.io/ai/gemma4"
[providers.openrouter]
api_key = "sk-or-abc"
[verify]
default = "warn"
[[verify.trust]]
pattern = "docker.io/myorg/**"
keys = ["keys/myorg.pub"]
mode = "enforce"
"#,
);
assert_eq!(
c.aliases.get("gemma4").map(String::as_str),
Some("docker.io/ai/gemma4")
);
assert_eq!(
c.provider_keys().get("openrouter").map(String::as_str),
Some("sk-or-abc")
);
assert_eq!(c.verify.default.as_deref(), Some("warn"));
assert_eq!(c.verify.trust.len(), 1);
assert_eq!(c.verify.trust[0].mode.as_deref(), Some("enforce"));
}
#[test]
fn every_section_is_optional() {
let c = conf("");
assert!(c.aliases.is_empty());
assert!(c.provider_keys().is_empty());
assert!(c.verify.default.is_none());
assert!(c.verify.trust.is_empty());
assert!(!conf("[aliases]\nx = \"y\"").aliases.is_empty());
assert!(conf("[verify]\ndefault = \"off\"").aliases.is_empty());
}
#[test]
fn a_key_is_trimmed_and_an_unset_one_is_absent() {
let keys = conf(
r#"
[providers.openai]
api_key = " sk-padded "
[providers.groq]
api_key = " "
[providers.mistral]
"#,
)
.provider_keys();
assert_eq!(keys.get("openai").map(String::as_str), Some("sk-padded"));
assert_eq!(keys.get("groq").map(String::as_str), Some(""));
assert_eq!(keys.get("mistral"), None);
}
#[test]
fn a_later_blank_shadows_an_earlier_key_and_is_never_spent() {
let system = HashMap::from([
("openai".to_string(), "sk-system".to_string()),
("groq".to_string(), "sk-groq".to_string()),
]);
let user = HashMap::from([("openai".to_string(), String::new())]);
let merged = merge_keys(vec![system, user]);
assert_eq!(merged.get("openai"), None, "blanked out by the user file");
assert_eq!(merged.get("groq").map(String::as_str), Some("sk-groq"));
let merged = merge_keys(vec![
HashMap::from([("openai".to_string(), "sk-system".to_string())]),
HashMap::from([("openai".to_string(), "sk-user".to_string())]),
]);
assert_eq!(merged.get("openai").map(String::as_str), Some("sk-user"));
}
#[test]
fn a_misspelled_section_or_field_is_rejected_rather_than_ignored() {
assert!(parse("[provider.openai]\napi_key = \"x\"").is_err());
assert!(parse("[providers.openai]\napi_kye = \"x\"").is_err());
assert!(parse("[alias]\nx = \"y\"").is_err());
assert!(parse("[verify]\ndefualt = \"off\"").is_err());
assert!(parse("[[verify.trust]]\npattern = \"a/b\"\nkyes = []").is_err());
assert!(parse("api_key = \"x\"").is_err());
}
#[test]
fn malformed_toml_is_an_error() {
assert!(parse("[providers.openai").is_err());
}
#[test]
fn a_base_url_turns_a_provider_table_into_a_definition() {
let files = [file(
r#"
[providers.gpubox]
base_url = "http://gpubox:8000/v1/"
[providers.relay]
base_url = "https://relay.example/v1"
wire = "anthropic"
api_key_env = "RELAY_KEY"
name = "Claude relay"
api_key = "sk-relay"
[providers.openrouter]
api_key = "sk-or"
"#,
)];
let configured = configured_from(&files);
assert_eq!(
configured,
vec![
ConfiguredProvider {
id: "gpubox".into(),
name: "gpubox".into(),
base_url: "http://gpubox:8000/v1".into(),
wire: crate::providers::Wire::OpenAi,
key_env: None,
},
ConfiguredProvider {
id: "relay".into(),
name: "Claude relay".into(),
base_url: "https://relay.example/v1".into(),
wire: crate::providers::Wire::Anthropic,
key_env: Some("RELAY_KEY".into()),
},
]
);
assert_eq!(
files[0]
.conf
.provider_keys()
.get("relay")
.map(String::as_str),
Some("sk-relay")
);
assert!(configured_from(&[]).is_empty());
}
#[test]
fn a_later_definition_overrides_field_by_field() {
let system = file(
"[providers.gpubox]\nbase_url = \"http://gpubox:8000/v1\"\nname = \"Shared box\"\n\
api_key_env = \"SHARED_KEY\"",
);
let user = file(
"[providers.gpubox]\nbase_url = \"http://10.0.0.5:8000/v1\"\nwire = \"anthropic\"\n\
api_key_env = \"\"",
);
let merged = configured_from(&[system, user]);
assert_eq!(merged.len(), 1);
assert_eq!(merged[0].base_url, "http://10.0.0.5:8000/v1");
assert_eq!(merged[0].name, "Shared box");
assert_eq!(merged[0].wire, crate::providers::Wire::Anthropic);
assert_eq!(merged[0].key_env, None);
}
#[test]
fn a_bad_provider_definition_is_a_parse_error() {
let bad = |body: &str| parse(&format!("[providers.gpubox]\n{body}")).expect_err(body);
assert!(bad("base_url = \"gpubox:8000\"").contains("base_url"));
assert!(bad("base_url = \"gpubox:8000/v1\"").contains("base_url"));
assert!(bad("base_url = \"ftp://gpubox/v1\"").contains("http or https"));
assert!(bad("base_url = \"http://\"").contains("base_url"));
assert!(bad("base_url = \"http://gpubox/v1?x=1\"").contains("query"));
assert!(bad("base_url = \"\"").contains("base_url"));
assert!(bad("base_url = \"https://user:pw@gpubox/v1\"").contains("api_key"));
assert!(bad("base_url = \"https://user@gpubox/v1\"").contains("api_key"));
assert!(
parse("[providers.\"team/gpu\"]\nbase_url = \"http://g/v1\"")
.expect_err("slash id")
.contains("'/'")
);
assert!(parse("[providers.\"\"]\napi_key = \"x\"").is_err());
let err = bad("wire = \"anthropic\"");
assert!(err.contains("no base_url"), "{err}");
assert!(err.contains("wire"), "{err}");
let err = bad("api_key_env = \"X\"\nname = \"n\"");
assert!(err.contains("api_key_env, name"), "{err}");
assert!(bad("base_url = \"http://g/v1\"\nwire = \"ollama\"").contains("wire"));
assert!(bad("base_url = \"http://g/v1\"\nbase_ulr = \"x\"").contains("base_ulr"));
for (url, want) in [
("http://gpubox:8000/v1", "http://gpubox:8000/v1"),
("http://gpubox", "http://gpubox"),
("HTTP://GPUBox:8000/v1/", "http://gpubox:8000/v1"),
("http://127.0.0.1:11434/v1", "http://127.0.0.1:11434/v1"),
("http://[::1]:8000/v1", "http://[::1]:8000/v1"),
(
"https://relay.example/api/v1",
"https://relay.example/api/v1",
),
] {
assert_eq!(base_url_of(url).expect(url), want);
parse(&format!("[providers.gpubox]\nbase_url = {url:?}")).expect(url);
}
}
#[test]
fn debug_output_shows_a_definition_but_never_a_key() {
let c = conf(
"[providers.gpubox]\nbase_url = \"http://gpubox:8000/v1\"\napi_key = \"sk-secret-value\"",
);
let rendered = format!("{c:?}");
assert!(rendered.contains("gpubox:8000"), "{rendered}");
assert!(!rendered.contains("sk-secret-value"), "{rendered}");
}
fn file(text: &str) -> File {
File {
path: PathBuf::from("llmman.conf"),
dir: PathBuf::from("."),
conf: conf(text),
}
}
#[test]
fn peers_come_from_the_environment_then_the_last_file_that_sets_them() {
let system = || file("[aggregation]\npeers = \"a, b\"");
let user = file("[aggregation]\npeers = \"c\"");
let silent = file("");
let opted_out = file("[aggregation]\npeers = \"\"");
assert_eq!(
peers_from(Some(" x , ,y:1 "), &[]),
vec!["x".to_string(), "y:1".to_string()]
);
assert!(peers_from(Some(""), &[system()]).is_empty());
assert_eq!(
peers_from(None, &[system(), silent]),
vec!["a".to_string(), "b".to_string()]
);
assert_eq!(peers_from(None, &[system(), user]), vec!["c".to_string()]);
assert!(peers_from(None, &[system(), opted_out]).is_empty());
assert!(peers_from(None, &[]).is_empty());
assert!(parse("[aggregation]\npeer = \"a\"").is_err());
}
#[test]
fn the_search_path_is_etc_then_the_user_directory() {
let paths = search_paths();
assert_eq!(
paths.first().expect("a system path"),
&system_dir().join(FILE)
);
assert!(system_dir().ends_with("etc/llmman"), "{:?}", system_dir());
assert!(system_dir().is_absolute(), "{:?}", system_dir());
assert!(
!paths.iter().any(|p| p.starts_with("/usr/share")),
"{paths:?}"
);
if let Some(user) = user_path() {
assert_eq!(paths.last(), Some(&user));
assert!(user.ends_with("llmman/llmman.conf"), "{}", user.display());
}
}
#[test]
fn there_is_one_user_directory_on_every_platform() {
assert_eq!(search_paths().len(), user_dir().iter().count() + 1);
if let Some(dir) = user_dir() {
assert!(dir.ends_with(".config/llmman"), "{}", dir.display());
}
}
#[cfg(unix)]
#[test]
fn a_group_or_world_readable_file_is_refused() {
use std::os::unix::fs::PermissionsExt;
let dir = std::env::temp_dir().join(format!("llmman-conf-{}", std::process::id()));
std::fs::create_dir_all(&dir).expect("temp dir");
let path = dir.join(FILE);
std::fs::write(&path, "[providers.openai]\napi_key = \"sk-x\"\n").expect("write");
std::fs::set_permissions(&path, std::fs::Permissions::from_mode(0o644)).expect("chmod");
let err = owner_readable_only(&path).expect_err("0644 is refused");
assert!(err.contains("chmod 600"), "{err}");
std::fs::set_permissions(&path, std::fs::Permissions::from_mode(0o600)).expect("chmod");
assert!(owner_readable_only(&path).is_ok());
std::fs::remove_dir_all(&dir).ok();
}
}