Crate jmap_base_client

Expand description

RFC 8620 base JMAP client: auth, session fetch, blob, SSE, and WebSocket.

Extension-specific clients (jmap-chat-client, jmap-mail-client) depend on this crate.

§Usage

let auth = BearerAuth::new("...")?;
let client = JmapClient::new(
    DefaultTransport,
    auth,
    "https://jmap.example.com",
    ClientConfig::default(),
)?;
let session = client.fetch_session().await?;

§`extra` field equality and the `serde_json/preserve_order` feature (bd:JMAP-6r7c.43)

Every public deserializable struct in this crate carries an extra: serde_json::Map<String, serde_json::Value> field per the workspace extras-preservation policy (see workspace AGENTS.md). Several of these structs also derive PartialEq / Eq so callers can write assert_eq!(a, b) in tests and if state_a == state_b { ... } in application code.

The derived PartialEq impl compares the extra field via serde_json::Map’s PartialEq impl, whose semantics depend on a third-party feature flag:

Default (this workspace’s posture). serde_json::Map is BTreeMap-backed; equality is order-insensitive (keys are stored in lexicographic order regardless of insertion order).
serde_json/preserve_order enabled anywhere in the dep graph. serde_json::Map switches to IndexMap (insertion-order preserved); equality becomes order-sensitive.

Two values constructed with the same extra entries inserted in different orders therefore compare EQUAL under the default configuration and UNEQUAL under preserve_order. The feature flag is a global toggle: any crate in the consumer’s dep graph that enables preserve_order flips the semantics for every crate in the graph.

In-scope structs: BlobUploadResponse, Session, AccountInfo, WebSocketCapability, and StateChange.

Workspace memory note: jmap-base-client (and the full workspace) does NOT enable preserve_order. Consumers in the same posture get deterministic == behaviour on extra. Consumers that enable preserve_order elsewhere and need stable equality independent of that flag should compare the serialised forms instead:

let a_json = serde_json::to_value(&a)?;
let b_json = serde_json::to_value(&b)?;
assert_eq!(a_json, b_json);

Structs§

AccountInfo: Per-account metadata in a JMAP Session (RFC 8620 §2).
AccountName: The human-readable account name (RFC 8620 §2 name field on the per-account object).
AuthHeader: Single HTTP (name, value) header pair, returned by AuthProvider::auth_header (bd:JMAP-6r7c.62, bd:JMAP-6r7c.20).
BasicAuth: HTTP Basic authentication (Authorization: Basic <base64(username:password)>).
BearerAuth: Bearer-token authentication (Authorization: Bearer <token>).
BlobDownloadStream: A blob body being downloaded, returned by JmapClient::download_blob_stream.
BlobUploadResponse: Response body returned by a successful blob upload (RFC 8620 §6.1).
BuilderTransport: Concrete TransportConfig produced by CustomTransportBuilder::build.
ClientConfig: Per-client configuration for timeouts and body size limits.
CustomCaTransport: Custom CA trust root (DER-encoded). No Authorization header is injected.
CustomTransportBuilder: Builder for a TransportConfig with multi-root trust chains and optional mTLS client certificate (bd:JMAP-6r7c.65).
DefaultTransport: Standard reqwest client with a 10-second connect timeout; no custom TLS.
DownloadBlobParams: Parameters for JmapClient::download_blob.
DownloadBlobSessionParams: Parameters for JmapClient::download_blob_session (bd:JMAP-6r7c.64).
HttpClient: Opaque HTTP client returned by TransportConfig::build_client (bd:JMAP-6r7c.36).
HttpError: HTTP transport error reported by the underlying HTTP client.
InvalidHeaderValueError: A header value (typically an authentication token) contained bytes that are not valid for an HTTP header.
JmapClient: Auth-agnostic JMAP base HTTP client.
JmapRequestBuilder: Fluent builder for multi-method JmapRequest objects.
JmapUrl: A plain JMAP URL — no RFC 6570 template variables expected.
JmapUrlTemplate: An RFC 6570 Level-1 URI template — requires variable substitution before use as a request URL.
NoneAuth: No authentication: no Authorization header.
ParseError: JSON deserialize / parse error reported by the underlying JSON parser.
QueryParams: The RFC 8620 §5.5 /query arguments shared by every Foo/query method: which window of the result list to return and whether to compute the total.
SerializeError: JSON serialize error reported by the underlying JSON serializer.
Session: JMAP Session object returned by GET /.well-known/jmap (RFC 8620 §2).
SseFrame: A parsed SSE frame: the event and the id: line value (if any).
SseReconnectPolicy: Backoff policy for JmapClient::subscribe_events_reconnecting.
StateChange: A state change push notification (RFC 8620 §7.1).
SubscribeEventsSessionParams: Parameters for JmapClient::subscribe_events_session (bd:JMAP-6r7c.64).
UploadBlobParams: Parameters for JmapClient::upload_blob.
UploadBlobSessionParams: Parameters for JmapClient::upload_blob_session (bd:JMAP-6r7c.64).
UploadBlobStreamParams: Parameters for JmapClient::upload_blob_stream.
Username: The authenticated user’s username (RFC 8620 §2 username field).
WebSocketCapability: Capability object for "urn:ietf:params:jmap:websocket" (RFC 8887).
WebSocketError: WebSocket transport error reported by the underlying WebSocket client.
WsReceiver: Owning receive-half of a WebSocket connection (bd:JMAP-6r7c.31).
WsRequestError: A request-level error received over WebSocket (RFC 8887 §4.3.4).
WsSender: Owning send-half of a WebSocket connection (bd:JMAP-6r7c.31).
WsSession: An established JMAP WebSocket session (RFC 8887).

