feat(M3.2): add the fake audio worker contract

Add adapter capabilities, snapshot barriers with buffered race reconciliation, deterministic volume/mute writes and readback, and normal removal failures. Reject stale epochs and backend-ID incarnations while preserving newer pending reducer intent.

Tests: cargo fmt --all -- --check; cargo test -p fader-core -p volume_lib --all-targets --locked; cargo clippy -p fader-core -p volume_lib --all-targets --locked -- -D warnings (all pass)
This commit is contained in:
Dandaedre 2026-10-14 15:38:42 +02:00
parent 013ff0de9f
commit 4e115b8562
Signed by: Dandaedre
GPG Key ID: 440C6592E8A26D99
4 changed files with 338 additions and 0 deletions

View File

@ -9,6 +9,12 @@ use thiserror::Error;
pub struct OperationId(u64);
impl OperationId {
/// Creates an identifier at an adapter or wire boundary.
#[must_use]
pub const fn new(value: u64) -> Self {
Self(value)
}
#[must_use]
pub const fn get(self) -> u64 {
self.0
@ -146,6 +152,7 @@ pub struct ServerReducer {
write_ceiling: Gain,
streams: BTreeMap<StreamHandle, StreamState>,
operations: BTreeMap<OperationId, Pending>,
active_epoch: Option<crate::BackendEpoch>,
}
impl ServerReducer {
@ -157,6 +164,7 @@ impl ServerReducer {
write_ceiling,
streams: BTreeMap::new(),
operations: BTreeMap::new(),
active_epoch: None,
}
}
@ -243,6 +251,10 @@ impl ServerReducer {
muted,
operation,
} => {
if self.event_is_stale(stream) {
return Ok(Transition::default());
}
self.adopt_epoch_and_incarnation(stream);
if let Some(operation) = operation {
self.settle_if_current(operation);
}
@ -324,6 +336,38 @@ impl ServerReducer {
Ok(operation)
}
fn event_is_stale(&self, stream: StreamHandle) -> bool {
if self
.active_epoch
.is_some_and(|epoch| stream.epoch() < epoch)
{
return true;
}
self.streams.keys().any(|known| {
known.epoch() == stream.epoch()
&& known.backend_id() == stream.backend_id()
&& known.incarnation() > stream.incarnation()
})
}
fn adopt_epoch_and_incarnation(&mut self, stream: StreamHandle) {
if self.active_epoch.is_none_or(|epoch| stream.epoch() > epoch) {
self.active_epoch = Some(stream.epoch());
self.streams.clear();
self.operations.clear();
}
self.streams.retain(|known, _| {
known.epoch() != stream.epoch()
|| known.backend_id() != stream.backend_id()
|| known.incarnation() >= stream.incarnation()
});
self.operations.retain(|_, pending| {
pending.stream.epoch() != stream.epoch()
|| pending.stream.backend_id() != stream.backend_id()
|| pending.stream.incarnation() >= stream.incarnation()
});
}
fn settle_if_current(&mut self, operation: OperationId) -> bool {
let Some(pending) = self.operations.remove(&operation) else {
return false;

View File

@ -112,3 +112,56 @@ fn external_observation_updates_views_without_an_audio_effect() {
assert_eq!(transition.confirmed[0].revision, Revision::new(1));
assert_eq!(transition.confirmed[0].muted, Mute::Muted);
}
#[test]
fn older_completion_cannot_clear_newer_pending_intent() {
let mut reducer = ServerReducer::new(Gain::UNITY);
observe(&mut reducer, channels(0.2, 0.4), Mute::Unmuted);
let first = reducer
.command(ServerCommand::SetVolume {
origin: CommandOrigin::Client { request: 1 },
expected_revision: reducer.revision(),
stream: stream(),
target: Gain::new(0.5).unwrap(),
})
.unwrap();
let second = reducer
.command(ServerCommand::SetVolume {
origin: CommandOrigin::Client { request: 2 },
expected_revision: reducer.revision(),
stream: stream(),
target: Gain::new(0.8).unwrap(),
})
.unwrap();
let AdapterCommand::SetVolume {
operation: first, ..
} = first.adapter[0]
else {
panic!("first volume operation");
};
let AdapterCommand::SetVolume {
operation: second, ..
} = second.adapter[0]
else {
panic!("second volume operation");
};
reducer
.event(AdapterEvent::Observed {
stream: stream(),
channels: channels(0.25, 0.5),
muted: Mute::Unmuted,
operation: Some(first),
})
.unwrap();
assert!(reducer.view(stream()).unwrap().pending);
reducer
.event(AdapterEvent::Observed {
stream: stream(),
channels: channels(0.4, 0.8),
muted: Mute::Unmuted,
operation: Some(second),
})
.unwrap();
assert!(!reducer.view(stream()).unwrap().pending);
}

View File

@ -1,3 +1,172 @@
//! Audio adapter workers for fader_master.
#![forbid(unsafe_code)]
use std::collections::BTreeMap;
use fader_core::{AdapterCommand, AdapterEvent, BackendEpoch, ChannelGains, Mute, StreamHandle};
/// Capabilities reported before an adapter becomes authoritative.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub struct AdapterCapabilities {
pub volume: bool,
pub mute: bool,
pub subscriptions: bool,
}
/// Snapshot framing and copied adapter events.
#[derive(Clone, Debug, PartialEq)]
pub enum WorkerEvent {
SnapshotBegin(BackendEpoch),
Adapter(AdapterEvent),
SnapshotEnd(BackendEpoch),
}
#[derive(Clone, Debug)]
struct FakeStream {
channels: ChannelGains,
muted: Mute,
}
/// Deterministic, hardware-free implementation of the audio worker contract.
#[derive(Debug)]
pub struct FakeAdapter {
epoch: BackendEpoch,
streams: BTreeMap<StreamHandle, FakeStream>,
snapshot: Option<BTreeMap<StreamHandle, FakeStream>>,
during_snapshot: Vec<AdapterEvent>,
}
impl FakeAdapter {
#[must_use]
pub fn new(epoch: BackendEpoch) -> Self {
Self {
epoch,
streams: BTreeMap::new(),
snapshot: None,
during_snapshot: Vec::new(),
}
}
#[must_use]
pub const fn capabilities(&self) -> AdapterCapabilities {
AdapterCapabilities {
volume: true,
mute: true,
subscriptions: true,
}
}
pub fn begin_snapshot(&mut self) -> WorkerEvent {
self.snapshot = Some(self.streams.clone());
self.during_snapshot.clear();
WorkerEvent::SnapshotBegin(self.epoch)
}
pub fn finish_snapshot(&mut self) -> Vec<WorkerEvent> {
let snapshot = self.snapshot.take().unwrap_or_default();
let mut events = snapshot
.into_iter()
.map(|(stream, state)| {
WorkerEvent::Adapter(AdapterEvent::Observed {
stream,
channels: state.channels,
muted: state.muted,
operation: None,
})
})
.collect::<Vec<_>>();
events.extend(self.during_snapshot.drain(..).map(WorkerEvent::Adapter));
events.push(WorkerEvent::SnapshotEnd(self.epoch));
events
}
pub fn upsert(
&mut self,
stream: StreamHandle,
channels: ChannelGains,
muted: Mute,
) -> Option<AdapterEvent> {
self.streams.insert(
stream,
FakeStream {
channels: channels.clone(),
muted,
},
);
let event = AdapterEvent::Observed {
stream,
channels,
muted,
operation: None,
};
if self.snapshot.is_some() {
self.during_snapshot.push(event);
None
} else {
Some(event)
}
}
pub fn remove(&mut self, stream: StreamHandle) -> Option<AdapterEvent> {
self.streams.remove(&stream)?;
let event = AdapterEvent::StreamRemoved { stream };
if self.snapshot.is_some() {
self.during_snapshot.push(event);
None
} else {
Some(event)
}
}
#[must_use]
pub fn execute(&mut self, command: AdapterCommand) -> Vec<AdapterEvent> {
match command {
AdapterCommand::SetVolume {
operation,
stream,
channels,
} => match self.streams.get_mut(&stream) {
Some(state) => {
state.channels = channels;
vec![AdapterEvent::WriteAccepted { operation }]
}
None => vec![AdapterEvent::WriteFailed {
operation,
message: "stream disappeared before volume write".into(),
}],
},
AdapterCommand::SetMute {
operation,
stream,
muted,
} => match self.streams.get_mut(&stream) {
Some(state) => {
state.muted = muted;
vec![AdapterEvent::WriteAccepted { operation }]
}
None => vec![AdapterEvent::WriteFailed {
operation,
message: "stream disappeared before mute write".into(),
}],
},
AdapterCommand::Readback { operation, stream } => self
.streams
.get(&stream)
.map(|state| {
vec![AdapterEvent::Observed {
stream,
channels: state.channels.clone(),
muted: state.muted,
operation: Some(operation),
}]
})
.unwrap_or_else(|| {
vec![AdapterEvent::WriteFailed {
operation,
message: "stream disappeared before readback".into(),
}]
}),
}
}
}

View File

@ -0,0 +1,72 @@
use fader_core::{
AdapterCommand, AdapterEvent, BackendEpoch, ChannelGains, Gain, Mute, OperationId,
ServerReducer, StreamHandle,
};
use volume_lib::{FakeAdapter, WorkerEvent};
fn handle(epoch: u64, incarnation: u64) -> StreamHandle {
StreamHandle::new(BackendEpoch::new(epoch), 4, incarnation)
}
fn channels(value: f64) -> ChannelGains {
ChannelGains::new(vec![Gain::new(value).unwrap()]).unwrap()
}
#[test]
fn snapshot_buffers_changes_and_replays_them_after_enumeration() {
let mut adapter = FakeAdapter::new(BackendEpoch::new(2));
adapter.upsert(handle(2, 1), channels(0.2), Mute::Unmuted);
assert!(matches!(
adapter.begin_snapshot(),
WorkerEvent::SnapshotBegin(_)
));
adapter.upsert(handle(2, 1), channels(0.7), Mute::Muted);
let events = adapter.finish_snapshot();
let observations = events
.iter()
.filter_map(|event| match event {
WorkerEvent::Adapter(AdapterEvent::Observed { channels, .. }) => {
Some(channels.maximum())
}
_ => None,
})
.collect::<Vec<_>>();
assert_eq!(
observations,
vec![Gain::new(0.2).unwrap(), Gain::new(0.7).unwrap()]
);
assert!(matches!(events.last(), Some(WorkerEvent::SnapshotEnd(_))));
}
#[test]
fn removal_during_write_is_a_normal_failure() {
let mut adapter = FakeAdapter::new(BackendEpoch::new(1));
adapter.upsert(handle(1, 1), channels(0.3), Mute::Unmuted);
adapter.remove(handle(1, 1));
let events = adapter.execute(AdapterCommand::SetMute {
operation: OperationId::new(1),
stream: handle(1, 1),
muted: Mute::Muted,
});
assert!(matches!(
events.as_slice(),
[AdapterEvent::WriteFailed { .. }]
));
}
#[test]
fn reducer_ignores_old_epochs_and_reused_backend_incarnations() {
let mut reducer = ServerReducer::new(Gain::UNITY);
for stream in [handle(2, 2), handle(1, 9), handle(2, 1)] {
reducer
.event(AdapterEvent::Observed {
stream,
channels: channels(stream.incarnation() as f64 / 10.0),
muted: Mute::Unmuted,
operation: None,
})
.unwrap();
}
assert_eq!(reducer.view(handle(2, 2)).unwrap().channels, channels(0.2));
assert!(reducer.view(handle(1, 9)).is_none());
assert!(reducer.view(handle(2, 1)).is_none());
}