//! Bounded, stateful console simulation and an in-memory duplex stream. use crate::protocol::{ firmware_frequency_hz, ScanRequest, BASIC_RAW_LEVEL_OFFSET_DB, ULTRA_RAW_LEVEL_OFFSET_DB, }; use serde::{Deserialize, Serialize}; use std::{ collections::VecDeque, io::{self, Read, Write}, }; /// Synthetic identity and command differences, not hardware certification. #[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)] #[serde(rename_all = "snake_case")] pub enum MockModel { /// Basic low/high input syntax; initial raw offset 128 dB. Basic, /// Ultra input syntax, LNA/Ultra toggles; initial raw offset 174 dB. Ultra, } /// One-shot fault applied to the first matching command in each new session. #[derive(Debug, Clone, Copy, Default, Serialize, Deserialize, PartialEq, Eq)] #[serde(rename_all = "snake_case")] pub enum MockFault { /// Normal behavior. #[default] None, /// Reject the command without changing device state. Reject, /// Drop the command and its response, making the next empty read time out. Timeout, /// Close the stream immediately without processing the command. Disconnect, /// Omit the trailing prompt after executing the command. MissingPrompt, /// Remove the end of a scanraw frame and its prompt. TruncatedFrame, /// Replace the first scanraw record's alignment byte. BadAlignment, } /// Simulator policy, loadable from TOML independently of application settings. #[derive(Debug, Clone, Serialize, Deserialize)] #[serde(default, deny_unknown_fields)] pub struct MockConfig { /// Synthetic device identity. pub model: MockModel, /// Echo complete commands before responding. pub echo: bool, /// Maximum bytes returned per in-memory read (also server write chunk size). pub read_chunk_bytes: usize, /// Maximum bytes accepted per in-memory write, exercising complete writes. pub write_chunk_bytes: usize, /// TCP example read/write timeout, in milliseconds (1 through 600,000). pub session_timeout_ms: u64, /// Maximum command line size, before a terminator. pub command_limit_bytes: usize, /// Maximum requested scan points, bounding frame allocation. pub max_points: usize, /// Synthetic Ultra ceiling in Hz; not a hardware capability claim. pub ultra_max_hz: u64, /// Deterministic spectrum floor, in dBm. pub floor_dbm: f64, /// Triangular peak level, in dBm. pub peak_dbm: f64, /// Synthetic carrier center, in Hz. pub peak_frequency_hz: u64, /// Half-width of the triangular peak, in Hz. pub peak_width_hz: u64, /// One-shot response fault. pub fault: MockFault, /// Command verb on which to inject the fault, for example `scanraw`. pub fault_command: String, } impl Default for MockConfig { fn default() -> Self { Self { model: MockModel::Basic, echo: true, read_chunk_bytes: 4096, write_chunk_bytes: 4096, session_timeout_ms: 30_000, command_limit_bytes: 256, max_points: 10001, ultra_max_hz: 6_000_000_000, floor_dbm: -96.0, peak_dbm: -32.0, peak_frequency_hz: 300_000_000, peak_width_hz: 10_000_000, fault: MockFault::None, fault_command: "scanraw".into(), } } } impl MockConfig { /// Reject unbounded allocations, non-finite signal values and invalid fault settings. pub fn validate(&self) -> io::Result<()> { let valid = (1..=600_000).contains(&self.session_timeout_ms) && (1..=65536).contains(&self.read_chunk_bytes) && (1..=65536).contains(&self.write_chunk_bytes) && (16..=4096).contains(&self.command_limit_bytes) && (2..=1_000_001).contains(&self.max_points) && (960_000_000..=12_000_000_000).contains(&self.ultra_max_hz) && self.floor_dbm.is_finite() && self.peak_dbm.is_finite() && (-174.0..=100.0).contains(&self.floor_dbm) && (self.floor_dbm..=100.0).contains(&self.peak_dbm) && self.peak_frequency_hz <= 12_000_000_000 && (1..=12_000_000_000).contains(&self.peak_width_hz) && !self.fault_command.is_empty() && self .fault_command .bytes() .all(|b| b.is_ascii_lowercase() || b == b'_') && (!matches!( self.fault, MockFault::TruncatedFrame | MockFault::BadAlignment ) || self.fault_command == "scanraw"); if valid { Ok(()) } else { Err(io::Error::new( io::ErrorKind::InvalidInput, "invalid mock configuration bounds or fault/command combination", )) } } } /// Observable simulated state. No field represents a physical measurement. #[derive(Debug, Clone, PartialEq)] pub struct MockState { /// Synthetic model. pub model: MockModel, /// Whether normal sweeping is paused. pub paused: bool, /// Last selected input keyword (`low`, `high`, or `input`). pub input: String, /// Display sweep start, in Hz. pub start_hz: u64, /// Display sweep stop, in Hz. pub stop_hz: u64, /// Last requested raw scan sample count. pub points: usize, /// Measurement repeat count. pub repeat: usize, /// Offset used by raw fixed-point encoding, in dB. pub zero_offset: u16, /// Simulated LNA state (Ultra only; no RF effect). pub lna: bool, /// Simulated Ultra state (no RF effect). pub ultra: bool, /// Last 1,024 complete commands, oldest first; excludes overlong lines. pub commands: VecDeque, } /// A deterministic `Read + Write` fake instrument with partial I/O support. /// /// Empty reads return `TimedOut`, not EOF; a disconnect fault returns EOF and /// rejects later writes. Responses are generated only when commands arrive. /// Use `Shell::new(&mut mock, limit)` to inspect state after dropping the shell. pub struct MockStream { config: MockConfig, state: MockState, input: Vec, output: VecDeque, discarding: bool, connected: bool, fault_used: bool, } impl MockStream { /// Construct a fresh session with an initial shell prompt. pub fn new(config: MockConfig) -> io::Result { config.validate()?; let state = MockState { model: config.model, paused: false, input: if config.model == MockModel::Basic { "low" } else { "input" } .into(), start_hz: 240_000_000, stop_hz: 960_000_000, points: 101.min(config.max_points), repeat: 1, zero_offset: if config.model == MockModel::Basic { BASIC_RAW_LEVEL_OFFSET_DB } else { ULTRA_RAW_LEVEL_OFFSET_DB }, lna: false, ultra: false, commands: VecDeque::new(), }; Ok(Self { config, state, input: Vec::new(), output: VecDeque::from(b"ch>".to_vec()), discarding: false, connected: true, fault_used: false, }) } /// Read-only state and bounded command history, for assertions. pub fn state(&self) -> &MockState { &self.state } /// Whether a disconnect fault closed the simulated connection. pub fn is_connected(&self) -> bool { self.connected } /// Number of currently queued response bytes; used by the TCP adapter. pub fn pending_bytes(&self) -> usize { self.output.len() } /// Bound pipelined responses as well as individual scan allocations. fn enqueue(&mut self, bytes: &[u8]) -> io::Result<()> { let limit = self.config.max_points * 3 + self.config.command_limit_bytes + 65536; if self.output.len().saturating_add(bytes.len()) > limit { return Err(io::Error::new( io::ErrorKind::OutOfMemory, "mock response queue limit exceeded; read responses before pipelining commands", )); } self.output.extend(bytes); Ok(()) } fn execute(&mut self, command: &str) -> io::Result<()> { if self.state.commands.len() == 1024 { self.state.commands.pop_front(); } self.state.commands.push_back(command.into()); let verb = command.split_whitespace().next().unwrap_or(""); let fault = if !self.fault_used && verb == self.config.fault_command { self.fault_used = true; self.config.fault } else { MockFault::None }; match fault { MockFault::Timeout => return Ok(()), MockFault::Disconnect => { self.connected = false; self.output.clear(); return Ok(()); } _ => {} } let mut response = if self.config.echo { format!("{command}\r\n").into_bytes() } else { Vec::new() }; let mut body = if fault == MockFault::Reject { b"error: injected rejection\r\n".to_vec() } else { self.respond(command) }; if fault == MockFault::BadAlignment && body.first() == Some(&b'{') { body[1] = b'!'; } if fault == MockFault::TruncatedFrame && body.first() == Some(&b'{') { body.truncate(body.len().saturating_sub(4)); } response.extend(body); if !matches!(fault, MockFault::MissingPrompt | MockFault::TruncatedFrame) { response.extend_from_slice(b"ch>"); } self.enqueue(&response) } /// Unsupported commands fail explicitly rather than inventing successful firmware behavior. fn respond(&mut self, command: &str) -> Vec { let fields: Vec<_> = command.split_whitespace().collect(); let ok = b"".to_vec(); let invalid = || b"error: unsupported command or invalid arguments in mock\r\n".to_vec(); match fields.as_slice() { [] => ok, ["version"] => match self.state.model { MockModel::Basic => b"tinySA_v1.4-mock (synthetic)\r\n".to_vec(), MockModel::Ultra => b"tinySA4_v1.4-mock (synthetic)\r\n".to_vec(), }, ["info"] => match self.state.model { MockModel::Basic => b"tinySA\nmock; not real firmware\r\n".to_vec(), MockModel::Ultra => b"tinySA Ultra mock; not real firmware\r\n".to_vec(), }, ["help"] => { let extra = if self.state.model == MockModel::Ultra { " lna ultra" } else { "" }; format!("Commands: version info help pause resume mode repeat zero sweep scan scanraw leveloffset vbat usart_cfg threads marker{extra}\r\n").into_bytes() } ["pause"] => { self.state.paused = true; ok } ["resume"] => { self.state.paused = false; ok } ["mode", "low" | "high", "input"] if self.state.model == MockModel::Basic => { self.state.input = fields[1].into(); ok } ["mode", "input"] | ["mode", "low", "input"] if self.state.model == MockModel::Ultra => { self.state.input = "input".into(); ok } ["lna", value] | ["ultra", value] if self.state.model == MockModel::Ultra && matches!(*value, "on" | "off") => { if fields[0] == "lna" { self.state.lna = *value == "on"; } else { self.state.ultra = *value == "on"; } ok } ["repeat", value] => match value.parse::() { Ok(value) if (1..=1000).contains(&value) => { self.state.repeat = value; ok } _ => invalid(), }, ["zero", value] => match value.parse::() { Ok(value) if value <= 2047 => { self.state.zero_offset = value; ok } _ => invalid(), }, ["zero"] => { format!("usage: zero {{level}}\r\n{}dBm\r\n", self.state.zero_offset).into_bytes() } ["sweep", "start" | "stop", value] => match value.parse::() { Ok(value) if value <= self.max_hz() => { if fields[1] == "start" { self.state.start_hz = value; } else { self.state.stop_hz = value; } ok } _ => invalid(), }, ["sweep"] => format!( "{} {} {}\r\n", self.state.start_hz, self.state.stop_hz, self.state.points ) .into_bytes(), ["scanraw", start, stop, points] => { if let Some((start, stop, points)) = self.scan_arguments(start, stop, points) { self.state.points = points; let mut frame = Vec::with_capacity(points * 3 + 4); frame.push(b'{'); let request = ScanRequest { start_hz: start, stop_hz: stop, points, repeat: self.state.repeat, }; for index in 0..points { let frequency = firmware_frequency_hz(&request, index) as f64; let strength = (1.0 - (frequency - self.config.peak_frequency_hz as f64).abs() / self.config.peak_width_hz as f64) .clamp(0.0, 1.0); let level = self.config.floor_dbm + strength * (self.config.peak_dbm - self.config.floor_dbm); let raw = ((level + f64::from(self.state.zero_offset)) * 32.0) .round() .clamp(0.0, 65535.0) as u16; frame.push(b'x'); frame.extend(raw.to_le_bytes()); } frame.extend_from_slice(b"}\r\n"); frame } else { invalid() } } // Compatibility-only preparation used by the current application. No trace is returned. ["scan", start, stop, "290", "101"] if self.scan_arguments(start, stop, "2").is_some() => { ok } ["leveloffset"] => b"leveloffset mock 0\r\n".to_vec(), ["vbat"] => b"4000 mV (mock)\r\n".to_vec(), ["usart_cfg"] => b"115200 (mock)\r\n".to_vec(), ["threads"] => b"mock: synchronous\r\n".to_vec(), ["marker"] => b"1 0 300000000 -32 (mock)\r\n".to_vec(), _ => invalid(), } } fn max_hz(&self) -> u64 { if self.state.model == MockModel::Basic { 960_000_000 } else { self.config.ultra_max_hz } } fn scan_arguments(&self, start: &str, stop: &str, points: &str) -> Option<(u64, u64, usize)> { let (start, stop, points) = ( start.parse::().ok()?, stop.parse::().ok()?, points.parse::().ok()?, ); if start > stop || stop > self.max_hz() || !(2..=self.config.max_points).contains(&points) { return None; } if self.state.model == MockModel::Basic { let valid = match self.state.input.as_str() { "low" => stop < 350_000_000, "high" => start >= 240_000_000, _ => false, }; if !valid { return None; } } Some((start, stop, points)) } } impl Read for MockStream { fn read(&mut self, buffer: &mut [u8]) -> io::Result { if buffer.is_empty() { return Ok(0); } if self.output.is_empty() { return if self.connected { Err(io::ErrorKind::TimedOut.into()) } else { Ok(0) }; } let count = buffer .len() .min(self.config.read_chunk_bytes) .min(self.output.len()); for byte in &mut buffer[..count] { *byte = self.output.pop_front().expect("queue length checked"); } Ok(count) } } impl Write for MockStream { fn write(&mut self, bytes: &[u8]) -> io::Result { if bytes.is_empty() { return Ok(0); } if !self.connected { return Err(io::ErrorKind::BrokenPipe.into()); } let count = bytes.len().min(self.config.write_chunk_bytes); for (index, &byte) in bytes[..count].iter().enumerate() { if matches!(byte, b'\r' | b'\n') { if self.discarding { self.discarding = false; self.enqueue(b"error: command too long\r\nch>")?; } else if !self.input.is_empty() { let input = std::mem::take(&mut self.input); match String::from_utf8(input) { Ok(command) if command.bytes().all(|c| (b' '..=b'~').contains(&c)) => { self.execute(&command)? } _ => self.enqueue(b"error: command must be printable ASCII\r\nch>")?, } } } else if !self.discarding { if self.input.len() == self.config.command_limit_bytes { self.input.clear(); self.discarding = true; } else { self.input.push(byte); } } if !self.connected { return Ok(index + 1); } } Ok(count) } fn flush(&mut self) -> io::Result<()> { Ok(()) } }