feat: add validated typed configuration and atomic persistence

This commit is contained in:
Dandaedre 2026-10-04 22:13:29 +02:00
parent 77559e5b47
commit b117029c76
5 changed files with 551 additions and 0 deletions

45
config/default.toml Normal file
View File

@ -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 = "."

67
docs/configuration.md Normal file
View File

@ -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.

372
src/config.rs Normal file
View File

@ -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<u32>,
/// Fallback port names, tried in order after `port`.
pub preferred_ports: Vec<String>,
}
/// 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<Self, ConfigError> {
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<Self, ConfigError> {
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();
}
}

9
src/lib.rs Normal file
View File

@ -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;

58
src/storage.rs Normal file
View File

@ -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",
))
}