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 JmapBackend::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.
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.
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).
PushSubscription
A push subscription (RFC 8620 §7.2).
QueryChangesParams
The /queryChanges arguments (RFC 8620 §5.6) passed to JmapBackend::query_changes, after accountId.
QueryChangesResult
Result of a /queryChanges call (RFC 8620 §5.6).
QueryParams
The /query arguments (RFC 8620 §5.5) passed to JmapBackend::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).
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).
SetError
A per-item error in a /set response (notCreated, notUpdated, notDestroyed maps) (RFC 8620 §5.3).
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 JmapBackend::get_changes and JmapBackend::query_changes.
BackendQueryError
Error type returned by JmapBackend::query_objects.
BackendSetError
Error type returned by create/update/destroy backend methods.
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.
SetErrorType
The machine-readable type for a SetError (RFC 8620 §5.3 and RFC 8621).

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_PUSH_EXPIRY_SECS
The furthest in the future, in seconds from now, that PushSubscription/set lets expires be: 7 days.
SERVER_FAIL_INTERNAL_DESC
Static description used for every serverFail invocation that wraps a JmapBackend::Error (bd:JMAP-wlip.2).

Traits§

GetObject
Marker for object types that support get and changes operations.
JmapBackend
Read-side backend supertrait shared by all JMAP server crates.
JmapHandler
Implement this for each JMAP method handler.
JmapObject
Marker trait for all JMAP object types.
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.
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) to target in-place.
apply_patch_object
Apply a whole RFC 8620 §5.3 PatchObject to target.
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 JmapBackend::get_changes error to the Foo/changes method error (RFC 8620 §5.2).
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.
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).
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).
handle_changes
Generic */changes handler (RFC 8620 §5.2).
handle_get
Generic */get handler (RFC 8620 §5.1).
handle_get_with_metadata
handle_get for a type the backend may list for draft-ietf-jmap-metadata-05 (JmapBackend::metadata_info).
handle_query
Generic */query handler (RFC 8620 §5.5).
handle_query_changes
Generic */queryChanges handler (RFC 8620 §5.6).
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).
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.
optional_arg
Extract an optional, deserializable argument from a method-arguments envelope (bd:JMAP-wlip.32).
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_wire_id
Parse a client-supplied id: a /set update key, a destroy element or an Id-typed property value.
query_anchor_args
Parse the RFC 8620 §5.5 /query arguments anchor (Id|null) and anchorOffset (Int, default 0) from args.
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.
resolve_args
Resolve all #key ResultReference fields in args against prior_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 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 JmapBackend::query_objects implementations.
serialize_value
Serialize any serde::Serialize type to a serde_json::Value, mapping serialization errors to JmapError::server_fail.
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_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).
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.
HandlerFuture
The return type for all JmapHandler implementations.