Skip to main content

Crate jmap_server

Crate jmap_server 

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

AddedItem
One entry in the added list of a /queryChanges response (RFC 8620 §5.6).
CallContext
Everything Dispatcher::dispatch hands a JmapHandler for one method call (RFC 8620 §3.2 Invocation, plus the caller).
ChangesParams
The /changes arguments (RFC 8620 §5.2) passed to JmapReads::get_changes, after accountId.
ChangesResult
Result of a /changes call (RFC 8620 §5.2).
ClosureHandler
A JmapHandler that wraps an async closure over a shared backend and forwards CallerCtx to it.
DataTypeMetadataInfo
The draft-ietf-jmap-metadata-05 §1.2.1 DataTypeMetadataInfo that JmapAccounts::metadata_info returns, re-exported so a backend or a wrapper can name it without a direct jmap-metadata-types dependency. Per-data-type metadata capability advertisement (draft-ietf-jmap-metadata-05 §1.2.1).
DeferredFailure
One change rejected at commit, with its SetError.
DestroyedQueryChangesParams
The parameters of ObjectHistoryBackend::query_destroyed_changes: an ordinary queryChanges plus the window the client passed to the Foo/query (-04 §4).
DestroyedQueryParams
The parameters of ObjectHistoryBackend::query_destroyed: an ordinary query over destroyed objects plus the §4 window.
Dispatcher
Dispatches a JmapRequest to registered method handlers.
DuplicateMethodError
Returned by Dispatcher::try_register when a handler is already registered under the requested method name.
HandlerOutput
The successful result of one JmapHandler::call.
HistoryGetParams
The parameters of ObjectHistoryBackend::get_object_history.
HistoryGetResult
What ObjectHistoryBackend::get_object_history returns.
I18nInfo
What a backend supports for urn:ietf:params:jmap:i18n in one account, as JmapAccounts::i18n_info returns it.
I18nProjection
How a Foo/get handler returns locale and localizations (draft-atwood-jmap-updates-00 §3, §4.2.1).
I18nSet
How a Foo/set handler treats locale and localizations (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).
JmapError
JMAP method-level error, serializable for inclusion in methodResponses.
JmapRequest
JMAP request envelope (RFC 8620 §3.3).
JmapResponse
JMAP response envelope (RFC 8620 §3.4).
MetadataProjection
How a Foo/get handler returns metadata and privateMetadata (draft-ietf-jmap-metadata-05 §2 and §3.1).
NoRestoreHooks
RestoreHooks with every default: no extra checks, no same-type references.
ParentRestoreHooks
RestoreHooks for a type whose objects refer to others of the same type through one Id-valued property, such as parentId.
PushSubscription
A push subscription (RFC 8620 §7.2).
QueryChangesParams
The /queryChanges arguments (RFC 8620 §5.6) passed to JmapReads::query_changes, after accountId.
QueryChangesResult
Result of a /queryChanges call (RFC 8620 §5.6).
QueryParams
The /query arguments (RFC 8620 §5.5) passed to JmapReads::query_objects, after accountId.
QueryResult
Result of a /query call (RFC 8620 §5.5).
RequestError
A request-level JMAP error response: HTTP status code + JMAP error body.
ReservedExtrasKey
Returned by SetError::validate_extras when SetError::extra contains a key that collides with a typed-field wire-name (bd:JMAP-jfia.17).
RestoreAccumulators
What run_restore_phase produced.
Restored
What ObjectHistoryBackend::restore_object returns.
ResultReference
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).
ScopeGatescoped-state
The lock a ScopedState waits on while another task’s SetScope is open.
ScopedGuardscoped-state
Access to a ScopedState’s value, from ScopedState::lock or ScopedState::lock_unscoped.
ScopedStatescoped-state
A memory backend’s state behind a mutex, gated by a ScopeGate so a conditional-02 SetScope can isolate it and roll it back (docs/design/conditional.md §7).
SetError
A per-item error in a /set response (notCreated, notUpdated, notDestroyed maps) (RFC 8620 §5.3).
SetScopeId
Identifies one Foo/set method call’s SetScope.
SetScopeRequest
What ConditionalBackend::begin_set is 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).
StoredPushSubscription
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.
BackendChangesError
Error type returned by JmapReads::get_changes and JmapReads::query_changes.
BackendQueryError
Error type returned by JmapReads::query_objects.
BackendSetError
Error type returned by create/update/destroy backend methods.
BeginSetError
Why ConditionalBackend::begin_set did not open a scope.
CommitError
Why SetScope::commit did not commit.
MergePatchError
Error returned by json_merge_patch when a patch cannot be applied.
PatchPathError
Error returned by apply_jmap_patch and apply_patch_object when a PatchObject cannot be applied.
RegistrationError
Why Dispatcher::attach_set_support refused.
SetErrorType
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 SetScope could not commit.

