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:
parent
013ff0de9f
commit
4e115b8562
|
|
@ -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;
|
||||
|
|
|
|||
|
|
@ -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);
|
||||
}
|
||||
|
|
|
|||
169
sound/src/lib.rs
169
sound/src/lib.rs
|
|
@ -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(),
|
||||
}]
|
||||
}),
|
||||
}
|
||||
}
|
||||
}
|
||||
|
|
|
|||
|
|
@ -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());
|
||||
}
|
||||
Loading…
Reference in New Issue