Skip to main content

ObjectHistoryBackend

Trait ObjectHistoryBackend 

Source
pub trait ObjectHistoryBackend: JmapBackend {
    // Required methods
    fn object_history_capability(
        &self,
        caller: &Self::CallerCtx,
        account_id: &Id,
    ) -> Option<ObjectHistoryAccountCapability>;
    fn get_object_history<O: HistoryObject>(
        &self,
        caller: &Self::CallerCtx,
        account_id: &Id,
        params: HistoryGetParams<'_>,
    ) -> impl Future<Output = Result<HistoryGetResult<O>, BackendQueryError<Self::Error>>> + Send;
    fn query_destroyed<O: HistoryObject + QueryObject>(
        &self,
        caller: &Self::CallerCtx,
        account_id: &Id,
        params: DestroyedQueryParams<'_, O>,
    ) -> impl Future<Output = Result<QueryResult, BackendQueryError<Self::Error>>> + Send;
    fn query_destroyed_changes<O: HistoryObject + QueryObject>(
        &self,
        caller: &Self::CallerCtx,
        account_id: &Id,
        params: DestroyedQueryChangesParams<'_, O>,
    ) -> impl Future<Output = Result<QueryChangesResult, BackendChangesError<Self::Error>>> + Send;
    fn restore_object<O: HistoryObject + SetObject>(
        &self,
        caller: &Self::CallerCtx,
        account_id: &Id,
        id: &Id,
        patch: Option<PatchObject>,
    ) -> impl Future<Output = Result<Restored<O>, BackendSetError<Self::Error>>> + Send;
}
Expand description

Storage for object history (docs/design/object-history.md §6): the hooks behind the history Foo/get, destroyed Foo/query and Foo/queryChanges, and restore in Foo/set.

A separate trait, so a backend that offers history implements every method. None has a default: each would put wrong data on the wire.

§Contracts on the backend’s other methods

  • Every id-minting path (create, copy, import, …) MUST NOT mint “the id of a destroyed object for which it retains any history, other than by restoring” (§5.1).
  • Updates, destroys, server cascades and changes through other protocols record versions; an object “counts as destroyed however it was removed” (§3).
  • get_changes classifies a restored id by whether it existed at sinceState and exists now, “exactly as if the object had never been destroyed between them” (-04 §5.1): both ⇒ updated, now only ⇒ created, sinceState only ⇒ destroyed, neither ⇒ not reported. A restore is never a metadata-only change.
  • Only current objects reference blobs: a non-current version counts for neither garbage collection, blobHasReference, nor Blob/lookup (for blob2 and RFC 9404 alike, decision 11). A version whose blob is gone is never returned (§3.1).
  • Retention: discard oldest first (decision 24). The final version of a destroyed object is the newest one retained, and its replaced is then the destruction time (-04 §3.1).
  • §8.2: history never shows a version the caller could not read if it were current, nor the existence of a destroyed object the caller could not have seen.

Required Methods§

Source

fn object_history_capability( &self, caller: &Self::CallerCtx, account_id: &Id, ) -> Option<ObjectHistoryAccountCapability>

The urn:ietf:params:jmap:object-history value of account_id’s accountCapabilities (§2.1), or None for no history in the account. The handlers accept history arguments only for the types it lists, so advertisement and behaviour agree. List only types for which jmap_object_history_types::is_history_type is true.

Source

fn get_object_history<O: HistoryObject>( &self, caller: &Self::CallerCtx, account_id: &Id, params: HistoryGetParams<'_>, ) -> impl Future<Output = Result<HistoryGetResult<O>, BackendQueryError<Self::Error>>> + Send

The §3 selection for a history Foo/get (at least one flag set).

Per id: with includeDestroyed false a destroyed id is notFound; without includeReplaced only the live version (or a destroyed object’s final version). historyAfter/historyBefore are strict; the live version is kept by after and dropped by before; then historySkip from the newest (the live version counts as one); then historyLimit keeps the newest. notFound only when nothing is left after the skip. Each id’s entries ascend by version; the live version has the highest, with replaced and expires null; replaced values are distinct per object. hasOlder counts retained older versions whether returned or not. A supported type without retained history still returns the live version (§3.1). jmap_object_history_server::VersionLog implements all of this.

No default: one would answer “no history” or a wrong notFound.

Source

fn query_destroyed<O: HistoryObject + QueryObject>( &self, caller: &Self::CallerCtx, account_id: &Id, params: DestroyedQueryParams<'_, O>, ) -> impl Future<Output = Result<QueryResult, BackendQueryError<Self::Error>>> + Send

Foo/query with onlyDestroyed (§4): over the destroyed objects with a retained version, restored ones excluded; filter and sort apply to the final version; the window is strict on the final version’s replaced; a null or empty sort orders by destruction time, most recent first. An unsupported filter or sort is BackendQueryError::Method (unsupportedFilter/unsupportedSort).

The returned query_state MUST encode that it is a destroyed query and its window (decision 25), so query_destroyed_changes can tell a mismatched state and the plain query_changes never takes it for a live one.

No default: one would claim nothing was destroyed.

Source

fn query_destroyed_changes<O: HistoryObject + QueryObject>( &self, caller: &Self::CallerCtx, account_id: &Id, params: DestroyedQueryChangesParams<'_, O>, ) -> impl Future<Output = Result<QueryChangesResult, BackendChangesError<Self::Error>>> + Send

Foo/queryChanges with onlyDestroyed (-04 §4): a destroy adds an object, a restore or discard removes it. A since_query_state not minted by query_destroyed for the same window is CannotCalculate; so is a state the backend cannot track (§4 MAY).

No default: one would claim nothing changed.

Source

fn restore_object<O: HistoryObject + SetObject>( &self, caller: &Self::CallerCtx, account_id: &Id, id: &Id, patch: Option<PatchObject>, ) -> impl Future<Output = Result<Restored<O>, BackendSetError<Self::Error>>> + Send

Restore the destroyed object id (§5.1), applying patch (already shape-checked; None for none) to its final version.

Atomically: forbidden without write access, or when policy declines (§8.5). notFound unless id is a destroyed object with a retained version (a current id is notFound). Start from the final version, the newest retained (-04 §3.1), and apply the patch with apply_restore_patch (or the type’s own parser): values that do not make a valid object are invalidProperties. Validate as an update: a reference to a missing object is invalidProperties naming the property; a conflict is the error Foo/set would give (alreadyExists, …). Change nothing an update could not (-04 §5.1): immutable values are kept (an Email keeps threadId, and its Thread exists again under the same id), or the restore is forbidden; mutable server-set values may change. Quota counts the restored object (overQuota). Store it under the old id, continue its history, advance the type’s state, and record the change for get_changes. Inside a conditional scope the write belongs to the scope.

No default: it is a write with spec semantics.

Dyn Compatibility§

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors§