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
//! Realtime distribution of recorded activities to user-scoped subscribers.
//!
//! Mirrors the WebSocket notification consumer: an independent (ungrouped)
//! topic consumer feeds a per-user broadcast, and each event is routed to
//! its addressed recipient only — recipients were resolved at publish time
//! (the acting subject plus the touched entities' current accessors), so no
//! access expansion happens here.
#[cfg(test)]
mod test;
use std::{num::NonZeroUsize, sync::Arc, time::Duration};
use broadcast::{BroadcastManager, GlobalSpawner};
use macro_user_id::cowlike::CowLike as _;
use macro_user_id::user_id::MacroUserIdStr;
use rootcause::prelude::{Report, ResultExt as _};
use tokio_retry::{Retry, strategy::ExponentialBackoff};
use super::events::ActivityTopicEvent;
use super::models::ActivityRecord;
/// Number of messages retained by each user-keyed broadcast channel.
const BROADCAST_BUFFER_CAPACITY: NonZeroUsize = NonZeroUsize::new(64).unwrap();
/// Number of messages buffered for each individual subscriber.
const SUBSCRIBER_BUFFER_CAPACITY: NonZeroUsize = NonZeroUsize::new(16).unwrap();
/// Total receive attempts before the consumer returns for supervision.
const MAX_RECEIVE_ATTEMPTS: usize = 5;
/// Retries after one, two, four, and eight seconds.
fn receive_retry_strategy() -> impl Iterator<Item = Duration> {
ExponentialBackoff::from_millis(2)
.factor(500)
.take(MAX_RECEIVE_ATTEMPTS - 1)
}
/// One realtime activity update delivered to a subscriber.
#[derive(Debug, Clone)]
pub enum ActivitySubscriptionUpdate {
/// An activity row was durably recorded.
Updated(Arc<ActivityRecord>),
/// Refresh mounted activity queries through authorized reads.
Invalidated,
}
/// Why an activity subscription ended after its messages were drained.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum ActivitySubscriptionExit {
/// The subscription closed normally.
Closed,
/// The subscriber's bounded buffer filled.
SlowConsumer,
/// The subscriber fell behind the shared broadcast buffer.
Lagging {
/// Number of messages skipped by the broadcast receiver.
skipped: u64,
},
}
/// An activity update receiver with independently observable completion.
pub struct ActivitySubscription {
receiver: tokio::sync::mpsc::Receiver<ActivitySubscriptionUpdate>,
exit_reason: tokio::sync::oneshot::Receiver<ActivitySubscriptionExit>,
invalidations: Option<tokio::sync::watch::Receiver<()>>,
}
impl ActivitySubscription {
/// Creates a subscription from its message and exit-reason receivers.
pub fn from_parts(
receiver: tokio::sync::mpsc::Receiver<ActivitySubscriptionUpdate>,
exit_reason: tokio::sync::oneshot::Receiver<ActivitySubscriptionExit>,
) -> Self {
Self {
receiver,
exit_reason,
invalidations: None,
}
}
/// Receives the next buffered update.
pub async fn recv(&mut self) -> Option<ActivitySubscriptionUpdate> {
loop {
let Some(invalidations) = &mut self.invalidations else {
return self.receiver.recv().await;
};
tokio::select! {
update = self.receiver.recv() => return update,
changed = invalidations.changed() => {
if changed.is_ok() { return Some(ActivitySubscriptionUpdate::Invalidated); }
self.invalidations = None;
}
}
}
}
/// Returns why the forwarding task stopped, after messages are drained.
pub async fn exit_reason(self) -> ActivitySubscriptionExit {
self.exit_reason
.await
.unwrap_or(ActivitySubscriptionExit::Closed)
}
}
/// Provides user-scoped subscriptions to realtime activity updates.
pub trait ActivitySubscriptionService: Send + Sync + 'static {
/// Subscribes to activity updates addressed to `user_id`.
fn subscribe(&self, user_id: MacroUserIdStr<'static>) -> ActivitySubscription;
}
impl<S: ActivitySubscriptionService> ActivitySubscriptionService for Arc<S> {
fn subscribe(&self, user_id: MacroUserIdStr<'static>) -> ActivitySubscription {
self.as_ref().subscribe(user_id)
}
}
/// No-op activity subscription service for schema-only consumers.
#[derive(Clone, Copy, Debug, Default)]
pub struct NoOpActivitySubscriptionService;
impl ActivitySubscriptionService for NoOpActivitySubscriptionService {
fn subscribe(&self, _user_id: MacroUserIdStr<'static>) -> ActivitySubscription {
let (_sender, receiver) = tokio::sync::mpsc::channel(1);
let (exit_reason_sender, exit_reason) = tokio::sync::oneshot::channel();
let _ = exit_reason_sender.send(ActivitySubscriptionExit::Closed);
ActivitySubscription::from_parts(receiver, exit_reason)
}
}
/// Receives events from the activity topic.
pub trait ActivityTopicEventConsumer: Send + Sync + 'static {
/// Waits for and returns the next activity topic event.
fn recv(&self) -> impl Future<Output = Result<ActivityTopicEvent, Report>> + Send;
}
/// Service distributing received activity rows to user-scoped subscribers.
pub struct ActivityRealtimeConsumerService<C> {
consumer: C,
invalidations: tokio::sync::watch::Sender<()>,
broadcasts:
BroadcastManager<GlobalSpawner, MacroUserIdStr<'static>, ActivitySubscriptionUpdate>,
}
impl<C: ActivityTopicEventConsumer> ActivityRealtimeConsumerService<C> {
/// Creates an activity realtime consumer service backed by `consumer`.
pub fn new(consumer: C) -> Self {
Self {
consumer,
invalidations: tokio::sync::watch::channel(()).0,
broadcasts: BroadcastManager::new(GlobalSpawner, BROADCAST_BUFFER_CAPACITY),
}
}
/// Subscribes to activity updates addressed to `user_id`.
///
/// The returned subscription reports if its buffer fills, so a slow
/// subscriber cannot delay the shared consumer or other subscribers.
#[must_use]
pub fn subscribe(&self, user_id: MacroUserIdStr<'static>) -> ActivitySubscription {
let (receiver, broadcast_exit_reason) = self
.broadcasts
.subscribe(user_id, SUBSCRIBER_BUFFER_CAPACITY)
.into_parts();
let (exit_reason_sender, exit_reason) = tokio::sync::oneshot::channel();
tokio::spawn(async move {
let reason = match broadcast_exit_reason.await {
Ok(broadcast::ExitReason::SlowConsumer) => ActivitySubscriptionExit::SlowConsumer,
Ok(broadcast::ExitReason::Lagging { skipped }) => {
ActivitySubscriptionExit::Lagging { skipped }
}
Ok(broadcast::ExitReason::ReceiverClosed | broadcast::ExitReason::SenderClosed)
| Err(_) => ActivitySubscriptionExit::Closed,
};
let _ = exit_reason_sender.send(reason);
});
let mut subscription = ActivitySubscription::from_parts(receiver, exit_reason);
subscription.invalidations = Some(self.invalidations.subscribe());
subscription
}
/// Receives topic events and distributes updates until reception fails.
///
/// Callers should run this future in a supervised task. Updates for
/// users without active subscribers are intentionally dropped, as are
/// events addressed to non-user principals (nothing can subscribe as a
/// bot). Rows keep whatever subject they carry — entity watchers receive
/// other principals' rows, bot subjects included.
#[tracing::instrument(skip(self), err)]
pub async fn run(&self) -> Result<(), Report> {
loop {
let event = Retry::start(receive_retry_strategy(), || self.consumer.recv())
.await
.context(format!(
"failed to receive activity topic event after {MAX_RECEIVE_ATTEMPTS} attempts"
))?;
let ActivityTopicEvent::Recorded {
recipient_id,
activities,
} = event
else {
self.invalidations.send_replace(());
continue;
};
let Ok(recipient) = MacroUserIdStr::parse_from_str(&recipient_id) else {
continue;
};
let recipient = recipient.into_owned();
// A single large source event must not overflow healthy subscribers.
// One invalidation recovers the whole batch with authorized reads.
if activities.len() > SUBSCRIBER_BUFFER_CAPACITY.get() {
let _ = self
.broadcasts
.publish(&recipient, ActivitySubscriptionUpdate::Invalidated);
continue;
}
for record in activities.into_iter().filter_map(|row| row.into_record()) {
let _ = self.broadcasts.publish(
&recipient,
ActivitySubscriptionUpdate::Updated(Arc::new(record)),
);
}
}
}
}
impl<C: ActivityTopicEventConsumer> ActivitySubscriptionService
for ActivityRealtimeConsumerService<C>
{
fn subscribe(&self, user_id: MacroUserIdStr<'static>) -> ActivitySubscription {
ActivityRealtimeConsumerService::subscribe(self, user_id)
}
}