1use std::collections::{BTreeMap, BTreeSet};
13
14use jmap_object_history_types::{
15 DestroyedQueryArguments, HistoryEntry, HistoryGetArguments, HistoryObject,
16 JMAP_OBJECT_HISTORY_URI, ObjectHistoryAccountCapability,
17};
18use jmap_types::{PatchObject, QueryObject, SetObject, State, UTCDate};
19use serde_json::{Map, Value, json};
20
21use crate::backend::{
22 BackendChangesError, BackendQueryError, BackendSetError, JmapBackend, QueryChangesParams,
23 QueryChangesResult, QueryParams, QueryResult,
24};
25use crate::handlers::{
26 handle_get_with_metadata, handle_query_changes_with_i18n, handle_query_with_i18n,
27 server_fail_from_backend,
28};
29use crate::helpers::{
30 MetadataProjection, apply_patch_object, check_patch_paths, enforce_max_objects_in_get,
31 extract_account_id, filter_arg, json_type_name, not_found_json, optional_arg,
32 parse_max_changes, query_anchor_args, serialize_value,
33};
34use crate::i18n::I18nProjection;
35use crate::{
36 Dispatcher, HandlerOutput, Id, JmapError, JmapHandler, SetError, SetErrorType,
37 backend_set_error_value,
38};
39
40pub const OBJECT_HISTORY_PROPERTY: &str = "objectHistory";
42
43#[non_exhaustive]
49#[derive(Debug, Clone, Copy)]
50pub struct HistoryGetParams<'a> {
51 pub ids: Option<&'a [Id]>,
55 pub properties: Option<&'a [String]>,
57 pub arguments: &'a HistoryGetArguments,
59}
60
61impl<'a> HistoryGetParams<'a> {
62 pub fn new(arguments: &'a HistoryGetArguments) -> Self {
64 Self {
65 ids: None,
66 properties: None,
67 arguments,
68 }
69 }
70
71 #[must_use]
73 pub fn ids(mut self, ids: Option<&'a [Id]>) -> Self {
74 self.ids = ids;
75 self
76 }
77
78 #[must_use]
80 pub fn properties(mut self, properties: Option<&'a [String]>) -> Self {
81 self.properties = properties;
82 self
83 }
84}
85
86#[non_exhaustive]
88#[derive(Debug, Clone, PartialEq)]
89pub struct HistoryGetResult<O> {
90 pub entries: Vec<HistoryEntry<O>>,
93 pub not_found: Vec<Id>,
95}
96
97impl<O> HistoryGetResult<O> {
98 pub fn new(entries: Vec<HistoryEntry<O>>, not_found: Vec<Id>) -> Self {
100 Self { entries, not_found }
101 }
102}
103
104#[non_exhaustive]
107pub struct DestroyedQueryParams<'a, O: QueryObject> {
108 pub query: QueryParams<'a, O>,
111 pub destroyed_after: Option<&'a UTCDate>,
113 pub destroyed_before: Option<&'a UTCDate>,
115}
116
117impl<'a, O: QueryObject> DestroyedQueryParams<'a, O> {
118 pub fn new(query: QueryParams<'a, O>) -> Self {
120 Self {
121 query,
122 destroyed_after: None,
123 destroyed_before: None,
124 }
125 }
126
127 #[must_use]
129 pub fn destroyed_after(mut self, t: Option<&'a UTCDate>) -> Self {
130 self.destroyed_after = t;
131 self
132 }
133
134 #[must_use]
136 pub fn destroyed_before(mut self, t: Option<&'a UTCDate>) -> Self {
137 self.destroyed_before = t;
138 self
139 }
140}
141
142#[non_exhaustive]
146pub struct DestroyedQueryChangesParams<'a, O: QueryObject> {
147 pub query_changes: QueryChangesParams<'a, O>,
149 pub destroyed_after: Option<&'a UTCDate>,
151 pub destroyed_before: Option<&'a UTCDate>,
153}
154
155impl<'a, O: QueryObject> DestroyedQueryChangesParams<'a, O> {
156 pub fn new(query_changes: QueryChangesParams<'a, O>) -> Self {
158 Self {
159 query_changes,
160 destroyed_after: None,
161 destroyed_before: None,
162 }
163 }
164
165 #[must_use]
167 pub fn destroyed_after(mut self, t: Option<&'a UTCDate>) -> Self {
168 self.destroyed_after = t;
169 self
170 }
171
172 #[must_use]
174 pub fn destroyed_before(mut self, t: Option<&'a UTCDate>) -> Self {
175 self.destroyed_before = t;
176 self
177 }
178}
179
180#[non_exhaustive]
182#[derive(Debug, Clone, PartialEq)]
183pub struct Restored<O> {
184 pub stored: O,
186 pub baseline: Map<String, Value>,
190}
191
192impl<O> Restored<O> {
193 pub fn new(stored: O, baseline: Map<String, Value>) -> Self {
195 Self { stored, baseline }
196 }
197}
198
199pub trait ObjectHistoryBackend: JmapBackend {
230 fn object_history_capability(
236 &self,
237 caller: &Self::CallerCtx,
238 account_id: &Id,
239 ) -> Option<ObjectHistoryAccountCapability>;
240
241 fn get_object_history<O: HistoryObject>(
258 &self,
259 caller: &Self::CallerCtx,
260 account_id: &Id,
261 params: HistoryGetParams<'_>,
262 ) -> impl std::future::Future<
263 Output = Result<HistoryGetResult<O>, BackendQueryError<Self::Error>>,
264 > + Send;
265
266 fn query_destroyed<O: HistoryObject + QueryObject>(
281 &self,
282 caller: &Self::CallerCtx,
283 account_id: &Id,
284 params: DestroyedQueryParams<'_, O>,
285 ) -> impl std::future::Future<Output = Result<QueryResult, BackendQueryError<Self::Error>>> + Send;
286
287 fn query_destroyed_changes<O: HistoryObject + QueryObject>(
295 &self,
296 caller: &Self::CallerCtx,
297 account_id: &Id,
298 params: DestroyedQueryChangesParams<'_, O>,
299 ) -> impl std::future::Future<
300 Output = Result<QueryChangesResult, BackendChangesError<Self::Error>>,
301 > + Send;
302
303 fn restore_object<O: HistoryObject + SetObject>(
325 &self,
326 caller: &Self::CallerCtx,
327 account_id: &Id,
328 id: &Id,
329 patch: Option<PatchObject>,
330 ) -> impl std::future::Future<Output = Result<Restored<O>, BackendSetError<Self::Error>>> + Send;
331}
332
333fn uses_history(using: &[String]) -> bool {
338 using.iter().any(|u| u == JMAP_OBJECT_HISTORY_URI)
339}
340
341fn invalid(msg: impl Into<String>) -> JmapError {
342 JmapError::invalid_arguments(msg.into())
343}
344
345fn without_uri(name: &str) -> JmapError {
346 invalid(format!(
347 "{name} needs {JMAP_OBJECT_HISTORY_URI} in using (decision 18)"
348 ))
349}
350
351fn take_flag(args: &mut Map<String, Value>, name: &str) -> Result<bool, JmapError> {
353 match args.remove(name) {
354 None | Some(Value::Null) => Ok(false),
355 Some(Value::Bool(b)) => Ok(b),
356 Some(v) => Err(invalid(format!(
357 "{name}: expected a boolean, got {}",
358 json_type_name(&v)
359 ))),
360 }
361}
362
363fn parse_date(name: &str, v: Option<Value>) -> Result<Option<UTCDate>, JmapError> {
364 match v {
365 None | Some(Value::Null) => Ok(None),
366 Some(Value::String(s)) => UTCDate::new_validated(s)
367 .map(Some)
368 .map_err(|e| invalid(format!("{name}: {e}"))),
369 Some(v) => Err(invalid(format!(
370 "{name}: expected a UTCDate or null, got {}",
371 json_type_name(&v)
372 ))),
373 }
374}
375
376fn parse_unsigned(name: &str, v: Option<Value>) -> Result<Option<u64>, JmapError> {
377 match v {
378 None | Some(Value::Null) => Ok(None),
379 Some(v) => v.as_u64().map(Some).ok_or_else(|| {
380 invalid(format!(
381 "{name}: expected an UnsignedInt, got {}",
382 json_type_name(&v)
383 ))
384 }),
385 }
386}
387
388pub fn parse_history_get_arguments(
401 args: &mut Map<String, Value>,
402 using: &[String],
403) -> Result<Option<HistoryGetArguments>, JmapError> {
404 let include_replaced = take_flag(args, "includeReplaced")?;
405 let include_destroyed = take_flag(args, "includeDestroyed")?;
406 let after = args.remove("historyAfter");
407 let before = args.remove("historyBefore");
408 let skip = args.remove("historySkip");
409 let limit = args.remove("historyLimit");
410 if !include_replaced && !include_destroyed {
411 return Ok(None);
412 }
413 if !uses_history(using) {
414 return Err(without_uri(if include_replaced {
415 "includeReplaced"
416 } else {
417 "includeDestroyed"
418 }));
419 }
420 let mut out = HistoryGetArguments::new();
421 out.include_replaced = include_replaced;
422 out.include_destroyed = include_destroyed;
423 out.history_after = parse_date("historyAfter", after)?;
424 out.history_before = parse_date("historyBefore", before)?;
425 out.history_skip = parse_unsigned("historySkip", skip)?.unwrap_or(0);
426 out.history_limit = parse_unsigned("historyLimit", limit)?;
427 Ok(Some(out))
428}
429
430pub fn parse_destroyed_query_arguments(
443 args: &mut Map<String, Value>,
444 using: &[String],
445) -> Result<Option<DestroyedQueryArguments>, JmapError> {
446 let only_destroyed = take_flag(args, "onlyDestroyed")?;
447 let after = parse_date("destroyedAfter", args.remove("destroyedAfter"))?;
448 let before = parse_date("destroyedBefore", args.remove("destroyedBefore"))?;
449 let windowed = after.is_some() || before.is_some();
450 if (only_destroyed || windowed) && !uses_history(using) {
451 return Err(without_uri(if only_destroyed {
452 "onlyDestroyed"
453 } else {
454 "destroyedAfter/destroyedBefore"
455 }));
456 }
457 if !only_destroyed {
458 if windowed {
459 return Err(invalid(
460 "destroyedAfter and destroyedBefore need onlyDestroyed: true (§4)",
461 ));
462 }
463 return Ok(None);
464 }
465 let mut out = DestroyedQueryArguments::new();
466 out.only_destroyed = true;
467 out.destroyed_after = after;
468 out.destroyed_before = before;
469 Ok(Some(out))
470}
471
472pub fn parse_restore_argument(
480 args: &mut Map<String, Value>,
481 using: &[String],
482) -> Result<Map<String, Value>, JmapError> {
483 let restore = match args.remove("restore") {
484 None | Some(Value::Null) => Map::new(),
485 Some(Value::Object(m)) => m,
486 Some(v) => {
487 return Err(invalid(format!(
488 "restore: expected an object or null, got {}",
489 json_type_name(&v)
490 )));
491 }
492 };
493 if !restore.is_empty() && !uses_history(using) {
494 return Err(without_uri("restore"));
495 }
496 Ok(restore)
497}
498
499pub fn require_history_support<O: HistoryObject, B: ObjectHistoryBackend>(
506 backend: &B,
507 caller: &B::CallerCtx,
508 account_id: &Id,
509) -> Result<(), JmapError> {
510 match backend.object_history_capability(caller, account_id) {
511 Some(cap) if cap.supports::<O>() => Ok(()),
512 _ => Err(invalid(format!(
513 "{} has no history in this account (supportedTypes)",
514 O::TYPE_NAME
515 ))),
516 }
517}
518
519pub fn strip_object_history_property(args: &mut Map<String, Value>) -> bool {
527 let Some(Value::Array(props)) = args.get_mut("properties") else {
528 return false;
529 };
530 let before = props.len();
531 props.retain(|p| p.as_str() != Some(OBJECT_HISTORY_PROPERTY));
532 props.len() != before
533}
534
535pub fn attach_object_history(
538 item: &mut Map<String, Value>,
539 object_history: Value,
540 properties: Option<&[String]>,
541) {
542 if let Some(props) = properties {
543 item.retain(|k, _| k == "id" || props.iter().any(|p| p == k));
544 }
545 item.insert(OBJECT_HISTORY_PROPERTY.to_owned(), object_history);
546}
547
548pub async fn handle_get_with_history<O: HistoryObject, B: ObjectHistoryBackend>(
566 backend: &B,
567 caller: &B::CallerCtx,
568 args: Value,
569 using: &[String],
570) -> Result<HandlerOutput, JmapError> {
571 history_get::<O, B, _, _>(backend, caller, args, using, |args| {
572 handle_get_with_metadata::<O, B>(backend, caller, args, using)
573 })
574 .await
575}
576
577pub async fn history_get<O: HistoryObject, B: ObjectHistoryBackend, F, Fut>(
586 backend: &B,
587 caller: &B::CallerCtx,
588 args: Value,
589 using: &[String],
590 plain: F,
591) -> Result<HandlerOutput, JmapError>
592where
593 F: FnOnce(Value) -> Fut,
594 Fut: std::future::Future<Output = Result<HandlerOutput, JmapError>>,
595{
596 let Value::Object(mut map) = args else {
597 return plain(args).await;
598 };
599 let Some(history) = parse_history_get_arguments(&mut map, using)? else {
600 strip_object_history_property(&mut map);
601 return plain(Value::Object(map)).await;
602 };
603 strip_object_history_property(&mut map);
604 let (account_id, mut args) = extract_account_id(Value::Object(map))?;
605 if !backend
606 .account_exists(caller, &account_id)
607 .await
608 .map_err(|e| server_fail_from_backend(&e))?
609 {
610 return Err(JmapError::account_not_found());
611 }
612 require_history_support::<O, B>(backend, caller, &account_id)?;
613 enforce_max_objects_in_get(&args, backend.max_objects_in_get(caller, &account_id))?;
614 let i18n = I18nProjection::from_args::<O>(
615 &mut args,
616 using,
617 backend.i18n_info(caller, &account_id).as_ref(),
618 )?;
619 let ids: Option<Vec<Id>> = optional_arg(&mut args, "ids", || {
620 JmapError::invalid_arguments("ids must be an Id array")
621 })?;
622 let properties: Option<Vec<String>> = optional_arg(&mut args, "properties", || {
623 JmapError::invalid_arguments("properties must be a string array")
624 })?;
625 let metadata = match backend.metadata_info::<O>(caller, &account_id) {
626 Some(info) => Some(MetadataProjection::new(
627 properties.as_deref(),
628 true,
629 using,
630 Some(&info),
631 )?),
632 None => None,
633 };
634 let roots: Option<Vec<String>> = properties.as_ref().map(|props| {
636 let mut roots: Vec<String> = Vec::with_capacity(props.len());
637 for p in props {
638 let root = match (metadata.is_some(), p.split_once('/')) {
639 (true, Some((r @ ("metadata" | "privateMetadata"), _))) => r.to_owned(),
640 _ => p.clone(),
641 };
642 if !roots.contains(&root) {
643 roots.push(root);
644 }
645 }
646 roots
647 });
648 let backend_properties = i18n.backend_properties(roots.as_deref());
649 let result = backend
650 .get_object_history::<O>(
651 caller,
652 &account_id,
653 HistoryGetParams::new(&history)
654 .ids(ids.as_deref())
655 .properties(backend_properties.as_deref()),
656 )
657 .await
658 .map_err(JmapError::from)?;
659 let state = backend
660 .get_state::<O>(caller, &account_id)
661 .await
662 .map_err(|e| server_fail_from_backend(&e))?;
663
664 let mut list = Vec::with_capacity(result.entries.len());
665 for entry in result.entries {
666 let version = entry.object_history.version;
667 let info = serialize_value(&entry.object_history)?;
668 let mut item = serialize_value(&entry.object)?;
669 if let Value::Object(map) = &mut item {
670 map.remove(OBJECT_HISTORY_PROPERTY);
671 i18n.apply(map);
672 if let Some(roots) = &roots {
673 map.retain(|k, _| k == "id" || roots.iter().any(|p| p == k));
674 }
675 }
676 if let Some(projection) = &metadata {
677 let source = item.clone();
678 projection.apply(&source, &mut item);
679 }
680 if let Value::Object(map) = &mut item {
681 attach_object_history(map, info, None);
682 }
683 list.push((version, item));
684 }
685 sort_entries_by_version(&mut list);
686
687 Ok(HandlerOutput::new(json!({
688 "accountId": account_id.as_ref(),
689 "state": state.as_ref(),
690 "list": list.into_iter().map(|(_, v)| v).collect::<Vec<_>>(),
691 "notFound": not_found_json(&result.not_found),
692 })))
693}
694
695fn sort_entries_by_version(list: &mut [(u64, Value)]) {
699 let mut first: BTreeMap<String, usize> = BTreeMap::new();
700 let keys: Vec<(usize, u64)> = list
701 .iter()
702 .enumerate()
703 .map(|(i, (version, item))| {
704 let id = item
705 .get("id")
706 .and_then(Value::as_str)
707 .unwrap_or("")
708 .to_owned();
709 (*first.entry(id).or_insert(i), *version)
710 })
711 .collect();
712 let mut order: Vec<usize> = (0..list.len()).collect();
713 order.sort_by_key(|&i| keys[i]);
714 let sorted: Vec<(u64, Value)> = order.iter().map(|&i| list[i].clone()).collect();
715 for (slot, v) in list.iter_mut().zip(sorted) {
716 *slot = v;
717 }
718}
719
720pub async fn handle_query_with_history<O, B>(
741 backend: &B,
742 caller: &B::CallerCtx,
743 args: Value,
744 using: &[String],
745) -> Result<HandlerOutput, JmapError>
746where
747 O: HistoryObject + QueryObject,
748 B: ObjectHistoryBackend,
749{
750 history_query::<O, B, _, _>(backend, caller, args, using, |args| {
751 handle_query_with_i18n::<O, B>(backend, caller, args, using)
752 })
753 .await
754}
755
756pub async fn history_query<O, B, F, Fut>(
765 backend: &B,
766 caller: &B::CallerCtx,
767 args: Value,
768 using: &[String],
769 plain: F,
770) -> Result<HandlerOutput, JmapError>
771where
772 F: FnOnce(Value) -> Fut,
773 Fut: std::future::Future<Output = Result<HandlerOutput, JmapError>>,
774 O: HistoryObject + QueryObject,
775 B: ObjectHistoryBackend,
776{
777 let Value::Object(mut map) = args else {
778 return plain(args).await;
779 };
780 let Some(destroyed) = parse_destroyed_query_arguments(&mut map, using)? else {
781 return plain(Value::Object(map)).await;
782 };
783 let (account_id, mut args) = extract_account_id(Value::Object(map))?;
784 if !backend
785 .account_exists(caller, &account_id)
786 .await
787 .map_err(|e| server_fail_from_backend(&e))?
788 {
789 return Err(JmapError::account_not_found());
790 }
791 require_history_support::<O, B>(backend, caller, &account_id)?;
792 let i18n = I18nProjection::from_args::<O>(
793 &mut args,
794 using,
795 backend.i18n_info(caller, &account_id).as_ref(),
796 )?;
797 let calculate_total = args
798 .get("calculateTotal")
799 .and_then(Value::as_bool)
800 .unwrap_or(false);
801 let limit = parse_unsigned("limit", args.remove("limit"))?;
802 let position: i64 = match args.get("position") {
803 None | Some(Value::Null) => 0,
804 Some(v) => v.as_i64().ok_or_else(|| {
805 invalid(format!(
806 "position: expected an integer, got {}",
807 json_type_name(v)
808 ))
809 })?,
810 };
811 let (anchor, anchor_offset) = query_anchor_args(&args)?;
812 let filter: Option<O::Filter> = filter_arg(&mut args)?;
813 let sort: Option<Vec<O::Comparator>> = optional_arg(&mut args, "sort", || {
814 JmapError::invalid_arguments("sort must be an array")
815 })?;
816 let result = backend
817 .query_destroyed::<O>(
818 caller,
819 &account_id,
820 DestroyedQueryParams::new(
821 QueryParams::new()
822 .filter(filter.as_ref())
823 .sort(sort.as_deref())
824 .limit(limit)
825 .position(position)
826 .anchor(anchor.as_ref())
827 .anchor_offset(anchor_offset)
828 .language(i18n.language()),
829 )
830 .destroyed_after(destroyed.destroyed_after.as_ref())
831 .destroyed_before(destroyed.destroyed_before.as_ref()),
832 )
833 .await
834 .map_err(JmapError::from)?;
835 let mut resp = json!({
836 "accountId": account_id.as_ref(),
837 "queryState": result.query_state.as_ref(),
838 "canCalculateChanges": result.can_calculate_changes,
839 "position": result.position,
840 "ids": result.ids,
841 });
842 if calculate_total && let Some(t) = result.total {
843 resp["total"] = json!(t);
844 }
845 Ok(HandlerOutput::new(resp))
846}
847
848pub async fn handle_query_changes_with_history<O, B>(
863 backend: &B,
864 caller: &B::CallerCtx,
865 args: Value,
866 using: &[String],
867) -> Result<HandlerOutput, JmapError>
868where
869 O: HistoryObject + QueryObject,
870 B: ObjectHistoryBackend,
871{
872 history_query_changes::<O, B, _, _>(backend, caller, args, using, |args| {
873 handle_query_changes_with_i18n::<O, B>(backend, caller, args, using)
874 })
875 .await
876}
877
878pub async fn history_query_changes<O, B, F, Fut>(
887 backend: &B,
888 caller: &B::CallerCtx,
889 args: Value,
890 using: &[String],
891 plain: F,
892) -> Result<HandlerOutput, JmapError>
893where
894 F: FnOnce(Value) -> Fut,
895 Fut: std::future::Future<Output = Result<HandlerOutput, JmapError>>,
896 O: HistoryObject + QueryObject,
897 B: ObjectHistoryBackend,
898{
899 let Value::Object(mut map) = args else {
900 return plain(args).await;
901 };
902 let Some(destroyed) = parse_destroyed_query_arguments(&mut map, using)? else {
903 return plain(Value::Object(map)).await;
904 };
905 let (account_id, mut args) = extract_account_id(Value::Object(map))?;
906 if !backend
907 .account_exists(caller, &account_id)
908 .await
909 .map_err(|e| server_fail_from_backend(&e))?
910 {
911 return Err(JmapError::account_not_found());
912 }
913 require_history_support::<O, B>(backend, caller, &account_id)?;
914 let i18n = I18nProjection::from_args::<O>(
915 &mut args,
916 using,
917 backend.i18n_info(caller, &account_id).as_ref(),
918 )?;
919 let since: State = match args.get("sinceQueryState").and_then(Value::as_str) {
920 Some(s) => State::from(s),
921 None => return Err(invalid("sinceQueryState is required")),
922 };
923 let max_changes = parse_max_changes(args.get("maxChanges"))?;
924 let up_to_id: Option<Id> = match args.get("upToId") {
925 None | Some(Value::Null) => None,
926 Some(Value::String(s)) => Some(Id::from(s.as_str())),
927 Some(_) => return Err(invalid("upToId must be a string Id or null")),
928 };
929 let calculate_total = args
930 .get("calculateTotal")
931 .and_then(Value::as_bool)
932 .unwrap_or(false);
933 let filter: Option<O::Filter> = filter_arg(&mut args)?;
934 let sort: Option<Vec<O::Comparator>> = optional_arg(&mut args, "sort", || {
935 JmapError::invalid_arguments("sort must be an array")
936 })?;
937 let result = backend
938 .query_destroyed_changes::<O>(
939 caller,
940 &account_id,
941 DestroyedQueryChangesParams::new(
942 QueryChangesParams::new(&since)
943 .filter(filter.as_ref())
944 .sort(sort.as_deref())
945 .max_changes(max_changes)
946 .up_to_id(up_to_id.as_ref())
947 .language(i18n.language()),
948 )
949 .destroyed_after(destroyed.destroyed_after.as_ref())
950 .destroyed_before(destroyed.destroyed_before.as_ref()),
951 )
952 .await
953 .map_err(JmapError::from)?;
954 let added: Vec<Value> = result
955 .added
956 .iter()
957 .map(|a| json!({"id": a.id.as_ref(), "index": a.index}))
958 .collect();
959 let mut resp = json!({
960 "accountId": account_id.as_ref(),
961 "oldQueryState": result.old_query_state.as_ref(),
962 "newQueryState": result.new_query_state.as_ref(),
963 "removed": result.removed,
964 "added": added,
965 });
966 if calculate_total && let Some(t) = result.total {
967 resp["total"] = json!(t);
968 }
969 Ok(HandlerOutput::new(resp))
970}
971
972pub trait RestoreHooks: Sync {
978 fn check_patch(&self, id: &Id, patch: Option<&PatchObject>) -> Result<(), Box<SetError>> {
986 let _ = (id, patch);
987 Ok(())
988 }
989
990 fn same_type_references(&self, final_version: &Map<String, Value>) -> Vec<Id> {
995 let _ = final_version;
996 Vec::new()
997 }
998}
999
1000#[derive(Debug, Clone, Copy, Default)]
1003pub struct NoRestoreHooks;
1004
1005impl RestoreHooks for NoRestoreHooks {}
1006
1007#[derive(Debug, Clone, Copy)]
1010pub struct ParentRestoreHooks(pub &'static str);
1011
1012impl RestoreHooks for ParentRestoreHooks {
1013 fn same_type_references(&self, final_version: &Map<String, Value>) -> Vec<Id> {
1014 final_version
1015 .get(self.0)
1016 .and_then(Value::as_str)
1017 .map(|s| vec![Id::from(s)])
1018 .unwrap_or_default()
1019 }
1020}
1021
1022#[non_exhaustive]
1024#[derive(Debug, Clone, Default, PartialEq)]
1025pub struct RestoreAccumulators {
1026 pub restored: Map<String, Value>,
1028 pub not_restored: Map<String, Value>,
1030 pub mutated: bool,
1032}
1033
1034fn set_error(t: SetErrorType, description: impl Into<String>) -> SetError {
1035 SetError::new(t).with_description(description)
1036}
1037
1038fn set_error_value(e: SetError) -> Value {
1039 serde_json::to_value(e).unwrap_or_else(|_| json!({"type": "serverFail"}))
1040}
1041
1042pub async fn run_restore_phase<O, B>(
1064 backend: &B,
1065 caller: &B::CallerCtx,
1066 account_id: &Id,
1067 restore: Map<String, Value>,
1068 hooks: &dyn RestoreHooks,
1069) -> Result<RestoreAccumulators, JmapError>
1070where
1071 O: HistoryObject + SetObject,
1072 B: ObjectHistoryBackend,
1073{
1074 let mut acc = RestoreAccumulators::default();
1075 if restore.is_empty() {
1076 return Ok(acc);
1077 }
1078 require_history_support::<O, B>(backend, caller, account_id)?;
1079
1080 let mut ready: Vec<(String, Id, Option<PatchObject>)> = Vec::new();
1081 for (key, value) in restore {
1082 let Ok(id) = Id::new_validated(key.as_str()) else {
1083 acc.not_restored.insert(
1084 key,
1085 set_error_value(set_error(
1086 SetErrorType::NotFound,
1087 "not the id of a destroyed object",
1088 )),
1089 );
1090 continue;
1091 };
1092 let patch = match value {
1093 Value::Null => None,
1094 Value::Object(m) if m.is_empty() => None,
1095 Value::Object(m) => Some(m),
1096 v => {
1097 acc.not_restored.insert(
1098 key,
1099 set_error_value(set_error(
1100 SetErrorType::InvalidPatch,
1101 format!("expected a PatchObject or null, got {}", json_type_name(&v)),
1102 )),
1103 );
1104 continue;
1105 }
1106 };
1107 if let Some(p) = &patch {
1108 if let Err(e) = check_patch_paths(p) {
1109 acc.not_restored.insert(
1110 key,
1111 set_error_value(set_error(SetErrorType::InvalidPatch, e.to_string())),
1112 );
1113 continue;
1114 }
1115 if p.keys()
1116 .any(|k| k == OBJECT_HISTORY_PROPERTY || k.starts_with("objectHistory/"))
1117 {
1118 acc.not_restored
1119 .insert(key, set_error_value(object_history_set_error()));
1120 continue;
1121 }
1122 }
1123 let patch = patch.map(PatchObject::from_map);
1124 if let Err(e) = hooks.check_patch(&id, patch.as_ref()) {
1125 acc.not_restored.insert(key, set_error_value(*e));
1126 continue;
1127 }
1128 ready.push((key, id, patch));
1129 }
1130
1131 let ready = order_restores::<O, B>(backend, caller, account_id, ready, hooks, &mut acc).await?;
1132 for (key, id, patch) in ready {
1133 match backend
1134 .restore_object::<O>(caller, account_id, &id, patch)
1135 .await
1136 {
1137 Ok(restored) => {
1138 let stored = serialize_value(&restored.stored)?;
1139 let baseline =
1142 serde_json::from_value::<O>(Value::Object(restored.baseline.clone()))
1143 .ok()
1144 .and_then(|o| serde_json::to_value(o).ok())
1145 .and_then(|v| match v {
1146 Value::Object(m) => Some(m),
1147 _ => None,
1148 })
1149 .unwrap_or(restored.baseline);
1150 acc.restored
1151 .insert(id.as_ref().to_owned(), restored_diff(&baseline, &stored));
1152 acc.mutated = true;
1153 }
1154 Err(e) => {
1155 acc.not_restored.insert(key, backend_set_error_value(e));
1156 }
1157 }
1158 }
1159 Ok(acc)
1160}
1161
1162async fn order_restores<O, B>(
1165 backend: &B,
1166 caller: &B::CallerCtx,
1167 account_id: &Id,
1168 ready: Vec<(String, Id, Option<PatchObject>)>,
1169 hooks: &dyn RestoreHooks,
1170 acc: &mut RestoreAccumulators,
1171) -> Result<Vec<(String, Id, Option<PatchObject>)>, JmapError>
1172where
1173 O: HistoryObject + SetObject,
1174 B: ObjectHistoryBackend,
1175{
1176 if ready.len() < 2 {
1177 return Ok(ready);
1178 }
1179 let ids: Vec<Id> = ready.iter().map(|(_, id, _)| id.clone()).collect();
1180 let mut args = HistoryGetArguments::new();
1181 args.include_destroyed = true;
1182 let finals = backend
1183 .get_object_history::<O>(
1184 caller,
1185 account_id,
1186 HistoryGetParams::new(&args).ids(Some(&ids)),
1187 )
1188 .await
1189 .map_err(JmapError::from)?;
1190 let keys: BTreeSet<&Id> = ids.iter().collect();
1191 let mut deps: BTreeMap<Id, Vec<Id>> = BTreeMap::new();
1192 for entry in &finals.entries {
1193 let Ok(Value::Object(map)) = serde_json::to_value(&entry.object) else {
1194 continue;
1195 };
1196 let Some(id) = map.get("id").and_then(Value::as_str).map(Id::from) else {
1197 continue;
1198 };
1199 let refs: Vec<Id> = hooks
1200 .same_type_references(&map)
1201 .into_iter()
1202 .filter(|r| r != &id && keys.contains(r))
1203 .collect();
1204 deps.entry(id).or_default().extend(refs);
1205 }
1206 if deps.values().all(Vec::is_empty) {
1207 return Ok(ready);
1208 }
1209 let mut pending = ready;
1211 let mut done: BTreeSet<Id> = BTreeSet::new();
1212 let mut out = Vec::with_capacity(pending.len());
1213 loop {
1214 let before = pending.len();
1215 let mut rest = Vec::new();
1216 for entry in pending {
1217 let blocked = deps
1218 .get(&entry.1)
1219 .is_some_and(|d| d.iter().any(|r| !done.contains(r)));
1220 if blocked {
1221 rest.push(entry);
1222 } else {
1223 done.insert(entry.1.clone());
1224 out.push(entry);
1225 }
1226 }
1227 pending = rest;
1228 if pending.is_empty() {
1229 return Ok(out);
1230 }
1231 if pending.len() == before {
1232 for (key, _, _) in pending {
1233 acc.not_restored.insert(
1234 key,
1235 set_error_value(
1236 SetError::new(SetErrorType::InvalidProperties)
1237 .with_properties(vec!["id".to_owned()])
1238 .with_description("restore cycle among same-type references"),
1239 ),
1240 );
1241 }
1242 return Ok(out);
1243 }
1244 }
1245}
1246
1247pub async fn history_set<O, B, F, Fut>(
1270 backend: &B,
1271 caller: &B::CallerCtx,
1272 args: Value,
1273 using: &[String],
1274 hooks: &dyn RestoreHooks,
1275 plain: F,
1276) -> Result<HandlerOutput, JmapError>
1277where
1278 O: HistoryObject + SetObject,
1279 B: ObjectHistoryBackend,
1280 F: FnOnce(Value) -> Fut,
1281 Fut: std::future::Future<Output = Result<HandlerOutput, JmapError>>,
1282{
1283 let Value::Object(mut map) = args else {
1284 return plain(args).await;
1285 };
1286 let restore = parse_restore_argument(&mut map, using)?;
1287 let mut acc = RestoreAccumulators::default();
1288 let mut old_state = None;
1289 if !restore.is_empty() {
1290 let account_id = match map.get("accountId").and_then(Value::as_str) {
1291 Some(s) => Id::new_validated(s)
1292 .map_err(|e| invalid(format!("accountId is not a valid Id: {e}")))?,
1293 None => return Err(invalid("accountId is required")),
1294 };
1295 if !backend
1296 .account_exists(caller, &account_id)
1297 .await
1298 .map_err(|e| server_fail_from_backend(&e))?
1299 {
1300 return Err(JmapError::account_not_found());
1301 }
1302 enforce_max_objects_in_set_with_restore(
1303 &map,
1304 restore.len(),
1305 backend.max_objects_in_set(caller, &account_id),
1306 )?;
1307 let state = backend
1308 .get_state::<O>(caller, &account_id)
1309 .await
1310 .map_err(|e| server_fail_from_backend(&e))?;
1311 match map.remove("ifInState") {
1312 None | Some(Value::Null) => {}
1313 Some(Value::String(s)) if s == state.as_ref() => {}
1314 Some(Value::String(_)) => return Err(JmapError::state_mismatch()),
1315 Some(v) => {
1316 return Err(invalid(format!(
1317 "ifInState: expected a string or null, got {}",
1318 json_type_name(&v)
1319 )));
1320 }
1321 }
1322 acc = run_restore_phase::<O, B>(backend, caller, &account_id, restore, hooks).await?;
1323 old_state = Some(state);
1324 }
1325 let mut early_not_created = Map::new();
1326 let mut early_not_updated = Map::new();
1327 for (key, out) in [
1328 ("create", &mut early_not_created),
1329 ("update", &mut early_not_updated),
1330 ] {
1331 if let Some(Value::Object(entries)) = map.get_mut(key) {
1332 let named: Vec<String> = entries
1333 .iter()
1334 .filter(|(_, v)| v.as_object().is_some_and(names_object_history))
1335 .map(|(k, _)| k.clone())
1336 .collect();
1337 for k in named {
1338 entries.remove(&k);
1339 out.insert(k, set_error_value(object_history_set_error()));
1340 }
1341 }
1342 }
1343 let mut out = plain(Value::Object(map)).await?;
1344 if let Value::Object(primary) = &mut out.primary {
1345 if let Some(state) = old_state
1346 && primary.contains_key("oldState")
1347 {
1348 primary.insert("oldState".to_owned(), json!(state.as_ref()));
1349 }
1350 for (key, early) in [
1351 ("notCreated", early_not_created),
1352 ("notUpdated", early_not_updated),
1353 ] {
1354 if early.is_empty() {
1355 continue;
1356 }
1357 let slot = primary.entry(key.to_owned()).or_insert(Value::Null);
1358 if !slot.is_object() {
1359 *slot = Value::Object(Map::new());
1360 }
1361 if let Value::Object(m) = slot {
1362 m.extend(early);
1363 }
1364 }
1365 }
1366 if uses_history(using) {
1367 append_restore_results(&mut out.primary, &acc);
1368 }
1369 Ok(out)
1370}
1371
1372pub fn object_history_set_error() -> SetError {
1375 SetError::new(SetErrorType::InvalidProperties)
1376 .with_properties(vec![OBJECT_HISTORY_PROPERTY.to_owned()])
1377 .with_description("objectHistory is returned by Foo/get only")
1378}
1379
1380pub fn names_object_history(object: &Map<String, Value>) -> bool {
1383 object
1384 .keys()
1385 .any(|k| k == OBJECT_HISTORY_PROPERTY || k.starts_with("objectHistory/"))
1386}
1387
1388pub fn apply_restore_patch<O: SetObject>(
1401 final_version: &Map<String, Value>,
1402 patch: Option<&PatchObject>,
1403) -> Result<Map<String, Value>, Box<SetError>> {
1404 let mut out = final_version.clone();
1405 let Some(patch) = patch else {
1406 return Ok(out);
1407 };
1408 apply_patch_object(&mut out, patch.as_map())
1409 .map_err(|e| Box::new(set_error(SetErrorType::InvalidPatch, e.to_string())))?;
1410 let mut changed: Vec<String> = O::SERVER_SET
1411 .iter()
1412 .chain(O::IMMUTABLE)
1413 .filter(|p| **p != "id" || patch.as_map().contains_key("id"))
1414 .filter(|p| final_version.get(**p) != out.get(**p))
1415 .map(|p| (*p).to_owned())
1416 .collect();
1417 changed.sort();
1418 changed.dedup();
1419 if changed.is_empty() {
1420 Ok(out)
1421 } else {
1422 Err(Box::new(
1423 SetError::new(SetErrorType::InvalidProperties)
1424 .with_properties(changed)
1425 .with_description("a restore may not change a server-set or immutable property"),
1426 ))
1427 }
1428}
1429
1430pub fn restored_diff(baseline: &Map<String, Value>, stored: &Value) -> Value {
1434 let Value::Object(stored) = stored else {
1435 return Value::Null;
1436 };
1437 let diff: Map<String, Value> = stored
1438 .iter()
1439 .filter(|(k, v)| *k != "id" && baseline.get(*k) != Some(*v))
1440 .map(|(k, v)| (k.clone(), v.clone()))
1441 .collect();
1442 if diff.is_empty() {
1443 Value::Null
1444 } else {
1445 Value::Object(diff)
1446 }
1447}
1448
1449pub fn append_restore_results(primary: &mut Value, acc: &RestoreAccumulators) {
1453 let Value::Object(map) = primary else {
1454 return;
1455 };
1456 let as_value = |m: &Map<String, Value>| {
1457 if m.is_empty() {
1458 Value::Null
1459 } else {
1460 Value::Object(m.clone())
1461 }
1462 };
1463 map.insert("restored".to_owned(), as_value(&acc.restored));
1464 map.insert("notRestored".to_owned(), as_value(&acc.not_restored));
1465}
1466
1467pub fn enforce_max_objects_in_set_with_restore(
1474 args: &Map<String, Value>,
1475 restore_count: usize,
1476 max: u64,
1477) -> Result<(), JmapError> {
1478 let len = |k: &str| -> u64 {
1479 let n = match args.get(k) {
1480 Some(Value::Object(m)) => m.len(),
1481 Some(Value::Array(a)) => a.len(),
1482 _ => 0,
1483 };
1484 u64::try_from(n).unwrap_or(u64::MAX)
1485 };
1486 let count = len("create")
1487 .saturating_add(len("update"))
1488 .saturating_add(len("destroy"))
1489 .saturating_add(u64::try_from(restore_count).unwrap_or(u64::MAX));
1490 if count > max {
1491 let mut err = JmapError::request_too_large();
1492 err.description = Some("maxObjectsInSet".into());
1493 return Err(err);
1494 }
1495 Ok(())
1496}
1497
1498impl<C: Clone + Send + 'static> Dispatcher<C> {
1503 pub fn register_history_aware(
1507 &mut self,
1508 method: impl Into<String>,
1509 handler: std::sync::Arc<dyn JmapHandler<C>>,
1510 ) {
1511 let method = method.into();
1512 self.register(method.clone(), handler);
1513 self.history_aware.insert(method);
1514 }
1515
1516 pub fn object_history_gaps(&self, supported_types: &[&str]) -> Vec<String> {
1522 let mut gaps: Vec<String> = supported_types
1523 .iter()
1524 .flat_map(|t| {
1525 ["get", "set", "query", "queryChanges"]
1526 .into_iter()
1527 .map(move |m| format!("{t}/{m}"))
1528 })
1529 .filter(|m| self.handlers.contains_key(m) && !self.history_aware.contains(m))
1530 .collect();
1531 gaps.sort();
1532 gaps
1533 }
1534}
1535
1536pub(crate) fn check_history_arguments(
1558 method: &str,
1559 args: &mut Value,
1560 using: &[String],
1561 history_aware: bool,
1562) -> Result<(), JmapError> {
1563 let with_uri = uses_history(using);
1564 if with_uri && history_aware {
1565 return Ok(());
1566 }
1567 let Value::Object(map) = args else {
1568 return Ok(());
1569 };
1570 let Some((_, verb)) = method.rsplit_once('/') else {
1571 return Ok(());
1572 };
1573 let keys: &[&str] = match verb {
1574 "get" => &["includeReplaced", "includeDestroyed"],
1575 "query" | "queryChanges" => &["onlyDestroyed", "destroyedAfter", "destroyedBefore"],
1576 "set" => &["restore"],
1577 _ => return Ok(()),
1578 };
1579 for key in keys {
1580 let at_default = match map.get(*key) {
1581 None | Some(Value::Null) => true,
1582 Some(Value::Bool(false)) => !key.starts_with("destroyed") && *key != "restore",
1583 Some(Value::Object(m)) => *key == "restore" && m.is_empty(),
1584 Some(_) => false,
1585 };
1586 if !at_default {
1587 return Err(if with_uri {
1588 invalid(format!(
1589 "{method} keeps no object history, so {key} is not supported \
1590 (draft-ietf-jmap-object-history §3.1, §4, §5.1)"
1591 ))
1592 } else {
1593 without_uri(key)
1594 });
1595 }
1596 }
1597 for key in keys {
1598 map.remove(*key);
1599 }
1600 Ok(())
1601}