use core::ops::Deref;
use core::sync::atomic::{AtomicUsize, Ordering};
use std::sync::{Arc, OnceLock};
use bytes::Bytes;
use globset::{Glob, GlobSet, GlobSetBuilder};
use shep_core::protocol::{BusEvent, encode_frame};
use tokio::sync::broadcast::{self, error::RecvError};
use tokio::sync::mpsc;
use tokio::task::JoinHandle;
pub const BUS_CAPACITY: usize = 1024;
pub const MAX_TOPIC_PATTERNS: usize = 32;
#[must_use]
pub fn new_bus() -> Bus {
Bus {
tx: broadcast::channel(BUS_CAPACITY).0,
log_subscribers: Arc::new(AtomicUsize::new(0)),
}
}
#[derive(Clone, Debug)]
pub struct Bus {
tx: broadcast::Sender<SharedEvent>,
log_subscribers: Arc<AtomicUsize>,
}
impl Bus {
pub fn publish_log(&self, event: BusEvent) {
if self.log_subscribers.load(Ordering::Relaxed) == 0 {
return;
}
let _ = self.tx.send(SharedEvent::new(event));
}
#[must_use]
fn subscribe_for(
&self,
filter: &TopicFilter,
) -> (broadcast::Receiver<SharedEvent>, LogInterest) {
let interest = if filter.wants_logs() {
self.log_subscribers.fetch_add(1, Ordering::Relaxed);
LogInterest(Some(Arc::clone(&self.log_subscribers)))
} else {
LogInterest(None)
};
(self.tx.subscribe(), interest)
}
#[cfg(test)]
fn log_subscribers(&self) -> usize {
self.log_subscribers.load(Ordering::Relaxed)
}
}
impl Deref for Bus {
type Target = broadcast::Sender<SharedEvent>;
#[inline]
fn deref(&self) -> &broadcast::Sender<SharedEvent> {
&self.tx
}
}
pub fn publish_dog_config_changed(bus: &Bus, dogs: &[String]) {
for dog in dogs {
let _ = bus.send(BusEvent::DogConfigChanged { dog: dog.clone() }.into());
}
}
#[derive(Debug)]
pub struct LogInterest(Option<Arc<AtomicUsize>>);
impl Drop for LogInterest {
fn drop(&mut self) {
if let Some(count) = self.0.take() {
count.fetch_sub(1, Ordering::Relaxed);
}
}
}
#[cfg(test)]
pub(crate) fn test_bus(capacity: usize) -> (Bus, broadcast::Receiver<SharedEvent>) {
let (tx, rx) = broadcast::channel(capacity);
let bus = Bus {
tx,
log_subscribers: Arc::new(AtomicUsize::new(0)),
};
(bus, rx)
}
#[derive(Clone)]
pub struct SharedEvent(Arc<Shared>);
impl core::fmt::Debug for SharedEvent {
fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
f.debug_struct("SharedEvent")
.field("event", &self.0.event)
.field("encoded", &self.0.frame.get().is_some())
.finish()
}
}
#[derive(Debug)]
struct Shared {
event: BusEvent,
frame: OnceLock<Option<Bytes>>,
#[cfg(test)]
encodes: AtomicUsize,
}
impl SharedEvent {
#[must_use]
pub fn new(event: BusEvent) -> Self {
Self(Arc::new(Shared {
event,
frame: OnceLock::new(),
#[cfg(test)]
encodes: AtomicUsize::new(0),
}))
}
#[cfg(test)]
fn encodes(&self) -> usize {
self.0.encodes.load(Ordering::Relaxed)
}
#[must_use]
pub fn to_event(&self) -> BusEvent {
self.0.event.clone()
}
fn frame(&self) -> Option<&Bytes> {
self.0
.frame
.get_or_init(|| {
#[cfg(test)]
self.0.encodes.fetch_add(1, Ordering::Relaxed);
match encode_frame(&self.0.event) {
Ok(bytes) => Some(bytes),
Err(err) => {
tracing::warn!(
%err,
topic = %self.0.event.topic(),
"dropping an unencodable bus event"
);
None
}
}
})
.as_ref()
}
}
impl Deref for SharedEvent {
type Target = BusEvent;
#[inline]
fn deref(&self) -> &BusEvent {
&self.0.event
}
}
impl From<BusEvent> for SharedEvent {
fn from(event: BusEvent) -> Self {
Self::new(event)
}
}
impl PartialEq<BusEvent> for SharedEvent {
fn eq(&self, other: &BusEvent) -> bool {
self.0.event == *other
}
}
#[derive(Debug)]
pub struct TopicFilter {
set: GlobSet,
patterns: Vec<String>,
}
impl TopicFilter {
pub fn new(patterns: &[String]) -> Result<Self, BusError> {
if patterns.len() > MAX_TOPIC_PATTERNS {
return Err(BusError::TooManyPatterns(patterns.len()));
}
let mut builder = GlobSetBuilder::new();
for pattern in patterns {
let glob = Glob::new(pattern).map_err(|e| BusError::BadPattern {
pattern: pattern.clone(),
message: e.to_string(),
})?;
builder.add(glob);
}
let set = builder.build().map_err(|e| BusError::BadPattern {
pattern: patterns.join(", "),
message: e.to_string(),
})?;
Ok(Self {
set,
patterns: patterns.to_vec(),
})
}
#[must_use]
pub fn matches(&self, event: &BusEvent) -> bool {
self.set.is_match(&*event.topic())
}
#[must_use]
pub fn wants_logs(&self) -> bool {
["log.out", "log.err"]
.iter()
.any(|topic| self.set.is_match(topic))
}
#[inline]
#[must_use]
pub fn patterns(&self) -> &[String] {
&self.patterns
}
}
#[non_exhaustive]
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum BusError {
BadPattern {
pattern: String,
message: String,
},
TooManyPatterns(usize),
}
impl core::fmt::Display for BusError {
fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
match self {
Self::BadPattern { pattern, message } => {
write!(f, "invalid topic pattern `{pattern}`: {message}")
}
Self::TooManyPatterns(count) => {
write!(
f,
"{count} topic patterns exceeds the limit of {MAX_TOPIC_PATTERNS}"
)
}
}
}
}
impl core::error::Error for BusError {}
enum Forwarded {
Frame(Bytes),
Skip,
Stop,
}
fn step(received: Result<SharedEvent, RecvError>, filter: &TopicFilter) -> Forwarded {
let event = match received {
Ok(event) if filter.matches(&event) => event,
Ok(_) => return Forwarded::Skip,
Err(RecvError::Lagged(count)) => SharedEvent::new(BusEvent::Dropped { count }),
Err(RecvError::Closed) => return Forwarded::Stop,
};
match event.frame() {
Some(bytes) => Forwarded::Frame(bytes.clone()),
None => Forwarded::Skip,
}
}
pub fn spawn_forwarder(bus: &Bus, filter: TopicFilter, out: mpsc::Sender<Bytes>) -> JoinHandle<()> {
spawn_guarded_forwarder(bus, filter, out, || true)
}
pub(crate) fn spawn_guarded_forwarder(
bus: &Bus,
filter: TopicFilter,
out: mpsc::Sender<Bytes>,
still_allowed: impl Fn() -> bool + Send + 'static,
) -> JoinHandle<()> {
let (mut rx, interest) = bus.subscribe_for(&filter);
tokio::spawn(async move {
let _interest = interest;
loop {
match step(rx.recv().await, &filter) {
Forwarded::Frame(bytes) => {
if !still_allowed() || out.send(bytes).await.is_err() {
break; }
}
Forwarded::Skip => {}
Forwarded::Stop => break,
}
}
})
}
#[cfg(test)]
mod tests {
use super::*;
use shep_core::protocol::{BusEvent, ProcessEventKind, ProcessInfo, decode_frame};
use shep_core::status::ProcStatus;
const FORWARD_DEADLINE: core::time::Duration = core::time::Duration::from_secs(1);
async fn next_frame(out: &mut mpsc::Receiver<Bytes>) -> Bytes {
tokio::time::timeout(FORWARD_DEADLINE, out.recv())
.await
.expect("a forwarder must produce a frame rather than stall")
.expect("every subscriber must receive the event")
}
fn filter(patterns: &[&str]) -> TopicFilter {
let owned: Vec<String> = patterns.iter().map(|p| (*p).to_string()).collect();
TopicFilter::new(&owned).unwrap()
}
fn process_event(id: u32, event: ProcessEventKind) -> SharedEvent {
SharedEvent::new(BusEvent::Process {
event,
info: ProcessInfo::builder(id, format!("sheep-{id}"), ProcStatus::Online)
.pid(Some(1000 + id))
.out_file(Some(format!("/logs/sheep-{id}-0-out.log")))
.err_file(Some(format!("/logs/sheep-{id}-0-err.log")))
.build(),
manually: false,
at_ms: 0,
})
}
#[test]
fn globs_match_the_dotted_topic_grammar() {
let processes = filter(&["process.*"]);
assert!(processes.matches(&process_event(0, ProcessEventKind::Exit)));
assert!(!processes.matches(&BusEvent::LogOut {
id: 0,
line: String::new()
}));
let logs = filter(&["log.out", "log.err"]);
assert!(logs.matches(&BusEvent::LogOut {
id: 0,
line: String::new()
}));
assert!(logs.matches(&BusEvent::LogErr {
id: 0,
line: String::new()
}));
assert!(!logs.matches(&BusEvent::DaemonShutdown));
let everything = filter(&["*"]);
assert!(everything.matches(&BusEvent::DaemonShutdown));
assert!(everything.matches(&process_event(1, ProcessEventKind::Start)));
}
#[test]
fn an_empty_topic_list_matches_nothing() {
let none = TopicFilter::new(&[]).unwrap();
assert!(!none.matches(&BusEvent::DaemonShutdown));
assert!(none.patterns().is_empty());
}
#[test]
fn a_bad_pattern_is_a_typed_error_carrying_the_pattern() {
let err = TopicFilter::new(&["process.[".to_string()]).unwrap_err();
assert!(matches!(err, BusError::BadPattern { ref pattern, .. } if pattern == "process.["));
}
#[test]
fn too_many_patterns_are_refused_with_the_count() {
let many: Vec<String> = (0..=MAX_TOPIC_PATTERNS).map(|i| format!("t{i}")).collect();
assert_eq!(
TopicFilter::new(&many).unwrap_err(),
BusError::TooManyPatterns(MAX_TOPIC_PATTERNS + 1)
);
}
#[tokio::test(start_paused = true)]
async fn lag_becomes_a_dropped_notice_that_bypasses_the_filter() {
let (tx, mut rx) = test_bus(4);
for id in 0..10 {
tx.send(process_event(id, ProcessEventKind::Start)).unwrap();
}
let missed = match rx.recv().await {
Err(RecvError::Lagged(n)) => n,
other => panic!("expected a lag after overflowing the ring, got {other:?}"),
};
assert!(missed > 0);
let Forwarded::Frame(bytes) = step(Err(RecvError::Lagged(missed)), &filter(&["process.*"]))
else {
panic!("a lag must always produce a Dropped frame")
};
assert_eq!(
decode_frame::<BusEvent>(&bytes).unwrap(),
BusEvent::Dropped { count: missed }
);
}
#[tokio::test(start_paused = true)]
async fn forwarder_delivers_only_matching_frames_then_closes_with_the_bus() {
let (tx, _rx) = test_bus(16);
let (out_tx, mut out_rx) = tokio::sync::mpsc::channel(16);
let handle = spawn_forwarder(&tx, filter(&["process.*"]), out_tx);
tx.send(process_event(0, ProcessEventKind::Start)).unwrap();
tx.send(
BusEvent::LogOut {
id: 0,
line: "noise".to_string(),
}
.into(),
)
.unwrap();
tx.send(process_event(0, ProcessEventKind::Online)).unwrap();
drop(tx);
handle.await.unwrap();
let first: BusEvent = decode_frame(&out_rx.recv().await.unwrap()).unwrap();
let second: BusEvent = decode_frame(&out_rx.recv().await.unwrap()).unwrap();
assert!(matches!(
first,
BusEvent::Process {
event: ProcessEventKind::Start,
..
}
));
assert!(matches!(
second,
BusEvent::Process {
event: ProcessEventKind::Online,
..
}
));
assert!(
out_rx.recv().await.is_none(),
"forwarder must drop its sender at bus close"
);
}
#[tokio::test(start_paused = true)]
async fn every_subscriber_gets_the_same_frame_from_one_encode() {
let (tx, _keep) = test_bus(16);
let mut outs = Vec::new();
let mut forwarders = Vec::new();
for _ in 0..3 {
let (out_tx, out_rx) = tokio::sync::mpsc::channel(16);
forwarders.push(spawn_forwarder(&tx, filter(&["*"]), out_tx));
outs.push(out_rx);
}
let published = process_event(7, ProcessEventKind::Online);
tx.send(published.clone()).unwrap();
drop(tx);
let mut frames = Vec::new();
for out in &mut outs {
frames.push(next_frame(out).await);
}
for forwarder in forwarders {
forwarder.await.unwrap();
}
let (first, rest) = frames
.split_first()
.expect("three subscribers, three frames");
assert_eq!(
decode_frame::<BusEvent>(first).unwrap(),
published.to_event(),
"sharing the frame must not change what is on the wire"
);
for frame in rest {
assert_eq!(frame, first, "every subscriber must see identical bytes");
assert_eq!(
frame.as_ptr(),
first.as_ptr(),
"identical bytes are not enough: they must be the SAME buffer, \
or the daemon encoded this event once per subscriber"
);
}
}
#[tokio::test(start_paused = true)]
async fn encode_frame_runs_once_per_event_however_many_subscribers() {
const SUBSCRIBERS: usize = 5;
let (tx, _keep) = test_bus(16);
let mut outs = Vec::new();
let mut forwarders = Vec::new();
for _ in 0..SUBSCRIBERS {
let (out_tx, out_rx) = tokio::sync::mpsc::channel(16);
forwarders.push(spawn_forwarder(&tx, filter(&["*"]), out_tx));
outs.push(out_rx);
}
let published = process_event(11, ProcessEventKind::Start);
assert_eq!(
published.encodes(),
0,
"publishing must not encode before a subscriber needs the bytes"
);
tx.send(published.clone()).unwrap();
drop(tx);
let mut frames = Vec::new();
for out in &mut outs {
frames.push(next_frame(out).await);
}
for forwarder in forwarders {
forwarder.await.unwrap();
}
assert_eq!(
published.encodes(),
1,
"{SUBSCRIBERS} subscribers, one encode"
);
assert_eq!(frames.len(), SUBSCRIBERS);
let (first, rest) = frames.split_first().expect("one frame per subscriber");
for frame in rest {
assert_eq!(frame, first, "every subscriber must see identical bytes");
}
}
#[test]
fn shared_event_debug_prints_the_event_and_whether_it_is_encoded() {
let event = SharedEvent::new(BusEvent::LogOut {
id: 3,
line: "hello".to_string(),
});
assert_eq!(
format!("{event:?}"),
r#"SharedEvent { event: LogOut { id: 3, line: "hello" }, encoded: false }"#
);
event.frame().expect("a LogOut encodes");
assert_eq!(
format!("{event:?}"),
r#"SharedEvent { event: LogOut { id: 3, line: "hello" }, encoded: true }"#
);
}
#[tokio::test(start_paused = true)]
async fn forwarder_stops_when_the_subscriber_hangs_up() {
let (tx, _rx) = test_bus(16);
let (out_tx, out_rx) = tokio::sync::mpsc::channel(1);
let handle = spawn_forwarder(&tx, filter(&["*"]), out_tx);
drop(out_rx);
tx.send(BusEvent::DaemonShutdown.into()).unwrap();
handle.await.unwrap(); }
fn log_out(line: &str) -> BusEvent {
BusEvent::LogOut {
id: 1,
line: line.to_string(),
}
}
#[test]
fn wants_logs_agrees_with_the_topics_log_events_carry() {
let out = log_out("x");
let err = BusEvent::LogErr {
id: 1,
line: "x".to_string(),
};
for patterns in [vec!["*"], vec!["log.*"], vec!["log.out", "log.err"]] {
let f = filter(&patterns);
assert!(f.wants_logs(), "{patterns:?} must register log interest");
assert!(f.matches(&out) && f.matches(&err), "{patterns:?}");
}
let f = filter(&["process.*", "channel.*", "daemon.*"]);
assert!(!f.wants_logs(), "no pattern here names a log topic");
assert!(!f.matches(&out) && !f.matches(&err));
}
#[tokio::test(start_paused = true)]
async fn a_log_line_is_not_published_while_no_filter_wants_one() {
let (bus, mut plain) = test_bus(16);
assert_eq!(bus.log_subscribers(), 0);
bus.publish_log(log_out("dropped"));
assert!(
plain.try_recv().is_err(),
"a log line must not reach the ring while no filter wants one"
);
bus.send(BusEvent::DaemonShutdown.into()).unwrap();
assert_eq!(plain.try_recv().unwrap(), BusEvent::DaemonShutdown);
}
#[tokio::test(start_paused = true)]
async fn a_log_subscriber_opens_the_gate_and_closes_it_again() {
let (bus, mut plain) = test_bus(16);
let (out_tx, mut out_rx) = mpsc::channel(16);
let forwarder = spawn_forwarder(&bus, filter(&["log.*"]), out_tx);
assert_eq!(bus.log_subscribers(), 1, "a log.* filter must register");
bus.publish_log(log_out("delivered"));
assert_eq!(
decode_frame::<BusEvent>(&next_frame(&mut out_rx).await).unwrap(),
log_out("delivered")
);
assert_eq!(
plain.try_recv().unwrap(),
log_out("delivered"),
"one open gate publishes to every subscriber, not only the asker"
);
forwarder.abort();
let _ = forwarder.await;
assert_eq!(
bus.log_subscribers(),
0,
"an aborted forwarder must release its interest, not strand it"
);
bus.publish_log(log_out("dropped again"));
assert!(plain.try_recv().is_err());
}
#[test]
fn a_dog_config_event_is_under_the_config_glob_and_no_other() {
let event = BusEvent::DogConfigChanged {
dog: "bark".to_string(),
};
assert!(filter(&["config.*"]).matches(&event));
assert!(filter(&["config.dog.bark"]).matches(&event));
assert!(!filter(&["log.*"]).matches(&event));
assert!(!filter(&["process.*"]).matches(&event));
assert!(!filter(&["config.dog.metrics"]).matches(&event));
}
#[tokio::test(start_paused = true)]
async fn every_moved_dog_is_announced_exactly_once() {
let (bus, mut events) = test_bus(16);
let moved = ["metrics".to_string(), "bark".to_string()];
publish_dog_config_changed(&bus, &moved);
for dog in &moved {
let event = events.try_recv().expect("one event per moved dog");
assert_eq!(event.topic(), format!("config.dog.{dog}"));
}
assert!(
events.try_recv().is_err(),
"a dog announced twice is a dog restarted twice"
);
publish_dog_config_changed(&bus, &[]);
assert!(events.try_recv().is_err());
}
}