Constants§

CREATE_ID_PLACEHOLDER
The id a /set create handler fills in before parsing the create object into its typed struct, whose id is required.
MAX_FILTER_DEPTH
Maximum FilterOperator nesting a method call’s filter argument may have when it passes through crate::Dispatcher::dispatch.
MAX_PUSH_EXPIRY_SECS
The furthest in the future, in seconds from now, that PushSubscription/set lets expires be: 7 days.
OBJECT_HISTORY_PROPERTY
The property object history adds to every entry (§3.1).
SERVER_FAIL_INTERNAL_DESC
Static description used for every serverFail invocation that wraps a JmapAccounts::Error (bd:JMAP-wlip.2).

Traits§

ConditionalBackend
The conditional-02 backend hooks, required only by the opt-in register_<x>_conditional fns (decision 1).
DelegateJmapAccounts
Forward JmapAccounts to another backend, overriding only what the wrapper changes: implement this instead of JmapAccounts, and the blanket impl answers every JmapAccounts method with this trait’s method of the same name, each of which defaults to the one of Self::jmap_accounts.
DelegateJmapReads
Forward JmapReads to another backend: implement this instead of JmapReads, and the blanket impl sends every read to Self::jmap_reads.
GetObject
Marker for object types that support get and changes operations.
JmapAccounts
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.
JmapBackend
Backend supertrait shared by all JMAP server crates: JmapAccounts plus JmapReads.
JmapHandler
Implement this for each JMAP method handler.
JmapObject
Marker trait for all JMAP object types.
JmapReads
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.
MemoryCaller
A caller context the in-repo reference MemoryBackends accept as their JmapAccounts::CallerCtx: anything that names the caller’s Principal, or names none.
ObjectHistoryBackend
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.
PushSubscriptionBackend
Storage for RFC 8620 §7.2 push subscriptions, scoped to the caller’s credentials rather than to an account.
QueryObject
Marker for object types that support query and queryChanges operations.
RestoreHooks
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, from ConditionalBackend::begin_set.

Functions§

