jmap-websocket
JMAP over WebSocket (RFC 8887, urn:ietf:params:jmap:websocket) for the
jmap-* crate family: the capability object, the wire messages, and a
server session driver that runs a jmap_server::Dispatcher behind any
WebSocket library.
What it is
A support crate. Always available, with no async runtime:
| Item | RFC 8887 |
|---|---|
CAPABILITY, WebSocketCapability (url, supportsPush) |
§3 |
SUBPROTOCOL ("jmap"), offers_jmap |
§4.2, §6.1 |
WsRequest (@type: "Request", optional id) |
§4.3.2 |
WsResponse (@type: "Response", requestId) |
§4.3.3 |
WsRequestError (problem details, @type: "RequestError", requestId) |
§4.3.4 |
WsStateChange (StateChange plus pushState) |
§4.3.5.1 |
WebSocketPushEnable (dataTypes, pushState), WebSocketPushDisable |
§4.3.5.2, §4.3.5.3 |
ClientMessage, ServerMessage (pick the type by @type) |
§4.3 |
Feature server (module server):
Connection: one connection's driver.run(incoming, outgoing)takes anyStreamofInbound(text, binary, close) andSinkofOutbound(text, close).parse_client_message: one text message to aClientMessageor theWsRequestErrorto answer with (notJSON,notRequest,limit).RequestHandler: what answers a Request;DispatcherHandlerwraps aDispatcherand a caller, with an optionalunknownCapabilitycheck.PushSource: where push notifications come from;PushHubis an in-memory fan-out withpushStatetokens and replay;NoPushsends nothing.filter_state_changeappliesdataTypes.ConnectionConfig:maxCallsInRequest,maxSizeRequest,maxConcurrentRequests, binary-message policy.
Feature tungstenite: tungstenite::serve runs a Connection over a
tokio-tungstenite WebSocketStream.
What it's for
Servers built from the kit that want to offer RFC 8887. The *-server
crates stay transport-free (workspace AGENTS.md); a deployment adds this
crate next to its HTTP stack. jmap-testjig serves its /ws endpoint
with it over axum. Clients use jmap-base-client's connect_ws, which
has its own frame types today.
How to use
[]
= { = "0.6", = ["tungstenite"] }
use Arc;
use ;
use Dispatcher;
use State;
# async #
After each write, publish the changed states to the principal's
PushHub (hub.publish(state_change)); every connection of that
principal with push enabled gets them.
How it works
- Every message type serializes with its
@typefirst and checks it on deserialize (absent accepted, wrong value rejected); the enums need it. Unknown members are kept (extra, or the inner RFC 8620 object'sextra). runloops over three sources withtokio::select!: incoming messages, finished Requests (aFuturesUnordered, so Requests run concurrently and answer in finishing order, as §4.3.2 allows), and the push subscription. Writes go out one at a time; a slow client back-pressures the loop.- A text message is read in order: size, JSON, object with
@type, then the message's own shape. Every RequestError carries the message's stringidasrequestId, ornull. RequestHandler::prepare_problemruns on every RequestError, so a deployment can localizetitle.PushHubnumbers each published change. A token it issued replays the changes since then (merged into one notification), or the latest state of everything when they were already dropped; a foreign token replays nothing.
Gotchas
- The handshake is not done here: authentication (§4.1), TLS (§5.1) and
the
jmapsubprotocol echo (§4.2) are the deployment's. - A binary message closes the connection with 1003 by default
(
BinaryFrames::Ignoreto drop it instead); RFC 8887 does not answer it with a RequestError. WsRequestErroralways writesrequestId(nullwhen unknown), as the §4.4notJSONexample does;WsResponseomits it when the request had noid.- A request over
maxConcurrentRequestsis answered with alimitRequestError, not queued. To count HTTP requests too, share a semaphore withConnection::with_shared_limit. dataTypes: []matches no type (the RFC's literal reading); usenullfor all.- A
WebSocketPushEnablewith members of the wrong type is answered withnotRequestinstead of being ignored. PushHubdoes no access filtering: keep one per principal. Merging dropsStateChange.extra.- Two §4.4 examples are not valid as printed: the Response omits the
sessionStateRFC 8620 §3.4 requires, and the second StateChange misses a comma. The tests say so. Dispatcher::dispatchneeds a Tokio runtime, sorundoes too.- Requests from client-side extensions (e.g. the chat-wss
@types) are answered withnotRequest; there is no hook for them yet.