Skip to main content

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