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 toJmapBackend::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. - 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. - 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). - Push
Subscription - A push subscription (RFC 8620 §7.2).
- Query
Changes Params - The
/queryChangesarguments (RFC 8620 §5.6) passed toJmapBackend::query_changes, afteraccountId. - Query
Changes Result - Result of a
/queryChangescall (RFC 8620 §5.6). - Query
Params - The
/queryarguments (RFC 8620 §5.5) passed toJmapBackend::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). - 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).
- SetError
- A per-item error in a
/setresponse (notCreated,notUpdated,notDestroyedmaps) (RFC 8620 §5.3). - 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
JmapBackend::get_changesandJmapBackend::query_changes. - Backend
Query Error - Error type returned by
JmapBackend::query_objects. - Backend
SetError - Error type returned by create/update/destroy backend methods.
- 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 a PatchObject cannot be applied. - SetError
Type - The machine-readable type for a
SetError(RFC 8620 §5.3 and RFC 8621).
Constants§
- CREATE_
ID_ PLACEHOLDER - The
ida/setcreate handler fills in before parsing the create object into its typed struct, whoseidis required. - MAX_
PUSH_ EXPIRY_ SECS - The furthest in the future, in seconds from now, that
PushSubscription/setletsexpiresbe: 7 days. - SERVER_
FAIL_ INTERNAL_ DESC - Static description used for every
serverFailinvocation that wraps aJmapBackend::Error(bd:JMAP-wlip.2).
Traits§
- GetObject
- Marker for object types that support
getandchangesoperations. - Jmap
Backend - Read-side backend supertrait shared by all JMAP server crates.
- Jmap
Handler - Implement this for each JMAP method handler.
- Jmap
Object - Marker trait for all JMAP object types.
- 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. - SetObject
- Marker for object types that support
set(create/update/destroy) operations.
Functions§
- apply_
jmap_ patch - Apply one RFC 8620 §5.3 PatchObject entry (
path→value) totargetin-place. - apply_
patch_ object - Apply a whole RFC 8620 §5.3 PatchObject to
target. - 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
JmapBackend::get_changeserror to theFoo/changesmethod error (RFC 8620 §5.2). - check_
known_ capabilities - Validate that every capability URI in
req.usingis in theknownset. - check_
patch_ paths - Check the RFC 8620 §5.3 PatchObject errors that
patchalone 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. - 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). - 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). - handle_
changes - Generic
*/changeshandler (RFC 8620 §5.2). - handle_
get - Generic
*/gethandler (RFC 8620 §5.1). - handle_
get_ with_ metadata handle_getfor a type the backend may list for draft-ietf-jmap-metadata-05 (JmapBackend::metadata_info).- handle_
query - Generic
*/queryhandler (RFC 8620 §5.5). - handle_
query_ changes - Generic
*/queryChangeshandler (RFC 8620 §5.6). - 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). - 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. - optional_
arg - Extract an optional, deserializable argument from a method-arguments envelope (bd:JMAP-wlip.32).
- 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_
wire_ id - Parse a client-supplied id: a
/setupdatekey, adestroyelement or an Id-typed property value. - query_
anchor_ args - Parse the RFC 8620 §5.5
/queryargumentsanchor(Id|null) andanchorOffset(Int, default0) fromargs. - 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 update PatchObject that 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. - resolve_
args - Resolve all
#keyResultReference fields inargsagainstprior_responses. - 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), forJmapBackend::query_objectsimplementations. - serialize_
value - Serialize any
serde::Serializetype to aserde_json::Value, mapping serialization errors toJmapError::server_fail. - 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_
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).
- 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. - Handler
Future - The return type for all
JmapHandlerimplementations.