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.

feat(activity): realtime activityUpdates subscription (#5674)

teoe5f9dfb15ae0
diff --git a/.github/kafka-cluster-topics.json b/.github/kafka-cluster-topics.json
index 33e3f3f489..2b8e5c214b 100644
--- a/.github/kafka-cluster-topics.json
+++ b/.github/kafka-cluster-topics.json
@@ -1,4 +1,5 @@
[
+ "macro.activity",
"macro.agent_session_lifecycle",
"macro.agent_sessions",
"macro.bots",
diff --git a/.github/workspace-dep-closures.json b/.github/workspace-dep-closures.json
index 57ea0f4401..b158881030 100644
--- a/.github/workspace-dep-closures.json
+++ b/.github/workspace-dep-closures.json
@@ -5,6 +5,7 @@
"crates/activity",
"crates/ai_toolset",
"crates/bot_id",
+ "crates/broadcast",
"crates/channel_sender",
"crates/cowlike",
"crates/genai_telemetry",
@@ -2025,6 +2026,7 @@
"crates/attachment",
"crates/bot_id",
"crates/bot_token",
+ "crates/broadcast",
"crates/channel_sender",
"crates/chat",
"crates/cowlike",
@@ -4776,6 +4778,7 @@
"crates/ai_toolset",
"crates/bot_id",
"crates/bot_token",
+ "crates/broadcast",
"crates/channel_sender",
"crates/cowlike",
"crates/document_sub_type",
diff --git a/Cargo.lock b/Cargo.lock
index 6683862132..3f26ebd95f 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -14,12 +14,16 @@ version = "0.1.0"
dependencies = [
"ai_toolset",
"async-trait",
+ "bot_id",
+ "broadcast",
"channel_sender",
"chrono",
"chrono-tz",
+ "futures",
"kafka_util",
"macro_db_migrator",
"macro_event_broker",
+ "macro_event_topics",
"macro_user_id",
"model-entity",
"rdkafka",
@@ -31,6 +35,8 @@ dependencies = [
"sqlx",
"strum 0.27.2",
"tokio",
+ "tokio-retry",
+ "tokio-util",
"tracing",
"uuid",
"workspace-hack",
@@ -7486,6 +7492,7 @@ version = "0.1.0"
dependencies = [
"activity",
"async-graphql",
+ "async-stream",
"chrono",
"chrono-tz",
"futures",
@@ -7496,6 +7503,7 @@ dependencies = [
"serde",
"serde_json",
"tokio",
+ "tokio-stream",
"tracing",
"uuid",
"workspace-hack",
diff --git a/crates/activity/Cargo.toml b/crates/activity/Cargo.toml
index a8685bed64..0b28d1d41e 100644
--- a/crates/activity/Cargo.toml
+++ b/crates/activity/Cargo.toml
@@ -8,24 +8,35 @@ version = "0.1.0"
ai_tools = ["dep:ai_toolset", "dep:async-trait", "dep:schemars", "dep:tracing"]
consumer = [
"dep:kafka_util",
- "dep:macro_event_broker",
+ "dep:futures",
+ "dep:tokio-util",
"dep:rdkafka",
"dep:rootcause",
"dep:tokio",
"dep:tracing",
"macro_event_broker/outbound",
]
-default = ["consumer", "outbound"]
+default = ["consumer", "outbound", "realtime"]
outbound = ["dep:sqlx", "dep:tracing"]
+realtime = [
+ "dep:broadcast",
+ "dep:rootcause",
+ "dep:tokio",
+ "dep:tokio-retry",
+ "dep:tracing",
+]
[dependencies]
ai_toolset = { path = "../ai_toolset", optional = true }
async-trait = { workspace = true, optional = true }
+broadcast = { path = "../broadcast", optional = true }
channel_sender = { path = "../channel_sender" }
chrono = { workspace = true }
chrono-tz = { workspace = true }
+futures = { workspace = true, optional = true }
kafka_util = { path = "../kafka_util", optional = true }
-macro_event_broker = { path = "../macro_event_broker", default-features = false, optional = true }
+macro_event_broker = { path = "../macro_event_broker", default-features = false }
+macro_event_topics = { path = "../macro_event_topics" }
macro_user_id = { path = "../macro_user_id" }
model-entity = { path = "../model-entity" }
rdkafka = { workspace = true, optional = true }
@@ -37,10 +48,13 @@ serde_json = { workspace = true }
sqlx = { workspace = true, features = ["json"], optional = true }
strum = { workspace = true }
tokio = { workspace = true, features = ["sync", "time"], optional = true }
+tokio-util = { workspace = true, features = ["rt"], optional = true }
+tokio-retry = { workspace = true, optional = true }
tracing = { workspace = true, optional = true }
uuid = { workspace = true }
workspace-hack = { version = "0.1", path = "../workspace-hack" }
[dev-dependencies]
+bot_id = { path = "../bot_id" }
macro_db_migrator = { path = "../macro_db_migrator" }
tokio = { workspace = true, features = ["macros", "rt-multi-thread", "test-util"] }
diff --git a/crates/activity/src/domain/announcements.rs b/crates/activity/src/domain/announcements.rs
new file mode 100644
index 0000000000..a0fd38d299
--- /dev/null
+++ b/crates/activity/src/domain/announcements.rs
@@ -0,0 +1,123 @@
+//! Recipient policy and bounded best-effort activity delivery.
+
+#[cfg(test)]
+mod test;
+
+use futures::{StreamExt as _, stream};
+use macro_user_id::user_id::MacroUserIdStr;
+use model_entity::EntityType;
+use std::{
+ collections::{BTreeSet, HashMap},
+ time::Duration,
+};
+
+use super::{
+ events::{ActivityTopicEvent, ActivityWireRow},
+ models::Activity,
+ ports::{ActivityAudienceExpander, ActivityEventPublisher, ActivityRealtimePublisher},
+};
+
+/// Realtime must not hold up materialization while a broker or audience lookup
+/// is unavailable. Clients refetch on reconnect to recover missed delivery.
+const ANNOUNCEMENT_BUDGET: Duration = Duration::from_secs(5);
+const MAX_CONCURRENT_DELIVERIES: usize = 16;
+
+/// Expands entity audiences, deduplicates recipients, and announces committed rows.
+pub struct ActivityAnnouncements<P, A> {
+ publisher: P,
+ audience: A,
+}
+
+impl<P: ActivityEventPublisher, A: ActivityAudienceExpander> ActivityAnnouncements<P, A> {
+ /// Creates an announcer over transport and current-access ports.
+ pub fn new(publisher: P, audience: A) -> Self {
+ Self {
+ publisher,
+ audience,
+ }
+ }
+
+ async fn recipients(&self, rows: &[(EntityType, &str, &str)]) -> Vec<BTreeSet<String>> {
+ let mut audiences = HashMap::new();
+ let mut recipients = Vec::with_capacity(rows.len());
+ for &(kind, id, subject) in rows {
+ if let std::collections::hash_map::Entry::Vacant(entry) = audiences.entry((kind, id)) {
+ let users = match self.audience.entity_audience(kind, id).await {
+ Ok(users) => users,
+ Err(error) => {
+ tracing::warn!(?error, entity_type = ?kind, entity_id = id, "activity audience lookup failed");
+ Vec::new()
+ }
+ };
+ entry.insert(users);
+ }
+ let mut row_recipients: BTreeSet<String> = audiences[&(kind, id)]
+ .iter()
+ .map(|user| user.as_ref().to_owned())
+ .collect();
+ // A subject can read their own feed even after losing entity access.
+ // Bot principals cannot open a user subscription.
+ if MacroUserIdStr::parse_from_str(subject).is_ok() {
+ row_recipients.insert(subject.to_owned());
+ }
+ recipients.push(row_recipients);
+ }
+ recipients
+ }
+
+ async fn deliver(&self, events: Vec<ActivityTopicEvent>) {
+ stream::iter(events)
+ .for_each_concurrent(MAX_CONCURRENT_DELIVERIES, |event| async move {
+ if let Err(error) = self.publisher.publish(event).await {
+ tracing::warn!(?error, "activity announcement failed");
+ }
+ })
+ .await;
+ }
+
+ async fn bounded(&self, delivery: impl Future<Output = ()>) {
+ if tokio::time::timeout(ANNOUNCEMENT_BUDGET, delivery)
+ .await
+ .is_err()
+ {
+ tracing::warn!("activity announcement exceeded delivery budget");
+ }
+ }
+}
+
+impl<P: ActivityEventPublisher, A: ActivityAudienceExpander> ActivityRealtimePublisher
+ for ActivityAnnouncements<P, A>
+{
+ async fn publish_recorded(&self, activities: &[Activity]) {
+ self.bounded(async {
+ let keys: Vec<_> = activities
+ .iter()
+ .map(|a| (a.entity_type, a.entity_id.as_str(), a.subject_id.as_str()))
+ .collect();
+ let recipients = self.recipients(&keys).await;
+ let mut deliveries: HashMap<String, Vec<ActivityWireRow>> = HashMap::new();
+ for (activity, users) in activities.iter().zip(recipients) {
+ let row = ActivityWireRow::from_activity(activity);
+ for user in users {
+ deliveries.entry(user).or_default().push(row.clone());
+ }
+ }
+ self.deliver(
+ deliveries
+ .into_iter()
+ .map(|(recipient_id, activities)| ActivityTopicEvent::Recorded {
+ recipient_id,
+ activities,
+ })
+ .collect(),
+ )
+ .await;
+ })
+ .await;
+ }
+
+ async fn publish_invalidated(&self) {
+ self.bounded(self.deliver(vec![ActivityTopicEvent::Invalidated]))
+ .await;
+ }
+}
diff --git a/crates/activity/src/domain/announcements/test.rs b/crates/activity/src/domain/announcements/test.rs
new file mode 100644
index 0000000000..b1d3624d49
--- /dev/null
+++ b/crates/activity/src/domain/announcements/test.rs
@@ -0,0 +1,215 @@
+use std::collections::HashMap;
+use std::sync::{Arc, Mutex};
+
+use chrono::Utc;
+
+use uuid::Uuid;
+
+use super::*;
+use crate::domain::events::ActivityTopicEvent;
+use crate::domain::models::{Actor, CommonAction};
+
+#[derive(Clone, Default)]
+struct RecordingPublisher {
+ published: Arc<Mutex<Vec<(String, ActivityTopicEvent)>>>,
+}
+impl RecordingPublisher {
+ fn recorded_events(&self) -> Vec<(String, ActivityTopicEvent)> {
+ self.published.lock().unwrap().clone()
+ }
+}
+impl ActivityEventPublisher for RecordingPublisher {
+ type Err = std::io::Error;
+ async fn publish(&self, event: ActivityTopicEvent) -> Result<(), Self::Err> {
+ self.published
+ .lock()
+ .unwrap()
+ .push((event.key().to_owned(), event));
+ Ok(())
+ }
+}
+
+struct FakeAudience {
+ by_entity: HashMap<String, Vec<MacroUserIdStr<'static>>>,
+}
+
+impl ActivityAudienceExpander for FakeAudience {
+ type Err = std::convert::Infallible;
+
+ async fn entity_audience(
+ &self,
+ _entity_type: EntityType,
+ entity_id: &str,
+ ) -> Result<Vec<MacroUserIdStr<'static>>, Self::Err> {
+ Ok(self.by_entity.get(entity_id).cloned().unwrap_or_default())
+ }
+}
+
+struct FailingAudience;
+
+impl ActivityAudienceExpander for FailingAudience {
+ type Err = std::io::Error;
+
+ async fn entity_audience(
+ &self,
+ _entity_type: EntityType,
+ _entity_id: &str,
+ ) -> Result<Vec<MacroUserIdStr<'static>>, Self::Err> {
+ Err(std::io::Error::other("access lookup unavailable"))
+ }
+}
+
+fn user(local: &str) -> MacroUserIdStr<'static> {
+ MacroUserIdStr::try_from(format!("macro|{local}@example.com")).expect("valid user id")
+}
+
+fn edited(ordinal: u32, actor: Actor<'static>, entity_id: &str) -> Activity {
+ Activity::common(
+ Uuid::from_u128(7),
+ ordinal,
+ actor,
+ None,
+ EntityType::Document,
+ entity_id,
+ CommonAction::Edited,
+ Utc::now(),
+ )
+}
+
+fn rows_for<'a>(
+ events: &'a [(String, ActivityTopicEvent)],
+ recipient: &str,
+) -> &'a [ActivityWireRow] {
+ events
+ .iter()
+ .find_map(|(key, event)| {
+ let ActivityTopicEvent::Recorded {
+ recipient_id,
+ activities,
+ } = event
+ else {
+ return None;
+ };
+ assert_eq!(recipient_id, key, "events are keyed by their recipient");
+ (recipient_id == recipient).then_some(activities.as_slice())
+ })
+ .unwrap_or_else(|| panic!("no event addressed to {recipient}"))
+}
+
+#[tokio::test]
+async fn delivers_to_the_subject_and_the_entity_audience() {
+ let teo = user("teo");
+ let watcher = user("watcher");
+ let broker = RecordingPublisher::default();
+ let publisher = ActivityAnnouncements::new(
+ broker.clone(),
+ FakeAudience {
+ by_entity: HashMap::from([("doc-1".to_string(), vec![teo.clone(), watcher.clone()])]),
+ },
+ );
+
+ let activities = [
+ edited(0, Actor::new_from_user(teo.clone()), "doc-1"),
+ edited(1, Actor::new_from_user(teo.clone()), "doc-2"),
+ ];
+ publisher.publish_recorded(&activities).await;
+
+ let events = broker.recorded_events();
+ assert_eq!(events.len(), 2, "one event per distinct recipient");
+ // The subject receives both rows (doc-2 has no audience beyond them);
+ // the watcher receives only the row for the entity they can access.
+ assert_eq!(rows_for(&events, teo.as_ref()).len(), 2);
+ let watcher_rows = rows_for(&events, watcher.as_ref());
+ assert_eq!(watcher_rows.len(), 1);
+ assert_eq!(watcher_rows[0].entity_id, "doc-1");
+}
+
+#[tokio::test]
+async fn bot_subject_rows_reach_the_entity_audience_only() {
+ let watcher = user("watcher");
+ let bot = Actor::new_from_bot(bot_id::BotId::new_from_uuid(Uuid::from_u128(42)));
+ let broker = RecordingPublisher::default();
+ let publisher = ActivityAnnouncements::new(
+ broker.clone(),
+ FakeAudience {
+ by_entity: HashMap::from([("doc-1".to_string(), vec![watcher.clone()])]),
+ },
+ );
+
+ publisher.publish_recorded(&[edited(0, bot, "doc-1")]).await;
+
+ let events = broker.recorded_events();
+ assert_eq!(
+ events.len(),
+ 1,
+ "a bot subject is not an addressable recipient"
+ );
+ assert_eq!(rows_for(&events, watcher.as_ref()).len(), 1);
+}
+
+#[tokio::test]
+async fn expansion_failure_degrades_to_subject_only_delivery() {
+ let teo = user("teo");
+ let broker = RecordingPublisher::default();
+ let publisher = ActivityAnnouncements::new(broker.clone(), FailingAudience);
+
+ publisher
+ .publish_recorded(&[edited(0, Actor::new_from_user(teo.clone()), "doc-1")])
+ .await;
+
+ let events = broker.recorded_events();
+ assert_eq!(events.len(), 1);
+ assert_eq!(rows_for(&events, teo.as_ref()).len(), 1);
+}
+
+struct StalledPublisher {
+ started: std::sync::atomic::AtomicUsize,
+}
+
+impl ActivityEventPublisher for StalledPublisher {
+ type Err = std::io::Error;
+ async fn publish(&self, _event: ActivityTopicEvent) -> Result<(), Self::Err> {
+ self.started
+ .fetch_add(1, std::sync::atomic::Ordering::SeqCst);
+ std::future::pending().await
+ }
+}
+
+#[tokio::test(start_paused = true)]
+async fn bounds_total_delivery_latency_and_concurrency_for_a_large_audience() {
+ let publisher = ActivityAnnouncements::new(
+ StalledPublisher { started: 0.into() },
+ FakeAudience {
+ by_entity: HashMap::from([(
+ "doc-1".into(),
+ (0..1000).map(|i| user(&format!("watcher-{i}"))).collect(),
+ )]),
+ },
+ );
+ let before = tokio::time::Instant::now();
+ publisher
+ .publish_recorded(&[edited(0, Actor::new_from_user(user("subject")), "doc-1")])
+ .await;
+ assert_eq!(before.elapsed(), ANNOUNCEMENT_BUDGET);
+ assert_eq!(
+ publisher
+ .publisher
+ .started
+ .load(std::sync::atomic::Ordering::SeqCst),
+ MAX_CONCURRENT_DELIVERIES
+ );
+}
+
+#[tokio::test]
+async fn purge_invalidation_needs_no_deleted_entity_audience() {
+ let publisher = RecordingPublisher::default();
+ let announcements = ActivityAnnouncements::new(publisher.clone(), FailingAudience);
+ announcements.publish_invalidated().await;
+ assert_eq!(
+ publisher.recorded_events(),
+ vec![(
+ "activity-invalidated".into(),
+ ActivityTopicEvent::Invalidated
+ )]
+ );
+}
diff --git a/crates/activity/src/domain/events.rs b/crates/activity/src/domain/events.rs
new file mode 100644
index 0000000000..8ca3d2fb59
--- /dev/null
+++ b/crates/activity/src/domain/events.rs
@@ -0,0 +1,144 @@
+//! Broker event models for realtime activity delivery.
+//!
+//! Published by the materializing consumer after rows are durably inserted,
+//! addressed (and keyed) per recipient so every subscriber pod can route a
+//! message to its own user-scoped broadcast without re-deriving recipients.
+//! Recipients are resolved at publish time: the acting subject plus everyone
+//! with current access to the touched entities. The wire row stores the
+//! action as its two stored columns (tag + payload), so readers decode with
+//! the same forward tolerance as reads from Postgres.
+
+#[cfg(test)]
+mod test;
+
+use chrono::{DateTime, Utc};
+use macro_event_broker::{Event, MacroEvent, TopicEvent};
+use macro_event_topics::MacroActivityTopic;
+use model_entity::EntityType;
+use serde::{Deserialize, Serialize};
+use serde_json::Value;
+use uuid::Uuid;
+
+use super::models::{Activity, ActivityRecord, Actor, RecordedAction};
+
+/// One activity row on the wire — the realtime projection of an inserted
+/// `activity_events` row.
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub struct ActivityWireRow {
+ /// The stored activity id.
+ pub id: Uuid,
+ /// Who mechanically acted, as a principal string (`macro|…` / `bot|…`).
+ pub actor_id: String,
+ /// Whose activity this is (a principal string).
+ pub subject_id: String,
+ /// The kind of entity acted on.
+ pub entity_type: EntityType,
+ /// The entity acted on.
+ pub entity_id: String,
+ /// The stored action tag.
+ pub action: String,
+ /// The stored action payload, if any.
+ pub action_payload: Option<Value>,
+ /// When it happened.
+ pub occurred_at: DateTime<Utc>,
+}
+
+impl ActivityWireRow {
+ /// Projects an activity onto the wire using the stored column encoding.
+ pub fn from_activity(activity: &Activity) -> Self {
+ let (action, action_payload) = activity.action.to_columns();
+ Self {
+ id: activity.id,
+ actor_id: activity.actor.as_ref().to_owned(),
+ subject_id: activity.subject_id.clone(),
+ entity_type: activity.entity_type,
+ entity_id: activity.entity_id.clone(),
+ action: action.to_owned(),
+ action_payload,
+ occurred_at: activity.occurred_at,
+ }
+ }
+
+ /// Decodes into the read-side record, forward-tolerantly for the action.
+ /// Returns `None` when the row is too corrupt to represent (unparseable
+ /// actor) — the same skip semantics as reads from storage.
+ pub fn into_record(self) -> Option<ActivityRecord> {
+ let actor = Actor::try_from(self.actor_id).ok()?;
+ let (action, _decode_error) =
+ RecordedAction::from_columns(self.action, self.action_payload);
+ Some(ActivityRecord {
+ id: self.id,
+ actor,
+ subject_id: self.subject_id,
+ entity_type: self.entity_type,
+ entity_id: self.entity_id,
+ action,
+ occurred_at: self.occurred_at,
+ })
+ }
+}
+
+/// Events published to [`MacroActivityTopic`].
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+#[serde(tag = "event_type", content = "metadata")]
+pub enum ActivityTopicEvent {
+ /// Activities were durably recorded; addressed to one recipient.
+ #[serde(rename = "activity.recorded")]
+ Recorded {
+ /// The user this delivery is addressed to (a `macro|…` principal).
+ /// Not necessarily any row's subject: entity watchers receive other
+ /// principals' rows.
+ recipient_id: String,
+ /// The recorded rows this recipient may see.
+ activities: Vec<ActivityWireRow>,
+ },
+ /// Stored activity changed after a purge. Contains no entity or user data:
+ /// even former viewers must refresh through authorized read paths.
+ #[serde(rename = "activity.invalidated")]
+ Invalidated,
+}
+
+impl ActivityTopicEvent {
+ /// The partition key for addressed updates or global invalidation.
+ pub fn key(&self) -> &str {
+ match self {
+ Self::Recorded { recipient_id, .. } => recipient_id,
+ Self::Invalidated => "activity-invalidated",
+ }
+ }
+}
+
+impl TopicEvent for ActivityTopicEvent {
+ type Topic = MacroActivityTopic;
+
+ const SCHEMA_VERSION: u8 = 1;
+}
+
+/// Publishable realtime activity event, keyed by its recipient.
+pub struct ActivityMacroEvent {
+ key: String,
+ event: Event<ActivityTopicEvent>,
+}
+
+impl ActivityMacroEvent {
+ /// Returns the topic event carried by this event.
+ pub fn into_topic_event(self) -> ActivityTopicEvent {
+ self.event.event
+ }
+}
+
+impl MacroEvent for ActivityMacroEvent {
+ type EventPayload = ActivityTopicEvent;
+
+ fn key(&self) -> &str {
+ &self.key
+ }
+
+ fn event(&self) -> &Event<Self::EventPayload> {
+ &self.event
+ }
+
+ fn from_event(key: String, event: Event<Self::EventPayload>) -> Self {
+ Self { key, event }
+ }
+}
diff --git a/crates/activity/src/domain/events/test.rs b/crates/activity/src/domain/events/test.rs
new file mode 100644
index 0000000000..1c9a7cb324
--- /dev/null
+++ b/crates/activity/src/domain/events/test.rs
@@ -0,0 +1,111 @@
+use chrono::Utc;
+use macro_user_id::user_id::MacroUserIdStr;
+use serde_json::json;
+use uuid::Uuid;
+
+use super::*;
+use crate::domain::models::{Action, CommonAction, PropertyChange};
+
+fn user(id: &str) -> MacroUserIdStr<'static> {
+ MacroUserIdStr::try_from(id.to_string()).expect("valid user id")
+}
+
+fn activity(action: CommonAction) -> Activity {
+ Activity::common(
+ Uuid::from_u128(7),
+ 0,
+ Actor::new_from_user(user("macro|[email protected]")),
+ None,
+ EntityType::Document,
+ "doc-1",
+ action,
+ Utc::now(),
+ )
+}
+
+#[test]
+fn wire_row_round_trips_into_a_record() {
+ let activity = activity(CommonAction::Edited);
+ let row = ActivityWireRow::from_activity(&activity);
+ assert_eq!(row.id, activity.id);
+ assert_eq!(row.subject_id, activity.subject_id);
+ assert_eq!(row.action, "edited");
+ assert_eq!(row.action_payload, None);
+
+ let record = row.into_record().expect("well-formed row decodes");
+ assert_eq!(record.id, activity.id);
+ assert_eq!(record.actor, activity.actor);
+ assert_eq!(record.entity_type, EntityType::Document);
+ assert_eq!(record.action, RecordedAction::Known(Action::Edited));
+}
+
+#[test]
+fn unknown_action_tags_survive_the_wire() {
+ // A row written by a newer deployment: the tag is preserved raw rather
+ // than dropped, mirroring reads from storage.
+ let row = ActivityWireRow {
+ id: Uuid::from_u128(1),
+ actor_id: "macro|[email protected]".to_string(),
+ subject_id: "macro|[email protected]".to_string(),
+ entity_type: EntityType::Document,
+ entity_id: "doc-1".to_string(),
+ action: "transmogrified".to_string(),
+ action_payload: Some(json!({ "thoroughly": true })),
+ occurred_at: Utc::now(),
+ };
+
+ let record = row.into_record().expect("unknown tags still decode");
+ assert_eq!(
+ record.action,
+ RecordedAction::Unknown {
+ tag: "transmogrified".to_string(),
+ payload: Some(json!({ "thoroughly": true })),
+ }
+ );
+}
+
+#[test]
+fn corrupt_actor_rows_are_skipped() {
+ let row = ActivityWireRow {
+ id: Uuid::from_u128(2),
+ actor_id: "not-a-principal".to_string(),
+ subject_id: "macro|[email protected]".to_string(),
+ entity_type: EntityType::Document,
+ entity_id: "doc-1".to_string(),
+ action: "edited".to_string(),
+ action_payload: None,
+ occurred_at: Utc::now(),
+ };
+
+ assert_eq!(row.into_record(), None);
+}
+
+#[test]
+fn payload_actions_carry_their_columns() {
+ let source = Uuid::from_u128(9);
+ let activity = Activity::common(
+ source,
+ 1,
+ Actor::new_from_user(user("macro|[email protected]")),
+ Some(user("macro|[email protected]")),
+ EntityType::Chat,
+ "chat-1",
+ CommonAction::PropertyChanged(PropertyChange {
+ property: "prop-1".to_string(),
+ from: Some(json!("Todo")),
+ to: Some(json!("Done")),
+ }),
+ Utc::now(),
+ );
+
+ let row = ActivityWireRow::from_activity(&activity);
+ assert_eq!(row.subject_id, "macro|[email protected]");
+ assert_eq!(row.action, "property_changed");
+ assert_eq!(
+ row.action_payload,
+ Some(json!({ "property": "prop-1", "from": "Todo", "to": "Done" }))
+ );
+
+ let record = row.into_record().expect("decodes");
+ assert_eq!(record.subject_id, "macro|[email protected]");
+}
diff --git a/crates/activity/src/domain/materializer.rs b/crates/activity/src/domain/materializer.rs
new file mode 100644
index 0000000000..23b0c1b902
--- /dev/null
+++ b/crates/activity/src/domain/materializer.rs
@@ -0,0 +1,41 @@
+//! Durable activity ingestion followed by best-effort realtime announcement.
+
+#[cfg(test)]
+mod test;
+
+use super::{
+ models::Ingest,
+ ports::{ActivityRealtimePublisher, ActivityRepo},
+};
+
+/// Orchestrates storage and realtime side effects for decoded domain activity.
+pub struct ActivityMaterializer<R, P> {
+ repo: R,
+ realtime: P,
+}
+
+impl<R: ActivityRepo, P: ActivityRealtimePublisher> ActivityMaterializer<R, P> {
+ /// Creates the materializer from persistence and announcement ports.
+ pub fn new(repo: R, realtime: P) -> Self {
+ Self { repo, realtime }
+ }
+
+ /// Announces only after a successful durable write. Replayed inserts retain
+ /// deterministic ids; missed best-effort delivery is repaired by a fetch.
+ pub async fn apply(&self, ingest: Ingest) -> Result<(), R::Err> {
+ match ingest {
+ Ingest::Insert(rows) => {
+ self.repo.insert_activities(&rows).await?;
+ self.realtime.publish_recorded(&rows).await;
+ }
+ Ingest::Purge(entities) => {
+ if !entities.is_empty() {
+ self.repo.purge_entities(&entities).await?;
+ self.realtime.publish_invalidated().await;
+ }
+ }
+ Ingest::Ignore => {}
+ }
+ Ok(())
+ }
+}
diff --git a/crates/activity/src/domain/materializer/test.rs b/crates/activity/src/domain/materializer/test.rs
new file mode 100644
index 0000000000..20714d1e02
--- /dev/null
+++ b/crates/activity/src/domain/materializer/test.rs
@@ -0,0 +1,185 @@
+use std::sync::{Arc, Mutex};
+
+use chrono::Utc;
+use macro_user_id::user_id::MacroUserIdStr;
+use uuid::Uuid;
+
+use super::*;
+use crate::domain::ports::ActivityRepo;
+
+use crate::domain::models::{Activity, Actor, CommonAction, EntityType};
+
+/// Records the relative order of storage writes and realtime announcements.
+type CallLog = Arc<Mutex<Vec<&'static str>>>;
+
+struct FakeRepo {
+ log: CallLog,
+ fail: bool,
+}
+
+#[derive(Debug)]
+struct StorageDown;
+
+impl std::fmt::Display for StorageDown {
+ fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+ f.write_str("storage down")
+ }
+}
+
+impl std::error::Error for StorageDown {}
+
+impl ActivityRepo for FakeRepo {
+ type Err = StorageDown;
+
+ async fn insert_activities(&self, _activities: &[Activity]) -> Result<(), Self::Err> {
+ if self.fail {
+ return Err(StorageDown);
+ }
+ self.log.lock().expect("log lock").push("insert");
+ Ok(())
+ }
+
+ async fn purge_entities(&self, _entities: &[(EntityType, String)]) -> Result<(), Self::Err> {
+ if self.fail {
+ return Err(StorageDown);
+ }
+ self.log.lock().expect("log lock").push("purge");
+ Ok(())
+ }
+}
+
+struct FakePublisher {
+ log: CallLog,
+}
+
+impl ActivityRealtimePublisher for FakePublisher {
+ async fn publish_invalidated(&self) {
+ self.log.lock().expect("log lock").push("delete");
+ }
+ async fn publish_recorded(&self, _activities: &[Activity]) {
+ self.log.lock().expect("log lock").push("publish");
+ }
+}
+
+fn activity() -> Activity {
+ Activity::common(
+ Uuid::from_u128(7),
+ 0,
+ Actor::new_from_user(
+ MacroUserIdStr::try_from("macro|[email protected]".to_string()).expect("valid user"),
+ ),
+ None,
+ EntityType::Document,
+ "doc-1",
+ CommonAction::Edited,
+ Utc::now(),
+ )
+}
+
+#[tokio::test]
+async fn announces_only_after_a_successful_insert() {
+ let log: CallLog = Arc::default();
+ let consumer = ActivityMaterializer::new(
+ FakeRepo {
+ log: Arc::clone(&log),
+ fail: false,
+ },
+ FakePublisher {
+ log: Arc::clone(&log),
+ },
+ );
+
+ consumer
+ .apply(Ingest::Insert(vec![activity()]))
+ .await
+ .expect("insert succeeds");
+ assert_eq!(*log.lock().expect("log lock"), vec!["insert", "publish"]);
+}
+
+#[tokio::test]
+async fn does_not_announce_when_the_insert_fails() {
+ let log: CallLog = Arc::default();
+ let consumer = ActivityMaterializer::new(
+ FakeRepo {
+ log: Arc::clone(&log),
+ fail: true,
+ },
+ FakePublisher {
+ log: Arc::clone(&log),
+ },
+ );
+
+ consumer
+ .apply(Ingest::Insert(vec![activity()]))
+ .await
+ .expect_err("storage failure propagates");
+ assert!(log.lock().expect("log lock").is_empty());
+}
+
+#[tokio::test]
+async fn announces_after_purge() {
+ let log: CallLog = Arc::default();
+ let consumer = ActivityMaterializer::new(
+ FakeRepo {
+ log: Arc::clone(&log),
+ fail: false,
+ },
+ FakePublisher {
+ log: Arc::clone(&log),
+ },
+ );
+
+ consumer
+ .apply(Ingest::Purge(vec![(
+ EntityType::Document,
+ "doc-1".to_string(),
+ )]))
+ .await
+ .expect("purge succeeds");
+ assert_eq!(*log.lock().expect("log lock"), vec!["purge", "delete"]);
+}
+
+#[tokio::test]
+async fn replays_resend_purge_invalidation_and_empty_purges_do_nothing() {
+ let log: CallLog = Arc::default();
+ let materializer = ActivityMaterializer::new(
+ FakeRepo {
+ log: log.clone(),
+ fail: false,
+ },
+ FakePublisher { log: log.clone() },
+ );
+ materializer.apply(Ingest::Ignore).await.unwrap();
+ materializer.apply(Ingest::Purge(Vec::new())).await.unwrap();
+ assert!(log.lock().unwrap().is_empty());
+ for _ in 0..2 {
+ materializer
+ .apply(Ingest::Purge(vec![(
+ EntityType::Document,
+ "deleted-doc".into(),
+ )]))
+ .await
+ .unwrap();
+ }
+ assert_eq!(
+ *log.lock().unwrap(),
+ vec!["purge", "delete", "purge", "delete"]
+ );
+}
+
+#[tokio::test]
+async fn failed_purges_do_not_announce() {
+ let log: CallLog = Arc::default();
+ let materializer = ActivityMaterializer::new(
+ FakeRepo {
+ log: log.clone(),
+ fail: true,
+ },
+ FakePublisher { log: log.clone() },
+ );
+ materializer
+ .apply(Ingest::Purge(vec![(EntityType::Document, "doc-1".into())]))
+ .await
+ .expect_err("storage failure");
+ assert!(log.lock().unwrap().is_empty());
+}
diff --git a/crates/activity/src/domain/mod.rs b/crates/activity/src/domain/mod.rs
index ea00c93496..168c47d2e0 100644
--- a/crates/activity/src/domain/mod.rs
+++ b/crates/activity/src/domain/mod.rs
@@ -1,7 +1,16 @@
-//! Domain layer: the activity model and the storage port.
+//! Domain layer: the activity model, storage and realtime ports, and the
+//! realtime distribution service.
+pub mod events;
pub mod models;
pub mod overview;
pub mod ports;
+#[cfg(feature = "realtime")]
+pub mod realtime;
#[cfg(feature = "ai_tools")]
pub mod service;
+
+#[cfg(feature = "consumer")]
+pub mod announcements;
+#[cfg(feature = "consumer")]
+pub mod materializer;
diff --git a/crates/activity/src/domain/ports.rs b/crates/activity/src/domain/ports.rs
index a06720b7ae..082ffe2ba8 100644
--- a/crates/activity/src/domain/ports.rs
+++ b/crates/activity/src/domain/ports.rs
@@ -4,6 +4,7 @@ use std::collections::HashMap;
use std::num::NonZeroU32;
use chrono::{DateTime, Utc};
+use macro_user_id::user_id::MacroUserIdStr;
use model_entity::EntityType;
use uuid::Uuid;
@@ -65,6 +66,47 @@ pub struct ActivityRange {
pub truncated: bool,
}
+/// Announces durably recorded activities to realtime subscribers.
+///
+/// Best-effort: implementations bound delivery time and log failures instead
+/// of failing the durable write. Clients refetch on reconnect to recover
+/// missed pushes. Uncommitted source offsets may also replay announcements.
+pub trait ActivityRealtimePublisher: Send + Sync {
+ /// Announces recorded activities to their subjects and current accessors.
+ fn publish_recorded(&self, activities: &[Activity]) -> impl Future<Output = ()> + Send;
+
+ /// Announces the durable removal of activity rows.
+ fn publish_invalidated(&self) -> impl Future<Output = ()> + Send;
+}
+
+/// Resolves who may currently see an entity's activity.
+///
+/// Used at publish time to widen realtime delivery beyond the acting
+/// subject: entity timelines are watched by everyone with access to the
+/// entity, not only whoever acted.
+pub trait ActivityAudienceExpander: Send + Sync {
+ /// The adapter's error type.
+ type Err: std::error::Error + Send + Sync + 'static;
+
+ /// Returns all users with current access to the entity.
+ fn entity_audience(
+ &self,
+ entity_type: EntityType,
+ entity_id: &str,
+ ) -> impl Future<Output = Result<Vec<MacroUserIdStr<'static>>, Self::Err>> + Send;
+}
+
+/// Publishes an already addressed activity announcement.
+pub trait ActivityEventPublisher: Send + Sync {
+ /// The transport's error type.
+ type Err: std::fmt::Debug + Send + Sync + 'static;
+ /// Delivers a domain event without deciding its recipients.
+ fn publish(
+ &self,
+ event: super::events::ActivityTopicEvent,
+ ) -> impl Future<Output = Result<(), Self::Err>> + Send;
+}
+
/// Persists activities.
pub trait ActivityRepo {
/// The adapter's error type.
diff --git a/crates/activity/src/domain/realtime.rs b/crates/activity/src/domain/realtime.rs
new file mode 100644
index 0000000000..1bbec39afe
--- /dev/null
+++ b/crates/activity/src/domain/realtime.rs
@@ -0,0 +1,232 @@
+//! 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)
+ }
+}
diff --git a/crates/activity/src/domain/realtime/test.rs b/crates/activity/src/domain/realtime/test.rs
new file mode 100644
index 0000000000..132e11b856
--- /dev/null
+++ b/crates/activity/src/domain/realtime/test.rs
@@ -0,0 +1,244 @@
+use std::collections::VecDeque;
+use std::sync::Mutex;
+use std::sync::atomic::{AtomicUsize, Ordering};
+
+use chrono::Utc;
+use model_entity::EntityType;
+use rootcause::Report;
+use uuid::Uuid;
+
+use super::*;
+use crate::domain::events::ActivityWireRow;
+
+struct FakeConsumer {
+ messages: Mutex<VecDeque<Result<ActivityTopicEvent, Report>>>,
+ calls: Arc<AtomicUsize>,
+}
+
+impl ActivityTopicEventConsumer for FakeConsumer {
+ async fn recv(&self) -> Result<ActivityTopicEvent, Report> {
+ self.calls.fetch_add(1, Ordering::SeqCst);
+ self.messages
+ .lock()
+ .expect("consumer messages lock")
+ .pop_front()
+ .unwrap_or_else(|| Err(rootcause::report!("consumer stopped")))
+ }
+}
+
+fn user(local: &str) -> MacroUserIdStr<'static> {
+ MacroUserIdStr::try_from(format!("macro|{local}@example.com")).expect("valid user ID")
+}
+
+fn wire_row(subject: &MacroUserIdStr<'static>, entity_id: &str) -> ActivityWireRow {
+ ActivityWireRow {
+ id: Uuid::new_v4(),
+ actor_id: subject.as_ref().to_owned(),
+ subject_id: subject.as_ref().to_owned(),
+ entity_type: EntityType::Document,
+ entity_id: entity_id.to_string(),
+ action: "edited".to_string(),
+ action_payload: None,
+ occurred_at: Utc::now(),
+ }
+}
+
+fn recorded(recipient: &str, activities: Vec<ActivityWireRow>) -> ActivityTopicEvent {
+ ActivityTopicEvent::Recorded {
+ recipient_id: recipient.to_string(),
+ activities,
+ }
+}
+
+#[tokio::test(start_paused = true)]
+async fn distributes_activities_to_recipient_subscriptions() {
+ let one = user("one");
+ let two = user("two");
+ let receive_calls = Arc::new(AtomicUsize::new(0));
+ let consumer = FakeConsumer {
+ messages: Mutex::new(VecDeque::from([
+ Err(rootcause::report!("transient receive failure")),
+ Ok(recorded(one.as_ref(), vec![wire_row(&one, "doc-1")])),
+ Ok(recorded(two.as_ref(), vec![wire_row(&two, "doc-2")])),
+ ])),
+ calls: Arc::clone(&receive_calls),
+ };
+ let service = Arc::new(ActivityRealtimeConsumerService::new(consumer));
+ let mut one_first = service.subscribe(one.clone());
+ let mut one_second = service.subscribe(one);
+ let mut two_receiver = service.subscribe(two);
+
+ let run_error = tokio::spawn({
+ let service = Arc::clone(&service);
+ async move { service.run().await }
+ })
+ .await
+ .expect("consumer task joins")
+ .expect_err("fake consumer eventually stops");
+
+ assert!(run_error.to_string().contains("failed to receive"));
+ assert_eq!(
+ receive_calls.load(Ordering::SeqCst),
+ 3 + MAX_RECEIVE_ATTEMPTS,
+ "a successful event resets the receive retry strategy"
+ );
+ let ActivitySubscriptionUpdate::Updated(one_first) =
+ one_first.recv().await.expect("first subscriber receives")
+ else {
+ panic!("expected activity update");
+ };
+ let ActivitySubscriptionUpdate::Updated(one_second) =
+ one_second.recv().await.expect("second subscriber receives")
+ else {
+ panic!("expected activity update");
+ };
+ let ActivitySubscriptionUpdate::Updated(two) =
+ two_receiver.recv().await.expect("other user receives")
+ else {
+ panic!("expected activity update");
+ };
+ assert_eq!(one_first.entity_id, "doc-1");
+ assert_eq!(two.entity_id, "doc-2");
+ assert!(Arc::ptr_eq(&one_first, &one_second));
+}
+
+#[tokio::test(start_paused = true)]
+async fn routes_by_recipient_and_drops_non_user_recipients() {
+ let subscribed = user("subscribed");
+ let other = user("other");
+ // A row about someone else's action still reaches its addressed
+ // recipient — that is how entity watchers hear about other principals.
+ let mut foreign_subject_row = wire_row(&other, "doc-watched");
+ foreign_subject_row.subject_id = "bot|automation".to_string();
+ let consumer = FakeConsumer {
+ messages: Mutex::new(VecDeque::from([
+ // Addressed to a non-user principal: dropped whole.
+ Ok(recorded(
+ "bot|automation",
+ vec![wire_row(&subscribed, "ignored")],
+ )),
+ Ok(recorded(
+ subscribed.as_ref(),
+ vec![foreign_subject_row, wire_row(&subscribed, "doc-1")],
+ )),
+ ])),
+ calls: Arc::new(AtomicUsize::new(0)),
+ };
+ let service = Arc::new(ActivityRealtimeConsumerService::new(consumer));
+ let mut receiver = service.subscribe(subscribed);
+
+ let _ = tokio::spawn({
+ let service = Arc::clone(&service);
+ async move { service.run().await }
+ })
+ .await
+ .expect("consumer task joins")
+ .expect_err("fake consumer eventually stops");
+
+ // The dropped event preceded these, so the first deliveries being the
+ // addressed rows proves the non-user recipient was dropped whole.
+ let ActivitySubscriptionUpdate::Updated(first) =
+ receiver.recv().await.expect("subscriber receives")
+ else {
+ panic!("expected activity update");
+ };
+ assert_eq!(first.entity_id, "doc-watched");
+ assert_eq!(first.subject_id, "bot|automation");
+ let ActivitySubscriptionUpdate::Updated(second) =
+ receiver.recv().await.expect("subscriber receives")
+ else {
+ panic!("expected activity update");
+ };
+ assert_eq!(second.entity_id, "doc-1");
+}
+
+#[tokio::test(start_paused = true)]
+async fn reports_slow_consumer_subscription_exit() {
+ let subscribed = user("subscribed");
+ let consumer = FakeConsumer {
+ messages: Mutex::new(VecDeque::new()),
+ calls: Arc::new(AtomicUsize::new(0)),
+ };
+ let service = ActivityRealtimeConsumerService::new(consumer);
+ let subscription = service.subscribe(subscribed.clone());
+
+ for _ in 0..=SUBSCRIBER_BUFFER_CAPACITY.get() {
+ let row = wire_row(&subscribed, "doc-1");
+ let record = row.into_record().expect("decodes");
+ service
+ .broadcasts
+ .publish(
+ &subscribed,
+ ActivitySubscriptionUpdate::Updated(Arc::new(record)),
+ )
+ .expect("subscriber remains until its buffer fills");
+ tokio::task::yield_now().await;
+ }
+
+ assert_eq!(
+ subscription.exit_reason().await,
+ ActivitySubscriptionExit::SlowConsumer
+ );
+}
+
+#[tokio::test(start_paused = true)]
+async fn purge_invalidates_unrelated_subscribers_without_entity_access_data() {
+ let consumer = FakeConsumer {
+ messages: Mutex::new(VecDeque::from([
+ Ok(ActivityTopicEvent::Invalidated),
+ Ok(ActivityTopicEvent::Invalidated),
+ ])),
+ calls: Arc::new(AtomicUsize::new(0)),
+ };
+ let service = Arc::new(ActivityRealtimeConsumerService::new(consumer));
+ let mut one = service.subscribe(user("former-viewer"));
+ let mut two = service.subscribe(user("other-viewer"));
+ let task = tokio::spawn({
+ let service = service.clone();
+ async move { service.run().await }
+ });
+ task.await.unwrap().expect_err("test consumer stops");
+ assert!(matches!(
+ one.recv().await,
+ Some(ActivitySubscriptionUpdate::Invalidated)
+ ));
+ assert!(matches!(
+ two.recv().await,
+ Some(ActivitySubscriptionUpdate::Invalidated)
+ ));
+ assert!(
+ tokio::time::timeout(Duration::from_millis(1), one.recv())
+ .await
+ .is_err(),
+ "bursts coalesce"
+ );
+}
+
+#[tokio::test(start_paused = true)]
+async fn large_recorded_batch_refreshes_without_disconnect() {
+ let viewer = user("viewer");
+ let consumer = FakeConsumer {
+ messages: Mutex::new(VecDeque::from([Ok(recorded(
+ viewer.as_ref(),
+ (0..100).map(|_| wire_row(&viewer, "doc-1")).collect(),
+ ))])),
+ calls: Arc::new(AtomicUsize::new(0)),
+ };
+ let service = Arc::new(ActivityRealtimeConsumerService::new(consumer));
+ let mut receiver = service.subscribe(viewer);
+ let task = tokio::spawn({
+ let service = service.clone();
+ async move { service.run().await }
+ });
+ task.await.unwrap().expect_err("test consumer stops");
+ assert!(matches!(
+ receiver.recv().await,
+ Some(ActivitySubscriptionUpdate::Invalidated)
+ ));
+ assert!(
+ tokio::time::timeout(Duration::from_millis(1), receiver.recv())
+ .await
+ .is_err(),
+ "subscription remains open"
+ );
+}
diff --git a/crates/activity/src/inbound/kafka_consumer.rs b/crates/activity/src/inbound/kafka_consumer.rs
index 602cd81124..c44fe7b8b3 100644
--- a/crates/activity/src/inbound/kafka_consumer.rs
+++ b/crates/activity/src/inbound/kafka_consumer.rs
@@ -22,7 +22,10 @@ use rdkafka::message::{BorrowedMessage, Message as _};
use rootcause::prelude::{Report, ResultExt as _};
use tracing::Instrument as _;
-use crate::domain::{models::Ingest, ports::ActivityRepo};
+use crate::domain::{
+ models::Ingest,
+ ports::{ActivityRealtimePublisher, ActivityRepo},
+};
/// Consumer group for activity materialization offsets.
struct ActivityConsumerGroup;
@@ -36,34 +39,38 @@ impl GroupName for ActivityConsumerGroup {
/// `C` is the host's declared event collection (`declare_topics!`); `ingest`
/// is the host's dispatch from a decoded event to the owning domain's
/// mapping.
-pub struct ActivityConsumer<R, C, F> {
- repo: R,
+pub struct ActivityConsumer<R, C, F, P> {
+ materializer: crate::domain::materializer::ActivityMaterializer<R, P>,
ingest: F,
_events: PhantomData<fn() -> C>,
}
-impl<R, C, F> ActivityConsumer<R, C, F>
+impl<R, C, F, P> ActivityConsumer<R, C, F, P>
where
R: ActivityRepo,
C: MacroEventCollection + 'static,
F: Fn(&C) -> Ingest + Send + Sync,
+ P: ActivityRealtimePublisher,
{
- /// Builds the consumer over an activity store and an event dispatcher.
- pub fn new(repo: R, ingest: F) -> Self {
+ /// Builds the consumer over an activity store, an event dispatcher, and
+ /// a realtime announcer for durably inserted rows.
+ pub fn new(repo: R, ingest: F, realtime: P) -> Self {
Self {
- repo,
+ materializer: crate::domain::materializer::ActivityMaterializer::new(repo, realtime),
ingest,
_events: PhantomData,
}
}
- /// Applies one decoded event to storage.
+ /// Applies one decoded event to storage, announcing inserted rows.
+ ///
+ /// The announcement is deliberately not transactional with the insert:
+ /// if it is lost (crash between insert and publish), the uncommitted
+ /// offset replays the source event, the deterministic ids no-op the
+ /// insert, and the announcement is published again; duplicates are
+ /// idempotent for subscribers (records keyed by id).
async fn apply(&self, event: &C) -> Result<(), R::Err> {
- match (self.ingest)(event) {
- Ingest::Insert(activities) => self.repo.insert_activities(&activities).await,
- Ingest::Purge(entities) => self.repo.purge_entities(&entities).await,
- Ingest::Ignore => Ok(()),
- }
+ self.materializer.apply((self.ingest)(event)).await
}
/// Runs the consumer until `shutdown` resolves.
@@ -126,10 +133,12 @@ where
// forever. Returning Err restarts the consumer from the
// last committed offset; deterministic activity ids make
// the replay idempotent.
- self.apply(&event)
- .instrument(span)
- .await
- .context("failed to store activities")?;
+ tokio::select! {
+ _ = &mut shutdown => break,
+ result = self.apply(&event).instrument(span) => {
+ result.context("failed to store activities")?;
+ }
+ }
commit_logged(&consumer, kafka_message);
}
}
diff --git a/crates/activity/src/lib.rs b/crates/activity/src/lib.rs
index 5189b5f412..2c66d1f2ea 100644
--- a/crates/activity/src/lib.rs
+++ b/crates/activity/src/lib.rs
@@ -17,14 +17,17 @@
//! decoded event to the owning domain's mapping.
//!
//! Features: `outbound` (Postgres adapter), `consumer` (generic Kafka
-//! consumer); both on by default. The models are always available.
+//! consumer and realtime Kafka adapters), `realtime` (user-scoped realtime
+//! distribution); all on by default. The models and wire events are always
+//! available.
pub mod domain;
#[cfg(any(feature = "ai_tools", feature = "consumer"))]
pub mod inbound;
-#[cfg(feature = "outbound")]
+#[cfg(any(feature = "outbound", feature = "consumer"))]
pub mod outbound;
+pub use domain::events::{ActivityMacroEvent, ActivityTopicEvent, ActivityWireRow};
pub use domain::models::{
Action, ActionDecodeError, Activity, ActivityRecord, ActivitySource, Actor, Attribution,
CallStart, CommonAction, DomainActivity, EntityType, Ingest, ParticipantChange, PropertyChange,
@@ -34,9 +37,20 @@ pub use domain::overview::{
ActivityOverview, ActivityOverviewError, ActivityWindow, ActivityWindowError, DayCount,
EntityRank, MAX_ACTIVITY_WINDOW_DAYS, TOP_ENTITY_LIMIT, trailing_year,
};
+pub use domain::ports::{ActivityAudienceExpander, ActivityRealtimePublisher};
pub use domain::ports::{ActivityFeedPage, ActivityRange, ActivityReads, EntityActivityMap};
+#[cfg(feature = "realtime")]
+pub use domain::realtime::{
+ ActivityRealtimeConsumerService, ActivitySubscription, ActivitySubscriptionExit,
+ ActivitySubscriptionService, ActivitySubscriptionUpdate, ActivityTopicEventConsumer,
+ NoOpActivitySubscriptionService,
+};
#[cfg(feature = "ai_tools")]
pub use domain::{
ports::{ActivityMetadataResolver, ActivityPropertyMetadata},
service::{ActivityReadService, NoopActivityMetadataResolver, ResolvedActivityRange},
};
+#[cfg(all(feature = "consumer", feature = "realtime"))]
+pub use outbound::activity_topic_consumer::ActivityTopicConsumer;
+#[cfg(feature = "consumer")]
+pub use outbound::kafka_activity_realtime::KafkaActivityRealtimePublisher;
diff --git a/crates/activity/src/outbound/activity_topic_consumer.rs b/crates/activity/src/outbound/activity_topic_consumer.rs
new file mode 100644
index 0000000000..7c5ac22bf2
--- /dev/null
+++ b/crates/activity/src/outbound/activity_topic_consumer.rs
@@ -0,0 +1,105 @@
+//! Independent Kafka consumer for activity topic events.
+//!
+//! Every process receives every message published after it starts because
+//! this adapter manually assigns all `macro.activity` partitions without
+//! joining a durable consumer group. It does not commit offsets.
+
+use std::time::Duration;
+
+use kafka_util::{InitialOffset, KafkaEventConsumer, Ungrouped};
+use macro_event_broker::{
+ EventBrokerError, KafkaConsumerAdapter, MacroEventCollection, MacroEventConsumerService,
+};
+use rdkafka::message::Message as _;
+use rootcause::prelude::{Report, ResultExt as _};
+
+use crate::domain::events::{ActivityMacroEvent, ActivityTopicEvent};
+use crate::domain::realtime::ActivityTopicEventConsumer;
+
+/// Maximum time to wait for topic metadata during partition assignment.
+const TOPIC_METADATA_TIMEOUT: Duration = Duration::from_secs(10);
+
+type IndependentKafkaConsumer = KafkaConsumerAdapter<Ungrouped, DeclaredMacroEvent>;
+type ActivityEventConsumer =
+ MacroEventConsumerService<DeclaredMacroEvent, IndependentKafkaConsumer>;
+
+macro_event_broker::declare_topics!(DeclaredMacroEvent: ActivityMacroEvent);
+
+/// Independent consumer of activity topic events.
+///
+/// Starts at the end of every current `macro.activity` partition, so it
+/// receives only messages published after construction. Partitions added
+/// after construction require a new consumer so they can be assigned.
+pub struct ActivityTopicConsumer {
+ consumer: ActivityEventConsumer,
+}
+
+impl ActivityTopicConsumer {
+ /// Creates a consumer and assigns every current activity topic partition.
+ #[tracing::instrument(fields(brokers), err)]
+ pub fn from_env(brokers: &str) -> Result<Self, Report> {
+ let consumer = KafkaEventConsumer::<Ungrouped>::from_env(brokers)
+ .context("failed to create independent activity topic consumer")?;
+ let consumer =
+ IndependentKafkaConsumer::new(consumer, InitialOffset::Latest, TOPIC_METADATA_TIMEOUT)
+ .context("failed to assign activity topic partitions")?;
+
+ tracing::info!(
+ topics = ?DeclaredMacroEvent::topics(),
+ "independent activity topic consumer listening"
+ );
+
+ Ok(Self {
+ consumer: ActivityEventConsumer::new(consumer),
+ })
+ }
+
+ /// Receives and decodes the next activity topic event.
+ ///
+ /// Cancel-safe. Unsupported schema versions are poison records and are
+ /// skipped; other malformed payloads are returned as errors.
+ pub async fn recv(&self) -> Result<ActivityTopicEvent, Report> {
+ loop {
+ let message = self
+ .consumer
+ .recv()
+ .await
+ .context("failed to receive activity topic event")?;
+ let event = match message.decode_payload() {
+ Ok(event) => event,
+ Err(EventBrokerError::UnsupportedSchemaVersion {
+ topic,
+ expected,
+ actual,
+ }) => {
+ let kafka_message = message.inner();
+ tracing::warn!(
+ topic,
+ expected,
+ actual,
+ partition = kafka_message.partition(),
+ offset = kafka_message.offset(),
+ "dropping activity topic event with unsupported schema version"
+ );
+ continue;
+ }
+ Err(error) => {
+ return Err(Report::new(error)
+ .context("failed to decode activity topic event")
+ .into_dynamic());
+ }
+ };
+
+ return match event {
+ DeclaredMacroEvent::ActivityMacroEvent(event) => Ok(event.into_topic_event()),
+ };
+ }
+ }
+}
+
+impl ActivityTopicEventConsumer for ActivityTopicConsumer {
+ #[tracing::instrument(err, skip(self))]
+ async fn recv(&self) -> Result<ActivityTopicEvent, Report> {
+ ActivityTopicConsumer::recv(self).await
+ }
+}
diff --git a/crates/activity/src/outbound/kafka_activity_realtime.rs b/crates/activity/src/outbound/kafka_activity_realtime.rs
new file mode 100644
index 0000000000..2cc6d87df5
--- /dev/null
+++ b/crates/activity/src/outbound/kafka_activity_realtime.rs
@@ -0,0 +1,40 @@
+//! Kafka transport for addressed activity announcements.
+
+use macro_event_broker::{Event, MacroEvent, MacroEventBroker};
+use rootcause::prelude::{Report, ResultExt as _};
+use tokio_util::task::AbortOnDropHandle;
+
+use crate::domain::{
+ events::{ActivityMacroEvent, ActivityTopicEvent},
+ ports::ActivityEventPublisher,
+};
+
+/// Sends domain-selected activity announcements through the event broker.
+pub struct KafkaActivityRealtimePublisher<B> {
+ broker: B,
+}
+
+impl<B> KafkaActivityRealtimePublisher<B> {
+ /// Creates the Kafka transport.
+ pub fn new(broker: B) -> Self {
+ Self { broker }
+ }
+}
+
+impl<B: MacroEventBroker> ActivityEventPublisher for KafkaActivityRealtimePublisher<B> {
+ type Err = Report;
+
+ async fn publish(&self, event: ActivityTopicEvent) -> Result<(), Report> {
+ let event = ActivityMacroEvent::from_event(event.key().to_owned(), Event::new(event));
+ let publish = AbortOnDropHandle::new(
+ self.broker
+ .send_event(&event)
+ .context("failed to dispatch activity Kafka event")?,
+ );
+ publish
+ .await
+ .context("activity Kafka publish task failed")?
+ .context("failed to publish activity to Kafka")?;
+ Ok(())
+ }
+}
diff --git a/crates/activity/src/outbound/mod.rs b/crates/activity/src/outbound/mod.rs
index 1d7c4cc6bc..9a5a3da5de 100644
--- a/crates/activity/src/outbound/mod.rs
+++ b/crates/activity/src/outbound/mod.rs
@@ -1,3 +1,8 @@
//! Outbound adapters.
+#[cfg(all(feature = "consumer", feature = "realtime"))]
+pub mod activity_topic_consumer;
+#[cfg(feature = "consumer")]
+pub mod kafka_activity_realtime;
+#[cfg(feature = "outbound")]
pub mod pg_activity_repo;
diff --git a/crates/complete_graph/Cargo.toml b/crates/complete_graph/Cargo.toml
index 77a233fe6a..354e57964f 100644
--- a/crates/complete_graph/Cargo.toml
+++ b/crates/complete_graph/Cargo.toml
@@ -48,7 +48,7 @@ uuid = { workspace = true }
workspace-hack = { version = "0.1", path = "../workspace-hack" }
[dev-dependencies]
-activity = { path = "../activity", default-features = false }
+activity = { path = "../activity", default-features = false, features = ["realtime"] }
apollo-compiler = { workspace = true }
chrono = { workspace = true }
model_user = { path = "../model_user" }
diff --git a/crates/complete_graph/src/schema.rs b/crates/complete_graph/src/schema.rs
index 4b882914b2..df94504b27 100644
--- a/crates/complete_graph/src/schema.rs
+++ b/crates/complete_graph/src/schema.rs
@@ -13,8 +13,9 @@ use entity_access::domain::ports::{EntityAccessService, NoOpEntityAccessService}
use entity_mutation::{EntityMutationService, UnavailableEntityMutationService};
use favorites::domain::ports::FavoritesMutationService;
use graphql_activity::{
- ActivityFeedInput, ActivityOverviewInput, ActivityReader, GraphqlActivityOverview,
- GraphqlActivityPage, NoOpActivityReader, resolve_activity_feed, resolve_activity_overview,
+ ActivityFeedInput, ActivityOverviewInput, ActivityReader, ActivitySubscriptionRoot,
+ ActivitySubscriptionService, GraphqlActivityOverview, GraphqlActivityPage, NoOpActivityReader,
+ NoOpActivitySubscriptionService, resolve_activity_feed, resolve_activity_overview,
};
use graphql_channel::{
ChannelActivityAuthorizer, ChannelActivityMutationService, ChannelMutationRoot,
@@ -106,15 +107,18 @@ impl<
}
}
-/// Root subscription object combining realtime Soup and notification adapters.
+/// Root subscription object combining realtime Soup, notification, and
+/// activity adapters.
#[derive(MergedSubscription)]
-pub struct CompleteSubscriptionRoot<R, NS, Auth, St, NR, PR, ER, FR, AR, AcR>(
+pub struct CompleteSubscriptionRoot<R, NS, AS, Auth, St, NR, PR, ER, FR, AR, AcR>(
SoupSubscriptionRoot<R, Auth, St, NR, PR, ER, FR, AR, AcR>,
NotificationSubscriptionRoot<NS>,
+ ActivitySubscriptionRoot<AS>,
)
where
R: SoupRealtimeSubscriptionService,
NS: WebSocketNotificationSubscriptionService<NotificationSubscriptionUpdate<NotifEvent>>,
+ AS: ActivitySubscriptionService,
Auth: MacroAuthorizationService,
St: Clone + Send + Sync + 'static,
MacroAuthorizationState<Auth>: FromRef<St>,
@@ -128,23 +132,44 @@ where
/// GraphQL Soup schema type.
///
/// `S` is the soup query service, `R` the realtime Soup subscription service,
-/// `NS` the realtime notification subscription service, `E` the email service,
-/// `EAS` the entity access service, `Auth` the authorization service, `St` the
-/// embedding axum router state, `W` the property mutation writer, `M` the entity
-/// mutation service, `FM` the favorites mutation service, `C` the channel activity
-/// mutation service, `N` the notification mutation service, `NR` the notification
-/// edge reader, `PR` the property edge reader, `ER` the email-content edge reader,
-/// `FR` the favorite edge and query reader, `AR` the access edge reader, and `AcR` the
-/// activity reader.
-pub type SoupSchema<S, R, NS, E, EAS, Auth, St, W, M, FM, C, N, NR, PR, ER, FR, AR, AcR> = Schema<
- SoupQueryRoot<S, E, EAS, Auth, St, NR, PR, ER, FR, AR, AcR>,
- CompleteMutationRoot<W, M, FM, SoupEdges<NR, PR, ER, FR, AR, AcR>, C, N, EAS, E>,
- CompleteSubscriptionRoot<R, NS, Auth, St, NR, PR, ER, FR, AR, AcR>,
->;
+/// `NS` the realtime notification subscription service, `AS` the realtime
+/// activity subscription service, `E` the email service, `EAS` the entity
+/// access service, `Auth` the authorization service, `St` the embedding axum
+/// router state, `W` the property mutation writer, `M` the entity mutation
+/// service, `C` the channel activity mutation service, `N` the notification
+/// mutation service, `NR` the notification edge reader, `PR` the property edge
+/// reader, `ER` the email-content edge reader, `FR` the favorite edge reader,
+/// `AR` the access edge reader, and `AcR` the activity reader.
+pub type SoupSchema<S, R, NS, AS, E, EAS, Auth, St, W, M, FM, C, N, NR, PR, ER, FR, AR, AcR> =
+ Schema<
+ SoupQueryRoot<S, E, EAS, Auth, St, NR, PR, ER, FR, AR, AcR>,
+ CompleteMutationRoot<W, M, FM, SoupEdges<NR, PR, ER, FR, AR, AcR>, C, N, EAS, E>,
+ CompleteSubscriptionRoot<R, NS, AS, Auth, St, NR, PR, ER, FR, AR, AcR>,
+ >;
/// GraphQL Soup schema type backed by shared query and realtime services.
-pub type SharedSoupSchema<S, R, NS, E, EAS, Auth, St, W, M, FM, C, N, NR, PR, ER, FR, AR, AcR> =
- SoupSchema<Arc<S>, Arc<R>, Arc<NS>, E, EAS, Auth, St, W, M, FM, C, N, NR, PR, ER, FR, AR, AcR>;
+pub type SharedSoupSchema<S, R, NS, AS, E, EAS, Auth, St, W, M, FM, C, N, NR, PR, ER, FR, AR, AcR> =
+ SoupSchema<
+ Arc<S>,
+ Arc<R>,
+ Arc<NS>,
+ Arc<AS>,
+ E,
+ EAS,
+ Auth,
+ St,
+ W,
+ M,
+ FM,
+ C,
+ N,
+ NR,
+ PR,
+ ER,
+ FR,
+ AR,
+ AcR,
+ >;
/// GraphQL Soup schema type backed by the no-op services, used only for
/// SDL export or introspection.
@@ -152,6 +177,7 @@ pub type SchemaOnlySoupSchema = SoupSchema<
NoOpSoupService,
NoOpSoupRealtimeSubscriptionService,
NoopWebSocketNotificationSubscriptionService,
+ NoOpActivitySubscriptionService,
NoOpEmailService,
NoOpEntityAccessService,
SchemaOnlyAuthorizationService,
@@ -274,6 +300,7 @@ pub fn build_schema() -> SchemaOnlySoupSchema {
NoOpSoupService,
NoOpSoupRealtimeSubscriptionService,
NoopWebSocketNotificationSubscriptionService,
+ NoOpActivitySubscriptionService,
)
}
@@ -285,6 +312,7 @@ pub fn build_schema_with_service<S, E, EAS, Auth, St, W, M, FM, C, N, NR, PR, ER
S,
NoOpSoupRealtimeSubscriptionService,
NoopWebSocketNotificationSubscriptionService,
+ NoOpActivitySubscriptionService,
E,
EAS,
Auth,
@@ -326,6 +354,7 @@ where
service,
NoOpSoupRealtimeSubscriptionService,
NoopWebSocketNotificationSubscriptionService,
+ NoOpActivitySubscriptionService,
)
}
@@ -335,6 +364,7 @@ pub fn build_schema_with_services<
S,
R,
NS,
+ AS,
E,
EAS,
Auth,
@@ -354,12 +384,14 @@ pub fn build_schema_with_services<
service: S,
realtime_service: R,
notification_subscription_service: NS,
-) -> SoupSchema<S, R, NS, E, EAS, Auth, St, W, M, FM, C, N, NR, PR, ER, FR, AR, AcR>
+ activity_subscription_service: AS,
+) -> SoupSchema<S, R, NS, AS, E, EAS, Auth, St, W, M, FM, C, N, NR, PR, ER, FR, AR, AcR>
where
S: SoupService + Clone,
R: SoupRealtimeSubscriptionService + Clone,
NS: WebSocketNotificationSubscriptionService<NotificationSubscriptionUpdate<NotifEvent>>
+ Clone,
+ AS: ActivitySubscriptionService,
E: EmailService + EmailUserService,
EAS: EntityAccessService,
Auth: MacroAuthorizationService,
@@ -385,6 +417,7 @@ where
CompleteSubscriptionRoot(
SoupSubscriptionRoot::new(realtime_service),
NotificationSubscriptionRoot::new(notification_subscription_service),
+ ActivitySubscriptionRoot::new(activity_subscription_service),
),
)
.finish()
@@ -398,6 +431,7 @@ pub fn build_schema_from_arc<S, E, EAS, Auth, St, W, M, FM, C, N, NR, PR, ER, FR
Arc<S>,
NoOpSoupRealtimeSubscriptionService,
NoopWebSocketNotificationSubscriptionService,
+ NoOpActivitySubscriptionService,
E,
EAS,
Auth,
@@ -440,15 +474,37 @@ where
/// Build a GraphQL schema backed by `Arc`-shared query and realtime services.
#[allow(clippy::type_complexity)]
-pub fn build_schema_from_arcs<S, R, NS, E, EAS, Auth, St, W, M, FM, C, N, NR, PR, ER, FR, AR, AcR>(
+pub fn build_schema_from_arcs<
+ S,
+ R,
+ NS,
+ AS,
+ E,
+ EAS,
+ Auth,
+ St,
+ W,
+ M,
+ FM,
+ C,
+ N,
+ NR,
+ PR,
+ ER,
+ FR,
+ AR,
+ AcR,
+>(
service: Arc<S>,
realtime_service: Arc<R>,
notification_subscription_service: Arc<NS>,
-) -> SharedSoupSchema<S, R, NS, E, EAS, Auth, St, W, M, FM, C, N, NR, PR, ER, FR, AR, AcR>
+ activity_subscription_service: Arc<AS>,
+) -> SharedSoupSchema<S, R, NS, AS, E, EAS, Auth, St, W, M, FM, C, N, NR, PR, ER, FR, AR, AcR>
where
S: SoupService,
R: SoupRealtimeSubscriptionService,
NS: WebSocketNotificationSubscriptionService<NotificationSubscriptionUpdate<NotifEvent>>,
+ AS: ActivitySubscriptionService,
E: EmailService + EmailUserService,
EAS: EntityAccessService,
Auth: MacroAuthorizationService,
@@ -468,7 +524,12 @@ where
AR: EntityPermissionEdgeReader,
AcR: ActivityReader,
{
- build_schema_with_services(service, realtime_service, notification_subscription_service)
+ build_schema_with_services(
+ service,
+ realtime_service,
+ notification_subscription_service,
+ activity_subscription_service,
+ )
}
/// Root entry point for the complete GraphQL API.
diff --git a/crates/complete_graph/src/schema/test.rs b/crates/complete_graph/src/schema/test.rs
index ad9446a82a..a67783a766 100644
--- a/crates/complete_graph/src/schema/test.rs
+++ b/crates/complete_graph/src/schema/test.rs
@@ -987,6 +987,7 @@ struct TestHarness {
CountingSoupService,
NoOpSoupRealtimeSubscriptionService,
NoopWebSocketNotificationSubscriptionService,
+ graphql_activity::NoOpActivitySubscriptionService,
CountingEmailService,
CountingEntityAccessService,
FakeAuthorizationService,
@@ -1155,6 +1156,7 @@ async fn soup_updates_subscribes_as_the_authenticated_user() {
CountingSoupService,
TestRealtimeSubscriptionService,
NoopWebSocketNotificationSubscriptionService,
+ graphql_activity::NoOpActivitySubscriptionService,
NoOpEmailService,
NoOpEntityAccessService,
SchemaOnlyAuthorizationService,
@@ -1174,6 +1176,7 @@ async fn soup_updates_subscribes_as_the_authenticated_user() {
soup_service,
realtime,
NoopWebSocketNotificationSubscriptionService,
+ graphql_activity::NoOpActivitySubscriptionService,
);
let request = async_graphql::Request::new(
"subscription { soupUpdates { __typename ... on SoupUpdated { item { id cacheProjection } } ... on GraphqlCacheDeletion { graphqlTypeName entityId } } }",
@@ -1225,6 +1228,122 @@ async fn soup_updates_subscribes_as_the_authenticated_user() {
);
}
+#[tokio::test]
+async fn activity_updates_subscribes_as_the_authenticated_user() {
+ use activity::{
+ ActivitySubscription, ActivitySubscriptionExit, ActivitySubscriptionService,
+ ActivitySubscriptionUpdate,
+ };
+ use async_graphql::futures_util::{StreamExt as _, pin_mut};
+
+ let user_id = MacroUserIdStr::parse_from_str(VALID_USER_ID).unwrap();
+ let subscribed_user: Arc<Mutex<Option<MacroUserIdStr<'static>>>> = Arc::default();
+
+ struct TestActivitySubscriptionService {
+ subscribed_user: Arc<Mutex<Option<MacroUserIdStr<'static>>>>,
+ subscription: Mutex<Option<ActivitySubscription>>,
+ }
+
+ impl ActivitySubscriptionService for TestActivitySubscriptionService {
+ fn subscribe(&self, user_id: MacroUserIdStr<'static>) -> ActivitySubscription {
+ *self.subscribed_user.lock().expect("subscribed user lock") = Some(user_id);
+ self.subscription
+ .lock()
+ .expect("subscription lock")
+ .take()
+ .expect("subscription opened once")
+ }
+ }
+
+ let (sender, receiver) = tokio::sync::mpsc::channel(2);
+ let (exit_sender, exit_receiver) = tokio::sync::oneshot::channel();
+ exit_sender
+ .send(ActivitySubscriptionExit::Closed)
+ .expect("exit receiver remains open");
+ let service = TestActivitySubscriptionService {
+ subscribed_user: Arc::clone(&subscribed_user),
+ subscription: Mutex::new(Some(ActivitySubscription::from_parts(
+ receiver,
+ exit_receiver,
+ ))),
+ };
+
+ let schema: SoupSchema<
+ CountingSoupService,
+ NoOpSoupRealtimeSubscriptionService,
+ NoopWebSocketNotificationSubscriptionService,
+ TestActivitySubscriptionService,
+ NoOpEmailService,
+ NoOpEntityAccessService,
+ SchemaOnlyAuthorizationService,
+ SchemaOnlyState,
+ NoOpEntityPropertyWriter,
+ UnavailableEntityMutationService,
+ NoOpFavoriteMutationService,
+ NoOpChannelActivityMutationService,
+ NoOpNotificationMutationService,
+ NoOpSoupNotificationEdgeReader,
+ NoOpEntityPropertyReader,
+ NoOpSoupEmailContentEdgeReader,
+ NoOpEntityFavoriteEdgeReader,
+ NoOpEntityPermissionEdgeReader,
+ NoOpActivityReader,
+ > = build_schema_with_services(
+ CountingSoupService::default(),
+ NoOpSoupRealtimeSubscriptionService,
+ NoopWebSocketNotificationSubscriptionService,
+ service,
+ );
+
+ let request = async_graphql::Request::new(
+ "subscription { activityUpdates { __typename ... on GraphqlActivityEvent { id entityType entityId } } }",
+ )
+ .data(user_id.clone());
+ let responses = schema.execute_stream(request);
+ pin_mut!(responses);
+
+ let record = {
+ let activity = activity::Activity::common(
+ Uuid::from_u128(7),
+ 0,
+ activity::Actor::new_from_user(user_id.clone()),
+ None,
+ ModelEntityType::Document,
+ "doc-1",
+ activity::CommonAction::Edited,
+ chrono::Utc::now(),
+ );
+ activity::ActivityRecord {
+ id: activity.id,
+ actor: activity.actor.clone(),
+ subject_id: activity.subject_id.clone(),
+ entity_type: activity.entity_type,
+ entity_id: activity.entity_id.clone(),
+ action: activity::RecordedAction::Known(activity::Action::Edited),
+ occurred_at: activity.occurred_at,
+ }
+ };
+ let record_id = record.id;
+ sender
+ .send(ActivitySubscriptionUpdate::Updated(Arc::new(record)))
+ .await
+ .expect("subscription remains open");
+
+ let response = responses.next().await.expect("subscription response");
+ assert!(response.errors.is_empty(), "{:?}", response.errors);
+ let data = response.data.into_json().expect("response data is JSON");
+ assert_eq!(data["activityUpdates"]["id"], record_id.to_string());
+ assert_eq!(data["activityUpdates"]["entityType"], "DOCUMENT");
+ assert_eq!(data["activityUpdates"]["entityId"], "doc-1");
+ assert_eq!(
+ subscribed_user
+ .lock()
+ .expect("subscribed user lock")
+ .as_ref(),
+ Some(&user_id)
+ );
+}
+
#[tokio::test]
async fn user_id_resolves_without_touching_services() {
let harness = harness();
diff --git a/crates/complete_graph/src/schema/test/soup_patches.rs b/crates/complete_graph/src/schema/test/soup_patches.rs
index d0e8327413..f519bd5f85 100644
--- a/crates/complete_graph/src/schema/test/soup_patches.rs
+++ b/crates/complete_graph/src/schema/test/soup_patches.rs
@@ -17,6 +17,7 @@ type RealtimeSchema = SoupSchema<
CountingSoupService,
TestRealtimeSubscriptionService,
NoopWebSocketNotificationSubscriptionService,
+ graphql_activity::NoOpActivitySubscriptionService,
NoOpEmailService,
NoOpEntityAccessService,
SchemaOnlyAuthorizationService,
@@ -64,6 +65,7 @@ async fn subscription_responses(
subscribed_user: Arc::new(Mutex::new(None)),
},
NoopWebSocketNotificationSubscriptionService,
+ graphql_activity::NoOpActivitySubscriptionService,
);
let request = async_graphql::Request::new(format!(
"subscription {{ soupUpdates {{ {PATCH_SELECTION} }} }}"
diff --git a/crates/complete_graph/src/sdl_test.rs b/crates/complete_graph/src/sdl_test.rs
index 040a30b038..fcc3fe54e8 100644
--- a/crates/complete_graph/src/sdl_test.rs
+++ b/crates/complete_graph/src/sdl_test.rs
@@ -119,6 +119,8 @@ fn soup_response_schema_exposes_frontend_fields() {
"type GraphqlNewNotification {",
"notification: GraphqlNotification!",
"type GraphqlUpdatedNotification {",
+ "activityUpdates: GraphqlActivityPatch!",
+ "union GraphqlActivityPatch = GraphqlActivityEvent | GraphqlActivityInvalidation",
"type GraphqlNotification {",
"metadata: GraphqlNotifEvent!",
] {
diff --git a/crates/graphql_activity/Cargo.toml b/crates/graphql_activity/Cargo.toml
index b38d01c6f1..3731188936 100644
--- a/crates/graphql_activity/Cargo.toml
+++ b/crates/graphql_activity/Cargo.toml
@@ -5,7 +5,8 @@ publish = false
version = "0.1.0"
[dependencies]
-activity = { path = "../activity", default-features = false }
+activity = { path = "../activity", default-features = false, features = ["realtime"] }
+async-stream = { workspace = true }
async-graphql = { workspace = true, features = ["dataloader"] }
chrono = { workspace = true }
chrono-tz = { workspace = true }
@@ -17,6 +18,7 @@ models_pagination = { path = "../models_pagination" }
serde = { workspace = true }
serde_json = { workspace = true }
tokio = { workspace = true }
+tokio-stream = { workspace = true }
tracing = { workspace = true }
uuid = { workspace = true }
workspace-hack = { version = "0.1", path = "../workspace-hack" }
diff --git a/crates/graphql_activity/src/lib.rs b/crates/graphql_activity/src/lib.rs
index 67c65d1ff4..edd02170d3 100644
--- a/crates/graphql_activity/src/lib.rs
+++ b/crates/graphql_activity/src/lib.rs
@@ -24,7 +24,10 @@ mod loaders;
mod objects;
/// Trailing-year activity overview input, output, and resolver.
mod overview;
+/// Realtime activity subscription root and patch union.
+mod subscriptions;
+pub use activity::{ActivitySubscriptionService, NoOpActivitySubscriptionService};
pub use feed::{
ActivityFeedInput, DEFAULT_ACTIVITY_FEED_LIMIT, GraphqlActivityPage, MAX_ACTIVITY_FEED_LIMIT,
resolve_activity_feed,
@@ -40,3 +43,4 @@ pub use overview::{
ActivityOverviewInput, GraphqlActivityDay, GraphqlActivityEntityRank, GraphqlActivityOverview,
resolve_activity_overview,
};
+pub use subscriptions::{ActivitySubscriptionRoot, GraphqlActivityPatch, subscribe_to_activity};
diff --git a/crates/graphql_activity/src/subscriptions.rs b/crates/graphql_activity/src/subscriptions.rs
new file mode 100644
index 0000000000..50a3e86642
--- /dev/null
+++ b/crates/graphql_activity/src/subscriptions.rs
@@ -0,0 +1,101 @@
+//! Realtime activity subscription for the authenticated user.
+
+#[cfg(test)]
+mod test;
+
+use activity::{ActivitySubscriptionExit, ActivitySubscriptionService, ActivitySubscriptionUpdate};
+use async_graphql::{Context, SimpleObject, Subscription, Union};
+use graphql_common::require_authenticated_user;
+use tokio_stream::Stream;
+
+use crate::GraphqlActivityEvent;
+
+/// A content-free signal to refresh activity through authorized queries.
+#[derive(SimpleObject)]
+pub struct GraphqlActivityInvalidation {
+ /// True when mounted activity queries need a fresh read.
+ pub refresh: bool,
+}
+
+/// Realtime activity patch: a recorded event or a purge invalidation.
+#[expect(
+ clippy::large_enum_variant,
+ reason = "recorded rows dominate; invalidations carry no data"
+)]
+#[derive(Union)]
+pub enum GraphqlActivityPatch {
+ /// An activity event that was durably recorded.
+ Updated(GraphqlActivityEvent),
+ /// Activity queries must refresh after a purge.
+ Invalidated(GraphqlActivityInvalidation),
+}
+
+impl From<ActivitySubscriptionUpdate> for GraphqlActivityPatch {
+ fn from(value: ActivitySubscriptionUpdate) -> Self {
+ match value {
+ ActivitySubscriptionUpdate::Updated(record) => {
+ Self::Updated(GraphqlActivityEvent::from(record.as_ref().clone()))
+ }
+ ActivitySubscriptionUpdate::Invalidated => {
+ Self::Invalidated(GraphqlActivityInvalidation { refresh: true })
+ }
+ }
+ }
+}
+
+/// Subscribe to realtime activity addressed to the authenticated user.
+pub fn subscribe_to_activity<S: ActivitySubscriptionService>(
+ service: &S,
+ ctx: &Context<'_>,
+) -> async_graphql::Result<
+ impl Stream<Item = async_graphql::Result<GraphqlActivityPatch>> + Send + 'static,
+> {
+ let user_id = require_authenticated_user(ctx)?;
+ let mut subscription = service.subscribe(user_id.clone());
+
+ Ok(async_stream::stream! {
+ while let Some(update) = subscription.recv().await {
+ yield Ok(GraphqlActivityPatch::from(update));
+ }
+
+ match subscription.exit_reason().await {
+ ActivitySubscriptionExit::SlowConsumer => {
+ yield Err(async_graphql::Error::new(
+ "activity subscription closed because the client was too slow",
+ ));
+ }
+ ActivitySubscriptionExit::Lagging { .. } => {
+ yield Err(async_graphql::Error::new(
+ "activity subscription closed after falling behind",
+ ));
+ }
+ ActivitySubscriptionExit::Closed => {}
+ }
+ })
+}
+
+/// Root GraphQL adapter for realtime activity subscriptions.
+pub struct ActivitySubscriptionRoot<S> {
+ /// User-scoped activity subscription service.
+ service: S,
+}
+
+impl<S> ActivitySubscriptionRoot<S> {
+ /// Creates an activity subscription root backed by `service`.
+ pub fn new(service: S) -> Self {
+ Self { service }
+ }
+}
+
+#[Subscription]
+impl<S: ActivitySubscriptionService> ActivitySubscriptionRoot<S> {
+ /// Subscribe to realtime activity for the authenticated user.
+ async fn activity_updates(
+ &self,
+ ctx: &Context<'_>,
+ ) -> async_graphql::Result<
+ impl Stream<Item = async_graphql::Result<GraphqlActivityPatch>> + 'static,
+ > {
+ subscribe_to_activity(&self.service, ctx)
+ }
+}
diff --git a/crates/graphql_activity/src/subscriptions/test.rs b/crates/graphql_activity/src/subscriptions/test.rs
new file mode 100644
index 0000000000..7d3c86e0c5
--- /dev/null
+++ b/crates/graphql_activity/src/subscriptions/test.rs
@@ -0,0 +1,188 @@
+use std::{
+ collections::VecDeque,
+ sync::{Arc, Mutex},
+};
+
+use activity::{
+ Action, Activity, ActivityRecord, ActivitySubscription, Actor, CommonAction, RecordedAction,
+};
+use async_graphql::{EmptyMutation, Object, Schema};
+use chrono::Utc;
+use macro_user_id::user_id::MacroUserIdStr;
+use model_entity::EntityType;
+use uuid::Uuid;
+
+use super::*;
+
+struct Query;
+
+#[Object]
+impl Query {
+ async fn value(&self) -> bool {
+ true
+ }
+}
+
+struct TestSubscriptionService {
+ subscriptions: Mutex<VecDeque<ActivitySubscription>>,
+}
+
+impl ActivitySubscriptionService for TestSubscriptionService {
+ fn subscribe(&self, _user_id: MacroUserIdStr<'static>) -> ActivitySubscription {
+ self.subscriptions
+ .lock()
+ .expect("subscription lock")
+ .pop_front()
+ .expect("subscription opened once")
+ }
+}
+
+fn subscription(
+ exit: ActivitySubscriptionExit,
+) -> (
+ tokio::sync::mpsc::Sender<ActivitySubscriptionUpdate>,
+ ActivitySubscription,
+) {
+ let (sender, receiver) = tokio::sync::mpsc::channel(1);
+ let (exit_sender, exit_receiver) = tokio::sync::oneshot::channel();
+ exit_sender.send(exit).expect("exit receiver remains open");
+ (
+ sender,
+ ActivitySubscription::from_parts(receiver, exit_receiver),
+ )
+}
+
+fn record(user_id: &MacroUserIdStr<'static>) -> ActivityRecord {
+ let activity = Activity::common(
+ Uuid::from_u128(7),
+ 0,
+ Actor::new_from_user(user_id.clone()),
+ None,
+ EntityType::Document,
+ "doc-1",
+ CommonAction::Edited,
+ Utc::now(),
+ );
+ ActivityRecord {
+ id: activity.id,
+ actor: activity.actor.clone(),
+ subject_id: activity.subject_id.clone(),
+ entity_type: activity.entity_type,
+ entity_id: activity.entity_id.clone(),
+ action: RecordedAction::Known(Action::Edited),
+ occurred_at: activity.occurred_at,
+ }
+}
+
+#[tokio::test]
+async fn activity_updates_streams_recorded_events() {
+ let user_id = MacroUserIdStr::parse_from_str("macro|[email protected]").unwrap();
+ let (sender, subscription) = subscription(ActivitySubscriptionExit::Closed);
+ let service = TestSubscriptionService {
+ subscriptions: Mutex::new(VecDeque::from([subscription])),
+ };
+ let schema = Schema::new(Query, EmptyMutation, ActivitySubscriptionRoot::new(service));
+ let mut responses = Box::pin(schema.execute_stream(
+ async_graphql::Request::new(
+ "subscription { activityUpdates { __typename ... on GraphqlActivityEvent { id entityType entityId action { __typename } } } }",
+ )
+ .data(user_id.clone()),
+ ));
+
+ let record = record(&user_id);
+ let record_id = record.id;
+ sender
+ .send(ActivitySubscriptionUpdate::Updated(Arc::new(record)))
+ .await
+ .expect("subscription remains open");
+
+ let response = futures::StreamExt::next(&mut responses)
+ .await
+ .expect("subscription response");
+ assert!(response.errors.is_empty(), "{:?}", response.errors);
+ let data = response.data.into_json().expect("response data is JSON");
+ assert_eq!(data["activityUpdates"]["id"], record_id.to_string());
+ assert_eq!(data["activityUpdates"]["entityType"], "DOCUMENT");
+ assert_eq!(data["activityUpdates"]["entityId"], "doc-1");
+ assert_eq!(
+ data["activityUpdates"]["action"]["__typename"],
+ "GraphqlActivityEdited"
+ );
+}
+
+#[tokio::test]
+async fn activity_updates_streams_content_free_invalidation() {
+ let user_id = MacroUserIdStr::parse_from_str("macro|[email protected]").unwrap();
+ let (sender, subscription) = subscription(ActivitySubscriptionExit::Closed);
+ let service = TestSubscriptionService {
+ subscriptions: Mutex::new(VecDeque::from([subscription])),
+ };
+ let schema = Schema::new(Query, EmptyMutation, ActivitySubscriptionRoot::new(service));
+ let mut responses = Box::pin(schema.execute_stream(
+ async_graphql::Request::new(
+ "subscription { activityUpdates { __typename ... on GraphqlActivityInvalidation { refresh } } }",
+ )
+ .data(user_id),
+ ));
+
+ sender
+ .send(ActivitySubscriptionUpdate::Invalidated)
+ .await
+ .expect("subscription remains open");
+
+ let response = futures::StreamExt::next(&mut responses)
+ .await
+ .expect("subscription response");
+ assert!(response.errors.is_empty(), "{:?}", response.errors);
+ let data = response.data.into_json().expect("response data is JSON");
+ assert_eq!(
+ data["activityUpdates"]["__typename"],
+ "GraphqlActivityInvalidation"
+ );
+ assert_eq!(data["activityUpdates"]["refresh"], true);
+}
+
+#[tokio::test]
+async fn activity_updates_reports_slow_consumers() {
+ let user_id = MacroUserIdStr::parse_from_str("macro|[email protected]").unwrap();
+ let (sender, subscription) = subscription(ActivitySubscriptionExit::SlowConsumer);
+ drop(sender);
+ let service = TestSubscriptionService {
+ subscriptions: Mutex::new(VecDeque::from([subscription])),
+ };
+ let schema = Schema::new(Query, EmptyMutation, ActivitySubscriptionRoot::new(service));
+ let mut responses = Box::pin(
+ schema.execute_stream(
+ async_graphql::Request::new("subscription { activityUpdates { __typename } }")
+ .data(user_id),
+ ),
+ );
+
+ let response = futures::StreamExt::next(&mut responses)
+ .await
+ .expect("terminal error response");
+ assert!(
+ response
+ .errors
+ .iter()
+ .any(|error| error.message.contains("too slow")),
+ "{:?}",
+ response.errors
+ );
+}
+
+#[tokio::test]
+async fn activity_updates_requires_an_authenticated_user() {
+ let service = TestSubscriptionService {
+ subscriptions: Mutex::new(VecDeque::new()),
+ };
+ let schema = Schema::new(Query, EmptyMutation, ActivitySubscriptionRoot::new(service));
+ let mut responses = Box::pin(schema.execute_stream(async_graphql::Request::new(
+ "subscription { activityUpdates { __typename } }",
+ )));
+
+ let response = futures::StreamExt::next(&mut responses)
+ .await
+ .expect("error response");
+ assert!(!response.errors.is_empty());
+}
diff --git a/crates/macro_event_topics/src/lib.rs b/crates/macro_event_topics/src/lib.rs
index 12f939582b..e19c1d68fa 100644
--- a/crates/macro_event_topics/src/lib.rs
+++ b/crates/macro_event_topics/src/lib.rs
@@ -75,6 +75,8 @@ topics! {
MacroMentionsTopic => "macro.mentions",
/// Notifications awaiting delivery through WebSocket connections.
MacroNotificationsTopic => "macro.notifications",
+ /// Recorded activity rows awaiting delivery to realtime subscribers.
+ MacroActivityTopic => "macro.activity",
/// AI chat lifecycle and message events.
MacroChatsTopic => "macro.chats",
/// Calendar event changes, from provider sync and user mutations alike.
diff --git a/services/document_storage_service/src/api/context.rs b/services/document_storage_service/src/api/context.rs
index 3e6cd3d853..c32d518c1b 100644
--- a/services/document_storage_service/src/api/context.rs
+++ b/services/document_storage_service/src/api/context.rs
@@ -195,6 +195,10 @@ pub(crate) type DssNotificationRealtimeService =
model_notifications::NotifEvent,
>;
+/// Realtime activity consumer service used by GraphQL subscriptions.
+pub(crate) type DssActivityRealtimeService =
+ activity::ActivityRealtimeConsumerService<activity::ActivityTopicConsumer>;
+
/// GraphQL Soup schema wired to the DSS services; the `ApiContext` state
/// parameter lets GraphQL resolvers run the same axum extractors as the REST
/// routes, lazily, against the stored request parts.
@@ -202,6 +206,7 @@ pub(crate) type DssGraphqlSoupSchema = complete_graph::SharedSoupSchema<
DssSoupService,
DssSoupRealtimeService,
DssNotificationRealtimeService,
+ DssActivityRealtimeService,
DssEmailService,
EntityAccessService,
AuthorizationService,
diff --git a/services/document_storage_service/src/main.rs b/services/document_storage_service/src/main.rs
index 34a5ba16db..7bdd7a8c52 100644
--- a/services/document_storage_service/src/main.rs
+++ b/services/document_storage_service/src/main.rs
@@ -875,12 +875,23 @@ async fn run() -> anyhow::Result<()> {
consumer_tracker.spawn({
let cancellation_token = consumer_cancellation_token.clone();
let activity_repo = activity::outbound::pg_activity_repo::PgActivityRepo::new(db.clone());
+ let activity_realtime = activity::domain::announcements::ActivityAnnouncements::new(
+ activity::KafkaActivityRealtimePublisher::new(macro_event_broker.clone()),
+ crate::service::activity::EntityAccessActivityAudience::new(
+ entity_access_service.clone(),
+ ),
+ );
async move {
let consumer = activity::inbound::kafka_consumer::ActivityConsumer::<
_,
crate::service::activity::ActivitySourceEvent,
_,
- >::new(activity_repo, crate::service::activity::ingest);
+ _,
+ >::new(
+ activity_repo,
+ crate::service::activity::ingest,
+ activity_realtime,
+ );
loop {
if cancellation_token.is_cancelled() {
break;
@@ -1233,6 +1244,42 @@ async fn run() -> anyhow::Result<()> {
}
});
+ let activity_realtime_service = Arc::new(activity::ActivityRealtimeConsumerService::new(
+ activity::ActivityTopicConsumer::from_env(config.kafka_brokers.as_ref()).map_err(
+ |error| anyhow::anyhow!("failed to create realtime activity topic consumer: {error:?}"),
+ )?,
+ ));
+ consumer_tracker.spawn({
+ let service = Arc::clone(&activity_realtime_service);
+ let cancellation_token = consumer_cancellation_token.clone();
+ async move {
+ loop {
+ let result = tokio::select! {
+ biased;
+ _ = cancellation_token.cancelled() => break,
+ result = service.run() => result,
+ };
+
+ if cancellation_token.is_cancelled() {
+ break;
+ }
+
+ let _ = result.inspect_err(|error| {
+ tracing::error!(
+ error = ?error,
+ "realtime activity subscription consumer stopped"
+ );
+ });
+
+ tokio::select! {
+ biased;
+ _ = cancellation_token.cancelled() => break,
+ _ = tokio::time::sleep(Duration::from_secs(1)) => {}
+ }
+ }
+ }
+ });
+
let soup_realtime_service = Arc::new(SoupRealtimeConsumerService::new(
SoupTopicConsumer::from_env(config.kafka_brokers.as_ref()).map_err(|error| {
anyhow::anyhow!("failed to create realtime Soup topic consumer: {error:?}")
@@ -1466,6 +1513,7 @@ async fn run() -> anyhow::Result<()> {
soup_service,
soup_realtime_service,
websocket_notification_consumer_service,
+ activity_realtime_service,
),
graphql_notification_reader,
// GraphQL reads the activity log through the readonly pool; the
diff --git a/services/document_storage_service/src/service/activity.rs b/services/document_storage_service/src/service/activity.rs
index a9249fce99..11cec64c48 100644
--- a/services/document_storage_service/src/service/activity.rs
+++ b/services/document_storage_service/src/service/activity.rs
@@ -50,3 +50,40 @@ pub(crate) fn ingest(event: &ActivitySourceEvent) -> Ingest {
ActivitySourceEvent::CallMacroEvent(e) => arm(e.event()),
}
}
+
+/// Realtime activity audience: everyone with current access to the entity,
+/// so entity timelines (side panels) update live for watchers, not only for
+/// the acting subject.
+pub(crate) struct EntityAccessActivityAudience<S> {
+ service: std::sync::Arc<S>,
+}
+
+impl<S> EntityAccessActivityAudience<S> {
+ pub(crate) fn new(service: std::sync::Arc<S>) -> Self {
+ Self { service }
+ }
+}
+
+impl<S> activity::ActivityAudienceExpander for EntityAccessActivityAudience<S>
+where
+ S: entity_access::domain::ports::EntityAccessService,
+{
+ type Err = entity_access::domain::models::AccessError;
+
+ async fn entity_audience(
+ &self,
+ entity_type: activity::EntityType,
+ entity_id: &str,
+ ) -> Result<Vec<macro_user_id::user_id::MacroUserIdStr<'static>>, Self::Err> {
+ match self
+ .service
+ .get_users_by_entity(entity_id, entity_type)
+ .await
+ {
+ // Entity kinds without an expandable audience report BadRequest;
+ // deliver those subject-only instead of surfacing an error.
+ Err(entity_access::domain::models::AccessError::BadRequest(_)) => Ok(Vec::new()),
+ result => result,
+ }
+ }
+}
diff --git a/static_assets/schema.graphql b/static_assets/schema.graphql
index 93830ccb73..51f51b193e 100644
--- a/static_assets/schema.graphql
+++ b/static_assets/schema.graphql
@@ -134,7 +134,8 @@ type CompleteMutationRoot {
}
"""
-Root subscription object combining realtime Soup and notification adapters.
+Root subscription object combining realtime Soup, notification, and
+activity adapters.
"""
type CompleteSubscriptionRoot {
"""
@@ -145,6 +146,10 @@ type CompleteSubscriptionRoot {
Subscribe to realtime notifications for the authenticated user.
"""
notificationUpdates: GraphqlNotificationPatch!
+ """
+ Subscribe to realtime activity for the authenticated user.
+ """
+ activityUpdates: GraphqlActivityPatch!
}
"""
@@ -385,6 +390,16 @@ type GraphqlActivityEvent {
occurredAt: String!
}
+"""
+A content-free signal to refresh activity through authorized queries.
+"""
+type GraphqlActivityInvalidation {
+ """
+ True when mounted activity queries need a fresh read.
+ """
+ refresh: Boolean!
+}
+
"""
A message was sent in the entity.
"""
@@ -472,6 +487,11 @@ type GraphqlActivityParticipantRemoved {
participant: String!
}
+"""
+Realtime activity patch: a recorded event or a purge invalidation.
+"""
+union GraphqlActivityPatch = GraphqlActivityEvent | GraphqlActivityInvalidation
+
"""
A property value changed on the entity.
"""