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). - A message whose
@typeanExtensionHandlerregistered (Connection::with_extension) goes to that handler, for the extension message types the JMAP Chat, VTC and Scene WebSocket drafts define (ChatStreamEnable,VTCStreamEnable,SceneStreamEnable, …). The handler sends its server-to-client messages through anExtensionSender. Any other@typeis answered withnotRequest. - A
CloseHandle(Connection::close_handle) lets the deployment end the connection with a Close frame of its choosing, such as 1008 (CloseCode::POLICY_VIOLATION) when the credentials of the opening handshake expire (§4.2).
Structs§
- Close
Code - A WebSocket Close status code an endpoint may send (RFC 6455 §7.4).
- Close
Handle - Closes a running
Connectionfrom outside it, for example when the credentials of the opening handshake expire (RFC 8887 §4.2). Get one withConnection::close_handlebefore callingrun; clone it freely and send it to another task. - 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. - Extension
Message - One client message whose
@typeanExtensionHandlerregistered. - Extension
Sender - Queues server-to-client messages of one connection’s extensions.
- 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. - Extension
Send Error - Why an
ExtensionSenderdid not queue a message. - 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).
- MAX_
CLOSE_ REASON_ LEN - The longest Close reason, in bytes: a control frame payload is at most 125 bytes (RFC 6455 §5.5), two of them the status code.
Traits§
- Extension
Handler - Handles the client messages of one or more extension
@types on one connection, and sends that extension’s server-to-client messages. - 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: “AStateChangenotification will only be sent if the data for one of these types changes. Other types are omitted from theTypeStateobject.”). - parse_
client_ message - Reads one text message from the client (RFC 8887 §4.3).
- request_
error - The RFC 8887 §4.3.4
RequestErrorfor a request-levelerr: 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.