crates/gunnar-core/src/settings.rs
//! **The server's generic settings** (`refs/gunnar/settings`, owner decision 2026-10-26).
//!
//! Bytes under a NAME the client chooses, and nothing more. The server knows no setting
//! name and gives no value a meaning: a console stores its own switches here
//! (`console.<switch>`: its names, namespaced by it), so a switch an administrator
//! flips is kept on the server, replicated with the rest of the control state, and outlives a
//! console restart, while gunnar-server learns nothing about what the switch does.
//!
//! Bounded, and every refusal names its limit:
//!
//! * a name is 1 to [`MAX_NAME_BYTES`] bytes of `[a-z0-9._-]`, starting with a letter or digit;
//! * a value is at most [`MAX_VALUE_BYTES`] bytes;
//! * at most [`MAX_SETTINGS`] names are held.
//!
//! Who may read or write is the gRPC door's to decide (`Admin.GetSetting`, `Admin.SetSetting`:
//! server Admin); so is the audit line of each write (who, the name, old → new).
use std::sync::Arc;
use crate::control::ControlStore;
use crate::doc::{impl_doc, DocRef, ShardedMap};
use crate::error::{Error, Result};
/// **The name the settings document is stored under** in the control store.
pub const SETTINGS_REF: &str = "refs/gunnar/settings";
/// The longest setting name, in bytes.
pub const MAX_NAME_BYTES: usize = 128;
/// The largest setting value, in bytes.
pub const MAX_VALUE_BYTES: usize = 4096;
/// The most settings one server holds.
pub const MAX_SETTINGS: usize = 256;
#[derive(Default, Clone, serde::Serialize, serde::Deserialize)]
#[serde(deny_unknown_fields)]
struct SettingsDoc {
/// Name → the value's bytes, hex.
#[serde(default)]
values: ShardedMap<String>,
}
impl_doc!(SettingsDoc { values });
/// Read and write the server's generic settings. Cheap to clone; every clone is the same
/// document.
#[derive(Clone, Debug)]
pub struct SettingsStore {
doc: DocRef<SettingsDoc>,
}
/// Pure: **is `name` a setting name**: `Err` names the rule it breaks.
pub fn check_name(name: &str) -> Result<()> {
let refuse = |reason: String| {
Err(Error::InvalidInput {
what: "setting name",
reason,
})
};
if name.is_empty() {
return refuse("empty".to_owned());
}
if name.len() > MAX_NAME_BYTES {
return refuse(format!(
"{} bytes, more than the {MAX_NAME_BYTES} a name may have",
name.len()
));
}
if !name
.bytes()
.all(|b| b.is_ascii_lowercase() || b.is_ascii_digit() || matches!(b, b'.' | b'_' | b'-'))
{
return refuse(format!("{name:?} has a character outside [a-z0-9._-]"));
}
if !name.as_bytes()[0].is_ascii_alphanumeric() {
return refuse(format!("{name:?} does not start with a letter or a digit"));
}
Ok(())
}
fn hex(b: &[u8]) -> String {
b.iter().map(|x| format!("{x:02x}")).collect()
}
fn unhex(s: &str) -> Result<Vec<u8>> {
let bad = || Error::InvalidInput {
what: "stored setting",
reason: "not hex: the settings document is damaged".to_owned(),
};
if s.len() % 2 != 0 {
return Err(bad());
}
(0..s.len())
.step_by(2)
.map(|i| {
s.get(i..i + 2)
.and_then(|p| u8::from_str_radix(p, 16).ok())
.ok_or_else(bad)
})
.collect()
}
impl SettingsStore {
/// Open the settings document held in `store` (the server's control store).
pub fn new(store: Arc<dyn ControlStore>) -> Result<Self> {
Ok(SettingsStore {
doc: DocRef::new(store, SETTINGS_REF)?,
})
}
/// The value stored under `name`, or `None` where nothing is.
pub fn get(&self, name: &str) -> Result<Option<Vec<u8>>> {
check_name(name)?;
self.doc
.load()?
.values
.get(name)?
.map(|v| unhex(&v))
.transpose()
}
/// Store `value` under `name`, replacing what was there; the value it replaced, `None`
/// for a new name. Refused by name past a bound.
pub fn set(&self, name: &str, value: &[u8]) -> Result<Option<Vec<u8>>> {
check_name(name)?;
if value.len() > MAX_VALUE_BYTES {
return Err(Error::InvalidInput {
what: "setting value",
reason: format!(
"{} bytes, more than the {MAX_VALUE_BYTES} a value may have",
value.len()
),
});
}
let previous = self.doc.update(|doc| {
if !doc.values.contains_key(name)? && doc.values.len() >= MAX_SETTINGS {
return Err(Error::InvalidInput {
what: "setting",
reason: format!(
"this server holds {MAX_SETTINGS} settings already, the most it keeps"
),
});
}
doc.values.insert(name.to_owned(), hex(value))
})?;
previous.map(|v| unhex(&v)).transpose()
}
}
#[cfg(test)]
mod tests {
use super::*;
fn store() -> SettingsStore {
SettingsStore::new(Arc::new(
crate::control::RedbControlStore::in_memory().expect("a store"),
))
.expect("the document")
}
#[test]
fn a_setting_is_stored_replaced_and_read_back_and_an_unset_one_is_none() {
let s = store();
assert_eq!(s.get("console.a-switch").unwrap(), None);
assert_eq!(
s.set("console.a-switch", b"on").unwrap(),
None,
"a new name replaced nothing"
);
assert_eq!(
s.get("console.a-switch").unwrap().as_deref(),
Some(&b"on"[..])
);
assert_eq!(
s.set("console.a-switch", b"off").unwrap().as_deref(),
Some(&b"on"[..]),
"the value it replaced"
);
assert_eq!(
s.get("console.a-switch").unwrap().as_deref(),
Some(&b"off"[..])
);
assert_eq!(s.set("x", &[0, 255, 7]).unwrap(), None);
assert_eq!(
s.get("x").unwrap().as_deref(),
Some(&[0u8, 255, 7][..]),
"any bytes"
);
}
#[test]
fn every_bound_is_refused_by_name() {
let s = store();
let words = |e: Error| e.to_string();
assert!(words(s.set("", b"").unwrap_err()).contains("empty"));
assert!(words(s.set(&"a".repeat(MAX_NAME_BYTES + 1), b"").unwrap_err()).contains("128"));
assert!(
s.set(&"a".repeat(MAX_NAME_BYTES), b"").is_ok(),
"at the bound it is a name"
);
assert!(words(s.set("Console.X", b"").unwrap_err()).contains("[a-z0-9._-]"));
assert!(words(s.set("a/b", b"").unwrap_err()).contains("[a-z0-9._-]"));
assert!(words(s.set(".hidden", b"").unwrap_err()).contains("start with"));
assert!(words(s.set("v", &vec![0; MAX_VALUE_BYTES + 1]).unwrap_err()).contains("4096"));
assert!(
s.set("v", &vec![0; MAX_VALUE_BYTES]).is_ok(),
"at the bound it is a value"
);
assert!(
words(s.get("A").unwrap_err()).contains("[a-z0-9._-]"),
"a read names the rule too"
);
}
#[test]
fn a_full_server_refuses_a_new_name_but_replaces_a_held_one() {
let s = store();
for i in 0..MAX_SETTINGS {
s.set(&format!("n{i}"), b"1").unwrap();
}
assert!(s
.set("one-more", b"1")
.unwrap_err()
.to_string()
.contains(&MAX_SETTINGS.to_string()));
assert!(s.set("n0", b"2").is_ok(), "a held name is still replaced");
}
}