jmap-websocket 0.6.2

JMAP over WebSocket (RFC 8887, urn:ietf:params:jmap:websocket): wire frames, capability, and a framework-agnostic server session driver
Documentation

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 any Stream of Inbound (text, binary, close) and Sink of Outbound (text, close).
  • parse_client_message: one text message to a ClientMessage or the WsRequestError to answer with (notJSON, notRequest, limit).
  • RequestHandler: what answers a Request; DispatcherHandler wraps a Dispatcher and a caller, with an optional unknownCapability check.
  • PushSource: where push notifications come from; PushHub is an in-memory fan-out with pushState tokens and replay; NoPush sends nothing. filter_state_change applies dataTypes.
  • ExtensionHandler: takes the client messages of extension @types (ChatStreamEnable, VTCStreamEnable, SceneStreamEnable, ...) and sends the extension's events through an ExtensionSender; register it with Connection::with_extension.
  • ConnectionConfig: maxCallsInRequest, maxSizeRequest, maxConcurrentRequests, binary-message policy, extension queue size.

Feature tungstenite: tungstenite::serve runs a Connection over a tokio-tungstenite WebSocketStream. tungstenite::accept and accept_with_config do the handshake with the jmap subprotocol check and tungstenite's message and frame size capped at maxSizeRequest; websocket_config gives that WebSocketConfig for a handshake that authenticates in its callback.

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

[dependencies]
jmap-websocket = { version = "0.6", features = ["tungstenite"] }
use std::sync::Arc;
use jmap_websocket::server::{Connection, ConnectionConfig, DispatcherHandler, PushHub};
use jmap_websocket::jmap_server::Dispatcher;
use jmap_websocket::jmap_types::State;
use jmap_websocket::tokio_tungstenite::accept_hdr_async_with_config;
use jmap_websocket::tungstenite::{negotiate_jmap, websocket_config};

# async fn run(tcp: tokio::net::TcpStream, dispatcher: Arc<Dispatcher<()>>, hub: PushHub)
#     -> Result<(), Box<dyn std::error::Error>> {
// The limits the Session's core capability advertises.
let config = ConnectionConfig::default().max_size_request(Some(10_000_000));
// Authenticate in the handshake callback, then `negotiate_jmap` checks
// the `jmap` subprotocol and echoes it (RFC 8887 §4.1, §4.2).
// `websocket_config` caps tungstenite's message size at maxSizeRequest.
let ws = accept_hdr_async_with_config(tcp, negotiate_jmap, Some(websocket_config(&config)))
    .await?;
let handler = Arc::new(DispatcherHandler::new(dispatcher, (), || State::from("s0")));
let connection = Connection::new(handler).with_push(hub).with_config(config);
jmap_websocket::tungstenite::serve(connection, ws).await?;
# Ok(()) }

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.

Extension message types

The JMAP Chat, VTC and Scene WebSocket drafts update RFC 8887: a capability in the Session "MAY define additional WebSocket message types, each identified by its @type value", and the server sends them only after the client enabled them with that capability's control message (ChatStreamEnable, VTCStreamEnable, SceneStreamEnable). Implement ExtensionHandler for those types and register one value per connection, next to advertising the capability:

use jmap_websocket::jmap_types::JmapError;
use jmap_websocket::server::{ExtensionHandler, ExtensionMessage, ExtensionSender};

struct ToyStream {
    caller: String,
    events: Option<ExtensionSender>,
}

impl ExtensionHandler for ToyStream {
    fn message_types(&self) -> &[&str] {
        &["ToyStreamEnable", "ToyStreamDisable"]
    }

    fn start(&mut self, events: ExtensionSender) {
        // Keep it, or hand a clone to a task that forwards events.
        self.events = Some(events);
    }

    async fn handle(&mut self, message: ExtensionMessage) -> Result<(), JmapError> {
        // Update the subscription; Err becomes a RequestError whose
        // requestId is message.id.
        Ok(())
    }

    async fn close(&mut self) {
        // The connection ended: drop the subscription.
    }
}

# fn wire(connection: jmap_websocket::server::Connection<jmap_websocket::server::DispatcherHandler<()>>) {
let connection = connection.with_extension(ToyStream { caller: "u1".into(), events: None });
# let _ = connection; }
  • handle runs one message at a time, in order; the driver reads the next client message only after it returns, while Responses, StateChanges and queued events keep going out.
  • Events go through a bounded queue (ConnectionConfig::extension_queue_capacity, default 64): try_send drops on Full, send waits. An event must be a JSON object with an @type that is not an RFC 8887 one.
  • close runs once when run ends, however it ends, after the queue closed and a running handle finished.
  • A @type no handler registered is still answered with notRequest.

Closing on credential expiry

