Expand description
JMAP over WebSocket, RFC 8887
(urn:ietf:params:jmap:websocket).
This is a support crate (workspace AGENTS.md §Support crates): no
*-types or *-server crate depends on it, and a deployment opts in.
Always available, with no async runtime:
CAPABILITY,SUBPROTOCOLandoffers_jmapfor the Session object (§3) and the opening handshake (§4.2).WebSocketCapability, the §3 capability object.- The §4.3 messages:
WsRequest,WebSocketPushEnableandWebSocketPushDisablefrom the client (ClientMessage);WsResponse,WsRequestErrorandWsStateChangefrom the server (ServerMessage).
Feature server: server::Connection, a session driver that turns
incoming text frames into jmap_server::Dispatcher calls and writes
the answers and push notifications back, over any Stream and Sink
of messages, so it fits axum, tokio-tungstenite or another stack. Also
server::PushHub, an in-memory state-change source with pushState
replay.
Feature tungstenite: tungstenite::serve runs a connection over a
tokio-tungstenite WebSocketStream.
The authenticated HTTP request that opens the WebSocket, and the TLS under it (RFC 8887 §4.1, §5.1), are the deployment’s.
Re-exports§
pub use jmap_types;pub use futures;serverpub use jmap_server;serverpub use tokio_tungstenite;tungstenite
Modules§
- server
server - The server side of RFC 8887: a per-connection session driver.
- tungstenite
tungstenite - Running a
Connectionover tokio-tungstenite.
Structs§
- WebSocket
Capability - The value of the
CAPABILITYkey in a Session’scapabilities(RFC 8887 §3). - WebSocket
Push Disable - Turns off push notifications for the connection (RFC 8887 §4.3.5.3).
Its only RFC property is
@type. - WebSocket
Push Enable - Turns on push notifications for the connection (RFC 8887 §4.3.5.2).
- WsRequest
- A JMAP Request sent over the WebSocket (RFC 8887 §4.3.2): an RFC 8620
§3.3 Request plus
@type: "Request"and an optional clientid. - WsRequest
Error - A request-level error sent over the WebSocket (RFC 8887 §4.3.4): an
RFC 8620 §3.6.1 problem details object plus
@type: "RequestError"andrequestId. - WsResponse
- A JMAP Response sent over the WebSocket (RFC 8887 §4.3.3): an RFC 8620
§3.4 Response plus
@type: "Response"andrequestId. - WsState
Change - A push notification sent over the WebSocket (RFC 8887 §4.3.5.1): an
RFC 8620 §7.1 StateChange plus an optional
pushState.
Enums§
- Client
Message - A message a client sends (RFC 8887 §4.3): “a single JMAP Request object …, JMAP WebSocketPushEnable object …, or JMAP WebSocketPushDisable object”.
- Server
Message - A message a server sends (RFC 8887 §4.3): “a single JMAP Response object, JSON Problem Details object, or JMAP StateChange object”.
Constants§
- CAPABILITY
- The JMAP capability URI of this extension (RFC 8887 §3, §6): the key
of
WebSocketCapabilityin the Session’scapabilities. - SUBPROTOCOL
- The WebSocket subprotocol name (RFC 8887 §4.2, §6.1). The client MUST
list it in
Sec-WebSocket-Protocol, and the server’s reply MUST carry it for a JMAP connection to be established.
Functions§
- offers_
jmap - Whether a
Sec-WebSocket-Protocolrequest header value lists theSUBPROTOCOL(RFC 8887 §4.2).