Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.
TypeScript agentaiai-agentsall-in-onecrmcrm-systememaillinearmcpmessagingnotesnotionofficerustslackslack-alternativestartupstartup-toolstypescriptworkspace
seanaye/feat/broadcast fanout (#5062)
Sean Ayecffd8c822373
diff --git a/.github/workspace-dep-closures.json b/.github/workspace-dep-closures.jsonindex 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.lockindex 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.tomlindex 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.tomlnew file mode 100644index 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.rsnew file mode 100644index 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.rsnew file mode 100644index 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.tomlindex 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"] }