Skip to main content

JmapReads

Trait JmapReads 

Source
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§

Source

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.

Source

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.

Source

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.

Source

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.

Source

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".

Implementors§