Available on crate feature
server only.Expand description
The server side of RFC 8887: a per-connection session driver.
Connection::run reads Inbound messages from any Stream and
writes Outbound messages to any Sink, so it is independent of
the WebSocket library. The deployment does the opening handshake
(authentication, RFC 8887 §4.1; the jmap subprotocol, §4.2, see
offers_jmap), maps its library’s messages to
Inbound / Outbound (feature tungstenite does this for
tokio-tungstenite), and calls run once per connection.
- Each text message goes through
parse_client_message. AWsRequestis handed to theRequestHandler(DispatcherHandlerwraps ajmap_server::Dispatcher); itsWsResponseorWsRequestErrorcarries the request’sidback asrequestId(§4.3.3, §4.3.4). - Requests run concurrently, up to
ConnectionConfig::max_concurrent_requests, and answer in the order they finish: “JMAP over WebSocket allows the server to process requests out of order” (§4.3.2). A request over the limit gets alimiterror namingmaxConcurrentRequests, which “also applies to requests made on the WebSocket connection”.Connection::with_shared_limitshares the limit with the deployment’s HTTP API endpoint. - A
WebSocketPushEnablesubscribes to thePushSource; eachWsStateChangeit yields is cut to the requesteddataTypes(filter_state_change) and sent, in the order the source yields them. Enabling again replaces the subscription;WebSocketPushDisabledrops it (§4.3.5).PushHubis a ready source. - A binary message closes the connection with status 1003, or is
ignored (
BinaryFrames, §4.3.1).
Structs§
- Connection
- One JMAP-over-WebSocket connection: a
RequestHandler, aPushSourceand limits. See the module docs. - Connection
Config - Per-connection limits and policies.
- Dispatcher
Handler - A
RequestHandlerthat dispatches every Request on aDispatcherfor one caller. - NoPush
- A
PushSourcethat never pushes, for a server whose capability sayssupportsPush: false. AWebSocketPushEnableis accepted and yields nothing. - Publishing
Handler - A
RequestHandlerthat runsinner, then publishes the state changes of its/setresponses (state_change_for_response) to aPushHub, so connections with push enabled hear about writes made over the WebSocket without the deployment wiring it by hand. - PushHub
- A fan-out of state changes to every connection of one principal, with
RFC 8887 §4.3.5.1
pushStatetokens and replay.
Enums§
- Binary
Frames - What the driver does with a binary message (RFC 8887 §4.3.1: “the endpoint can either ignore the frame or close the WebSocket connection”).
- Connection
Error - Why
Connection::runstopped early. - Inbound
- A WebSocket message received from the client, as the driver needs it.
- Outbound
- A WebSocket message the driver sends.
Constants§
- CLOSE_
UNSUPPORTED_ DATA - The WebSocket close status for a binary message (RFC 8887 §4.3.1, RFC 6455 §7.4.1: 1003 Unsupported Data).
Traits§
- Push
Source - Where a connection’s push notifications come from (RFC 8887 §4.3.5).
- Request
Handler - Answers the Requests of one connection.
Functions§
- filter_
state_ change - Cuts
changetodata_types(RFC 8887 §4.3.5.2: “A StateChange notification will only be sent if the data for one of these types changes. Other types are omitted from the TypeState object.”). - parse_
client_ message - Reads one text message from the client (RFC 8887 §4.3).
- request_
error - The RFC 8887 §4.3.4 RequestError for a request-level
err: its RFC 8620 §3.6.1 problem details (status fromjmap_server::error_status) withrequestIdset torequest_id. - state_
change_ for_ response - The
StateChangea Response implies: thenewStateof everyFoo/setresponse whose state changed (oldStatediffers, RFC 8620 §5.3), keyed by itsaccountIdand the data typeFoo.Nonewhen nothing changed.