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:
parent
e1fe9b2733
commit
b4870a67b9
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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)
|
||||
}
|
||||
|
|
@ -3,6 +3,7 @@
|
|||
#![forbid(unsafe_code)]
|
||||
|
||||
pub mod cli;
|
||||
pub mod ipc;
|
||||
|
||||
use std::{collections::BTreeMap, error::Error, fmt};
|
||||
|
||||
|
|
|
|||
|
|
@ -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(_))
|
||||
));
|
||||
}
|
||||
Loading…
Reference in New Issue