//! Typed configuration with embedded defaults and validated partial overrides. //! //! The six original top-level selection keys remain supported. Missing files //! use defaults; unreadable files, unknown keys and invalid values are errors. //! Paths in settings are relative to the process working directory. use serde::{Deserialize, Serialize}; use std::{ fs, io, path::{Path, PathBuf}, }; /// Human-readable defaults, also used by tests and packaged with the binary. pub const DEFAULT_CONFIG: &str = include_str!("../config/default.toml"); /// Failures reading, validating or persisting configuration. #[derive(Debug, thiserror::Error)] pub enum ConfigError { /// The path could not be read or atomically replaced. #[error("configuration I/O: {0}")] Io(#[from] io::Error), /// TOML syntax or a typed setting is invalid. #[error("invalid configuration: {0}")] Parse(#[from] toml::de::Error), /// Serialization failed before replacing the existing file. #[error("cannot serialize configuration: {0}")] Serialize(#[from] toml::ser::Error), /// A setting violates an application invariant. #[error("invalid configuration: {0}")] Validation(String), } /// Complete application settings; fields retain units from the configuration file. #[derive(Debug, Clone, Serialize, Deserialize, PartialEq)] #[serde(deny_unknown_fields)] pub struct Config { /// Preferred serial port; empty selects the first available candidate. pub port: String, /// Selected baud rate, which must occur in `serial.baudrates`. pub baudrate: u32, /// Scan start in MHz, within the Basic 0–960 MHz envelope. pub start_frequency: usize, /// Scan stop in MHz, no lower than the start. pub stop_frequency: usize, /// Number of samples in the raw scan. pub points: usize, /// Measurements per point. pub repeat: usize, /// Serial or TCP transport selection; TCP is useful for bridges and simulation. pub connection: ConnectionConfig, /// Serial timing, response limits and selection preferences. pub serial: SerialConfig, /// Acquisition and numeric input policy. pub scan: ScanConfig, /// Rendering and event timing. pub ui: UiConfig, /// CSV destination and format. pub output: OutputConfig, /// File logging settings. pub logging: LoggingConfig, } /// Transport selected by the application, without changing shell framing. #[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)] #[serde(rename_all = "snake_case")] pub enum Backend { /// A native USB/serial port (requires the `serial` Cargo feature). Serial, /// A TCP bridge or mock server; tinySA hardware does not provide native TCP. Tcp, } /// Connection settings; read deadlines apply to individual I/O operations. #[derive(Debug, Clone, Serialize, Deserialize, PartialEq)] #[serde(deny_unknown_fields)] pub struct ConnectionConfig { /// Which connection adapter to open. pub backend: Backend, /// Numeric IPv4/IPv6 socket address used for TCP (no DNS lookup). pub tcp_address: String, /// TCP connect, read and write timeout, in milliseconds. pub tcp_timeout_ms: u64, } /// Serial settings, separate from the protocol's fixed byte grammar. #[derive(Debug, Clone, Serialize, Deserialize, PartialEq)] #[serde(deny_unknown_fields)] pub struct SerialConfig { /// Maximum idle wait for each read, in milliseconds. pub timeout_ms: u64, /// Delay after sending ordinary commands, in milliseconds. pub command_delay_ms: u64, /// Delay after a response, in milliseconds. pub settle_delay_ms: u64, /// Delay after the legacy preparatory scan, in milliseconds. pub scan_delay_ms: u64, /// Maximum text response or pre-frame echo size, in bytes. pub max_response_bytes: usize, /// Selectable nonzero baud rates, without duplicates. pub baudrates: Vec, /// Fallback port names, tried in order after `port`. pub preferred_ports: Vec, } /// Frequency labeling policy; this does not change the instrument's sweep. #[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)] #[serde(rename_all = "snake_case")] pub enum FrequencyAxis { /// Preserve historical CSV labels, including the requested stop frequency. Inclusive, /// Match the reviewed firmware's `span / points` calculation. Firmware, } /// Scan settings; Basic model frequency limits remain protocol invariants. #[derive(Debug, Clone, Serialize, Deserialize, PartialEq)] #[serde(deny_unknown_fields)] pub struct ScanConfig { /// Offset sent with `zero` and subtracted from raw levels, in dB. pub zero_offset: u16, /// Keyboard step for frequencies, in MHz. pub frequency_step_mhz: usize, /// Keyboard step for sample count. pub points_step: usize, /// Lowest selectable sample count; at least two. pub min_points: usize, /// Highest selectable sample count; at most 1,000,001. pub max_points: usize, /// Highest repeat count; at most the firmware limit of 1,000. pub max_repeat: usize, /// Host-side frequency labeling convention. pub frequency_axis: FrequencyAxis, /// Whether to retain the legacy `scan START STOP 290 101` preparation. pub legacy_pre_scan: bool, } /// Settings for the terminal presentation. #[derive(Debug, Clone, Serialize, Deserialize, PartialEq)] #[serde(deny_unknown_fields)] pub struct UiConfig { /// Maximum event polling interval, in milliseconds. pub poll_interval_ms: u64, /// Chart lower bound, in dBm; finite and lower than the upper bound. pub chart_min_dbm: f64, /// Chart upper bound, in dBm. pub chart_max_dbm: f64, } /// CSV settings; paths are relative to the working directory unless absolute. #[derive(Debug, Clone, Serialize, Deserialize, PartialEq)] #[serde(deny_unknown_fields)] pub struct OutputConfig { /// Directory for completed scans; created on export if absent. pub directory: PathBuf, /// Filename prefix containing only ASCII letters, digits, `_` or `-`. pub filename_prefix: String, /// Emit a `frequency_MHz,level_dBm` header when true. pub include_header: bool, } /// Settings accepted by the file logger. #[derive(Debug, Clone, Serialize, Deserialize, PartialEq)] #[serde(deny_unknown_fields)] pub struct LoggingConfig { /// flexi_logger filter expression, for example `info,tiny_wb=debug`. pub filter: String, /// Log destination directory. pub directory: PathBuf, } impl Default for Config { fn default() -> Self { toml::from_str(DEFAULT_CONFIG).expect("embedded configuration must be valid") } } impl Config { /// Overlay a partial TOML document onto embedded defaults and validate it. /// /// # Errors /// Returns an error for unknown keys, malformed TOML or invalid settings. pub fn from_toml(contents: &str) -> Result { let mut defaults: toml::Value = toml::from_str(DEFAULT_CONFIG)?; merge(&mut defaults, toml::from_str(contents)?); let config: Self = defaults.try_into()?; config.validate()?; Ok(config) } /// Load settings, using defaults only if the path does not exist. pub fn load(path: &Path) -> Result { match fs::read_to_string(path) { Ok(contents) => Self::from_toml(&contents), Err(error) if error.kind() == io::ErrorKind::NotFound => Ok(Self::default()), Err(error) => Err(error.into()), } } /// Validate and atomically replace settings without depending on UI state. /// /// All recognized sections survive saving; formatting and comments do not. /// The parent directory must exist. The old file survives a failed write. pub fn save(&self, path: &Path) -> Result<(), ConfigError> { self.validate()?; crate::storage::replace(path, toml::to_string_pretty(self)?.as_bytes())?; Ok(()) } /// Check bounds before values become allocations, durations or scan commands. pub fn validate(&self) -> Result<(), ConfigError> { let require = |condition, message: &str| { if condition { Ok(()) } else { Err(ConfigError::Validation(message.into())) } }; require( !self.serial.baudrates.is_empty() && self.serial.baudrates.iter().all(|&v| v > 0), "serial.baudrates must contain nonzero values", )?; let mut rates = self.serial.baudrates.clone(); rates.sort_unstable(); rates.dedup(); require( rates.len() == self.serial.baudrates.len(), "serial.baudrates must not contain duplicates", )?; require( rates.contains(&self.baudrate), "baudrate must be in serial.baudrates", )?; require( self.start_frequency <= self.stop_frequency && self.stop_frequency <= 960 && self.stop_frequency >= 10, "frequencies must be ordered in 0–960 MHz, with stop at least 10 MHz", )?; require( self.scan.min_points >= 2 && self.scan.min_points <= self.scan.max_points && self.scan.max_points <= 1_000_001, "scan point bounds must satisfy 2 <= min_points <= max_points <= 1000001", )?; require( (self.scan.min_points..=self.scan.max_points).contains(&self.points), "points must be within scan.min_points and scan.max_points", )?; require( (1..=1000).contains(&self.scan.max_repeat) && (1..=self.scan.max_repeat).contains(&self.repeat), "repeat must be within 1..=scan.max_repeat, which cannot exceed 1000", )?; require( (1..=960).contains(&self.scan.frequency_step_mhz) && (1..=self.scan.max_points).contains(&self.scan.points_step), "scan keyboard steps must be positive and within their bounds", )?; require( self.scan.zero_offset <= 2047, "scan.zero_offset must fit the 16-bit fixed-point encoding (0..=2047)", )?; require( (1..=600_000).contains(&self.serial.timeout_ms), "serial.timeout_ms must be in 1..=600000", )?; require( (1..=600_000).contains(&self.connection.tcp_timeout_ms), "connection.tcp_timeout_ms must be in 1..=600000", )?; require( self.connection .tcp_address .parse::() .is_ok_and(|address| address.port() != 0), "connection.tcp_address must be a numeric IP:port with a nonzero port", )?; for delay in [ self.serial.command_delay_ms, self.serial.settle_delay_ms, self.serial.scan_delay_ms, ] { require( delay <= 60_000, "serial command delays cannot exceed 60000 ms", )?; } require( (256..=16_777_216).contains(&self.serial.max_response_bytes), "serial.max_response_bytes must be in 256..=16777216", )?; require( (1..=1000).contains(&self.ui.poll_interval_ms), "ui.poll_interval_ms must be in 1..=1000", )?; require( self.ui.chart_min_dbm.is_finite() && self.ui.chart_max_dbm.is_finite() && self.ui.chart_min_dbm < self.ui.chart_max_dbm, "UI chart bounds must be finite and increasing", )?; require(!self.output.filename_prefix.is_empty() && self.output.filename_prefix.len() <= 64 && self.output.filename_prefix.bytes().all(|c| c.is_ascii_alphanumeric() || c == b'_' || c == b'-'), "output.filename_prefix must contain 1–64 ASCII letters, digits, underscores or hyphens")?; require( !self.output.directory.as_os_str().is_empty() && !self.logging.directory.as_os_str().is_empty(), "output and logging directories must not be empty", )?; require( !self.logging.filter.trim().is_empty(), "logging.filter must not be empty", ) } } /// Recursively overlay supplied tables; scalar and array values replace defaults. fn merge(base: &mut toml::Value, overrides: toml::Value) { match (base, overrides) { (toml::Value::Table(base), toml::Value::Table(overrides)) => { for (key, value) in overrides { if let Some(original) = base.get_mut(&key) { merge(original, value); } else { base.insert(key, value); } } } (base, value) => *base = value, } } #[cfg(test)] mod tests { use super::*; #[test] fn defaults_and_legacy_settings_are_supported() { Config::default().validate().unwrap(); let config = Config::from_toml("port = 'COM3'\nbaudrate = 57600\nstart_frequency = 20\nstop_frequency = 100\npoints = 101\nrepeat = 2").unwrap(); assert_eq!(config.port, "COM3"); assert_eq!(config.points, 101); assert_eq!(config.serial, Config::default().serial); } #[test] fn partial_sections_merge_and_round_trip() { let config = Config::from_toml("[serial]\ntimeout_ms = 5000\n[output]\ninclude_header = true") .unwrap(); assert_eq!(config.serial.timeout_ms, 5000); assert_eq!(config.serial.baudrates, Config::default().serial.baudrates); assert!(config.output.include_header); assert_eq!( Config::from_toml(&toml::to_string(&config).unwrap()).unwrap(), config ); } #[test] fn malformed_unknown_and_unsafe_settings_are_rejected() { for input in [ "broken", "pointz = 100", "points = 1", "start_frequency = 961", "start_frequency = 900\nstop_frequency = 100", "repeat = 0", "[serial]\nbaudrates = []", "[serial]\nbaudrates = [115200, 115200]", "[serial]\ntimeout_ms = 0", "[serial]\nmax_response_bytes = 0", "[scan]\nmin_points = 0", "[scan]\nfrequency_step_mhz = 0", "[scan]\nzero_offset = 2048", "[scan]\nfrequency_axis = 'unknown'", "[ui]\nchart_min_dbm = nan", "[ui]\nchart_min_dbm = 1.0", "[output]\nfilename_prefix = '../scan'", "[logging]\nfilter = ''", "[serial]\ntimeuot_ms = 5", ] { assert!(Config::from_toml(input).is_err(), "accepted {input}"); } } #[test] fn persistence_preserves_settings_and_rejects_invalid_replacement() { let directory = std::env::temp_dir().join(format!("tiny-wb-config-{}", std::process::id())); fs::create_dir_all(&directory).unwrap(); let path = directory.join("settings.toml"); assert_eq!( Config::load(&directory.join("missing")).unwrap(), Config::default() ); let mut config = Config::from_toml("[output]\ninclude_header = true").unwrap(); config.save(&path).unwrap(); assert_eq!(Config::load(&path).unwrap(), config); let original = fs::read(&path).unwrap(); config.points = 0; assert!(config.save(&path).is_err()); assert_eq!(fs::read(&path).unwrap(), original); assert!(Config::load(&directory).is_err()); fs::write(&path, "unknown = true").unwrap(); assert!(Config::load(&path).is_err()); assert_eq!(fs::read_dir(&directory).unwrap().count(), 1); fs::remove_dir_all(directory).unwrap(); } }