Expand description
Backend-agnostic JMAP server framework (RFC 8620).
Provides request parsing, ResultReference resolution, HTTP response helpers,
the Dispatcher machinery, shared backend infrastructure, and generic
JMAP method handlers.
§Version coupling with jmap-types (bd:JMAP-wlip.18)
This crate re-exports the wire-format types from jmap-types
(Id, JmapError, JmapRequest, JmapResponse, Invocation,
PushSubscription, ResultReference, Argument, State, UTCDate)
plus the marker traits (GetObject, JmapObject, QueryObject,
SetObject).
The public API of this crate is therefore coupled to
jmap-types’ public API: any breaking change to a re-exported
type in jmap-types is a breaking change here, even when this
crate’s own surface is otherwise additive.
Semver pin discipline: consumers that depend on both
jmap-server and jmap-types directly MUST pin the jmap-types
version to the exact version jmap-server resolves to. The
simplest path is to NOT depend on jmap-types directly and use
jmap_server::{Id, JmapError, ...} instead — re-exports
guarantee consistency. Depending on both with mismatched versions
produces cargo’s “expected jmap_types::Id, found jmap_types::Id”
error (same type name, two different version hashes).
Structs§
- Added
Item - One entry in the
addedlist of a/queryChangesresponse (RFC 8620 §5.6). - Call
Context - Everything
Dispatcher::dispatchhands aJmapHandlerfor one method call (RFC 8620 §3.2 Invocation, plus the caller). - Changes
Params - The
/changesarguments (RFC 8620 §5.2) passed toJmapReads::get_changes, afteraccountId. - Changes
Result - Result of a
/changescall (RFC 8620 §5.2). - Closure
Handler - A
JmapHandlerthat wraps an async closure over a shared backend and forwardsCallerCtxto it. - Data
Type Metadata Info - The draft-ietf-jmap-metadata-05 §1.2.1
DataTypeMetadataInfothatJmapAccounts::metadata_inforeturns, re-exported so a backend or a wrapper can name it without a directjmap-metadata-typesdependency. Per-data-type metadata capability advertisement (draft-ietf-jmap-metadata-05 §1.2.1). - Deferred
Failure - One change rejected at commit, with its
SetError. - Destroyed
Query Changes Params - The parameters of
ObjectHistoryBackend::query_destroyed_changes: an ordinary queryChanges plus the window the client passed to theFoo/query(-04 §4). - Destroyed
Query Params - The parameters of
ObjectHistoryBackend::query_destroyed: an ordinary query over destroyed objects plus the §4 window. - Dispatcher
- Dispatches a
JmapRequestto registered method handlers. - Duplicate
Method Error - Returned by
Dispatcher::try_registerwhen a handler is already registered under the requested method name. - Handler
Output - The successful result of one
JmapHandler::call. - History
GetParams - The parameters of
ObjectHistoryBackend::get_object_history. - History
GetResult - What
ObjectHistoryBackend::get_object_historyreturns. - I18n
Info - What a backend supports for
urn:ietf:params:jmap:i18nin one account, asJmapAccounts::i18n_inforeturns it. - I18n
Projection - How a
Foo/gethandler returnslocaleandlocalizations(draft-atwood-jmap-updates-00 §3, §4.2.1). - I18nSet
- How a
Foo/sethandler treatslocaleandlocalizations(draft-atwood-jmap-updates-00 §3, §4.1). - Id
- Opaque non-empty server-assigned identifier (RFC 8620 §1.2).
- Invocation
- A JMAP method invocation (RFC 8620 §3.2).
- Jmap
Error - JMAP method-level error, serializable for inclusion in
methodResponses. - Jmap
Request - JMAP request envelope (RFC 8620 §3.3).
- Jmap
Response - JMAP response envelope (RFC 8620 §3.4).
- Metadata
Projection - How a
Foo/gethandler returnsmetadataandprivateMetadata(draft-ietf-jmap-metadata-05 §2 and §3.1). - NoRestore
Hooks RestoreHookswith every default: no extra checks, no same-type references.- Parent
Restore Hooks RestoreHooksfor a type whose objects refer to others of the same type through one Id-valued property, such asparentId.- Push
Subscription - A push subscription (RFC 8620 §7.2).
- Query
Changes Params - The
/queryChangesarguments (RFC 8620 §5.6) passed toJmapReads::query_changes, afteraccountId. - Query
Changes Result - Result of a
/queryChangescall (RFC 8620 §5.6). - Query
Params - The
/queryarguments (RFC 8620 §5.5) passed toJmapReads::query_objects, afteraccountId. - Query
Result - Result of a
/querycall (RFC 8620 §5.5). - Request
Error - A request-level JMAP error response: HTTP status code + JMAP error body.
- Reserved
Extras Key - Returned by
SetError::validate_extraswhenSetError::extracontains a key that collides with a typed-field wire-name (bd:JMAP-jfia.17). - Restore
Accumulators - What
run_restore_phaseproduced. - Restored
- What
ObjectHistoryBackend::restore_objectreturns. - Result
Reference - A reference to the result of a previous invocation in the same JMAP request batch. Used in method arguments with a “#” prefix on the JSON key (RFC 8620 §9).
- Scope
Gate scoped-state - The lock a
ScopedStatewaits on while another task’sSetScopeis open. - Scoped
Guard scoped-state - Access to a
ScopedState’s value, fromScopedState::lockorScopedState::lock_unscoped. - Scoped
State scoped-state - A memory backend’s state behind a mutex, gated by a
ScopeGateso a conditional-02SetScopecan isolate it and roll it back (docs/design/conditional.md §7). - SetError
- A per-item error in a
/setresponse (notCreated,notUpdated,notDestroyedmaps) (RFC 8620 §5.3). - SetScope
Id - Identifies one Foo/set method call’s
SetScope. - SetScope
Request - What
ConditionalBackend::begin_setis asked to open. - SetSupport
- Conditional support for one Foo/set method, attached with
Dispatcher::attach_set_support. - State
- Opaque server state token (RFC 8620 §1.2).
- Stored
Push Subscription - A push subscription as the backend stores it.
- UTCDate
- RFC 3339 UTC timestamp string (RFC 8620 §1.4).
Enums§
- Argument
- A JMAP method argument that can be either a direct value or a
ResultReference. - Backend
Changes Error - Error type returned by
JmapReads::get_changesandJmapReads::query_changes. - Backend
Query Error - Error type returned by
JmapReads::query_objects. - Backend
SetError - Error type returned by create/update/destroy backend methods.
- Begin
SetError - Why
ConditionalBackend::begin_setdid not open a scope. - Commit
Error - Why
SetScope::commitdid not commit. - Merge
Patch Error - Error returned by
json_merge_patchwhen a patch cannot be applied. - Patch
Path Error - Error returned by
apply_jmap_patchandapply_patch_objectwhen aPatchObjectcannot be applied. - Registration
Error - Why
Dispatcher::attach_set_supportrefused. - SetError
Type - The machine-readable type for a
SetError(RFC 8620 §5.3 and RFC 8621). - SetMode
- How a Foo/set method’s changes must apply.
- SetOp
- A change a
SetScopecould not commit.
Constants§
- CREATE_
ID_ PLACEHOLDER - The
ida/setcreate handler fills in before parsing the create object into its typed struct, whoseidis required. - MAX_
FILTER_ DEPTH - Maximum
FilterOperatornesting a method call’sfilterargument may have when it passes throughcrate::Dispatcher::dispatch. - MAX_
PUSH_ EXPIRY_ SECS - The furthest in the future, in seconds from now, that
PushSubscription/setletsexpiresbe: 7 days. - OBJECT_
HISTORY_ PROPERTY - The property object history adds to every entry (§3.1).
- SERVER_
FAIL_ INTERNAL_ DESC - Static description used for every
serverFailinvocation that wraps aJmapAccounts::Error(bd:JMAP-wlip.2).
Traits§
- Conditional
Backend - The conditional-02 backend hooks, required only by the opt-in
register_<x>_conditionalfns (decision 1). - Delegate
Jmap Accounts - Forward
JmapAccountsto another backend, overriding only what the wrapper changes: implement this instead ofJmapAccounts, and the blanket impl answers everyJmapAccountsmethod with this trait’s method of the same name, each of which defaults to the one ofSelf::jmap_accounts. - Delegate
Jmap Reads - Forward
JmapReadsto another backend: implement this instead ofJmapReads, and the blanket impl sends every read toSelf::jmap_reads. - GetObject
- Marker for object types that support
getandchangesoperations. - Jmap
Accounts - Per-account information every JMAP backend supplies: the error and caller context types, the account check, the caller’s principal and Accept-Language, the request limits, and the metadata and i18n hooks.
- Jmap
Backend - Backend supertrait shared by all JMAP server crates:
JmapAccountsplusJmapReads. - Jmap
Handler - Implement this for each JMAP method handler.
- Jmap
Object - Marker trait for all JMAP object types.
- Jmap
Reads - The five standard reads (RFC 8620 §5.1, §5.2, §5.5, §5.6), the half of
JmapBackendthat a wrapper can forward withDelegateJmapReads. - Memory
Caller - A caller context the in-repo reference
MemoryBackends accept as theirJmapAccounts::CallerCtx: anything that names the caller’s Principal, or names none. - Object
History Backend - Storage for object history (docs/design/object-history.md §6): the
hooks behind the history
Foo/get, destroyedFoo/queryandFoo/queryChanges, andrestoreinFoo/set. - Push
Subscription Backend - Storage for RFC 8620 §7.2 push subscriptions, scoped to the caller’s credentials rather than to an account.
- Query
Object - Marker for object types that support
queryandqueryChangesoperations. - Restore
Hooks - Per-type hooks for
run_restore_phase. - SetObject
- Marker for object types that support
set(create/update/destroy) operations. - SetScope
- An open isolation (and, for
SetMode::Atomic, transaction) scope over one Foo/set method call, fromConditionalBackend::begin_set.
Functions§
- append_
restore_ results - Add
restoredandnotRestoredto aFoo/setresponse (§5.1: “The response has the following additional properties”), eachnullwhen empty. Call it whenever the URI is inusing. - apply_
jmap_ patch - Apply one RFC 8620 §5.3
PatchObjectentry (path→value) totargetin-place. - apply_
patch_ object - Apply a whole RFC 8620 §5.3
PatchObjecttotarget. - apply_
restore_ patch - Apply a restore
patchtofinal_version(§5.1: the patch “follows the same rules as aPatchObjectin an update in Foo/set”), all or nothing. - attach_
object_ history - Write one history entry’s
objectHistoryintoitem, and keep onlyproperties(plusidandobjectHistory) when given. - backend_
set_ error_ value - The
notCreated/notUpdated/notDestroyedmap value for a backend/setfailure (RFC 8620 §5.3). - bool_
arg - Read an optional boolean argument from a method-arguments envelope without removing it (bd:JMAP-ic0j.39).
- changes_
error_ from_ backend - Map a
JmapReads::get_changeserror to theFoo/changesmethod error (RFC 8620 §5.2). - check_
blob_ ids - Check that every blobId under one of
keysin a/setcreate object or update patch is an Id (RFC 8620 §1.2), at any depth: a key such as"blobId", or a patch path whose last segment is one (such as"media/p/blobId").nullpasses; the type decides whether it is allowed. - check_
known_ capabilities - Validate that every capability URI in
req.usingis in theknownset. - check_
patch_ paths - Check the RFC 8620 §5.3
PatchObjecterrors thatpatchalone determines, without the object it applies to. - check_
read_ only_ patch - Check a
/setupdatepatchof the stored objectidagainst the server-set and immutable properties ofO, and report a no-op. - current_
set_ scope - The
SetScopeof the conditional Foo/set method running on this task, orNoneoutside one. - enforce_
max_ objects_ in_ get - Enforce RFC 8620 §5.1
maxObjectsInGetat the top of a/gethandler (bd:JMAP-yt1w.31). - enforce_
max_ objects_ in_ set - Enforce RFC 8620 §5.3
maxObjectsInSetcap at the top of a/sethandler (bd:JMAP-ayoz.41.1). - enforce_
max_ objects_ in_ set_ with_ restore maxObjectsInSetover creates, updates, destroys andrestore_countrestores (-04 §5.1: “Each entry in restore counts as one object”).- error_
invocation - Wrap a method-level error as an error
InvocationformethodResponses. - error_
status - Map a
JmapErrortype string to the appropriate HTTP status code. - extract_
account_ id - Extract
accountIdfrom a JMAP method arguments envelope and return both the extractedIdand the remaining argument map. - filter_
arg - Remove and decode the optional
filterargument of a hand-written/queryor/queryChangeshandler (RFC 8620 §5.5). - filter_
nests_ deeper_ than trueiffilter(an RFC 8620 §5.5FilterOperatororFilterCondition) has more thanlevelsnestedconditionsarrays. A bareFilterConditionis depth 0; each enclosing operator adds one. Recurses at mostlevels + 1times.- handle_
changes - Generic
*/changeshandler (RFC 8620 §5.2). - handle_
get - Generic
*/gethandler (RFC 8620 §5.1). - handle_
get_ with_ history Foo/getwith object history (§3).- handle_
get_ with_ metadata handle_getfor a type the backend may list for draft-ietf-jmap-metadata-05 (JmapAccounts::metadata_info).- handle_
query - Generic
*/queryhandler (RFC 8620 §5.5). - handle_
query_ changes - Generic
*/queryChangeshandler (RFC 8620 §5.6). - handle_
query_ changes_ with_ history Foo/queryChangeswithonlyDestroyed(-04 §4: the client “MUST pass the same values that it passed to Foo/query”).- handle_
query_ changes_ with_ i18n handle_query_changesfor a type withJmapObject::LOCALIZABLEproperties (draft-atwood-jmap-updates-00 §4.2.3).- handle_
query_ with_ history Foo/querywithonlyDestroyed(§4).- handle_
query_ with_ i18n handle_queryfor a type withJmapObject::LOCALIZABLEproperties (draft-atwood-jmap-updates-00 §4.2.2).- history_
get handle_get_with_historywithplainas the call made when no history argument is set, for a type whose plain handler is its own (a custom getter, a type-specific query).- history_
query handle_query_with_historywithplainas the call made when no history argument is set, for a type whose plain handler is its own (a custom getter, a type-specific query).- history_
query_ changes handle_query_changes_with_historywithplainas the call made when no history argument is set, for a type whose plain handler is its own (a custom getter, a type-specific query).- history_
set - A history-aware
Foo/setaroundplain, the type’s own/sethandler, which runs unchanged for creates, updates and destroys. - is_
client_ updatable - Whether a client may change
propofOin a/setupdate: it is inSetObject::CLIENT_SETTABLEand not inSetObject::IMMUTABLE. - is_
deliverable - Whether a push may be sent to
storedatnow_secsseconds since the Unix epoch: the subscription is verified and has not expired. - json_
merge_ patch - Apply a JSON Merge Patch (RFC 7396) to
targetin-place. - json_
type_ name - Name the top-level JSON type of
v(null,boolean,number,string,arrayorobject) for an error description. - limit_
or_ max - Convert an RFC 8620
limit/maxChangesargument (UnsignedInt|null) to ausizeitem count forIterator::take(bd:JMAP-pgj7). - localized_
query_ state - The
queryStateto return from aFoo/querywhoselanguagewaslanguage(draft-atwood-jmap-updates-00 §4.2.3: “The queryState of a /query result reflects the language it was computed with”). - localized_
update - The draft-atwood-jmap-updates-00 §4.1 rules that need the patched
object, for a backend’s
update_objectof a type withJmapObject::LOCALIZABLEproperties. - names_
object_ history - Whether a create object or update patch names
objectHistory(or a path below it). - not_
found_ json - Convert a slice of
Ids to a JSONnotFoundvalue. - now_
utc_ string - Return the current UTC instant as an
UTCDate(RFC 3339, millisecond precision, formatYYYY-MM-DDTHH:MM:SS.mmmZ, orYYYY-MM-DDTHH:MM:SSZwhen the milliseconds are zero because RFC 8620 §1.4 says the “time-secfrac” “MUST always be omitted if zero”). For years0000..=9999the value passesUTCDate::new_validated. - now_
utc_ string_ checked - Return the current UTC instant as an
UTCDatein the same format asnow_utc_string, orNoneif the system clock cannot be expressed as an RFC 3339 timestamp. - object_
history_ set_ error - The
SetErrorforobjectHistoryin a create, update or restore patch: it is reserved (§7.3, §7.4) and never stored, soinvalidProperties. - optional_
arg - Extract an optional, deserializable argument from a method-arguments envelope (bd:JMAP-wlip.32).
- parse_
destroyed_ query_ arguments - Take the §4 arguments out of a
Foo/queryorFoo/queryChanges(-04)args. - parse_
history_ get_ arguments - Take the §3 history arguments out of a
Foo/get’sargs. - parse_
max_ changes - Parse the optional
maxChangesargument of/changesand/queryChanges. RFC 8620 §5.2: “If supplied by the client, the value MUST be a positive integer greater than 0. If a value outside of this range is given, the server MUST reject the call with an “invalidArguments” error.“ §5.6 gives no range of its own, so the same rule applies to/queryChanges. - parse_
request - Parse and validate a JMAP request from a raw JSON value.
- parse_
request_ bytes - Parse and validate a JMAP request from the raw HTTP request body.
- parse_
restore_ argument - Take
restore(§5.1) out of aFoo/set’sargs: each key as sent with its raw value. Empty when absent,nullor{}. - parse_
wire_ id - Parse a client-supplied id: a
/setupdatekey, adestroyelement or an Id-typed property value. - patch_
values_ as_ object - The values of an RFC 8620 §5.3
PatchObjectplaced at their JSON Pointer paths in an empty object, so checks written for a whole object can see what a patch writes:{"links/l1/uri": "x"}becomes{"links": {"l1": {"uri": "x"}}}. Paths are split on/and unescaped (RFC 6901~1,~0); a path that runs through a value already placed as a non-object is skipped.nullvalues (removals) are skipped. - problem_
response - An HTTP error response with an RFC 9457 problem details body, for any JMAP HTTP resource (draft-atwood-jmap-updates-00 §7.2: the Session resource, API, upload, download, event source, WebSocket opening handshake and extension resources SHOULD all return one on a 4xx or 5xx).
- query_
anchor_ args - Parse the RFC 8620 §5.5
/queryargumentsanchor(Id|null) andanchorOffset(Int, default0) fromargs. - register_
push_ subscription_ conditional - Opt
PushSubscription/setin to draft-ietf-jmap-conditional-02 (ifUnchangedByandatomic), afterregister_push_subscription_handlers(docs/design/DECISIONS.md decisions 1, 16 and 17). - register_
push_ subscription_ handlers - Register the
PushSubscription/get(RFC 8620 §7.2.1) andPushSubscription/set(RFC 8620 §7.2.2) handlers ondispatcher. - reject_
did_ bearing_ properties - Reject a
/setcreate object that carries a DID-bearing property, or an updatePatchObjectthat changes one (draft-atwood-jmap-did-00 §ThedidProperty). - reject_
metadata_ filter_ arg reject_metadata_filter_without_capabilityon the undecodedfilterargument of aFoo/queryorFoo/queryChangesrequest, for handlers that passargson tohandle_queryorhandle_query_changesand so never hold the decoded filter. Afilterthat does not decode is left for that handler to report.- reject_
metadata_ filter_ without_ capability - draft-ietf-jmap-metadata-05 §3: the §3.6 filter conditions extend
Foo/queryonly for “requests whose using includes urn:ietf:params:jmap:metadata”. Without it a metadata leaf anywhere infilter, asis_metadatajudges a condition, isunsupportedFilter(RFC 8620 §5.5: “The filter is syntactically valid, but the server cannot process it”).Foo/queryandFoo/queryChangeshandlers call it once the filter is decoded. - reject_
read_ only_ patch - Reject a
/setupdate patch that names a server-set or immutable property ofO. - reject_
server_ set - Reject a
/setcreate that carries a server-set property ofO. - request_
error - Convenience constructor: wrap a
JmapErrorin aRequestError, deriving the HTTP status code automatically. - require_
history_ support - Whether
Ohas history inaccount_id. - resolve_
args - Resolve all
#keyResultReferencefields inargsagainstprior_responses. - resolve_
blob_ ref - A blobId-typed value with a
#creationIdreference (RFC 8620 §5.3) replaced by the id an earlier method call of the request created, such as a blob fromBlob/upload,Blob/setorBlob/convert(draft-ietf-jmap-blobext-03 §8, “later method calls”). - resolve_
blob_ refs - Rewrite every blobId reference in a
/setcreate object or update patch throughresolve_blob_ref, before the handler parses it. - resolve_
creation_ ref - Resolve an Id-typed value that may be a creation-id reference (RFC 8620 §5.3).
- resolve_
query_ offset - Resolve a request-side
positionargument (RFC 8620 §5.5) into a 0-based start index suitable for slicing the full ordered result list (bd:JMAP-qz9v.48). - resolve_
query_ start - Start index of a
/querypage within the filtered, sortedids(RFC 8620 §5.5), forJmapReads::query_objectsimplementations. - resolve_
set_ id_ refs - Rewrite the
updatekeys anddestroyentries of/setarguments that are#creationIdreferences (RFC 8620 §5.3) to the ids they name. - restored_
diff - The
restoredvalue for one object (§5.1): the top-level properties ofstoredwhose values differ frombaseline(the final version with the patch applied), ornullwhen none do.idis never listed. - run_
restore_ phase - Restore every entry of
restore(fromparse_restore_argument), “before any create, update, or destroy in the same call” (§5.1). - serialize_
value - Serialize any
serde::Serializetype to aserde_json::Value, mapping serialization errors toJmapError::server_fail. - serialized_
writes_ scope - A
SetScopethat does nothing, for a backend that already serializes every write per account. - server_
fail_ from_ backend - Construct a
JmapError::server_failfor a backend-originated error without echoing the backend error’sDisplayoutput onto the wire (bd:JMAP-wlip.2). - server_
fail_ value_ from_ backend - Construct the per-id
serverFailValueused inside thenotCreated/notUpdated/notDestroyedmaps of/setresponses (bd:JMAP-ic0j.68), without echoing the backend error’sDisplayoutput onto the wire. - state_
change_ for - The
StateChangeto push tosubfor thechangedmap, orNoneif none of its types changed. - strip_
object_ history_ property - Remove
objectHistoryfrom apropertiesargument (§3.1: the client MAY list it; it is returned “if and only if” a flag is true). Returns whether it was listed. - strip_
read_ only_ patch - Reject a
/setupdatepatchthat changes a server-set or immutable property ofO, then drop the keys that repeat the stored value. - take_
bool_ arg - Read an optional boolean argument from a method-arguments envelope, removing it from the map (bd:JMAP-ic0j.39).
- unwrap_
query_ state - The backend’s queryState inside a
Foo/queryChangessinceQueryState, checked against the request’slanguage. - uses_
i18n trueifusingincludesurn:ietf:params:jmap:i18n(draft-atwood-jmap-updates-00 §3). Capability URIs compare as exact strings (§7.1).- uses_
metadata trueifusingincludesurn:ietf:params:jmap:metadata(draft-ietf-jmap-metadata-05 §3: the extensions “apply to requests whose using includes urn:ietf:params:jmap:metadata”).- utc_
date_ from_ epoch_ seconds - Format
secsseconds since the Unix epoch as a seconds-precisionUTCDate(YYYY-MM-DDTHH:MM:SSZ, RFC 8620 §1.4), orNoneif the year falls outside0000..=9999, which that four-digit form cannot express.
Type Aliases§
- Backend
Call Fn - Type alias for the closure stored inside
ClosureHandler. - Commit
Future - The future
SetScope::commitreturns. - Handler
Future - The return type for all
JmapHandlerimplementations. - Rollback
Future - The future
SetScope::rollbackreturns.