io_jmap/lib.rs
1#![no_std]
2#![deny(missing_docs)]
3#![cfg_attr(docsrs, feature(doc_cfg))]
4
5//! # io-jmap
6//!
7//! I/O-free JMAP client coroutines built on io-http: every network
8//! exchange is a resumable state machine emitting read and write
9//! requests instead of performing I/O itself. The caller owns the
10//! socket and pumps the coroutine with the bytes it read, whatever the
11//! runtime (blocking, async, in-memory tests). The `client` feature
12//! ships a ready-made std-blocking pump for callers who just want a
13//! working client.
14//!
15//! ## Layout: one folder per RFC
16//!
17//! The source tree mirrors how the JMAP specification itself is
18//! split, one module per RFC. [`rfc8620`] implements the core
19//! protocol: the session, request and response objects, the generic
20//! `Foo/get`, `Foo/set`, `Foo/query`, `Foo/changes` and
21//! `Foo/queryChanges` coroutines every data type builds on, the blob
22//! upload and download coroutines, plus the two push channels
23//! (PushSubscription and the SSE-based Event Source). [`rfc8621`]
24//! covers JMAP for Mail: Mailbox, Thread, Email, Identity,
25//! EmailSubmission and VacationResponse, each folder wrapping the
26//! generic core coroutines with the mail capability and its own data
27//! types. [`rfc9610`] covers JMAP for Contacts: AddressBook and
28//! ContactCard, where the JSContact payload stays raw JSON, converting
29//! it being out of scope.
30//!
31//! Two modules span the RFC modules and therefore live at the crate
32//! root: [`coroutine`] defines the coroutine contract every state
33//! machine implements, and the optional [`client`] module (`client`
34//! feature) is the std-blocking pump: a light client wrapping any
35//! stream you opened yourself, or a full client opening the TCP/TLS
36//! connection itself when one of the TLS features is enabled.
37//!
38//! ## The coroutine contract
39//!
40//! Every coroutine implements [`coroutine::JmapCoroutine`]: a resume
41//! method taking the bytes read since the last step and returning
42//! either an intermediate yield or a terminal completion. Standard
43//! coroutines yield the shared read/write requests of
44//! [`coroutine::JmapYield`]; richer coroutines declare their own yield
45//! type, like the redirect-aware session and blob coroutines surfacing
46//! 3xx responses to the caller instead of following them, or the
47//! streaming Event Source coroutine yielding one push frame at a
48//! time. Completion carries a per-coroutine output or error; the
49//! [`jmap_try`] macro chains an inner coroutine step inside an outer
50//! resume, re-yielding and short-circuiting like the question mark
51//! operator.
52//!
53//! ## Conventions
54//!
55//! The crate is no_std with alloc; std only enters behind the `client`
56//! feature. Every public item carries the bare `Jmap` prefix, the
57//! protocol not being version-scoped. Logging follows the library
58//! rules: state changes at debug level, in-process steps and data
59//! dumps at trace level.
60
61extern crate alloc;
62#[cfg(feature = "client")]
63extern crate std;
64
65#[cfg(feature = "client")]
66pub mod client;
67pub mod coroutine;
68pub mod rfc8620;
69pub mod rfc8621;
70pub mod rfc9610;