Skip to main content

jmap_server/
history.rs

1//! draft-ietf-jmap-object-history-03 (`urn:ietf:params:jmap:object-history`),
2//! with the -04 editor's copy changes listed in docs/design/object-history.md
3//! §2a: the [`ObjectHistoryBackend`] trait, argument parsing, the history
4//! `Foo/get`, `Foo/query` and `Foo/queryChanges` handlers, and the pieces a
5//! data-type crate's history-aware `Foo/set` uses for the `restore` stage.
6//!
7//! Opt-in (docs/design/DECISIONS.md decision 1): a data-type crate registers
8//! these handlers through `register_<x>_handlers_with_history` for a backend
9//! that also implements [`ObjectHistoryBackend`], using
10//! [`Dispatcher::register_history_aware`]. Plain handlers are unchanged.
11
12use 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
40/// The property object history adds to every entry (§3.1).
41pub const OBJECT_HISTORY_PROPERTY: &str = "objectHistory";
42
43// ---------------------------------------------------------------------------
44// Backend trait and its parameter and result types
45// ---------------------------------------------------------------------------
46
47/// The parameters of [`ObjectHistoryBackend::get_object_history`].
48#[non_exhaustive]
49#[derive(Debug, Clone, Copy)]
50pub struct HistoryGetParams<'a> {
51    /// `ids`; `None` for every object of the type, and with
52    /// `includeDestroyed` also "every destroyed object for which the server
53    /// still retains any version" (§3).
54    pub ids: Option<&'a [Id]>,
55    /// `properties` without `objectHistory`; `None` for all.
56    pub properties: Option<&'a [String]>,
57    /// The parsed §3 arguments; at least one flag is true.
58    pub arguments: &'a HistoryGetArguments,
59}
60
61impl<'a> HistoryGetParams<'a> {
62    /// Parameters for `arguments`, every object and every property.
63    pub fn new(arguments: &'a HistoryGetArguments) -> Self {
64        Self {
65            ids: None,
66            properties: None,
67            arguments,
68        }
69    }
70
71    /// Set [`ids`](Self::ids).
72    #[must_use]
73    pub fn ids(mut self, ids: Option<&'a [Id]>) -> Self {
74        self.ids = ids;
75        self
76    }
77
78    /// Set [`properties`](Self::properties).
79    #[must_use]
80    pub fn properties(mut self, properties: Option<&'a [String]>) -> Self {
81        self.properties = properties;
82        self
83    }
84}
85
86/// What [`ObjectHistoryBackend::get_object_history`] returns.
87#[non_exhaustive]
88#[derive(Debug, Clone, PartialEq)]
89pub struct HistoryGetResult<O> {
90    /// The selected entries; each id's entries ascending by version (the
91    /// handler stable-sorts them again).
92    pub entries: Vec<HistoryEntry<O>>,
93    /// Requested ids with no entry left (§3).
94    pub not_found: Vec<Id>,
95}
96
97impl<O> HistoryGetResult<O> {
98    /// `entries` and `not_found`.
99    pub fn new(entries: Vec<HistoryEntry<O>>, not_found: Vec<Id>) -> Self {
100        Self { entries, not_found }
101    }
102}
103
104/// The parameters of [`ObjectHistoryBackend::query_destroyed`]: an ordinary
105/// query over destroyed objects plus the §4 window.
106#[non_exhaustive]
107pub struct DestroyedQueryParams<'a, O: QueryObject> {
108    /// `filter`, `sort`, `position`, `anchor`, `anchorOffset`, `limit`;
109    /// applied to each object's final version.
110    pub query: QueryParams<'a, O>,
111    /// `destroyedAfter`: destroyed strictly after this time.
112    pub destroyed_after: Option<&'a UTCDate>,
113    /// `destroyedBefore`: destroyed strictly before this time.
114    pub destroyed_before: Option<&'a UTCDate>,
115}
116
117impl<'a, O: QueryObject> DestroyedQueryParams<'a, O> {
118    /// `query` with no window.
119    pub fn new(query: QueryParams<'a, O>) -> Self {
120        Self {
121            query,
122            destroyed_after: None,
123            destroyed_before: None,
124        }
125    }
126
127    /// Set [`destroyed_after`](Self::destroyed_after).
128    #[must_use]
129    pub fn destroyed_after(mut self, t: Option<&'a UTCDate>) -> Self {
130        self.destroyed_after = t;
131        self
132    }
133
134    /// Set [`destroyed_before`](Self::destroyed_before).
135    #[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/// The parameters of [`ObjectHistoryBackend::query_destroyed_changes`]: an
143/// ordinary queryChanges plus the window the client passed to the
144/// `Foo/query` (-04 §4).
145#[non_exhaustive]
146pub struct DestroyedQueryChangesParams<'a, O: QueryObject> {
147    /// `sinceQueryState`, `filter`, `sort`, `maxChanges`, `upToId`.
148    pub query_changes: QueryChangesParams<'a, O>,
149    /// `destroyedAfter`.
150    pub destroyed_after: Option<&'a UTCDate>,
151    /// `destroyedBefore`.
152    pub destroyed_before: Option<&'a UTCDate>,
153}
154
155impl<'a, O: QueryObject> DestroyedQueryChangesParams<'a, O> {
156    /// `query_changes` with no window.
157    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    /// Set [`destroyed_after`](Self::destroyed_after).
166    #[must_use]
167    pub fn destroyed_after(mut self, t: Option<&'a UTCDate>) -> Self {
168        self.destroyed_after = t;
169        self
170    }
171
172    /// Set [`destroyed_before`](Self::destroyed_before).
173    #[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/// What [`ObjectHistoryBackend::restore_object`] returns.
181#[non_exhaustive]
182#[derive(Debug, Clone, PartialEq)]
183pub struct Restored<O> {
184    /// The object as stored after the restore.
185    pub stored: O,
186    /// The final version with the patch applied, as JSON: `restored`
187    /// reports the properties of [`stored`](Self::stored) that differ
188    /// from it (§5.1).
189    pub baseline: Map<String, Value>,
190}
191
192impl<O> Restored<O> {
193    /// `stored`, restored from `baseline`.
194    pub fn new(stored: O, baseline: Map<String, Value>) -> Self {
195        Self { stored, baseline }
196    }
197}
198
199/// Storage for object history (docs/design/object-history.md §6): the
200/// hooks behind the history `Foo/get`, destroyed `Foo/query` and
201/// `Foo/queryChanges`, and `restore` in `Foo/set`.
202///
203/// A separate trait, so a backend that offers history implements every
204/// method. None has a default: each would put wrong data on the wire.
205///
206/// # Contracts on the backend's other methods
207///
208/// - Every id-minting path (create, copy, import, ...) MUST NOT mint "the
209///   id of a destroyed object for which it retains any history, other than
210///   by restoring" (§5.1).
211/// - Updates, destroys, server cascades and changes through other
212///   protocols record versions; an object "counts as destroyed however it
213///   was removed" (§3).
214/// - `get_changes` classifies a restored id by whether it existed at
215///   `sinceState` and exists now, "exactly as if the object had never been
216///   destroyed between them" (-04 §5.1): both ⇒ `updated`, now only ⇒
217///   `created`, `sinceState` only ⇒ `destroyed`, neither ⇒ not reported. A
218///   restore is never a metadata-only change.
219/// - Only current objects reference blobs: a non-current version counts for
220///   neither garbage collection, `blobHasReference`, nor `Blob/lookup` (for
221///   blob2 and RFC 9404 alike, decision 11). A version whose blob is gone
222///   is never returned (§3.1).
223/// - Retention: discard oldest first (decision 24). The final version of a
224///   destroyed object is the newest one retained, and its `replaced` is
225///   then the destruction time (-04 §3.1).
226/// - §8.2: history never shows a version the caller could not read if it
227///   were current, nor the existence of a destroyed object the caller
228///   could not have seen.
229pub trait ObjectHistoryBackend: JmapBackend {
230    /// The `urn:ietf:params:jmap:object-history` value of `account_id`'s
231    /// `accountCapabilities` (§2.1), or `None` for no history in the
232    /// account. The handlers accept history arguments only for the types it
233    /// lists, so advertisement and behaviour agree. List only types for
234    /// which `jmap_object_history_types::is_history_type` is true.
235    fn object_history_capability(
236        &self,
237        caller: &Self::CallerCtx,
238        account_id: &Id,
239    ) -> Option<ObjectHistoryAccountCapability>;
240
241    /// The §3 selection for a history `Foo/get` (at least one flag set).
242    ///
243    /// Per id: with `includeDestroyed` false a destroyed id is `notFound`;
244    /// without `includeReplaced` only the live version (or a destroyed
245    /// object's final version). `historyAfter`/`historyBefore` are strict;
246    /// the live version is kept by after and dropped by before; then
247    /// `historySkip` from the newest (the live version counts as one); then
248    /// `historyLimit` keeps the newest. `notFound` only when nothing is left
249    /// after the skip. Each id's entries ascend by `version`; the live
250    /// version has the highest, with `replaced` and `expires` null;
251    /// `replaced` values are distinct per object. `hasOlder` counts
252    /// retained older versions whether returned or not. A supported type
253    /// without retained history still returns the live version (§3.1).
254    /// `jmap_object_history_server::VersionLog` implements all of this.
255    ///
256    /// No default: one would answer "no history" or a wrong `notFound`.
257    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    /// `Foo/query` with `onlyDestroyed` (§4): over the destroyed objects
267    /// with a retained version, restored ones excluded; `filter` and `sort`
268    /// apply to the final version; the window is strict on the final
269    /// version's `replaced`; a null or empty sort orders by destruction
270    /// time, most recent first. An unsupported filter or sort is
271    /// `BackendQueryError::Method` (`unsupportedFilter`/`unsupportedSort`).
272    ///
273    /// The returned `query_state` MUST encode that it is a destroyed query
274    /// and its window (decision 25), so
275    /// [`query_destroyed_changes`](Self::query_destroyed_changes) can tell
276    /// a mismatched state and the plain `query_changes` never takes it for
277    /// a live one.
278    ///
279    /// No default: one would claim nothing was destroyed.
280    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    /// `Foo/queryChanges` with `onlyDestroyed` (-04 §4): a destroy adds an
288    /// object, a restore or discard removes it. A `since_query_state` not
289    /// minted by [`query_destroyed`](Self::query_destroyed) for the same
290    /// window is `CannotCalculate`; so is a state the backend cannot
291    /// track (§4 MAY).
292    ///
293    /// No default: one would claim nothing changed.
294    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    /// Restore the destroyed object `id` (§5.1), applying `patch` (already
304    /// shape-checked; `None` for none) to its final version.
305    ///
306    /// Atomically: `forbidden` without write access, or when policy
307    /// declines (§8.5). `notFound` unless `id` is a destroyed object with a
308    /// retained version (a current id is `notFound`). Start from the final
309    /// version, the newest retained (-04 §3.1), and apply the patch with
310    /// [`apply_restore_patch`] (or the type's own parser): values that do
311    /// not make a valid object are `invalidProperties`. Validate as an
312    /// update: a reference to a missing object is `invalidProperties`
313    /// naming the property; a conflict is the error `Foo/set` would give
314    /// (`alreadyExists`, ...). Change nothing an update could not (-04
315    /// §5.1): immutable values are kept (an Email keeps `threadId`, and its
316    /// Thread exists again under the same id), or the restore is
317    /// `forbidden`; mutable server-set values may change. Quota counts the
318    /// restored object (`overQuota`). Store it under the old id, continue
319    /// its history, advance the type's state, and record the change for
320    /// `get_changes`. Inside a conditional scope the write belongs to the
321    /// scope.
322    ///
323    /// No default: it is a write with spec semantics.
324    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
333// ---------------------------------------------------------------------------
334// Argument parsing
335// ---------------------------------------------------------------------------
336
337fn 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
351/// A Boolean argument with default false; `null` reads as the default.
352fn 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
388/// Take the §3 history arguments out of a `Foo/get`'s `args`.
389///
390/// `None` when both flags are false or absent: the other four are then
391/// removed unread ("the server ignores historyAfter, historyBefore,
392/// historySkip, and historyLimit"). Otherwise the parsed arguments.
393///
394/// # Errors
395///
396/// `invalidArguments` for a flag that is not a Boolean, a true flag
397/// without the URI in `using` (decision 18), or (with a flag set) a
398/// malformed `historyAfter`, `historyBefore`, `historySkip` or
399/// `historyLimit`.
400pub 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
430/// Take the §4 arguments out of a `Foo/query` or `Foo/queryChanges`
431/// (-04) `args`.
432///
433/// `None` when `onlyDestroyed` is false or absent. An explicit `null`
434/// window is not "supplied" (its default is null).
435///
436/// # Errors
437///
438/// `invalidArguments` for a malformed argument; a non-null
439/// `destroyedAfter` or `destroyedBefore` with `onlyDestroyed` false (§4);
440/// `onlyDestroyed: true` or a non-null window without the URI in `using`
441/// (decision 18).
442pub 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
472/// Take `restore` (§5.1) out of a `Foo/set`'s `args`: each key as sent
473/// with its raw value. Empty when absent, `null` or `{}`.
474///
475/// # Errors
476///
477/// `invalidArguments` for a `restore` that is neither an object nor
478/// `null`, or a non-empty one without the URI in `using` (decision 18).
479pub 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
499/// Whether `O` has history in `account_id`.
500///
501/// # Errors
502///
503/// `invalidArguments` when the account's capability does not list `O`
504/// (§3.1, §4, §5.1: the server "MUST reject the call").
505pub 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
519// ---------------------------------------------------------------------------
520// Foo/get
521// ---------------------------------------------------------------------------
522
523/// Remove `objectHistory` from a `properties` argument (§3.1: the client
524/// MAY list it; it is returned "if and only if" a flag is true). Returns
525/// whether it was listed.
526pub 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
535/// Write one history entry's `objectHistory` into `item`, and keep only
536/// `properties` (plus `id` and `objectHistory`) when given.
537pub 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
548/// `Foo/get` with object history (§3).
549///
550/// With neither flag set the history arguments are removed (the four
551/// others unread), `objectHistory` is removed from `properties`, and the
552/// call is [`handle_get_with_metadata`]. Otherwise: the account must list
553/// `O` ([`require_history_support`]); `maxObjectsInGet` counts ids, not
554/// entries; [`ObjectHistoryBackend::get_object_history`] selects the
555/// entries; each is projected like a plain `Foo/get` object (`properties`,
556/// with `id` and `objectHistory` always kept; metadata per
557/// [`MetadataProjection`]); each id's entries are stable-sorted by
558/// `version`.
559///
560/// # Errors
561///
562/// Those of [`handle_get_with_metadata`], of
563/// [`parse_history_get_arguments`] and [`require_history_support`], and a
564/// redacted `serverFail` for a backend error.
565pub 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
577/// [`handle_get_with_history`] with `plain` as the call made when no history
578/// argument is set, for a type whose plain handler is its own (a custom
579/// getter, a type-specific query).
580///
581/// # Errors
582///
583/// As [`handle_get_with_history`], with `plain`'s errors in place of the default
584/// handler's.
585pub 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    // The backend gets the root of each metadata subselector.
635    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
695/// Stable-sort each id's entries by version, keeping the position of each
696/// id's first entry (§3: same-id entries "MUST be ordered by
697/// objectHistory.version (ascending)"; ids MAY interleave).
698fn 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
720// ---------------------------------------------------------------------------
721// Foo/query and Foo/queryChanges
722// ---------------------------------------------------------------------------
723
724/// `Foo/query` with `onlyDestroyed` (§4).
725///
726/// Without `onlyDestroyed` it is [`handle_query_with_i18n`]. Otherwise the
727/// account must list `O`, the ordinary query arguments are parsed as
728/// `Foo/query` parses them, and
729/// [`ObjectHistoryBackend::query_destroyed`] answers, in the `Foo/query`
730/// response shape. A type whose `/query` takes arguments for current
731/// objects only (`collapseThreads`, `expandRecurrences`) removes them
732/// first: they are ignored for a destroyed query (§4).
733///
734/// # Errors
735///
736/// Those of [`handle_query_with_i18n`] and
737/// [`parse_destroyed_query_arguments`], `invalidArguments` for an
738/// unsupported type, and the backend's `BackendQueryError::Method`
739/// (`unsupportedFilter`, `unsupportedSort`, `anchorNotFound`).
740pub 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
756/// [`handle_query_with_history`] with `plain` as the call made when no history
757/// argument is set, for a type whose plain handler is its own (a custom
758/// getter, a type-specific query).
759///
760/// # Errors
761///
762/// As [`handle_query_with_history`], with `plain`'s errors in place of the default
763/// handler's.
764pub 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
848/// `Foo/queryChanges` with `onlyDestroyed` (-04 §4: the client "MUST pass
849/// the same values that it passed to Foo/query").
850///
851/// Without `onlyDestroyed` it is [`handle_query_changes_with_i18n`]; a
852/// destroyed query's state sent there is unknown to the live
853/// `query_changes`. Otherwise
854/// [`ObjectHistoryBackend::query_destroyed_changes`] answers, in the
855/// `Foo/queryChanges` response shape.
856///
857/// # Errors
858///
859/// As [`handle_query_with_history`], plus `cannotCalculateChanges` from
860/// the backend (a state of another kind or window, or one it cannot
861/// track).
862pub 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
878/// [`handle_query_changes_with_history`] with `plain` as the call made when no history
879/// argument is set, for a type whose plain handler is its own (a custom
880/// getter, a type-specific query).
881///
882/// # Errors
883///
884/// As [`handle_query_changes_with_history`], with `plain`'s errors in place of the default
885/// handler's.
886pub 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
972// ---------------------------------------------------------------------------
973// Foo/set: the restore stage
974// ---------------------------------------------------------------------------
975
976/// Per-type hooks for [`run_restore_phase`].
977pub trait RestoreHooks: Sync {
978    /// Check a restore entry's patch as the type checks an update patch
979    /// (`#creationId` references, metadata entries, ...). The default
980    /// accepts it.
981    ///
982    /// # Errors
983    ///
984    /// The entry's [`SetError`].
985    fn check_patch(&self, id: &Id, patch: Option<&PatchObject>) -> Result<(), Box<SetError>> {
986        let _ = (id, patch);
987        Ok(())
988    }
989
990    /// The ids of objects of the same type that `final_version` refers to
991    /// (a Mailbox's or `FileNode`'s `parentId`). Restores that refer to
992    /// another restore key run after it (-04 §5.1: "as for creates"). The
993    /// default: none, so restores run in key order.
994    fn same_type_references(&self, final_version: &Map<String, Value>) -> Vec<Id> {
995        let _ = final_version;
996        Vec::new()
997    }
998}
999
1000/// [`RestoreHooks`] with every default: no extra checks, no same-type
1001/// references.
1002#[derive(Debug, Clone, Copy, Default)]
1003pub struct NoRestoreHooks;
1004
1005impl RestoreHooks for NoRestoreHooks {}
1006
1007/// [`RestoreHooks`] for a type whose objects refer to others of the same
1008/// type through one Id-valued property, such as `parentId`.
1009#[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/// What [`run_restore_phase`] produced.
1023#[non_exhaustive]
1024#[derive(Debug, Clone, Default, PartialEq)]
1025pub struct RestoreAccumulators {
1026    /// `restored`: id → the changed properties, or `null`.
1027    pub restored: Map<String, Value>,
1028    /// `notRestored`: id as sent → [`SetError`].
1029    pub not_restored: Map<String, Value>,
1030    /// Whether any restore succeeded (the type's state changed).
1031    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
1042/// Restore every entry of `restore` (from [`parse_restore_argument`]),
1043/// "before any create, update, or destroy in the same call" (§5.1).
1044///
1045/// Per entry: a key that is not an Id is `notFound` (it is "not the id of
1046/// a destroyed object"); a value that is neither `null` nor an object is
1047/// `invalidPatch`, and `{}` is the same as `null`; a patch with a bad path
1048/// is `invalidPatch`; an `objectHistory` key is `invalidProperties`; then
1049/// [`RestoreHooks::check_patch`] and
1050/// [`ObjectHistoryBackend::restore_object`]. Restores referring to
1051/// another restore key (by [`RestoreHooks::same_type_references`] on the
1052/// final versions) run after it; a cycle fails its entries with
1053/// `invalidProperties` naming `id`. `restored` holds the properties of the
1054/// stored object that differ from the final version with the patch applied
1055/// ([`restored_diff`]); a backend error becomes the entry's [`SetError`],
1056/// `Other` redacted to `serverFail`.
1057///
1058/// # Errors
1059///
1060/// `invalidArguments` for an unsupported type when `restore` is
1061/// non-empty; a redacted `serverFail` when fetching final versions for the
1062/// order fails.
1063pub 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                // Through `O` too, so serde defaults are not reported as
1140                // changes.
1141                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
1162/// Order `ready` so a restore that refers to another restore key runs
1163/// after it (-04 §5.1). Entries in a cycle go to `notRestored`.
1164async 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    // Kahn's algorithm, taking ready entries in their original order.
1210    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
1247/// A history-aware `Foo/set` around `plain`, the type's own `/set`
1248/// handler, which runs unchanged for creates, updates and destroys.
1249///
1250/// It takes `restore` out of the arguments ([`parse_restore_argument`]),
1251/// moves each create or update naming `objectHistory` to
1252/// `notCreated`/`notUpdated` (§7.3, §7.4), and, when there are restores:
1253/// counts them toward `maxObjectsInSet` (-04 §5.1), checks `ifInState`
1254/// against the state before them and removes it, runs
1255/// [`run_restore_phase`] "before any create, update, or destroy" (§5.1),
1256/// calls `plain`, and puts the state read before the restores in
1257/// `oldState`. With the URI in `using` the response always has `restored`
1258/// and `notRestored` ([`append_restore_results`]).
1259///
1260/// A method-level error from `plain` after restores were applied is
1261/// returned as is; the restores stay applied unless the call runs in a
1262/// conditional `atomic` scope.
1263///
1264/// # Errors
1265///
1266/// Those of `plain`, [`parse_restore_argument`] and [`run_restore_phase`];
1267/// `accountNotFound`, `stateMismatch` and `requestTooLarge` when there are
1268/// restores.
1269pub 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
1372/// The [`SetError`] for `objectHistory` in a create, update or restore patch:
1373/// it is reserved (§7.3, §7.4) and never stored, so `invalidProperties`.
1374pub 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
1380/// Whether a create object or update patch names `objectHistory` (or a
1381/// path below it).
1382pub 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
1388/// Apply a restore `patch` to `final_version` (§5.1: the patch "follows the
1389/// same rules as a [`PatchObject`] in an update in Foo/set"), all or nothing.
1390///
1391/// A patch that changes a [`SetObject::SERVER_SET`] or
1392/// [`SetObject::IMMUTABLE`] property is `invalidProperties` naming each;
1393/// one that repeats the final version's value is allowed (-04: "a client
1394/// can send a whole version of the object as the patch"). A bad path is
1395/// `invalidPatch`.
1396///
1397/// # Errors
1398///
1399/// The [`SetError`] above.
1400pub 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
1430/// The `restored` value for one object (§5.1): the top-level properties of
1431/// `stored` whose values differ from `baseline` (the final version with the
1432/// patch applied), or `null` when none do. `id` is never listed.
1433pub 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
1449/// Add `restored` and `notRestored` to a `Foo/set` response (§5.1: "The
1450/// response has the following additional properties"), each `null` when
1451/// empty. Call it whenever the URI is in `using`.
1452pub 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
1467/// `maxObjectsInSet` over creates, updates, destroys and `restore_count`
1468/// restores (-04 §5.1: "Each entry in restore counts as one object").
1469///
1470/// # Errors
1471///
1472/// `requestTooLarge` with description `maxObjectsInSet`.
1473pub 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
1498// ---------------------------------------------------------------------------
1499// Dispatcher marks
1500// ---------------------------------------------------------------------------
1501
1502impl<C: Clone + Send + 'static> Dispatcher<C> {
1503    /// Register a history-aware handler for `method` and mark it, for
1504    /// [`object_history_gaps`](Self::object_history_gaps). A later plain
1505    /// [`register`](Self::register) of the same name clears the mark.
1506    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    /// The registered `/get`, `/set`, `/query` and `/queryChanges` methods
1517    /// of `supported_types` that are not history-aware, sorted. A server
1518    /// MUST NOT list a type in `supportedTypes` while it has a gap here,
1519    /// for example after a plain `register_<x>_handlers` ran last and
1520    /// silently dropped `restore`.
1521    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
1536// ---------------------------------------------------------------------------
1537// Dispatcher-wide check without the URI (decision 18)
1538// ---------------------------------------------------------------------------
1539
1540/// Decision 18: without the object-history URI in `using`, reject a
1541/// history argument that asks for history, and remove the ones at their
1542/// defaults, before any handler runs, plain or history-aware.
1543///
1544/// `*/get`: `includeReplaced`, `includeDestroyed` other than `false` or
1545/// `null`. `*/query` and `*/queryChanges` (-04): `onlyDestroyed` other than
1546/// `false` or `null`, `destroyedAfter`/`destroyedBefore` other than `null`.
1547/// `*/set`: `restore` other than `null` or `{}`. `historyAfter`,
1548/// `historyBefore`, `historySkip` and `historyLimit` are left alone: §3
1549/// ignores them when both flags are false.
1550///
1551/// With the URI, a method registered through
1552/// [`Dispatcher::register_history_aware`] is left to its handler; any other
1553/// method (a type without history, such as `TaskNotification`, or one
1554/// registered plain) gets the same `invalidArguments` for a history
1555/// argument, since its type cannot be in `supportedTypes` (§3.1: "MUST
1556/// reject the call"; `object_history_gaps`).
1557pub(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}