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_changesclassifies a restored id by whether it existed atsinceStateand exists now, “exactly as if the object had never been destroyed between them” (-04 §5.1): both ⇒updated, now only ⇒created,sinceStateonly ⇒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, norBlob/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
replacedis 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§
Sourcefn object_history_capability(
&self,
caller: &Self::CallerCtx,
account_id: &Id,
) -> Option<ObjectHistoryAccountCapability>
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.
Sourcefn 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 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.
Sourcefn 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<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.
Sourcefn 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 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.
Sourcefn 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
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".