pub trait JmapReads: JmapAccounts {
// Required methods
fn get_objects<O: GetObject + Send + Sync>(
&self,
caller: &Self::CallerCtx,
account_id: &Id,
ids: Option<&[Id]>,
properties: Option<&[String]>,
) -> impl Future<Output = Result<(Vec<O>, Vec<Id>), Self::Error>> + Send;
fn get_state<O: JmapObject + Send + Sync>(
&self,
caller: &Self::CallerCtx,
account_id: &Id,
) -> impl Future<Output = Result<State, Self::Error>> + Send;
fn get_changes<O: JmapObject + Send + Sync>(
&self,
caller: &Self::CallerCtx,
account_id: &Id,
params: ChangesParams<'_>,
) -> impl Future<Output = Result<ChangesResult, BackendChangesError<Self::Error>>> + Send;
fn query_objects<O: QueryObject + Send + Sync>(
&self,
caller: &Self::CallerCtx,
account_id: &Id,
params: QueryParams<'_, O>,
) -> impl Future<Output = Result<QueryResult, BackendQueryError<Self::Error>>> + Send;
fn query_changes<O: QueryObject + Send + Sync>(
&self,
caller: &Self::CallerCtx,
account_id: &Id,
params: QueryChangesParams<'_, O>,
) -> impl Future<Output = Result<QueryChangesResult, BackendChangesError<Self::Error>>> + Send;
}Expand description
The five standard reads (RFC 8620 §5.1, §5.2, §5.5, §5.6), the half of
JmapBackend that a wrapper can forward with DelegateJmapReads.
QueryChangesParams::collapse_threads is included for
Email/queryChanges (RFC 8621 §4.5). Non-mail backends may ignore it.
Required Methods§
Sourcefn get_objects<O: GetObject + Send + Sync>(
&self,
caller: &Self::CallerCtx,
account_id: &Id,
ids: Option<&[Id]>,
properties: Option<&[String]>,
) -> impl Future<Output = Result<(Vec<O>, Vec<Id>), Self::Error>> + Send
fn get_objects<O: GetObject + Send + Sync>( &self, caller: &Self::CallerCtx, account_id: &Id, ids: Option<&[Id]>, properties: Option<&[String]>, ) -> impl Future<Output = Result<(Vec<O>, Vec<Id>), Self::Error>> + Send
Fetch objects by id (or all objects when ids is None).
properties is the list of property names requested by the client
(RFC 8620 §5.1). None means the client did not send a properties
field; the backend should return all properties. When Some, the backend
MAY filter the response to only the named properties, but is not required
to — implementations that always return all properties are correct.
Returns (found, not_found) — objects that exist and ids that do not.
§Unknown account_id
The standard handlers (crate::handle_get, crate::handle_changes,
crate::handle_query, crate::handle_query_changes) check
JmapAccounts::account_exists before calling this method and return
accountNotFound (RFC 8620 §3.6.2) themselves, so implementations
need not repeat that check. A caller that bypasses those handlers can
still reach this method with an unknown account; backends SHOULD then
return Ok with an empty found list and every requested id in not_found. Returning Err is permitted but surfaces as
serverFail, not accountNotFound.
§Localized properties
For a type with JmapObject::LOCALIZABLE properties, return the
stored base values with their locale and localizations. The
handlers build the single-language view of the language argument
themselves. Do not let the request’s Accept-Language change what
this method or query_objects returns for a localizable property:
draft-atwood-jmap-updates-00 §4.2.1 says the server MUST NOT, since
a client that caches objects by id and state could not tell the
languages apart.
Sourcefn get_state<O: JmapObject + Send + Sync>(
&self,
caller: &Self::CallerCtx,
account_id: &Id,
) -> impl Future<Output = Result<State, Self::Error>> + Send
fn get_state<O: JmapObject + Send + Sync>( &self, caller: &Self::CallerCtx, account_id: &Id, ) -> impl Future<Output = Result<State, Self::Error>> + Send
Return the current state token for an object type in the given account.
§Unknown account_id
The standard handlers (crate::handle_get, crate::handle_changes,
crate::handle_query, crate::handle_query_changes) check
JmapAccounts::account_exists before calling this method and return
accountNotFound (RFC 8620 §3.6.2) themselves, so implementations
need not repeat that check. A caller that bypasses those handlers can
still reach this method with an unknown account; backends SHOULD then
return Ok with the state token an empty account would report. Returning Err is permitted but surfaces as
serverFail, not accountNotFound.
Sourcefn get_changes<O: JmapObject + Send + Sync>(
&self,
caller: &Self::CallerCtx,
account_id: &Id,
params: ChangesParams<'_>,
) -> impl Future<Output = Result<ChangesResult, BackendChangesError<Self::Error>>> + Send
fn get_changes<O: JmapObject + Send + Sync>( &self, caller: &Self::CallerCtx, account_id: &Id, params: ChangesParams<'_>, ) -> impl Future<Output = Result<ChangesResult, BackendChangesError<Self::Error>>> + Send
Return changes since params.since_state, up to
params.max_changes entries, honouring
params.ignore_metadata_only_changes (see ChangesParams).
§Unknown account_id
The standard handlers (crate::handle_get, crate::handle_changes,
crate::handle_query, crate::handle_query_changes) check
JmapAccounts::account_exists before calling this method and return
accountNotFound (RFC 8620 §3.6.2) themselves, so implementations
need not repeat that check. A caller that bypasses those handlers can
still reach this method with an unknown account; backends SHOULD then
return Ok with a ChangesResult whose change lists are empty. Returning Err is permitted but surfaces as
serverFail, not accountNotFound.
Sourcefn query_objects<O: QueryObject + Send + Sync>(
&self,
caller: &Self::CallerCtx,
account_id: &Id,
params: QueryParams<'_, O>,
) -> impl Future<Output = Result<QueryResult, BackendQueryError<Self::Error>>> + Send
fn query_objects<O: QueryObject + Send + Sync>( &self, caller: &Self::CallerCtx, account_id: &Id, params: QueryParams<'_, O>, ) -> impl Future<Output = Result<QueryResult, BackendQueryError<Self::Error>>> + Send
Execute a /query and return a page of matching ids.
params.position may be negative — negative values are relative to
the end of the result set per RFC 8620 §5.5 (e.g. -1 means the last
result).
params.anchor and params.anchor_offset are the RFC 8620 §5.5
anchor and anchorOffset arguments. With an anchor, position MUST be
ignored and the page starts at the anchor’s index in the filtered,
sorted results plus anchor_offset, clamped to 0; an anchor not in
the results is JmapError::anchor_not_found via
BackendQueryError::Method. Without one, anchor_offset MUST be
ignored. QueryResult::position is the page’s actual start index.
crate::resolve_query_start implements this over an in-memory id
list.
§Filter and sort handling
Implementations MUST honour the supplied filter and sort arguments
efficiently — typically by pushing both into the indexed storage layer
(database WHERE / ORDER BY, search index, etc.). Returning every
matching id and relying on the caller to paginate after the fact
degenerates to O(n) per page for IMAP-migration accounts.
Handler implementations in jmap-*-server crates SHOULD NOT
post-filter or post-sort the backend’s result; doing so re-introduces
the O(n) cost this method exists to avoid. The Mailbox handler in
jmap-mail-server is the canonical example of pushing filter/sort
fully into the backend.
§Errors
Return BackendQueryError::Method for an RFC 8620 §5.5 method
error (unsupportedFilter, unsupportedSort, anchorNotFound,
…); handlers pass it to the client unchanged. Return
BackendQueryError::Other (or use ? on Self::Error) for an
internal failure; handlers surface it as a redacted serverFail.
§Unknown account_id
The standard handlers (crate::handle_get, crate::handle_changes,
crate::handle_query, crate::handle_query_changes) check
JmapAccounts::account_exists before calling this method and return
accountNotFound (RFC 8620 §3.6.2) themselves, so implementations
need not repeat that check. A caller that bypasses those handlers can
still reach this method with an unknown account; backends SHOULD then
return Ok with an empty QueryResult page. Returning Err is permitted but surfaces as
serverFail, not accountNotFound.
Sourcefn query_changes<O: QueryObject + Send + Sync>(
&self,
caller: &Self::CallerCtx,
account_id: &Id,
params: QueryChangesParams<'_, O>,
) -> impl Future<Output = Result<QueryChangesResult, BackendChangesError<Self::Error>>> + Send
fn query_changes<O: QueryObject + Send + Sync>( &self, caller: &Self::CallerCtx, account_id: &Id, params: QueryChangesParams<'_, O>, ) -> impl Future<Output = Result<QueryChangesResult, BackendChangesError<Self::Error>>> + Send
Execute a /queryChanges and return deltas since since_query_state.
params.collapse_threads is only meaningful for Email/queryChanges
(RFC 8621 §4.5); it is false for all other object types.
§Unknown account_id
The standard handlers (crate::handle_get, crate::handle_changes,
crate::handle_query, crate::handle_query_changes) check
JmapAccounts::account_exists before calling this method and return
accountNotFound (RFC 8620 §3.6.2) themselves, so implementations
need not repeat that check. A caller that bypasses those handlers can
still reach this method with an unknown account; backends SHOULD then
return Ok with a QueryChangesResult whose removed and added lists are empty. Returning Err is permitted but surfaces as
serverFail, not accountNotFound.
Dyn Compatibility§
This trait is not dyn compatible.
In older versions of Rust, dyn compatibility was called "object safety".