From b4870a67b9513242d1404b2800d7c068baa12e5a Mon Sep 17 00:00:00 2001 From: Dandaedre Date: Thu, 15 Oct 2026 00:11:02 +0200 Subject: [PATCH] feat(M7.2): frame the local IPC protocol Define versioned requests, revisioned mixer snapshots, request IDs, stream keys, and bounded length-prefixed TOML framing with explicit malformed and truncated errors. Tests: cargo test -p fader_master --test ipc_frames --all-features Tests: cargo clippy -p fader_master --all-targets --all-features --locked -- -D warnings --- fader_master/Cargo.toml | 3 + fader_master/src/ipc.rs | 128 +++++++++++++++++++++++++++++++ fader_master/src/lib.rs | 1 + fader_master/tests/ipc_frames.rs | 61 +++++++++++++++ 4 files changed, 193 insertions(+) create mode 100644 fader_master/src/ipc.rs create mode 100644 fader_master/tests/ipc_frames.rs diff --git a/fader_master/Cargo.toml b/fader_master/Cargo.toml index 94f5e91..501be8a 100644 --- a/fader_master/Cargo.toml +++ b/fader_master/Cargo.toml @@ -13,5 +13,8 @@ clap.workspace = true fader-config.workspace = true fader-core.workspace = true midi.workspace = true +serde.workspace = true +thiserror.workspace = true +toml.workspace = true tui.workspace = true volume_lib.workspace = true diff --git a/fader_master/src/ipc.rs b/fader_master/src/ipc.rs new file mode 100644 index 0000000..bcc5ad5 --- /dev/null +++ b/fader_master/src/ipc.rs @@ -0,0 +1,128 @@ +use std::io::{self, Read, Write}; + +use serde::{Deserialize, Serialize, de::DeserializeOwned}; +use thiserror::Error; + +pub const PROTOCOL_VERSION: u16 = 1; +pub const MAX_FRAME_BYTES: usize = 64 * 1024; + +/// Stable wire representation of an ephemeral stream handle. +#[derive(Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)] +pub struct StreamKey { + pub epoch: u64, + pub backend_id: u64, + pub incarnation: u64, +} + +#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)] +pub struct ClientRequest { + pub version: u16, + pub request_id: u64, + pub command: RequestCommand, +} + +#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)] +#[serde(tag = "type", rename_all = "snake_case")] +pub enum RequestCommand { + Snapshot, + SetVolume { + stream: StreamKey, + gain: f64, + expected_revision: u64, + }, + ToggleMute { + stream: StreamKey, + expected_revision: u64, + }, +} + +#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)] +pub struct ServerResponse { + pub version: u16, + pub request_id: u64, + pub result: ResponseResult, +} + +#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)] +#[serde(tag = "type", rename_all = "snake_case")] +pub enum ResponseResult { + Snapshot { snapshot: MixerSnapshot }, + Error { message: String, resync: bool }, +} + +#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)] +pub struct MixerSnapshot { + pub revision: u64, + pub backend: String, + pub status: String, + pub streams: Vec, +} + +#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)] +pub struct MixerStream { + pub stream: StreamKey, + pub label: String, + pub process: Option, + pub gain: f64, + pub muted: bool, + pub pending: bool, + pub writable: bool, + pub error: Option, +} + +#[derive(Debug, Error)] +pub enum FrameError { + #[error("IPC frame length {actual} exceeds maximum {maximum}")] + TooLarge { actual: usize, maximum: usize }, + #[error("IPC frame is truncated: {0}")] + Truncated(io::Error), + #[error("could not encode IPC TOML: {0}")] + Encode(toml::ser::Error), + #[error("could not decode IPC TOML: {0}")] + Decode(toml::de::Error), + #[error("IPC frame is not UTF-8: {0}")] + Utf8(std::str::Utf8Error), + #[error("could not write IPC frame: {0}")] + Write(io::Error), +} + +pub fn write_frame(writer: &mut impl Write, value: &T) -> Result<(), FrameError> { + let payload = toml::to_string(value).map_err(FrameError::Encode)?; + if payload.len() > MAX_FRAME_BYTES { + return Err(FrameError::TooLarge { + actual: payload.len(), + maximum: MAX_FRAME_BYTES, + }); + } + let length = u32::try_from(payload.len()).map_err(|_| FrameError::TooLarge { + actual: payload.len(), + maximum: MAX_FRAME_BYTES, + })?; + writer + .write_all(&length.to_be_bytes()) + .and_then(|()| writer.write_all(payload.as_bytes())) + .map_err(FrameError::Write) +} + +pub fn read_frame(reader: &mut impl Read) -> Result { + let mut length = [0_u8; 4]; + reader + .read_exact(&mut length) + .map_err(FrameError::Truncated)?; + let length = usize::try_from(u32::from_be_bytes(length)).map_err(|_| FrameError::TooLarge { + actual: usize::MAX, + maximum: MAX_FRAME_BYTES, + })?; + if length > MAX_FRAME_BYTES { + return Err(FrameError::TooLarge { + actual: length, + maximum: MAX_FRAME_BYTES, + }); + } + let mut payload = vec![0_u8; length]; + reader + .read_exact(&mut payload) + .map_err(FrameError::Truncated)?; + let payload = std::str::from_utf8(&payload).map_err(FrameError::Utf8)?; + toml::from_str(payload).map_err(FrameError::Decode) +} diff --git a/fader_master/src/lib.rs b/fader_master/src/lib.rs index 90ae160..8ce2b94 100644 --- a/fader_master/src/lib.rs +++ b/fader_master/src/lib.rs @@ -3,6 +3,7 @@ #![forbid(unsafe_code)] pub mod cli; +pub mod ipc; use std::{collections::BTreeMap, error::Error, fmt}; diff --git a/fader_master/tests/ipc_frames.rs b/fader_master/tests/ipc_frames.rs new file mode 100644 index 0000000..f5f9ba1 --- /dev/null +++ b/fader_master/tests/ipc_frames.rs @@ -0,0 +1,61 @@ +use std::io::Cursor; + +use fader_master::ipc::{ + ClientRequest, FrameError, MAX_FRAME_BYTES, PROTOCOL_VERSION, RequestCommand, StreamKey, + read_frame, write_frame, +}; + +fn request() -> ClientRequest { + ClientRequest { + version: PROTOCOL_VERSION, + request_id: 42, + command: RequestCommand::SetVolume { + stream: StreamKey { + epoch: 2, + backend_id: 9, + incarnation: 3, + }, + gain: 0.25, + expected_revision: 7, + }, + } +} + +#[test] +fn bounded_toml_frame_round_trips_request_identity_and_revision() { + let expected = request(); + let mut bytes = Vec::new(); + write_frame(&mut bytes, &expected).unwrap(); + assert!(bytes.len() <= MAX_FRAME_BYTES + 4); + assert_eq!( + read_frame::(&mut Cursor::new(bytes)).unwrap(), + expected + ); +} + +#[test] +fn oversized_length_is_rejected_before_payload_allocation_or_read() { + let length = u32::try_from(MAX_FRAME_BYTES + 1).unwrap().to_be_bytes(); + assert!(matches!( + read_frame::(&mut Cursor::new(length)), + Err(FrameError::TooLarge { .. }) + )); +} + +#[test] +fn truncated_and_malformed_frames_are_explicit_errors() { + let mut truncated = Vec::from(10_u32.to_be_bytes()); + truncated.extend_from_slice(b"short"); + assert!(matches!( + read_frame::(&mut Cursor::new(truncated)), + Err(FrameError::Truncated(_)) + )); + + let invalid = b"not = [valid"; + let mut malformed = Vec::from(u32::try_from(invalid.len()).unwrap().to_be_bytes()); + malformed.extend_from_slice(invalid); + assert!(matches!( + read_frame::(&mut Cursor::new(malformed)), + Err(FrameError::Decode(_)) + )); +}