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
This commit is contained in:
Dandaedre 2026-10-15 00:11:02 +02:00
parent e1fe9b2733
commit b4870a67b9
Signed by: Dandaedre
GPG Key ID: 440C6592E8A26D99
4 changed files with 193 additions and 0 deletions

View File

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

128
fader_master/src/ipc.rs Normal file
View File

@ -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<MixerStream>,
}
#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
pub struct MixerStream {
pub stream: StreamKey,
pub label: String,
pub process: Option<String>,
pub gain: f64,
pub muted: bool,
pub pending: bool,
pub writable: bool,
pub error: Option<String>,
}
#[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<T: Serialize>(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<T: DeserializeOwned>(reader: &mut impl Read) -> Result<T, FrameError> {
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)
}

View File

@ -3,6 +3,7 @@
#![forbid(unsafe_code)]
pub mod cli;
pub mod ipc;
use std::{collections::BTreeMap, error::Error, fmt};

View File

@ -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::<ClientRequest>(&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::<ClientRequest>(&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::<ClientRequest>(&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::<ClientRequest>(&mut Cursor::new(malformed)),
Err(FrameError::Decode(_))
));
}