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

Re-exports§

pub use backend::AddedItem;
pub use backend::BackendChangesError;
pub use backend::BackendQueryError;
pub use backend::BackendSetError;
pub use backend::ChangesResult;
pub use backend::JmapBackend;
pub use backend::QueryChangesResult;
pub use backend::QueryResult;
pub use backend::ReservedExtrasKey;
pub use backend::SetError;
pub use backend::SetErrorType;
pub use backend::RESERVED_SET_ERROR_WIRE_NAMES;
pub use handlers::handle_changes;
pub use handlers::handle_get;
pub use handlers::handle_query;
pub use handlers::handle_query_changes;
pub use handlers::server_fail_from_backend;
pub use handlers::server_fail_value_from_backend;
pub use handlers::SERVER_FAIL_INTERNAL_DESC;

Modules§

backend
Shared backend infrastructure for all JMAP server crates.
handlers
Generic JMAP method handlers shared across all server crates.

Structs§

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).
PushSubscription
A push subscription (RFC 8620 §7.2).
RequestError
A request-level JMAP error response: HTTP status code + JMAP error body.
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).
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.
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.

Constants§

MAX_PUSH_EXPIRY_SECS
The furthest in the future, in seconds from now, that PushSubscription/set lets expires be: 7 days.

Traits§

GetObject
Marker for object types that support get and changes operations.
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.
bool_arg
Read an optional boolean argument from a method-arguments envelope without removing it (bd:JMAP-ic0j.39).
check_known_capabilities
Validate that every capability URI in req.using is in the known set.
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).
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.
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).
now_utc_string_checked
Return the current UTC instant as an UTCDate (RFC 3339, millisecond precision, format YYYY-MM-DDTHH:MM:SS.mmmZ), 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_request
Parse and validate a JMAP request from a raw JSON 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.
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_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.
serDeprecated
Deprecated alias for serialize_value (bd:JMAP-wlip.21).
serialize_value
Serialize any serde::Serialize type to a serde_json::Value, mapping serialization errors to JmapError::server_fail.
state_change_for
The StateChange to push to sub for the changed map, or None if none of its types changed.
take_bool_arg
Read an optional boolean argument from a method-arguments envelope, removing it from the map (bd:JMAP-ic0j.39).
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.