WebSockets
Over plain HTTP, every JMAP request opens a new HTTP request and authenticates again, and push notifications need a separate connection. JMAP over WebSocket, defined in RFC 8887, carries JMAP requests, responses and push notifications over one persistent WebSocket connection instead. A client authenticates once, when it opens the connection. It then sends requests without the cost of a new HTTP request each time, and receives change notifications on the same connection.
The endpoint is /jmap/ws. Clients find it in the urn:ietf:params:jmap:websocket capability of the session resource. The capability gives the URL, wss://<host>/jmap/ws, built from the server’s public URL, and states that push is supported.
The client opens the connection with a GET request that upgrades to WebSocket over HTTP/1.1, with the jmap subprotocol, and authenticates it like any other JMAP request. A reverse proxy in front of Stalwart must forward the upgrade, or the connection fails.
Settings
Section titled “Settings”The connection is governed by settings on the Jmap singleton (found in the WebUI under Settings › Network › JMAP › Limits, Settings › Network › JMAP › Push, Settings › Network › JMAP › WebSocket).
A persistent connection needs to be kept alive, and closed when it is no longer used. The server keeps the connection alive by sending pings at the interval set in websocketHeartbeat. It closes a connection that has seen no activity for websocketTimeout, 10 minutes unless changed.
Push notifications on a connection are paced by websocketThrottle, the minimum time between two of them. Changes that occur in between are combined into the next notification.
Requests sent over the connection are subject to the same limits as requests over HTTP.