Crate jmap_server 

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, 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::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.

Id

Opaque non-empty server-assigned identifier (RFC 8620 §1.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).

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

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.

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.

QueryObject

Marker for object types that support query and queryChanges operations.

SetObject

Marker for object types that support set (create/update/destroy) operations.

Functions

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

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.

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

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.

take_bool_arg

Read an optional boolean argument from a method-arguments envelope, removing it from the map (bd:JMAP-ic0j.39).

Type Aliases

BackendCallFn

Type alias for the closure stored inside ClosureHandler.

HandlerFuture

The return type for all JmapHandler implementations.

Invocation

A JMAP method invocation: [method_name, arguments, call_id].