append_restore_results
Add restored and notRestored to a Foo/set response (§5.1: “The response has the following additional properties”), each null when empty. Call it whenever the URI is in using.
apply_jmap_patch
Apply one RFC 8620 §5.3 PatchObject entry (path → value) to target in-place.
apply_patch_object
Apply a whole RFC 8620 §5.3 PatchObject to target.
apply_restore_patch
Apply a restore patch to final_version (§5.1: the patch “follows the same rules as a PatchObject in an update in Foo/set”), all or nothing.
attach_object_history
Write one history entry’s objectHistory into item, and keep only properties (plus id and objectHistory) when given.
backend_set_error_value
The notCreated / notUpdated / notDestroyed map value for a backend /set failure (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_changes error to the Foo/changes method error (RFC 8620 §5.2).
check_blob_ids
Check that every blobId under one of keys in a /set create 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"). null passes; the type decides whether it is allowed.
check_known_capabilities
Validate that every capability URI in req.using is in the known set.
check_patch_paths
Check the RFC 8620 §5.3 PatchObject errors that patch alone determines, without the object it applies to.
check_read_only_patch
Check a /set update patch of the stored object id against the server-set and immutable properties of O, and report a no-op.
current_set_scope
The SetScope of the conditional Foo/set method running on this task, or None outside one.
enforce_max_objects_in_get
Enforce RFC 8620 §5.1 maxObjectsInGet at the top of a /get handler (bd:JMAP-yt1w.31).
enforce_max_objects_in_set
Enforce RFC 8620 §5.3 maxObjectsInSet cap at the top of a /set handler (bd:JMAP-ayoz.41.1).
enforce_max_objects_in_set_with_restore
maxObjectsInSet over creates, updates, destroys and restore_count restores (-04 §5.1: “Each entry in restore counts as one object”).
error_invocation
Wrap a method-level error as an error Invocation for methodResponses.
error_status
Map a JmapError type string to the appropriate HTTP status code.
extract_account_id
Extract accountId from a JMAP method arguments envelope and return both the extracted Id and the remaining argument map.
filter_arg
Remove and decode the optional filter argument of a hand-written /query or /queryChanges handler (RFC 8620 §5.5).
filter_nests_deeper_than
true if filter (an RFC 8620 §5.5 FilterOperator or FilterCondition) has more than levels nested conditions arrays. A bare FilterCondition is depth 0; each enclosing operator adds one. Recurses at most levels + 1 times.
handle_changes
Generic */changes handler (RFC 8620 §5.2).
handle_get
Generic */get handler (RFC 8620 §5.1).
handle_get_with_history
Foo/get with object history (§3).
handle_get_with_metadata
handle_get for a type the backend may list for draft-ietf-jmap-metadata-05 (JmapAccounts::metadata_info).
handle_query
Generic */query handler (RFC 8620 §5.5).
handle_query_changes
Generic */queryChanges handler (RFC 8620 §5.6).
handle_query_changes_with_history
Foo/queryChanges with onlyDestroyed (-04 §4: the client “MUST pass the same values that it passed to Foo/query”).
handle_query_changes_with_i18n
handle_query_changes for a type with JmapObject::LOCALIZABLE properties (draft-atwood-jmap-updates-00 §4.2.3).
handle_query_with_history
Foo/query with onlyDestroyed (§4).
handle_query_with_i18n
handle_query for a type with JmapObject::LOCALIZABLE properties (draft-atwood-jmap-updates-00 §4.2.2).
history_get
handle_get_with_history with plain as 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_history with plain as 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_history with plain as 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/set around plain, the type’s own /set handler, which runs unchanged for creates, updates and destroys.
is_client_updatable
Whether a client may change prop of O in a /set update: it is in SetObject::CLIENT_SETTABLE and not in SetObject::IMMUTABLE.
is_deliverable
Whether a push may be sent to stored at now_secs seconds since the Unix epoch: the subscription is verified and has not expired.
json_merge_patch
Apply a JSON Merge Patch (RFC 7396) to target in-place.
json_type_name
Name the top-level JSON type of v (null, boolean, number, string, array or object) for an error description.
limit_or_max
Convert an RFC 8620 limit / maxChanges argument (UnsignedInt|null) to a usize item count for Iterator::take (bd:JMAP-pgj7).
localized_query_state
The queryState to return from a Foo/query whose language was language (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_object of a type with JmapObject::LOCALIZABLE properties.
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 JSON notFound value.
now_utc_string
Return the current UTC instant as an UTCDate (RFC 3339, millisecond precision, format YYYY-MM-DDTHH:MM:SS.mmmZ, or YYYY-MM-DDTHH:MM:SSZ when the milliseconds are zero because RFC 8620 §1.4 says the “time-secfrac” “MUST always be omitted if zero”). For years 0000..=9999 the value passes UTCDate::new_validated.
now_utc_string_checked
Return the current UTC instant as an UTCDate in the same format as now_utc_string, or None if the system clock cannot be expressed as an RFC 3339 timestamp.
object_history_set_error
The SetError for objectHistory in a create, update or restore patch: it is reserved (§7.3, §7.4) and never stored, so invalidProperties.
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/query or Foo/queryChanges (-04) args.
parse_history_get_arguments
Take the §3 history arguments out of a Foo/get’s args.
parse_max_changes
Parse the optional maxChanges argument of /changes and /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 a Foo/set’s args: each key as sent with its raw value. Empty when absent, null or {}.
parse_wire_id
Parse a client-supplied id: a /set update key, a destroy element or an Id-typed property value.
patch_values_as_object
The values of an RFC 8620 §5.3 PatchObject placed 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. null values (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 /query arguments anchor (Id|null) and anchorOffset (Int, default 0) from args.
register_push_subscription_conditional
Opt PushSubscription/set in to draft-ietf-jmap-conditional-02 (ifUnchangedBy and atomic), after register_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) and PushSubscription/set (RFC 8620 §7.2.2) handlers on dispatcher.
reject_did_bearing_properties
Reject a /set create object that carries a DID-bearing property, or an update PatchObject that changes one (draft-atwood-jmap-did-00 §The did Property).
reject_metadata_filter_arg
reject_metadata_filter_without_capability on the undecoded filter argument of a Foo/query or Foo/queryChanges request, for handlers that pass args on to handle_query or handle_query_changes and so never hold the decoded filter. A filter that 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/query only for “requests whose using includes urn:ietf:params:jmap:metadata”. Without it a metadata leaf anywhere in filter, as is_metadata judges a condition, is unsupportedFilter (RFC 8620 §5.5: “The filter is syntactically valid, but the server cannot process it”). Foo/query and Foo/queryChanges handlers call it once the filter is decoded.
reject_read_only_patch
Reject a /set update patch that names a server-set or immutable property of O.
reject_server_set
Reject a /set create that carries a server-set property of O.
request_error
Convenience constructor: wrap a JmapError in a RequestError, deriving the HTTP status code automatically.
require_history_support
Whether O has history in account_id.
resolve_args
Resolve all #key ResultReference fields in args against prior_responses.
resolve_blob_ref
A blobId-typed value with a #creationId reference (RFC 8620 §5.3) replaced by the id an earlier method call of the request created, such as a blob from Blob/upload, Blob/set or Blob/convert (draft-ietf-jmap-blobext-03 §8, “later method calls”).
resolve_blob_refs
Rewrite every blobId reference in a /set create object or update patch through resolve_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 position argument (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 /query page within the filtered, sorted ids (RFC 8620 §5.5), for JmapReads::query_objects implementations.
resolve_set_id_refs
Rewrite the update keys and destroy entries of /set arguments that are #creationId references (RFC 8620 §5.3) to the ids they name.
restored_diff
The restored value for one object (§5.1): the top-level properties of stored whose values differ from baseline (the final version with the patch applied), or null when none do. id is never listed.
run_restore_phase
Restore every entry of restore (from parse_restore_argument), “before any create, update, or destroy in the same call” (§5.1).
serialize_value
Serialize any serde::Serialize type to a serde_json::Value, mapping serialization errors to JmapError::server_fail.
serialized_writes_scope
A SetScope that does nothing, for a backend that already serializes every write per account.
server_fail_from_backend
Construct a JmapError::server_fail for a backend-originated error without echoing the backend error’s Display output onto the wire (bd:JMAP-wlip.2).
server_fail_value_from_backend
Construct the per-id serverFail Value used inside the notCreated/notUpdated/notDestroyed maps of /set responses (bd:JMAP-ic0j.68), without echoing the backend error’s Display output onto the wire.
state_change_for
The StateChange to push to sub for the changed map, or None if none of its types changed.
strip_object_history_property
Remove objectHistory from a properties argument (§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 /set update patch that changes a server-set or immutable property of O, 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/queryChanges sinceQueryState, checked against the request’s language.
uses_i18n
true if using includes urn:ietf:params:jmap:i18n (draft-atwood-jmap-updates-00 §3). Capability URIs compare as exact strings (§7.1).
uses_metadata
true if using includes urn: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 secs seconds since the Unix epoch as a seconds-precision UTCDate (YYYY-MM-DDTHH:MM:SSZ, RFC 8620 §1.4), or None if the year falls outside 0000..=9999, which that four-digit form cannot express.

Type Aliases§

BackendCallFn
Type alias for the closure stored inside ClosureHandler.
CommitFuture
The future SetScope::commit returns.
HandlerFuture
The return type for all JmapHandler implementations.
RollbackFuture
The future SetScope::rollback returns.