Skip to content

armgit / macro

Public Imported from GitHub
0

Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.

seanaye/feat/broadcast fanout (#5062)

Sean Ayecffd8c822373
diff --git a/.github/workspace-dep-closures.json b/.github/workspace-dep-closures.json
index 06e0b5ff58..4492294b28 100644
--- a/.github/workspace-dep-closures.json
+++ b/.github/workspace-dep-closures.json
@@ -533,6 +533,10 @@
"crates/unfurl",
"crates/workspace-hack"
],
+ "broadcast": [
+ "crates/broadcast",
+ "crates/workspace-hack"
+ ],
"cache-core": [
"crates/client/cache-core",
"crates/maybe_send"
diff --git a/Cargo.lock b/Cargo.lock
index b559feb54d..f8cc42a589 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -2159,6 +2159,17 @@ dependencies = [
"workspace-hack",
]
+[[package]]
+name = "broadcast"
+version = "0.1.0"
+dependencies = [
+ "dashmap",
+ "tokio",
+ "tokio-util",
+ "tracing",
+ "workspace-hack",
+]
+
[[package]]
name = "bs58"
version = "0.5.1"
@@ -14406,6 +14417,7 @@ dependencies = [
"futures-core",
"futures-io",
"futures-sink",
+ "futures-util",
"pin-project-lite",
"tokio",
]
diff --git a/Cargo.toml b/Cargo.toml
index c88cfe3fca..084f871484 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -7,6 +7,7 @@ members = [
"crates/ai_usage",
"crates/bot_id",
"crates/bots",
+ "crates/broadcast",
"crates/channel_bots",
"crates/client/cache-core",
"crates/client/cache-idb",
diff --git a/crates/broadcast/Cargo.toml b/crates/broadcast/Cargo.toml
new file mode 100644
index 0000000000..61c5c39599
--- /dev/null
+++ b/crates/broadcast/Cargo.toml
@@ -0,0 +1,15 @@
+[package]
+edition = "2024"
+name = "broadcast"
+publish = false
+version = "0.1.0"
+
+[dependencies]
+dashmap = { workspace = true }
+tokio = { workspace = true }
+tokio-util = { workspace = true, features = ["rt"] }
+tracing = { workspace = true }
+workspace-hack = { version = "0.1", path = "../workspace-hack" }
+
+[dev-dependencies]
+tokio = { workspace = true, features = ["time"] }
diff --git a/crates/broadcast/src/lib.rs b/crates/broadcast/src/lib.rs
new file mode 100644
index 0000000000..d98eec8a29
--- /dev/null
+++ b/crates/broadcast/src/lib.rs
@@ -0,0 +1,199 @@
+//! Instance-local keyed asynchronous fan-out.
+//!
+//! [`BroadcastManager`] maintains one Tokio broadcast channel per active key.
+//! Each subscription is exposed as a bounded MPSC receiver so a slow subscriber
+//! can be disconnected without delaying publishers or other subscribers.
+
+#![deny(missing_docs)]
+
+use dashmap::DashMap;
+use std::{hash::Hash, num::NonZeroUsize, sync::Arc};
+use tokio::task::JoinHandle;
+use tokio_util::task::TaskTracker;
+
+#[cfg(test)]
+mod test;
+
+/// Spawns forwarding tasks used by a [`BroadcastManager`].
+pub trait Spawner {
+ /// Spawns `future` and returns a handle to the resulting task.
+ fn spawn<F>(&self, future: F) -> JoinHandle<F::Output>
+ where
+ F: Future + Send + 'static,
+ F::Output: Send + 'static;
+}
+
+/// A [`Spawner`] that uses the current Tokio runtime without tracking tasks.
+#[derive(Debug, Clone, Copy)]
+pub struct GlobalSpawner;
+
+impl Spawner for GlobalSpawner {
+ fn spawn<F>(&self, future: F) -> JoinHandle<F::Output>
+ where
+ F: Future + Send + 'static,
+ F::Output: Send + 'static,
+ {
+ tokio::spawn(future)
+ }
+}
+
+impl Spawner for TaskTracker {
+ fn spawn<F>(&self, future: F) -> JoinHandle<F::Output>
+ where
+ F: Future + Send + 'static,
+ F::Output: Send + 'static,
+ {
+ TaskTracker::spawn(self, future)
+ }
+}
+
+/// Publishes values to subscribers grouped by a key.
+///
+/// A separate Tokio broadcast channel is created for each active key. The
+/// channel is removed as soon as its last forwarding task exits, so keys do not
+/// accumulate after their subscribers disconnect.
+pub struct BroadcastManager<T, K, V> {
+ spawner: T,
+ broadcast_buffer: NonZeroUsize,
+ channels: Arc<DashMap<K, tokio::sync::broadcast::Sender<V>>>,
+}
+
+#[derive(Debug)]
+enum ExitReason {
+ ReceiverClosed,
+ SenderClosed,
+ SlowConsumer,
+ Lagging { skipped: u64 },
+}
+
+/// An error returned when a value has no active subscribers.
+#[derive(Debug)]
+pub struct NoSubscribers<V>(
+ /// The inner value which failed to send
+ pub V,
+);
+
+impl<K, V, T> BroadcastManager<T, K, V>
+where
+ K: Hash + Eq + Clone + Send + Sync + 'static,
+ V: Clone + Send + 'static,
+ T: Spawner,
+{
+ /// Creates a manager with the given per-key broadcast buffer capacity.
+ pub fn new(spawner: T, broadcast_buffer: NonZeroUsize) -> Self {
+ Self {
+ spawner,
+ broadcast_buffer,
+ channels: Arc::new(DashMap::new()),
+ }
+ }
+
+ /// Subscribes to values published for `key`.
+ ///
+ /// `subscriber_buffer` controls the capacity of the returned MPSC
+ /// receiver. If that buffer fills, the forwarding task treats the
+ /// subscriber as a slow consumer, disconnects it, and closes the receiver
+ /// after its buffered values have been drained.
+ #[must_use]
+ pub fn subscribe(
+ &self,
+ key: K,
+ subscriber_buffer: NonZeroUsize,
+ ) -> tokio::sync::mpsc::Receiver<V> {
+ let (subscriber_tx, subscriber_rx) = tokio::sync::mpsc::channel(subscriber_buffer.get());
+
+ let entry = self
+ .channels
+ .entry(key.clone())
+ .or_insert_with(|| tokio::sync::broadcast::Sender::new(self.broadcast_buffer.get()));
+ let mut broadcast_rx = entry.subscribe();
+ drop(entry);
+
+ let channels = Arc::downgrade(&self.channels);
+ let _join_handle = self.spawner.spawn(async move {
+ let reason = loop {
+ tokio::select! {
+ () = subscriber_tx.closed() => {
+ break ExitReason::ReceiverClosed;
+ }
+ message = broadcast_rx.recv() => {
+ match message {
+ Ok(value) => match subscriber_tx.try_send(value) {
+ Ok(()) => {}
+ Err(tokio::sync::mpsc::error::TrySendError::Full(_)) => {
+ break ExitReason::SlowConsumer;
+ }
+ Err(tokio::sync::mpsc::error::TrySendError::Closed(_)) => {
+ break ExitReason::ReceiverClosed;
+ }
+ },
+ Err(tokio::sync::broadcast::error::RecvError::Lagged(skipped)) => {
+ break ExitReason::Lagging { skipped };
+ }
+ Err(tokio::sync::broadcast::error::RecvError::Closed) => {
+ break ExitReason::SenderClosed;
+ }
+ }
+ }
+ }
+ };
+
+ drop(broadcast_rx);
+ if let Some(channels) = channels.upgrade() {
+ channels.remove_if(&key, |_key, sender| sender.receiver_count() == 0);
+ }
+
+ match reason {
+ ExitReason::Lagging { skipped } => {
+ tracing::debug!(
+ skipped,
+ "broadcast subscriber task exited because it lagged"
+ );
+ }
+ reason => {
+ tracing::debug!(?reason, "broadcast subscriber task exited");
+ }
+ }
+ });
+
+ subscriber_rx
+ }
+
+ /// Publishes `value` to every active subscriber for `key`.
+ ///
+ /// The returned count is the number of subscribers present when the value
+ /// was published. It does not guarantee that every subscriber processes the
+ /// value; slow subscribers can subsequently be disconnected.
+ pub fn publish(&self, key: &K, value: V) -> Result<usize, NoSubscribers<V>> {
+ let Some(sender) = self.channels.get(key) else {
+ return Err(NoSubscribers(value));
+ };
+
+ sender.send(value).map_err(|error| NoSubscribers(error.0))
+ }
+
+ /// Returns the current number of subscribers for `key`.
+ ///
+ /// The count can briefly include a subscriber whose returned MPSC receiver
+ /// was just dropped but whose forwarding task has not yet observed closure.
+ pub fn subscriber_count(&self, key: &K) -> usize {
+ self.channels
+ .get(key)
+ .map_or(0, |sender| sender.receiver_count())
+ }
+}
+
+impl<K, V> BroadcastManager<TaskTracker, K, V> {
+ /// Closes every keyed channel and waits for all forwarding tasks to exit.
+ ///
+ /// The task tracker supplied to this manager should not also track unrelated
+ /// tasks because shutdown closes and waits for the entire tracker.
+ pub async fn shutdown(self) {
+ let Self {
+ channels, spawner, ..
+ } = self;
+ drop(channels);
+ spawner.close();
+ spawner.wait().await;
+ }
+}
diff --git a/crates/broadcast/src/test.rs b/crates/broadcast/src/test.rs
new file mode 100644
index 0000000000..6872c430c0
--- /dev/null
+++ b/crates/broadcast/src/test.rs
@@ -0,0 +1,114 @@
+use std::{num::NonZeroUsize, time::Duration};
+
+use tokio::time::timeout;
+use tokio_util::task::TaskTracker;
+
+use super::*;
+
+fn capacity(value: usize) -> NonZeroUsize {
+ NonZeroUsize::new(value).expect("test capacities are non-zero")
+}
+
+async fn wait_until(mut predicate: impl FnMut() -> bool) {
+ timeout(Duration::from_secs(1), async {
+ while !predicate() {
+ tokio::task::yield_now().await;
+ }
+ })
+ .await
+ .expect("condition should become true before timeout");
+}
+
+#[tokio::test]
+async fn publishes_only_to_the_requested_key() {
+ let manager = BroadcastManager::new(TaskTracker::new(), capacity(8));
+ let mut first = manager.subscribe("first", capacity(2));
+ let mut second = manager.subscribe("second", capacity(2));
+
+ assert_eq!(manager.publish(&"first", 42).unwrap(), 1);
+ assert_eq!(first.recv().await, Some(42));
+ assert_eq!(
+ second.try_recv(),
+ Err(tokio::sync::mpsc::error::TryRecvError::Empty)
+ );
+
+ drop(first);
+ drop(second);
+ manager.shutdown().await;
+}
+
+#[tokio::test]
+async fn publishes_to_every_subscriber_for_a_key() {
+ let manager = BroadcastManager::new(TaskTracker::new(), capacity(8));
+ let mut first = manager.subscribe("user", capacity(2));
+ let mut second = manager.subscribe("user", capacity(2));
+
+ assert_eq!(manager.publish(&"user", 42).unwrap(), 2);
+ assert_eq!(first.recv().await, Some(42));
+ assert_eq!(second.recv().await, Some(42));
+
+ drop(first);
+ drop(second);
+ manager.shutdown().await;
+}
+
+#[tokio::test]
+async fn returns_the_unpublished_value_when_there_are_no_subscribers() {
+ let manager = BroadcastManager::new(TaskTracker::new(), capacity(8));
+
+ assert_eq!(
+ manager
+ .publish(&"missing", String::from("message"))
+ .unwrap_err()
+ .0,
+ String::from("message")
+ );
+
+ manager.shutdown().await;
+}
+
+#[tokio::test]
+async fn removes_a_key_after_its_last_receiver_closes() {
+ let manager = BroadcastManager::<_, &str, usize>::new(TaskTracker::new(), capacity(8));
+ let receiver = manager.subscribe("user", capacity(2));
+
+ assert!(manager.subscriber_count(&"user") > 0);
+ assert_eq!(manager.subscriber_count(&"user"), 1);
+
+ drop(receiver);
+ wait_until(|| manager.subscriber_count(&"user") == 0).await;
+ wait_until(|| manager.channels.is_empty()).await;
+
+ assert_eq!(manager.publish(&"user", 42).unwrap_err().0, 42);
+
+ manager.shutdown().await;
+}
+
+#[tokio::test]
+async fn disconnects_a_subscriber_when_its_buffer_is_full() {
+ let manager = BroadcastManager::new(TaskTracker::new(), capacity(8));
+ let mut receiver = manager.subscribe("user", capacity(1));
+
+ assert_eq!(manager.publish(&"user", 1).unwrap(), 1);
+ wait_until(|| receiver.len() == 1).await;
+
+ assert_eq!(manager.publish(&"user", 2).unwrap(), 1);
+ wait_until(|| manager.subscriber_count(&"user") == 0).await;
+
+ assert_eq!(receiver.recv().await, Some(1));
+ assert_eq!(receiver.recv().await, None);
+
+ manager.shutdown().await;
+}
+
+#[tokio::test]
+async fn shutdown_closes_active_subscriptions_without_waiting_for_receivers() {
+ let manager = BroadcastManager::<_, &str, usize>::new(TaskTracker::new(), capacity(8));
+ let mut receiver = manager.subscribe("user", capacity(1));
+
+ timeout(Duration::from_secs(1), manager.shutdown())
+ .await
+ .expect("shutdown should not wait for the subscriber receiver");
+
+ assert_eq!(receiver.recv().await, None);
+}
diff --git a/crates/workspace-hack/Cargo.toml b/crates/workspace-hack/Cargo.toml
index 2fefd52da4..92ae1d72a7 100644
--- a/crates/workspace-hack/Cargo.toml
+++ b/crates/workspace-hack/Cargo.toml
@@ -124,7 +124,7 @@ time = { version = "0.3", features = ["formatting", "macros", "parsing"] }
tokio = { version = "1", features = ["fs", "io-util", "macros", "net", "parking_lot", "process", "rt-multi-thread", "signal", "test-util"] }
tokio-rustls = { version = "0.26", default-features = false, features = ["logging", "tls12"] }
tokio-stream = { version = "0.1", features = ["fs"] }
-tokio-util = { version = "0.7", features = ["codec", "compat", "io"] }
+tokio-util = { version = "0.7", features = ["codec", "compat", "io", "rt"] }
tower = { version = "0.5", default-features = false, features = ["balance", "buffer", "limit", "load-shed", "log"] }
tower-http = { version = "0.6", features = ["compression-gzip", "cors", "fs", "limit", "request-id", "timeout", "trace", "util"] }
tracing = { version = "0.1", features = ["log"] }
@@ -253,7 +253,7 @@ time = { version = "0.3", features = ["formatting", "macros", "parsing"] }
tokio = { version = "1", features = ["fs", "io-util", "macros", "net", "parking_lot", "process", "rt-multi-thread", "signal", "test-util"] }
tokio-rustls = { version = "0.26", default-features = false, features = ["logging", "tls12"] }
tokio-stream = { version = "0.1", features = ["fs"] }
-tokio-util = { version = "0.7", features = ["codec", "compat", "io"] }
+tokio-util = { version = "0.7", features = ["codec", "compat", "io", "rt"] }
tower = { version = "0.5", default-features = false, features = ["balance", "buffer", "limit", "load-shed", "log"] }
tower-http = { version = "0.6", features = ["compression-gzip", "cors", "fs", "limit", "request-id", "timeout", "trace", "util"] }
tracing = { version = "0.1", features = ["log"] }