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(calendar): expose calendarChanges and page watermarks over GraphQL (#7675)

gbirman1899b9e62fbd
diff --git a/crates/complete_graph/src/schema/test/calendar.rs b/crates/complete_graph/src/schema/test/calendar.rs
index e4dbd21bc1..c975dc99ce 100644
--- a/crates/complete_graph/src/schema/test/calendar.rs
+++ b/crates/complete_graph/src/schema/test/calendar.rs
@@ -1,6 +1,7 @@
use std::sync::{Arc, Mutex};
use calendar_events::domain::{
+ changes::{CalendarChangeQueryService, CalendarChangesPage, CalendarWatermark},
models::{
CalendarEvent, CalendarMentionPreview, CalendarMentionRequestItem, CalendarOccurrence,
CalendarOccurrenceCursor, CalendarSyncStatus, EventReminders, EventStatus, EventTime,
@@ -128,11 +129,30 @@ impl CalendarOccurrenceService for RecordingCalendarReads {
}
}
+impl CalendarChangeQueryService for RecordingCalendarReads {
+ async fn current_watermark(&self, requester_id: &str) -> Result<CalendarWatermark, Report> {
+ self.viewers.lock().unwrap().push(requester_id.to_owned());
+ Ok(CalendarWatermark::default())
+ }
+
+ async fn changes_since(
+ &self,
+ requester_id: &str,
+ _since: CalendarWatermark,
+ ) -> Result<CalendarChangesPage, Report> {
+ self.viewers.lock().unwrap().push(requester_id.to_owned());
+ Ok(CalendarChangesPage {
+ reset_required: true,
+ ..CalendarChangesPage::default()
+ })
+ }
+}
+
#[tokio::test]
async fn calendar_fields_read_through_request_data_for_the_viewer() {
let harness = harness();
let reads = Arc::new(RecordingCalendarReads::default());
- let context = CalendarGraphqlContext::new(Arc::clone(&reads));
+ let context = CalendarGraphqlContext::new(Arc::clone(&reads), Arc::clone(&reads));
let id_only = harness
.schema
@@ -157,8 +177,9 @@ async fn calendar_fields_read_through_request_data_for_the_viewer() {
start: "2026-10-05T00:00:00Z", end: "2026-10-12T00:00:00Z"
}) {
nodes { id eventId linkId event { id title } }
- hasNextPage syncStatus
+ hasNextPage syncStatus watermark { linkId seq }
}
+ calendarChanges(input: { since: [] }) { resetRequired }
} }"#,
authenticated_parts(),
)
@@ -174,10 +195,10 @@ async fn calendar_fields_read_through_request_data_for_the_viewer() {
assert_eq!(node["id"], format!("{EVENT_ID}:2026-10-06T15:00:00+00:00"));
assert_eq!(node["event"]["title"], "Planning");
assert_eq!(user["calendarOccurrences"]["syncStatus"], "READY");
- assert_eq!(
- *reads.viewers.lock().unwrap(),
- vec![VALID_USER_ID.to_owned(), VALID_USER_ID.to_owned()]
- );
+ assert_eq!(user["calendarChanges"]["resetRequired"], true);
+ let viewers = reads.viewers.lock().unwrap();
+ assert_eq!(viewers.len(), 4);
+ assert!(viewers.iter().all(|viewer| viewer == VALID_USER_ID));
}
#[tokio::test]
diff --git a/crates/complete_graph/src/sdl_test.rs b/crates/complete_graph/src/sdl_test.rs
index 3f14904080..ec0410b75d 100644
--- a/crates/complete_graph/src/sdl_test.rs
+++ b/crates/complete_graph/src/sdl_test.rs
@@ -720,6 +720,10 @@ fn calendar_reads_hang_off_the_authenticated_user() {
"calendarOccurrences(input: CalendarRangeInput!): GraphqlCalendarOccurrencePage!",
"union GraphqlEventTime = GraphqlTimedEventTime | GraphqlAllDayEventTime",
"watermark: [GraphqlCalendarLinkWatermark!]!",
+ "calendarChanges(input: CalendarChangesInput!): GraphqlCalendarChanges!",
+ "since: [CalendarLinkWatermarkInput!]!",
+ "newWatermark: [GraphqlCalendarLinkWatermark!]!",
+ "occurrences: [GraphqlCalendarOccurrence!]!",
"needsCalendarPermission: Boolean!",
"calendarDisabled: Boolean!",
"hasCalendarData: Boolean!",
@@ -756,6 +760,7 @@ fn calendar_reads_hang_off_the_authenticated_user() {
};
assert!(!root.fields.contains_key("calendars"));
assert!(!root.fields.contains_key("calendarOccurrences"));
+ assert!(!root.fields.contains_key("calendarChanges"));
}
/// The exported SDL is a frontend contract: `schema.graphql` feeds the client
diff --git a/crates/graphql_calendar/src/inputs.rs b/crates/graphql_calendar/src/inputs.rs
index 4d8ff6b2dd..d600035cde 100644
--- a/crates/graphql_calendar/src/inputs.rs
+++ b/crates/graphql_calendar/src/inputs.rs
@@ -1,6 +1,10 @@
-use async_graphql::InputObject;
-use calendar_events::domain::models::{CalendarOccurrenceCursor, OccurrenceRange};
+use async_graphql::{ID, InputObject};
+use calendar_events::domain::{
+ changes::{CalendarLinkWatermark, CalendarWatermark},
+ models::{CalendarOccurrenceCursor, OccurrenceRange},
+};
use chrono::{DateTime, NaiveDate, NaiveTime, Utc};
+use graphql_common::parse_id;
use models_pagination::Base64Str;
use crate::bad_input;
@@ -106,3 +110,41 @@ fn default_end_date(end: DateTime<Utc>) -> Option<NaiveDate> {
end.date_naive().succ_opt()
}
}
+
+/// How far the client has applied one connected inbox's change log.
+#[derive(InputObject, Clone, Debug)]
+pub struct CalendarLinkWatermarkInput {
+ /// Connected inbox identifier.
+ pub link_id: ID,
+ /// Last applied sequence, as the decimal string the server returned.
+ pub seq: String,
+}
+
+/// A request for calendar changes after a watermark.
+#[derive(InputObject, Clone, Debug)]
+pub struct CalendarChangesInput {
+ /// The client's watermark, one entry per tracked connected inbox. Empty
+ /// returns only the current watermark.
+ pub since: Vec<CalendarLinkWatermarkInput>,
+}
+
+impl CalendarChangesInput {
+ pub(crate) fn into_watermark(self) -> async_graphql::Result<CalendarWatermark> {
+ let links = self
+ .since
+ .into_iter()
+ .map(|link| {
+ let link_id = parse_id(link.link_id, "since.linkId")
+ .map_err(|_| bad_input("since.linkId must be a UUID"))?;
+ let seq = link
+ .seq
+ .parse::<i64>()
+ .ok()
+ .filter(|seq| *seq >= 0)
+ .ok_or_else(|| bad_input("since.seq must be a non-negative integer"))?;
+ Ok(CalendarLinkWatermark { link_id, seq })
+ })
+ .collect::<async_graphql::Result<Vec<_>>>()?;
+ Ok(CalendarWatermark::from_links(links))
+ }
+}
diff --git a/crates/graphql_calendar/src/lib.rs b/crates/graphql_calendar/src/lib.rs
index 522c9776a6..767dc44cac 100644
--- a/crates/graphql_calendar/src/lib.rs
+++ b/crates/graphql_calendar/src/lib.rs
@@ -9,10 +9,11 @@ mod reads;
mod test_fixtures;
mod user_query;
-pub use inputs::CalendarRangeInput;
+pub use inputs::{CalendarChangesInput, CalendarLinkWatermarkInput, CalendarRangeInput};
pub use objects::{
GraphqlAllDayEventTime, GraphqlCalendar, GraphqlCalendarAttendee,
- GraphqlCalendarAttendeeResponseStatus, GraphqlCalendarConferenceProvider, GraphqlCalendarEvent,
+ GraphqlCalendarAttendeeResponseStatus, GraphqlCalendarChanges,
+ GraphqlCalendarConferenceProvider, GraphqlCalendarEvent, GraphqlCalendarEventChange,
GraphqlCalendarEventSource, GraphqlCalendarEventStatus, GraphqlCalendarEventTransparency,
GraphqlCalendarEventType, GraphqlCalendarEventVisibility, GraphqlCalendarLinkWatermark,
GraphqlCalendarOccurrence, GraphqlCalendarOccurrencePage, GraphqlCalendarReminderOverride,
diff --git a/crates/graphql_calendar/src/objects.rs b/crates/graphql_calendar/src/objects.rs
index 355bb45d78..346365f45c 100644
--- a/crates/graphql_calendar/src/objects.rs
+++ b/crates/graphql_calendar/src/objects.rs
@@ -1,9 +1,14 @@
+use std::{collections::HashMap, sync::Arc};
+
use async_graphql::{Enum, ID, SimpleObject, Union};
-use calendar_events::domain::models::{
- AttendeeResponseStatus, CalendarAttendee, CalendarEvent, CalendarEventSourceContent,
- CalendarOccurrence, CalendarSyncStatus, ConferenceProvider, EventReminderOverride,
- EventReminders, EventStatus, EventTime, EventTransparency, EventType, EventVisibility,
- OccurrenceListing, VisibleCalendar,
+use calendar_events::domain::{
+ changes::{CalendarChangesPage, CalendarEventChange, CalendarWatermark},
+ models::{
+ AttendeeResponseStatus, CalendarAttendee, CalendarEvent, CalendarEventSourceContent,
+ CalendarOccurrence, CalendarSyncStatus, ConferenceProvider, EventReminderOverride,
+ EventReminders, EventStatus, EventTime, EventTransparency, EventType, EventVisibility,
+ OccurrenceException, OccurrenceListing, VisibleCalendar,
+ },
};
use uuid::Uuid;
@@ -437,7 +442,7 @@ pub struct GraphqlCalendarOccurrence {
/// Connected inbox whose grant backs the event.
link_id: ID,
/// The series event.
- event: GraphqlCalendarEvent,
+ event: Arc<GraphqlCalendarEvent>,
/// Stable key within the event.
occurrence_key: String,
/// Provider recurrence identifier, when applicable.
@@ -459,14 +464,13 @@ pub struct GraphqlCalendarOccurrence {
override_attendees: Option<Vec<GraphqlCalendarAttendee>>,
}
-impl From<OccurrenceListing> for GraphqlCalendarOccurrence {
- fn from(listing: OccurrenceListing) -> Self {
- let OccurrenceListing {
- event,
- occurrence,
- link_id,
- exception,
- } = listing;
+impl GraphqlCalendarOccurrence {
+ fn new(
+ event: Arc<GraphqlCalendarEvent>,
+ link_id: Uuid,
+ occurrence: CalendarOccurrence,
+ exception: OccurrenceException,
+ ) -> Self {
let CalendarOccurrence {
event_id,
occurrence_key,
@@ -478,7 +482,7 @@ impl From<OccurrenceListing> for GraphqlCalendarOccurrence {
id: occurrence_id(event_id, &occurrence_key),
event_id: id(event_id),
link_id: id(link_id),
- event: GraphqlCalendarEvent::new(event, link_id),
+ event,
occurrence_key,
recurrence_id,
time: time.into(),
@@ -494,6 +498,29 @@ impl From<OccurrenceListing> for GraphqlCalendarOccurrence {
}
}
+/// Map viewport listings, sharing one series event per event among its
+/// occurrences.
+pub(crate) fn occurrence_nodes(listings: Vec<OccurrenceListing>) -> Vec<GraphqlCalendarOccurrence> {
+ let mut events: HashMap<Uuid, Arc<GraphqlCalendarEvent>> = HashMap::new();
+ listings
+ .into_iter()
+ .map(|listing| {
+ let OccurrenceListing {
+ event,
+ occurrence,
+ link_id,
+ exception,
+ } = listing;
+ let event = Arc::clone(
+ events
+ .entry(event.id)
+ .or_insert_with(|| Arc::new(GraphqlCalendarEvent::new(event, link_id))),
+ );
+ GraphqlCalendarOccurrence::new(event, link_id, occurrence, exception)
+ })
+ .collect()
+}
+
/// A calendar visible to the viewer.
#[derive(SimpleObject, Clone, Debug, PartialEq, Eq)]
pub struct GraphqlCalendar {
@@ -550,6 +577,89 @@ pub struct GraphqlCalendarLinkWatermark {
pub(crate) seq: String,
}
+pub(crate) fn watermark_entries(
+ watermark: &CalendarWatermark,
+) -> Vec<GraphqlCalendarLinkWatermark> {
+ watermark
+ .links()
+ .map(|link| GraphqlCalendarLinkWatermark {
+ link_id: id(link.link_id),
+ seq: link.seq.to_string(),
+ })
+ .collect()
+}
+
+/// A changed event with its complete current set of visible occurrences.
+/// Clients replace everything they hold for the event with it.
+#[derive(SimpleObject, Clone, Debug, PartialEq, Eq)]
+pub struct GraphqlCalendarEventChange {
+ /// The series event.
+ event: Arc<GraphqlCalendarEvent>,
+ /// Every non-cancelled materialized occurrence, ordered by start.
+ occurrences: Vec<GraphqlCalendarOccurrence>,
+}
+
+impl From<CalendarEventChange> for GraphqlCalendarEventChange {
+ fn from(change: CalendarEventChange) -> Self {
+ let CalendarEventChange {
+ event,
+ link_id,
+ occurrences,
+ } = change;
+ let event = Arc::new(GraphqlCalendarEvent::new(event, link_id));
+ Self {
+ occurrences: occurrences
+ .into_iter()
+ .map(|instance| {
+ GraphqlCalendarOccurrence::new(
+ Arc::clone(&event),
+ link_id,
+ instance.occurrence,
+ instance.exception,
+ )
+ })
+ .collect(),
+ event,
+ }
+ }
+}
+
+/// One bounded page of calendar changes after a watermark.
+#[derive(SimpleObject, Clone, Debug, PartialEq, Eq)]
+pub struct GraphqlCalendarChanges {
+ /// Events created or changed, each with its full occurrence set.
+ events: Vec<GraphqlCalendarEventChange>,
+ /// Events that no longer exist or no longer have a visible occurrence.
+ deleted_event_ids: Vec<ID>,
+ /// Calendars created or changed.
+ calendars: Vec<GraphqlCalendar>,
+ /// Calendars that were removed.
+ deleted_calendar_ids: Vec<ID>,
+ /// Position after this page, one entry per currently visible connected
+ /// inbox. An inbox missing here is no longer visible.
+ new_watermark: Vec<GraphqlCalendarLinkWatermark>,
+ /// Whether more changes follow `newWatermark`.
+ has_more: bool,
+ /// Whether the client must drop every calendar record and coverage it
+ /// holds and refetch: its watermark fell behind retention, or an inbox
+ /// became visible that it never tracked.
+ reset_required: bool,
+}
+
+impl From<CalendarChangesPage> for GraphqlCalendarChanges {
+ fn from(page: CalendarChangesPage) -> Self {
+ Self {
+ events: page.events.into_iter().map(Into::into).collect(),
+ deleted_event_ids: page.deleted_event_ids.into_iter().map(id).collect(),
+ calendars: page.calendars.into_iter().map(Into::into).collect(),
+ deleted_calendar_ids: page.deleted_calendar_ids.into_iter().map(id).collect(),
+ new_watermark: watermark_entries(&page.new_watermark),
+ has_more: page.has_more,
+ reset_required: page.reset_required,
+ }
+ }
+}
+
/// One page of occurrences overlapping a viewport.
#[derive(SimpleObject, Clone, Debug, PartialEq, Eq)]
pub struct GraphqlCalendarOccurrencePage {
diff --git a/crates/graphql_calendar/src/objects/test.rs b/crates/graphql_calendar/src/objects/test.rs
index 4370d3b05d..924069a0de 100644
--- a/crates/graphql_calendar/src/objects/test.rs
+++ b/crates/graphql_calendar/src/objects/test.rs
@@ -12,7 +12,7 @@ fn occurrence_identity_composes_event_id_and_occurrence_key() {
let listing = timed_listing(7);
let key = listing.occurrence.occurrence_key.clone();
- let occurrence = GraphqlCalendarOccurrence::from(listing);
+ let occurrence = occurrence_nodes(vec![listing]).remove(0);
assert_eq!(occurrence.id, ID(format!("{EVENT_ID}:{key}")));
assert_eq!(occurrence.event_id, ID(EVENT_ID.to_string()));
@@ -35,7 +35,7 @@ fn exception_stays_on_the_occurrence_and_the_event_keeps_series_content() {
)]),
};
- let occurrence = GraphqlCalendarOccurrence::from(listing);
+ let occurrence = occurrence_nodes(vec![listing]).remove(0);
assert_eq!(occurrence.event.title, "Standup");
assert_eq!(
@@ -58,7 +58,7 @@ fn exception_stays_on_the_occurrence_and_the_event_keeps_series_content() {
#[test]
fn occurrence_without_exception_inherits_everything() {
- let occurrence = GraphqlCalendarOccurrence::from(timed_listing(8));
+ let occurrence = occurrence_nodes(vec![timed_listing(8)]).remove(0);
assert_eq!(occurrence.override_title, None);
assert_eq!(occurrence.override_status, None);
diff --git a/crates/graphql_calendar/src/reads.rs b/crates/graphql_calendar/src/reads.rs
index ecb0108438..4b975c60ce 100644
--- a/crates/graphql_calendar/src/reads.rs
+++ b/crates/graphql_calendar/src/reads.rs
@@ -1,6 +1,7 @@
use std::{future::Future, pin::Pin, sync::Arc};
use calendar_events::domain::{
+ changes::{CalendarChangeQueryService, CalendarChangesPage, CalendarWatermark},
models::{
CalendarOccurrenceCursor, CalendarSyncStatus, OccurrenceListing, OccurrenceRange,
VisibleCalendar,
@@ -11,8 +12,8 @@ use rootcause::Report;
pub(crate) type ReadFuture<'a, T> = Pin<Box<dyn Future<Output = Result<T, Report>> + Send + 'a>>;
-/// Object-safe view of the calendar read service, so request data does not
-/// carry the service's type parameters.
+/// Object-safe view of the calendar read services, so request data does not
+/// carry their type parameters.
pub(crate) trait CalendarGraphqlReads: Send + Sync {
fn list_occurrences(
&self,
@@ -25,28 +26,49 @@ pub(crate) trait CalendarGraphqlReads: Send + Sync {
fn sync_status(&self, viewer: String) -> ReadFuture<'_, CalendarSyncStatus>;
fn list_visible_calendars(&self, viewer: String) -> ReadFuture<'_, Vec<VisibleCalendar>>;
+
+ fn current_watermark(&self, viewer: String) -> ReadFuture<'_, CalendarWatermark>;
+
+ fn changes_since(
+ &self,
+ viewer: String,
+ since: CalendarWatermark,
+ ) -> ReadFuture<'_, CalendarChangesPage>;
}
-/// Type-erased calendar read service stored in GraphQL request data.
+/// Type-erased calendar read services stored in GraphQL request data.
#[derive(Clone)]
pub struct CalendarGraphqlContext {
pub(crate) reads: Arc<dyn CalendarGraphqlReads>,
}
impl CalendarGraphqlContext {
- /// Erase `service` so request data does not carry its type parameters.
- pub fn new<S: CalendarOccurrenceService>(service: Arc<S>) -> Self {
+ /// Erase the occurrence and change-log services so request data does not
+ /// carry their type parameters.
+ pub fn new<S, C>(occurrences: Arc<S>, changes: Arc<C>) -> Self
+ where
+ S: CalendarOccurrenceService,
+ C: CalendarChangeQueryService,
+ {
Self {
- reads: Arc::new(OccurrenceServiceReads { service }),
+ reads: Arc::new(ServiceReads {
+ occurrences,
+ changes,
+ }),
}
}
}
-struct OccurrenceServiceReads<S> {
- service: Arc<S>,
+struct ServiceReads<S, C> {
+ occurrences: Arc<S>,
+ changes: Arc<C>,
}
-impl<S: CalendarOccurrenceService> CalendarGraphqlReads for OccurrenceServiceReads<S> {
+impl<S, C> CalendarGraphqlReads for ServiceReads<S, C>
+where
+ S: CalendarOccurrenceService,
+ C: CalendarChangeQueryService,
+{
fn list_occurrences(
&self,
viewer: String,
@@ -55,17 +77,29 @@ impl<S: CalendarOccurrenceService> CalendarGraphqlReads for OccurrenceServiceRea
limit: u16,
) -> ReadFuture<'_, Vec<OccurrenceListing>> {
Box::pin(async move {
- self.service
+ self.occurrences
.list_occurrences(&viewer, range, cursor, limit)
.await
})
}
fn sync_status(&self, viewer: String) -> ReadFuture<'_, CalendarSyncStatus> {
- Box::pin(async move { self.service.sync_status(&viewer).await })
+ Box::pin(async move { self.occurrences.sync_status(&viewer).await })
}
fn list_visible_calendars(&self, viewer: String) -> ReadFuture<'_, Vec<VisibleCalendar>> {
- Box::pin(async move { self.service.list_visible_calendars(&viewer).await })
+ Box::pin(async move { self.occurrences.list_visible_calendars(&viewer).await })
+ }
+
+ fn current_watermark(&self, viewer: String) -> ReadFuture<'_, CalendarWatermark> {
+ Box::pin(async move { self.changes.current_watermark(&viewer).await })
+ }
+
+ fn changes_since(
+ &self,
+ viewer: String,
+ since: CalendarWatermark,
+ ) -> ReadFuture<'_, CalendarChangesPage> {
+ Box::pin(async move { self.changes.changes_since(&viewer, since).await })
}
}
diff --git a/crates/graphql_calendar/src/user_query.rs b/crates/graphql_calendar/src/user_query.rs
index 66eff77f69..110d85b9eb 100644
--- a/crates/graphql_calendar/src/user_query.rs
+++ b/crates/graphql_calendar/src/user_query.rs
@@ -5,8 +5,11 @@ use rootcause::Report;
use crate::{
CalendarGraphqlContext, bad_input,
- inputs::{CalendarRangeInput, encode_cursor},
- objects::{GraphqlCalendar, GraphqlCalendarOccurrence, GraphqlCalendarOccurrencePage},
+ inputs::{CalendarChangesInput, CalendarRangeInput, encode_cursor},
+ objects::{
+ GraphqlCalendar, GraphqlCalendarChanges, GraphqlCalendarOccurrencePage, occurrence_nodes,
+ watermark_entries,
+ },
unavailable,
};
@@ -46,7 +49,8 @@ impl GraphqlCalendarQuery {
}
/// One page of occurrences overlapping the viewport, across owned and
- /// delegated inboxes, ordered by start.
+ /// delegated inboxes, ordered by start. `watermark` is read before the
+ /// occurrences, so the page reflects at least every change it covers.
#[tracing::instrument(skip_all, err(Debug))]
async fn calendar_occurrences(
&self,
@@ -56,6 +60,10 @@ impl GraphqlCalendarQuery {
let reads = &ctx.data::<CalendarGraphqlContext>()?.reads;
let request = input.into_page_request()?;
let page_size = usize::from(request.page_size);
+ let watermark = reads
+ .current_watermark(self.viewer())
+ .await
+ .map_err(|error| unavailable(error, "calendar occurrences are unavailable"))?;
let (mut rows, sync_status) = futures::try_join!(
reads.list_occurrences(
self.viewer(),
@@ -74,16 +82,30 @@ impl GraphqlCalendarQuery {
))
});
Ok(GraphqlCalendarOccurrencePage {
- nodes: rows
- .into_iter()
- .map(GraphqlCalendarOccurrence::from)
- .collect(),
+ nodes: occurrence_nodes(rows),
has_next_page,
end_cursor,
sync_status: sync_status.into(),
- watermark: Vec::new(),
+ watermark: watermark_entries(&watermark),
})
}
+
+ /// Changes to the viewer's calendars after `since`, one bounded page at a
+ /// time. An empty `since` returns only the current watermark.
+ #[tracing::instrument(skip_all, err(Debug))]
+ async fn calendar_changes(
+ &self,
+ ctx: &Context<'_>,
+ input: CalendarChangesInput,
+ ) -> async_graphql::Result<GraphqlCalendarChanges> {
+ let reads = &ctx.data::<CalendarGraphqlContext>()?.reads;
+ let since = input.into_watermark()?;
+ reads
+ .changes_since(self.viewer(), since)
+ .await
+ .map(Into::into)
+ .map_err(|error| unavailable(error, "calendar changes are unavailable"))
+ }
}
fn occurrences_error(error: Report) -> async_graphql::Error {
diff --git a/crates/graphql_calendar/src/user_query/test.rs b/crates/graphql_calendar/src/user_query/test.rs
index d69ec552e1..2b660d3277 100644
--- a/crates/graphql_calendar/src/user_query/test.rs
+++ b/crates/graphql_calendar/src/user_query/test.rs
@@ -2,6 +2,10 @@ use std::sync::{Arc, Mutex};
use async_graphql::{EmptyMutation, EmptySubscription, Schema};
use calendar_events::domain::{
+ changes::{
+ CalendarChangeQueryService, CalendarChangesPage, CalendarEventChange,
+ CalendarLinkWatermark, CalendarWatermark, EventOccurrence,
+ },
models::{
CalendarMentionPreview, CalendarMentionRequestItem, CalendarOccurrenceCursor,
CalendarSyncStatus, OccurrenceListing, OccurrenceRange, TeamOutOfOffice, VisibleCalendar,
@@ -31,8 +35,12 @@ enum Failure {
struct FakeReads {
listings: Vec<OccurrenceListing>,
calendars: Vec<VisibleCalendar>,
+ watermark: CalendarWatermark,
+ changes: CalendarChangesPage,
failure: Failure,
requests: Mutex<Vec<(String, Option<CalendarOccurrenceCursor>, u16)>>,
+ calls: Mutex<Vec<&'static str>>,
+ since: Mutex<Vec<CalendarWatermark>>,
}
impl FakeReads {
@@ -59,6 +67,7 @@ impl CalendarOccurrenceService for FakeReads {
.lock()
.unwrap()
.push((requester_id.to_owned(), cursor, limit));
+ self.calls.lock().unwrap().push("occurrences");
self.fail()?;
Ok(self
.listings
@@ -106,6 +115,23 @@ impl CalendarOccurrenceService for FakeReads {
}
}
+impl CalendarChangeQueryService for FakeReads {
+ async fn current_watermark(&self, _viewer: &str) -> Result<CalendarWatermark, Report> {
+ self.calls.lock().unwrap().push("watermark");
+ Ok(self.watermark.clone())
+ }
+
+ async fn changes_since(
+ &self,
+ _viewer: &str,
+ since: CalendarWatermark,
+ ) -> Result<CalendarChangesPage, Report> {
+ self.since.lock().unwrap().push(since);
+ self.fail()?;
+ Ok(self.changes.clone())
+ }
+}
+
const VIEWER: &str = "macro|[email protected]";
async fn execute(reads: Arc<FakeReads>, query: &str) -> async_graphql::Response {
@@ -114,7 +140,7 @@ async fn execute(reads: Arc<FakeReads>, query: &str) -> async_graphql::Response
EmptyMutation,
EmptySubscription,
)
- .data(CalendarGraphqlContext::new(reads))
+ .data(CalendarGraphqlContext::new(Arc::clone(&reads), reads))
.finish();
schema.execute(query).await
}
@@ -159,6 +185,11 @@ async fn a_full_page_reports_a_cursor_and_requests_one_extra_row() {
assert_eq!(page["hasNextPage"], true);
assert_eq!(page["syncStatus"], "SYNCING");
assert_eq!(page["watermark"], Value::Array(Vec::new()));
+ assert_eq!(
+ reads.calls.lock().unwrap()[..2],
+ ["watermark", "occurrences"],
+ "the watermark is captured before the page is read"
+ );
let cursor = page["endCursor"].as_str().unwrap().to_owned();
let requests = reads.requests.lock().unwrap().clone();
@@ -271,3 +302,165 @@ async fn infrastructure_failures_are_masked() {
);
}
}
+
+#[tokio::test]
+async fn pages_report_the_watermark_as_decimal_strings() {
+ let reads = Arc::new(FakeReads {
+ listings: vec![timed_listing(6)],
+ watermark: CalendarWatermark::from_links([CalendarLinkWatermark {
+ link_id: LINK_ID,
+ seq: 9_007_199_254_740_993,
+ }]),
+ ..Default::default()
+ });
+
+ let response = execute(reads, PAGE_QUERY).await;
+
+ assert!(response.errors.is_empty(), "{:?}", response.errors);
+ let data = response.data.into_json().unwrap();
+ assert_eq!(
+ data["calendarOccurrences"]["watermark"],
+ serde_json::json!([{ "linkId": LINK_ID.to_string(), "seq": "9007199254740993" }])
+ );
+}
+
+#[tokio::test]
+async fn occurrences_of_one_event_share_the_series_event() {
+ let reads = Arc::new(FakeReads {
+ listings: vec![timed_listing(6), timed_listing(7)],
+ ..Default::default()
+ });
+
+ let response = execute(reads, PAGE_QUERY).await;
+
+ let data = response.data.into_json().unwrap();
+ let nodes = data["calendarOccurrences"]["nodes"].as_array().unwrap();
+ assert_eq!(nodes[0]["event"], nodes[1]["event"]);
+}
+
+const CHANGES_QUERY: &str = r#"{
+ calendarChanges(input: { since: [{ linkId: "LINK", seq: "4" }] }) {
+ events {
+ event { __typename id linkId }
+ occurrences { id eventId linkId event { id } }
+ }
+ deletedEventIds
+ calendars { id }
+ deletedCalendarIds
+ newWatermark { linkId seq }
+ hasMore
+ resetRequired
+ }
+}"#;
+
+fn changes_query() -> String {
+ CHANGES_QUERY.replace("LINK", &LINK_ID.to_string())
+}
+
+#[tokio::test]
+async fn changes_map_the_page_and_parse_the_watermark() {
+ let listing = timed_listing(6);
+ let deleted_event = uuid::Uuid::from_u128(0x99);
+ let deleted_calendar = uuid::Uuid::from_u128(0x98);
+ let reads = Arc::new(FakeReads {
+ changes: CalendarChangesPage {
+ events: vec![CalendarEventChange {
+ event: listing.event.clone(),
+ link_id: LINK_ID,
+ occurrences: vec![EventOccurrence {
+ occurrence: listing.occurrence.clone(),
+ exception: listing.exception.clone(),
+ }],
+ }],
+ deleted_event_ids: vec![deleted_event],
+ calendars: Vec::new(),
+ deleted_calendar_ids: vec![deleted_calendar],
+ new_watermark: CalendarWatermark::from_links([CalendarLinkWatermark {
+ link_id: LINK_ID,
+ seq: 12,
+ }]),
+ has_more: true,
+ reset_required: false,
+ },
+ ..Default::default()
+ });
+
+ let response = execute(Arc::clone(&reads), &changes_query()).await;
+
+ assert!(response.errors.is_empty(), "{:?}", response.errors);
+ let data = response.data.into_json().unwrap();
+ let changes = &data["calendarChanges"];
+ assert_eq!(
+ changes["events"][0]["event"]["__typename"],
+ "GraphqlCalendarEvent"
+ );
+ assert_eq!(changes["events"][0]["event"]["id"], EVENT_ID.to_string());
+ let occurrence = &changes["events"][0]["occurrences"][0];
+ assert_eq!(
+ occurrence["id"],
+ format!("{EVENT_ID}:2026-10-06T15:00:00+00:00")
+ );
+ assert_eq!(occurrence["event"]["id"], EVENT_ID.to_string());
+ assert_eq!(changes["deletedEventIds"][0], deleted_event.to_string());
+ assert_eq!(
+ changes["deletedCalendarIds"][0],
+ deleted_calendar.to_string()
+ );
+ assert_eq!(
+ changes["newWatermark"],
+ serde_json::json!([{ "linkId": LINK_ID.to_string(), "seq": "12" }])
+ );
+ assert_eq!(changes["hasMore"], true);
+ assert_eq!(changes["resetRequired"], false);
+ assert_eq!(
+ *reads.since.lock().unwrap(),
+ vec![CalendarWatermark::from_links([CalendarLinkWatermark {
+ link_id: LINK_ID,
+ seq: 4,
+ }])]
+ );
+}
+
+#[tokio::test]
+async fn a_malformed_watermark_is_a_user_error() {
+ for since in [
+ r#"[{ linkId: "not-a-uuid", seq: "1" }]"#.to_owned(),
+ format!(r#"[{{ linkId: "{LINK_ID}", seq: "-1" }}]"#),
+ format!(r#"[{{ linkId: "{LINK_ID}", seq: "one" }}]"#),
+ ] {
+ let reads = Arc::new(FakeReads::default());
+ let response = execute(
+ Arc::clone(&reads),
+ &format!("{{ calendarChanges(input: {{ since: {since} }}) {{ hasMore }} }}"),
+ )
+ .await;
+
+ assert_eq!(
+ response.errors[0]
+ .extensions
+ .as_ref()
+ .unwrap()
+ .get("code")
+ .unwrap()
+ .to_string(),
+ "\"BAD_USER_INPUT\"",
+ "{since}"
+ );
+ assert!(reads.since.lock().unwrap().is_empty());
+ }
+}
+
+#[tokio::test]
+async fn change_failures_are_masked() {
+ let reads = Arc::new(FakeReads {
+ failure: Failure::Internal,
+ ..Default::default()
+ });
+
+ let response = execute(reads, &changes_query()).await;
+
+ assert_eq!(
+ response.errors[0].message,
+ "calendar changes are unavailable"
+ );
+}
diff --git a/services/document_storage_service/src/server.rs b/services/document_storage_service/src/server.rs
index c3156e4d01..ea2b141460 100644
--- a/services/document_storage_service/src/server.rs
+++ b/services/document_storage_service/src/server.rs
@@ -1734,8 +1734,14 @@ pub async fn run() -> anyhow::Result<()> {
let calendar_read_service = Arc::new(calendar_events::domain::service::CalendarService::new(
calendar_events::outbound::pg::PgCalendarRepository::new(readonly_db.clone()),
));
- let graphql_calendar_context =
- graphql_calendar::CalendarGraphqlContext::new(calendar_read_service.clone());
+ let graphql_calendar_context = graphql_calendar::CalendarGraphqlContext::new(
+ calendar_read_service.clone(),
+ Arc::new(
+ calendar_events::domain::changes::CalendarChangeService::new(
+ calendar_events::outbound::pg::PgCalendarRepository::new(readonly_db.clone()),
+ ),
+ ),
+ );
let calendar_state =
CalendarRouterState::new(calendar_read_service, authorization_state.clone());
diff --git a/static_assets/schema.graphql b/static_assets/schema.graphql
index 99c70ef430..f2cd7c5a25 100644
--- a/static_assets/schema.graphql
+++ b/static_assets/schema.graphql
@@ -23,6 +23,31 @@ input ActivityOverviewInput {
timeZone: String
}
+"""
+A request for calendar changes after a watermark.
+"""
+input CalendarChangesInput {
+ """
+ The client's watermark, one entry per tracked connected inbox. Empty
+ returns only the current watermark.
+ """
+ since: [CalendarLinkWatermarkInput!]!
+}
+
+"""
+How far the client has applied one connected inbox's change log.
+"""
+input CalendarLinkWatermarkInput {
+ """
+ Connected inbox identifier.
+ """
+ linkId: ID!
+ """
+ Last applied sequence, as the decimal string the server returned.
+ """
+ seq: String!
+}
+
"""
A bounded occurrence viewport and page request.
"""
@@ -1105,6 +1130,43 @@ enum GraphqlCalendarAttendeeResponseStatus {
TENTATIVE
}
+"""
+One bounded page of calendar changes after a watermark.
+"""
+type GraphqlCalendarChanges {
+ """
+ Events created or changed, each with its full occurrence set.
+ """
+ events: [GraphqlCalendarEventChange!]!
+ """
+ Events that no longer exist or no longer have a visible occurrence.
+ """
+ deletedEventIds: [ID!]!
+ """
+ Calendars created or changed.
+ """
+ calendars: [GraphqlCalendar!]!
+ """
+ Calendars that were removed.
+ """
+ deletedCalendarIds: [ID!]!
+ """
+ Position after this page, one entry per currently visible connected
+ inbox. An inbox missing here is no longer visible.
+ """
+ newWatermark: [GraphqlCalendarLinkWatermark!]!
+ """
+ Whether more changes follow `newWatermark`.
+ """
+ hasMore: Boolean!
+ """
+ Whether the client must drop every calendar record and coverage it
+ holds and refetch: its watermark fell behind retention, or an inbox
+ became visible that it never tracked.
+ """
+ resetRequired: Boolean!
+}
+
"""
Conferencing system backing an event's join URL.
"""
@@ -1247,6 +1309,21 @@ input GraphqlCalendarEventBinaryExpr {
right: GraphqlCalendarEventExpr!
}
+"""
+A changed event with its complete current set of visible occurrences.
+Clients replace everything they hold for the event with it.
+"""
+type GraphqlCalendarEventChange {
+ """
+ The series event.
+ """
+ event: GraphqlCalendarEvent!
+ """
+ Every non-cancelled materialized occurrence, ordered by start.
+ """
+ occurrences: [GraphqlCalendarOccurrence!]!
+}
+
"""
A recursive `CalendarEventFilterExpr` filter expression.
"""
@@ -7806,10 +7883,16 @@ type GraphqlUser {
calendars: [GraphqlCalendar!]!
"""
One page of occurrences overlapping the viewport, across owned and
- delegated inboxes, ordered by start.
+ delegated inboxes, ordered by start. `watermark` is read before the
+ occurrences, so the page reflects at least every change it covers.
"""
calendarOccurrences(input: CalendarRangeInput!): GraphqlCalendarOccurrencePage!
"""
+ Changes to the viewer's calendars after `since`, one bounded page at a
+ time. An empty `since` returns only the current watermark.
+ """
+ calendarChanges(input: CalendarChangesInput!): GraphqlCalendarChanges!
+ """
Labels across every owned or delegated inbox accessible to the authenticated user.
"""
emailLabels: [GraphqlSoupEmailLabel!]!