Enums§

ClientError: Errors produced by the base JMAP client.
CloseAfter: The RFC 8620 §7.3 closeafter event-source variable, which “MUST be one of” these two values.
HttpErrorKind: Classification of an HttpError returned by HttpError::kind.
ParseCategory: Classification of a ParseError / SerializeError failure.
SseEvent: A parsed SSE event from a JMAP event source (RFC 8620 §7.3).
WebSocketErrorKind: Classification of a WebSocketError returned by WebSocketError::kind.
WsFrame: A parsed frame received from the JMAP WebSocket.

Constants§

DEFAULT_WS_MAX_MESSAGE_BYTES: Maximum WebSocket message size (1 MiB), consistent with the SSE frame limit. Prevents a misbehaving or hostile server from forcing the client to buffer large messages over the event connection. Default per-message / per-frame byte cap for WebSocket connections opened via connect_ws (which does not take a limit parameter). Callers that need a different cap should use connect_ws_with_limit or the crate::JmapClient::connect_ws_session convenience method which reads the max_ws_message field from ClientConfig. Default: 1 MiB.

Traits§

AuthProvider: Injects per-request authentication credentials.
TransportConfig: Controls how the underlying HttpClient is constructed.

Functions§

connect_ws: Open a JMAP WebSocket connection (RFC 8887).
connect_ws_allow_plaintext: Establish a WebSocket connection that also accepts plaintext ws://.
connect_ws_with_limit: Establish a WebSocket connection with an explicit per-message / per-frame byte cap.
expand_url_template: Expand a RFC 6570 Level-1 URI template by substituting variables.
extract_response: Find the method response matching call_id in resp and deserialize its arguments into T.
method_error_details: Return the full JMAP "error" object for call_id, including any properties beyond type and description.
parse_sse_block: Parse a single SSE block (the text between two blank lines) into an SseFrame.
to_args: Serialize a method argument to a serde_json::Value for a JMAP method call’s arguments object.
upload_body_from_reader: Wrap a tokio::io::AsyncRead (a file, a pipe, a decompressor) as a BlobUploadBody. The reader is read in chunks as the request body is sent; it is never buffered whole.

Type Aliases§

BlobUploadBody: Request body for JmapClient::upload_blob_stream: a stream of byte chunks sent to the server in order.