jmap-chat-server
Pre-stable (0.3.x). The JMAP Chat crates (
jmap-chat-types,jmap-chat-server,jmap-chat-client) do not yet have a stable API. Expect breaking changes, especially new requiredChatBackendmethods, until the 0.4 API freeze.
What it is
JMAP Chat extension method handlers and the ChatBackend trait
(draft-atwood-jmap-chat). Backend-agnostic — plugs into
jmap-server::Dispatcher. Consumers implement ChatBackend for their
storage; the crate handles all wire protocol, RFC 8620 conformance, and
non-trivial concurrency logic (Direct chat dedup, Space/join TOCTOU,
invite-use accounting).
What it's for
Implements the JMAP Chat extension (draft-atwood-jmap-chat-00) — Chat,
Message, Space, ChatContact, ReadPosition, SpaceInvite, SpaceBan,
CustomEmoji, and PresenceStatus objects — so consumers can wire chat method
dispatch into their HTTP transport. Sibling to jmap-mail-server (the
canonical extension-server template) and the other jmap-*-server crates;
all of them inter-depend through the workspace JmapHandler trait in
jmap-server. The consumer supplies a ChatBackend impl (storage), a
CallerCtx type (auth identity), and wires the dispatcher into HTTP / SSE
/ WebSocket transport themselves.
How to use
use Arc;
use ;
use Dispatcher;
// MyCallerCtx is the application's per-request context type — typically the
// authenticated identity (user id, tenant, rate-limit token, etc.).
// It must be `Clone + Send + 'static`. Use `()` if you have no per-request
// context.
// 1. Implement ChatBackend for your storage.
// 2. Wire into a Dispatcher parameterised over your CallerCtx type.
let mut dispatcher: = new;
register_chat_handlers;
// 3. Dispatch requests in your HTTP handler.
// let ctx = MyCallerCtx { /* ... */ };
// let response = dispatcher.dispatch(request, ctx, session_state).await;
register_chat_handlers is generic over <B, C> — B: ChatBackend is your
storage backend, and C: Clone + Send + 'static is the dispatcher's
CallerCtx type. The same Arc<B> is shared across all registered methods;
each request's C value is forwarded into the closure as _ctx (see
CallerCtx below).
Registered methods
register_chat_handlers installs handlers for all of the following:
| Object | Methods |
|---|---|
Chat |
get, changes, query, queryChanges, set, typing |
Message |
get, changes, query, queryChanges, set |
Space |
get, changes, query, queryChanges, set, join |
ChatContact |
get, changes, query, queryChanges, set |
ReadPosition |
get, changes, set |
SpaceInvite |
get, changes, set |
SpaceBan |
get, changes, set |
CustomEmoji |
get, changes, query, queryChanges, set |
PresenceStatus |
get, changes, set |
ChatBackend trait
The read-side operations (get_objects, get_state, get_changes, query_objects,
query_changes) are defined on the JmapBackend supertrait from jmap-server.
How it works
Generic handlers
*/get, */changes, */query, and */queryChanges all delegate to generic
implementations from jmap-server, ensuring RFC 8620 conformance across every object type
without duplication.
Chat/set — Direct chat deduplication
Creating a Chat with kind: "direct" must be idempotent: if a Direct chat with the same
member set already exists, the caller should get back the existing chat rather than a
duplicate.
The handler uses optimistic create-then-validate deduplication:
- Before the create loop, fetch all existing Direct chats for the account once (hoisted to avoid N+1 queries).
- Attempt the create normally.
- After the create, re-fetch to catch concurrent races where two clients create the same Direct chat simultaneously.
- The canonical winner is the object with the lexicographically smallest ID. The loser
destroys itself and returns an
alreadyExistsSetError pointing at the winner's ID.
Space/join — invite-code and TOCTOU handling
Space/join is a non-standard method (not /set) that adds the caller as a member. It
accepts either an inviteCode or a spaceId (for public spaces).
- After the join write succeeds at the storage layer, the handler re-reads the member list
to detect concurrent joins. If two callers both succeed, the racer with the later
joinedAttimestamp undoes its write and returns a retryable error. SpaceInvite.usesis incremented only on the success path (after the TOCTOU check), so race-losses do not silently exhaust invite capacity.
Chat/typing — ephemeral push
Chat/typing stores no state. It fires a push event via JmapBackend::push_event if the
backend implements push, then returns immediately. The wire response carries no payload
beyond the standard invocation envelope.
CallerCtx
register_chat_handlers registers each method as a ClosureHandler
that forwards the dispatcher's CallerCtx value into the closure as _ctx.
The standard handle_* handler bodies ignore _ctx and receive only
(Arc<B>, call_id, args); the value is still available for backends that
register handlers individually via ClosureHandler. If you need
per-request auth context inside one of the standard handle_* functions
(e.g., to enforce that a caller can only modify their own PresenceStatus),
implement JmapHandler<C> directly for that method instead of relying on
the registered handler.
Gotchas
- Direct chat deduplication is eventually consistent. The
Chat/setcreate handler uses optimistic create-then-validate to detect duplicate Direct chats. Under concurrent load two clients may both successfully create the same Direct chat; the loser's write is rolled back and it receivesalreadyExists, but the duplicate briefly exists. Backends can eliminate this window by enforcing uniqueness atomically increate_object. Space/joinTOCTOU window. After a successful join write, the handler re-reads the member list to detect concurrent joins. There is a brief window between the write and the re-read during which a second concurrent join can succeed. Both joiners will detect the race, but the loser's join is rolled back, not the winner's — so the final state is consistent.- Draft spec only.
draft-atwood-jmap-chathas not been submitted to the IETF; wire format and method semantics may change.
Crate family
jmap-types
├── jmap-server Dispatcher this crate plugs into
└── jmap-chat-types domain types (Chat, Message, Space, etc.)
└── jmap-chat-server ← this crate
References
| Document | Covers |
|---|---|
| draft-atwood-jmap-chat-00 | Core Chat objects and methods |
| draft-atwood-jmap-chat-push-00 | Push notification payloads |
| draft-atwood-jmap-chat-wss-00 | WebSocket ephemeral events |
| RFC 8620 | JMAP Core (request format, SetError, ResultReference) |