From b117029c76e4b0573e4c9e0491e9484a5cc05abf Mon Sep 17 00:00:00 2001 From: Dandaedre Date: Sun, 4 Oct 2026 22:13:29 +0200 Subject: [PATCH] feat: add validated typed configuration and atomic persistence --- config/default.toml | 45 +++++ docs/configuration.md | 67 ++++++++ src/config.rs | 372 ++++++++++++++++++++++++++++++++++++++++++ src/lib.rs | 9 + src/storage.rs | 58 +++++++ 5 files changed, 551 insertions(+) create mode 100644 config/default.toml create mode 100644 docs/configuration.md create mode 100644 src/config.rs create mode 100644 src/lib.rs create mode 100644 src/storage.rs diff --git a/config/default.toml b/config/default.toml new file mode 100644 index 0000000..b04ce4a --- /dev/null +++ b/config/default.toml @@ -0,0 +1,45 @@ +# Embedded defaults. Copy to config.toml to customize; partial overrides work. +# Frequencies here and in CSV are MHz; commands sent to tinySA use Hz. +port = "" +baudrate = 115200 +start_frequency = 240 +stop_frequency = 960 +points = 10001 +repeat = 1 + +[serial] +# Timeout for each blocking serial read, not a whole-scan deadline. +timeout_ms = 3000 +command_delay_ms = 20 +settle_delay_ms = 200 +scan_delay_ms = 2000 +max_response_bytes = 65536 +baudrates = [19200, 38400, 57600, 115200, 230400, 460800, 921600, 1843200, 2000000, 3000000] +preferred_ports = ["/dev/ttyACM0", "COM3", "COM5", "/dev/ttyS16"] + +[scan] +# Sent with `zero`; the decoder uses this same offset. +zero_offset = 128 +frequency_step_mhz = 10 +points_step = 100 +min_points = 101 +max_points = 1000001 +max_repeat = 1000 +# Retain historical endpoint labels. `firmware` uses span / points instead. +frequency_axis = "inclusive" +# Retain the historical preparatory text scan until hardware confirms removal. +legacy_pre_scan = true + +[ui] +poll_interval_ms = 16 +chart_min_dbm = -128.0 +chart_max_dbm = 0.0 + +[output] +directory = "." +filename_prefix = "scan" +include_header = false + +[logging] +filter = "info" +directory = "." diff --git a/docs/configuration.md b/docs/configuration.md new file mode 100644 index 0000000..44bd8e8 --- /dev/null +++ b/docs/configuration.md @@ -0,0 +1,67 @@ +# Application configuration + +`config/default.toml` is the authoritative, commented set of defaults embedded +in the binary at compile time. To customize them, copy it to `config.toml` in +the working directory, or supply a partial file containing only overrides. +Rebuild after changing the embedded file; it is not read at runtime. + +The configuration API is in `src/config.rs`. It recursively merges supplied +TOML tables with the embedded defaults, deserializes into typed settings, and +validates before use. Arrays replace their defaults. Unknown keys, invalid +numbers, malformed files and I/O failures are errors; only an absent file uses +defaults. The original six top-level keys remain compatible: + +```toml +port = "/dev/ttyACM0" +baudrate = 115200 +start_frequency = 240 +stop_frequency = 960 +points = 10001 +repeat = 1 +``` + +Start/stop frequencies are **MHz**. The Basic envelope remains 0–960 MHz, +with stop at least 10 MHz; the protocol separately rejects spans that cannot +use one input path. Values must be ordered. The selected baud rate must be in +`serial.baudrates`; points and repeat must fit the configured bounds. + +| Section | Settings and units | +| --- | --- | +| `serial` | Read timeout and command/settling/pre-scan delays in milliseconds; bounded text response size in bytes; baud-rate choices and preferred ports. | +| `scan` | Raw zero offset in dB, frequency/sample keyboard steps, sample/repeat limits, frequency-axis convention, and legacy pre-scan toggle. | +| `ui` | Event polling interval in milliseconds and finite increasing chart bounds in dBm. | +| `output` | CSV directory, filename prefix, and optional column header. | +| `logging` | Logger filter expression and destination directory. | + +For example, this partial file changes the serial timeout and output format +while retaining the default scan selection: + +```toml +[serial] +timeout_ms = 5000 + +[output] +directory = "scans" +filename_prefix = "measurement" +include_header = true +``` + +All relative paths are relative to the process working directory. Saving a +selection preserves every recognized section, using a same-directory temporary +file, flush, and rename. The old configuration survives validation or write +failure. TOML formatting and comments are not preserved; retain comments in a +separate template if needed. The configuration file's parent must exist. + +`scan.frequency_axis = "inclusive"` preserves the historical CSV frequency +labels (`span / (points - 1)`). `"firmware"` uses `span / points`, matching the +reviewed upstream implementation. Neither changes the request or proves which +firmware is connected. See [frequency assignment](usb-protocol.md#frequency-assignment). + +The preparatory `scan START STOP 290 101` remains enabled by default with +`scan.legacy_pre_scan = true` for compatibility. Its undocumented output mask +is not a tunable protocol contract. Disable the step only after checking the +target instrument; hardware validation remains necessary. + +Protocol delimiters, fixed-point scaling, command grammar and Basic input-path +limits remain code invariants. Configuration cannot turn a Basic-only client +into an Ultra-compatible one by increasing a numeric limit. diff --git a/src/config.rs b/src/config.rs new file mode 100644 index 0000000..2aa3ed5 --- /dev/null +++ b/src/config.rs @@ -0,0 +1,372 @@ +//! 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 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, +} + +/// 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", + )?; + 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(); + } +} diff --git a/src/lib.rs b/src/lib.rs new file mode 100644 index 0000000..8b57bbd --- /dev/null +++ b/src/lib.rs @@ -0,0 +1,9 @@ +//! Reusable configuration and acquisition building blocks for tiny-wb. +//! +//! The core does not depend on terminal state. Parsers and writers accept data +//! or I/O interfaces so callers can test them without a connected instrument. + +#![warn(missing_docs)] + +pub mod config; +mod storage; diff --git a/src/storage.rs b/src/storage.rs new file mode 100644 index 0000000..5601f69 --- /dev/null +++ b/src/storage.rs @@ -0,0 +1,58 @@ +//! Same-directory replacement for configuration files. + +use std::{ + fs::{self, OpenOptions}, + io::{self, Write}, + path::{Path, PathBuf}, + sync::atomic::{AtomicU64, Ordering}, +}; + +/// Distinguish writes in one process, including concurrent callers. +static NEXT_FILE: AtomicU64 = AtomicU64::new(0); + +/// Remove an incomplete temporary file on errors and unwinding. +struct TemporaryFile(PathBuf); + +impl Drop for TemporaryFile { + fn drop(&mut self) { + let _ = fs::remove_file(&self.0); + } +} + +/// Replace a file only after its complete new contents have been flushed. +pub(crate) fn replace(path: &Path, contents: &[u8]) -> io::Result<()> { + let parent = path + .parent() + .filter(|p| !p.as_os_str().is_empty()) + .unwrap_or(Path::new(".")); + let name = path + .file_name() + .ok_or_else(|| io::Error::new(io::ErrorKind::InvalidInput, "missing file name"))?; + for _ in 0..100 { + let temporary = parent.join(format!( + ".{}.{}.{}.tmp", + name.to_string_lossy(), + std::process::id(), + NEXT_FILE.fetch_add(1, Ordering::Relaxed) + )); + let mut file = match OpenOptions::new() + .write(true) + .create_new(true) + .open(&temporary) + { + Ok(file) => file, + Err(error) if error.kind() == io::ErrorKind::AlreadyExists => continue, + Err(error) => return Err(error), + }; + let guard = TemporaryFile(temporary); + file.write_all(contents)?; + file.sync_all()?; + drop(file); + fs::rename(&guard.0, path)?; + return Ok(()); + } + Err(io::Error::new( + io::ErrorKind::AlreadyExists, + "could not allocate a configuration temporary file", + )) +}