Skip to main content

jmap_chat_server/memory/
history.rs

1//! Object history for the memory backend (draft-ietf-jmap-object-history-03
2//! with the -04 editor's copy changes; docs/design/object-history.md §7),
3//! for Chat, Message, Space, `ChatContact`, `CustomEmoji`, `SpaceBan`, `ChatBan` and
4//! `SpaceInvite` (`ReadPosition` and `PresenceStatus` are excluded, decision 22).
5//!
6//! Two chat-00 rules (decision 22): a Message's versions are purged when it
7//! is deleted (`deletedAt` set) or hard-deleted, so a Message is never a
8//! destroyed object; and a Space destroy purges the history of the Space
9//! and everything in it, so a Space is never restored.
10//!
11//! Off until [`MemoryBackend::with_object_history`]. Versions live in a
12//! `jmap_object_history_server::HistoryStore` inside the scoped state, so a
13//! conditional rollback discards them with the rest.
14
15use std::collections::HashMap;
16
17use jmap_object_history_server::{HistoryRetention, HistoryStore};
18use jmap_object_history_types::{HistoryEntry, HistoryObject, ObjectHistoryAccountCapability};
19use jmap_server::{
20    AddedItem, BackendChangesError, BackendQueryError, BackendSetError,
21    DestroyedQueryChangesParams, DestroyedQueryParams, HistoryGetParams, HistoryGetResult,
22    MemoryCaller, ObjectHistoryBackend, QueryChangesResult, QueryObject, QueryResult, Restored,
23    SetError, SetErrorType, SetObject, apply_restore_patch, limit_or_max, resolve_query_start,
24};
25use jmap_types::{Id, JmapError, PatchObject, State, UTCDate};
26use serde_json::Value;
27
28use super::{ChangeEntry, Inner, MemoryBackend, MemoryError, emoji_name_holder};
29
30/// The types this backend keeps history for.
31const SUPPORTED: &[&str] = &[
32    "Chat",
33    "Message",
34    "Space",
35    "ChatContact",
36    "CustomEmoji",
37    "SpaceBan",
38    "ChatBan",
39    "SpaceInvite",
40];
41
42impl Inner {
43    fn prune_history(&mut self) {
44        if let Some(h) = self.history.as_mut() {
45            h.prune();
46        }
47    }
48
49    /// Destroyed objects in result order, most recently destroyed first
50    /// (§4). This backend evaluates no filter or sort over destroyed chat
51    /// objects: any filter is `unsupportedFilter` and any sort
52    /// `unsupportedSort` (§4: "The server need not support every filter
53    /// condition or comparator for destroyed objects").
54    fn destroyed_results<O: QueryObject>(
55        &self,
56        account: &Id,
57        after: Option<&UTCDate>,
58        before: Option<&UTCDate>,
59        filter: Option<&O::Filter>,
60        sort: Option<&[O::Comparator]>,
61    ) -> Result<Vec<Id>, BackendQueryError<MemoryError>> {
62        let Some(h) = self.history.as_ref() else {
63            return Ok(Vec::new());
64        };
65        if sort.is_some_and(|s| !s.is_empty()) {
66            return Err(BackendQueryError::Method(JmapError::unsupported_sort()));
67        }
68        if filter.is_some() {
69            return Err(BackendQueryError::Method(JmapError::unsupported_filter()));
70        }
71        Ok(h.destroyed(O::TYPE_NAME, account, after, before)
72            .map_err(|e| BackendQueryError::Method(JmapError::invalid_arguments(e.to_string())))?
73            .into_iter()
74            .map(|d| d.id)
75            .collect())
76    }
77
78    /// chat-00 §Message (decision 22): forget every version of `id`.
79    pub(super) fn purge_message_history(&mut self, account: &Id, id: &Id) {
80        if let Some(h) = self.history.as_mut() {
81            h.purge("Message", account, id);
82        }
83    }
84
85    /// chat-00 §Space/set "Hard-deletes all records; no tombstones are
86    /// retained" (decision 22): forget the history of the Space, of the
87    /// Chats `chat_ids` and every Chat, `SpaceBan`, `SpaceInvite` and
88    /// `CustomEmoji` whose newest version names the Space, and of every
89    /// Message in those Chats.
90    pub(super) fn purge_space_history(&mut self, account: &Id, space: &Id, chat_ids: &[Id]) {
91        let Some(h) = self.history.as_mut() else {
92            return;
93        };
94        h.purge("Space", account, space);
95        let in_space = |v: &Value| v.get("spaceId").and_then(Value::as_str) == Some(space.as_ref());
96        let mut chats: Vec<Id> = chat_ids.to_vec();
97        for t in ["SpaceBan", "SpaceInvite", "CustomEmoji"] {
98            h.purge_where(t, account, in_space);
99        }
100        h.purge_where("Chat", account, |v| {
101            let hit = in_space(v);
102            if hit && let Some(id) = v.get("id").and_then(Value::as_str) {
103                chats.push(Id::from(id));
104            }
105            hit
106        });
107        for chat in &chats {
108            h.purge("Chat", account, chat);
109        }
110        h.purge_where("Message", account, |v| {
111            v.get("chatId")
112                .and_then(Value::as_str)
113                .is_some_and(|c| chats.iter().any(|x| x.as_ref() == c))
114        });
115    }
116
117    /// The restore rules of the chat types, as an update would apply them:
118    /// a referenced Space must exist (`invalidProperties` naming
119    /// `spaceId`), so must a `ChatBan`'s Chat (naming `chatId`), and a
120    /// `CustomEmoji`'s name must be free.
121    fn check_chat_restore(
122        &self,
123        type_name: &str,
124        account: &Id,
125        id: &Id,
126        object: &Value,
127    ) -> Result<(), BackendSetError<MemoryError>> {
128        if matches!(
129            type_name,
130            "Chat" | "SpaceBan" | "SpaceInvite" | "CustomEmoji"
131        ) && let Some(space) = object.get("spaceId").and_then(Value::as_str)
132        {
133            let exists = self
134                .objects_ref("Space", account.as_ref())
135                .is_some_and(|m| m.contains_key(&Id::from(space)));
136            if !exists {
137                return Err(invalid("spaceId"));
138            }
139        }
140        // A restored ChatBan names a Chat that must exist, as a create
141        // requires. Restoring it does not touch `members`.
142        if type_name == "ChatBan"
143            && let Some(chat) = object.get("chatId").and_then(Value::as_str)
144            && !self
145                .objects_ref("Chat", account.as_ref())
146                .is_some_and(|m| m.contains_key(&Id::from(chat)))
147        {
148            return Err(invalid("chatId"));
149        }
150        if type_name == "CustomEmoji"
151            && emoji_name_holder(self, account, object, Some(id)).is_some()
152        {
153            return Err(invalid("name"));
154        }
155        Ok(())
156    }
157}
158
159impl<C: MemoryCaller> MemoryBackend<C> {
160    /// Keep object history for the types `capability.supportedTypes` lists
161    /// (the eight chat history types), in every account, with `retention`;
162    /// `capability` is also what
163    /// [`ObjectHistoryBackend::object_history_capability`] advertises.
164    ///
165    /// # Panics
166    ///
167    /// When `supportedTypes` names a type without history, or another type.
168    #[must_use]
169    pub fn with_object_history(
170        self,
171        capability: ObjectHistoryAccountCapability,
172        retention: HistoryRetention,
173    ) -> Self {
174        for t in &capability.supported_types {
175            assert!(
176                SUPPORTED.contains(&t.as_str()),
177                "the memory backend keeps no history for {t}"
178            );
179        }
180        self.inner.lock_unscoped().history = Some(HistoryStore::new(capability, retention));
181        self
182    }
183
184    /// Fix the history clock at `ms` milliseconds since the epoch.
185    pub fn set_history_clock_for_test(&self, ms: i64) {
186        if let Some(h) = self.inner.lock_unscoped().history.as_mut() {
187            h.set_clock(ms);
188        }
189    }
190
191    /// Discard one version of an object, in any order (§3.1).
192    pub fn discard_version_for_test(&self, type_name: &str, account: &Id, id: &Id, version: u64) {
193        if let Some(h) = self.inner.lock_unscoped().history.as_mut() {
194            h.discard_version(type_name, account, id, version);
195        }
196    }
197
198    /// Discard every version of an object: the §8.3 administrative purge.
199    pub fn purge_object_history(&self, type_name: &str, account: &Id, id: &Id) {
200        if let Some(h) = self.inner.lock_unscoped().history.as_mut() {
201            h.purge(type_name, account, id);
202        }
203    }
204
205    /// Set the §8.2 cut for `type_name` in `account`: versions replaced
206    /// before `ms`, and objects destroyed before it, are hidden.
207    pub fn set_rights_changed_at_for_test(&self, type_name: &str, account: &Id, ms: i64) {
208        if let Some(h) = self.inner.lock_unscoped().history.as_mut() {
209            h.set_rights_changed(type_name, account, ms);
210        }
211    }
212}
213
214fn not_found() -> BackendSetError<MemoryError> {
215    BackendSetError::SetError(Box::new(SetError::new(SetErrorType::NotFound)))
216}
217
218fn invalid(property: &str) -> BackendSetError<MemoryError> {
219    BackendSetError::SetError(Box::new(
220        SetError::new(SetErrorType::InvalidProperties).with_properties([property]),
221    ))
222}
223
224impl<C: MemoryCaller> ObjectHistoryBackend for MemoryBackend<C> {
225    fn object_history_capability(
226        &self,
227        _caller: &C,
228        account_id: &Id,
229    ) -> Option<ObjectHistoryAccountCapability> {
230        let inner = self.inner.lock_unscoped();
231        if !inner.known_accounts.contains(account_id.as_ref()) {
232            return None;
233        }
234        inner.history.as_ref().map(|h| h.capability().clone())
235    }
236
237    async fn get_object_history<O: HistoryObject>(
238        &self,
239        _caller: &C,
240        account_id: &Id,
241        params: HistoryGetParams<'_>,
242    ) -> Result<HistoryGetResult<O>, BackendQueryError<MemoryError>> {
243        let mut inner = self.inner.lock().await;
244        inner.prune_history();
245        let empty = HashMap::new();
246        let live = inner
247            .objects_ref(O::TYPE_NAME, account_id.as_ref())
248            .unwrap_or(&empty);
249        let Some(h) = inner.history.as_ref() else {
250            return Ok(HistoryGetResult::new(
251                Vec::new(),
252                params.ids.map(<[Id]>::to_vec).unwrap_or_default(),
253            ));
254        };
255        let (rows, not_found) = h
256            .select(O::TYPE_NAME, account_id, params.ids, live, params.arguments)
257            .map_err(|e| BackendQueryError::Method(JmapError::invalid_arguments(e.to_string())))?;
258        let mut entries = Vec::with_capacity(rows.len());
259        for (snapshot, info) in rows {
260            let object = O::deserialize(&snapshot)
261                .map_err(|e| BackendQueryError::Other(MemoryError::new(e.to_string())))?;
262            entries.push(HistoryEntry::new(object, info));
263        }
264        Ok(HistoryGetResult::new(entries, not_found))
265    }
266
267    async fn query_destroyed<O: HistoryObject + QueryObject>(
268        &self,
269        _caller: &C,
270        account_id: &Id,
271        params: DestroyedQueryParams<'_, O>,
272    ) -> Result<QueryResult, BackendQueryError<MemoryError>> {
273        let mut inner = self.inner.lock().await;
274        inner.prune_history();
275        let q = &params.query;
276        let all = inner.destroyed_results::<O>(
277            account_id,
278            params.destroyed_after,
279            params.destroyed_before,
280            q.filter,
281            q.sort,
282        )?;
283        let start = resolve_query_start(&all, q.position, q.anchor, q.anchor_offset)
284            .map_err(BackendQueryError::Method)?;
285        let ids: Vec<Id> = all[start..]
286            .iter()
287            .take(limit_or_max(q.limit))
288            .cloned()
289            .collect();
290        let state = inner.history.as_ref().map_or_else(String::new, |h| {
291            h.destroyed_query_state(
292                O::TYPE_NAME,
293                account_id,
294                params.destroyed_after,
295                params.destroyed_before,
296            )
297        });
298        Ok(QueryResult::new(
299            ids,
300            start as u64,
301            Some(all.len() as u64),
302            State::from(state),
303            true,
304        ))
305    }
306
307    async fn query_destroyed_changes<O: HistoryObject + QueryObject>(
308        &self,
309        _caller: &C,
310        account_id: &Id,
311        params: DestroyedQueryChangesParams<'_, O>,
312    ) -> Result<QueryChangesResult, BackendChangesError<MemoryError>> {
313        let mut inner = self.inner.lock().await;
314        inner.prune_history();
315        let q = &params.query_changes;
316        let all = inner
317            .destroyed_results::<O>(
318                account_id,
319                params.destroyed_after,
320                params.destroyed_before,
321                q.filter,
322                q.sort,
323            )
324            .map_err(|e| match e {
325                BackendQueryError::Other(e) => BackendChangesError::Other(e),
326                _ => BackendChangesError::CannotCalculate,
327            })?;
328        let Some(h) = inner.history.as_ref() else {
329            return Err(BackendChangesError::CannotCalculate);
330        };
331        // A state of another kind or window cannot be calculated (decision
332        // 25).
333        let changed = h
334            .destroyed_changes_since(
335                O::TYPE_NAME,
336                account_id,
337                q.since_query_state.as_ref(),
338                params.destroyed_after,
339                params.destroyed_before,
340            )
341            .ok_or(BackendChangesError::CannotCalculate)?;
342        if let Some(max) = q.max_changes
343            && changed.len() as u64 > max
344        {
345            return Err(BackendChangesError::TooManyChanges { limit: max });
346        }
347        let new_state = h.destroyed_query_state(
348            O::TYPE_NAME,
349            account_id,
350            params.destroyed_after,
351            params.destroyed_before,
352        );
353        let added: Vec<AddedItem> = all
354            .iter()
355            .enumerate()
356            .filter(|(_, id)| changed.contains(id))
357            .map(|(i, id)| AddedItem::new(id.clone(), i as u64))
358            .collect();
359        Ok(QueryChangesResult::new(
360            q.since_query_state.clone(),
361            State::from(new_state),
362            Some(all.len() as u64),
363            changed,
364            added,
365        ))
366    }
367
368    async fn restore_object<O: HistoryObject + SetObject>(
369        &self,
370        _caller: &C,
371        account_id: &Id,
372        id: &Id,
373        patch: Option<PatchObject>,
374    ) -> Result<Restored<O>, BackendSetError<MemoryError>> {
375        let mut inner = self.inner.lock().await;
376        inner.require_account_for_target(account_id.as_ref())?;
377        inner.prune_history();
378        if inner
379            .objects_ref(O::TYPE_NAME, account_id.as_ref())
380            .is_some_and(|m| m.contains_key(id))
381        {
382            return Err(not_found());
383        }
384        let Some(Value::Object(final_version)) = inner
385            .history
386            .as_ref()
387            .and_then(|h| h.final_version(O::TYPE_NAME, account_id, id))
388            .cloned()
389        else {
390            return Err(not_found());
391        };
392        let baseline = apply_restore_patch::<O>(&final_version, patch.as_ref())
393            .map_err(BackendSetError::SetError)?;
394        inner.check_chat_restore(
395            O::TYPE_NAME,
396            account_id,
397            id,
398            &Value::Object(baseline.clone()),
399        )?;
400        let stored = baseline.clone();
401        let value = Value::Object(stored);
402        let Ok(object) = O::deserialize(&value) else {
403            // -04 §5.1: values that no longer make a valid object.
404            let props: Vec<String> = patch
405                .as_ref()
406                .map(|p| p.as_map().keys().cloned().collect())
407                .filter(|v: &Vec<String>| !v.is_empty())
408                .unwrap_or_else(|| vec!["id".to_owned()]);
409            return Err(BackendSetError::SetError(Box::new(
410                SetError::new(SetErrorType::InvalidProperties).with_properties(props),
411            )));
412        };
413        if let Some(h) = inner.history.as_mut() {
414            h.restore(O::TYPE_NAME, account_id, id);
415        }
416        inner
417            .objects_mut(O::TYPE_NAME, account_id.as_ref())
418            .insert(id.clone(), value);
419        let new_state = inner.bump_state(O::TYPE_NAME, account_id.as_ref());
420        inner
421            .change_log_mut(O::TYPE_NAME, account_id.as_ref())
422            .push(ChangeEntry {
423                new_state,
424                created: vec![],
425                updated: vec![],
426                destroyed: vec![],
427                restored: vec![id.clone()],
428                updated_props: None,
429            });
430        Ok(Restored::new(object, baseline))
431    }
432}