RFC 8887 §4.2 lets the server close the connection when the handshake's credentials expire, with a Close frame of status 1008 (Policy Violation); the JMAP Chat, VTC and Scene WebSocket drafts make 1008 a SHOULD. Take a CloseHandle before running the connection and close through it from the task that tracks the expiry:

use jmap_websocket::server::{CloseCode, Connection, DispatcherHandler};

# async fn serve(
#     connection: Connection<DispatcherHandler<()>>,
#     ws: jmap_websocket::tokio_tungstenite::WebSocketStream<tokio::net::TcpStream>,
#     expires_in: std::time::Duration,
# ) -> Result<(), jmap_websocket::server::ConnectionError> {
let close = connection.close_handle();
tokio::spawn(async move {
    tokio::time::sleep(expires_in).await;
    close.close(CloseCode::POLICY_VIOLATION, "credentials expired");
});
jmap_websocket::tungstenite::serve(connection, ws).await
# }

run then sends the Close, drops the push subscription, runs every ExtensionHandler::close, and returns Ok(()).

How it works

  • Every message type serializes with its @type first 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's extra).
  • run loops over three sources with tokio::select!: incoming messages, finished Requests (a FuturesUnordered, 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 string id as requestId, or null.
  • RequestHandler::prepare_problem runs on every RequestError, so a deployment can localize title.
  • PushHub numbers 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 jmap subprotocol echo (§4.2) are the deployment's.
  • The WebSocket library reads a whole message before the driver checks maxSizeRequest, so cap the library too, or one client can make the server hold the library's own cap per connection (64 MiB for tungstenite, against a 10 MB maxSizeRequest). tungstenite::accept caps at the default ConnectionConfig's 10 000 000 octets; with another maxSizeRequest use accept_with_config, or pass websocket_config(&config) to accept_hdr_async_with_config. An axum deployment sets WebSocketUpgrade::max_message_size and max_frame_size, and maps the capacity error to Inbound::TooBig (see jmap-testjig's ws.rs). The frame cap equals the message cap: most clients send a message as one frame.
  • A message over the library's cap closes the connection with 1009 (Message Too Big, RFC 6455 §7.4.1), not with a limit RequestError: RFC 8887 does not say maxSizeRequest applies per WebSocket message, and the library refuses it before it is a whole message. The limit RequestError still answers a message under the library's cap and over maxSizeRequest, when the two differ. serve sends the Close and returns without reading the rest of the message.
  • A binary message closes the connection with 1003 by default (BinaryFrames::Ignore to drop it instead); RFC 8887 does not answer it with a RequestError.
  • WsRequestError always writes requestId (null when unknown), as the §4.4 notJSON example does; WsResponse omits it when the request had no id.
  • A request over maxConcurrentRequests is answered with a limit RequestError, not queued. To count HTTP requests too, share a semaphore with Connection::with_shared_limit.
  • dataTypes: [] matches no type (the RFC's literal reading); use null for all.
  • A WebSocketPushEnable with members of the wrong type is answered with notRequest instead of being ignored.
  • PushHub does no access filtering: keep one per principal. Merging drops StateChange.extra.
  • Two §4.4 examples are not valid as printed: the Response omits the sessionState RFC 8620 §3.4 requires, and the second StateChange misses a comma. The tests say so.
  • Dispatcher::dispatch needs a Tokio runtime, so run does too.
  • Extension @types are answered with notRequest unless an ExtensionHandler is registered for them. The driver does not check using for them: the drafts tie them to the Session capability, so register a handler only where the capability is advertised.
  • A handler error's extra members become problem-details members, except names the driver writes itself (type, status, title, detail, instance, limit, requestId, @type).
  • ExtensionHandler::close does not run if the run future is dropped (a cancelled task); put cleanup that must happen then in Drop.
  • Ending incoming ends the connection without a Close frame. To close with a status code (1008 for expired credentials), use Connection::close_handle. The first close wins; later ones, and any after run returned, do nothing and return false. Nothing queued is sent ahead of the Close: Responses still running, queued extension events and pending StateChanges are dropped. A reason over 123 bytes (the RFC 6455 control-frame limit) is cut on a character boundary. CloseCode::new refuses codes an endpoint may not send.

References

  • RFC 8887 — A JSON Meta Application Protocol (JMAP) Subprotocol for WebSocket
  • RFC 8620 §3.3, §3.4, §3.6.1, §7.1 — JMAP Core requests, responses, request-level errors, StateChange
  • RFC 6455 — The WebSocket Protocol
  • RFC 9457 — Problem Details for HTTP APIs
  • draft-atwood-jmap-chat-wss-00, draft-atwood-jmap-vtc-wss-00, draft-atwood-jmap-scene-wss-00 — the extension message types (jmap-chat-spec)