pub trait ExtensionHandler: Send + 'static {
// Required methods
fn message_types(&self) -> &[&str];
fn handle(
&mut self,
message: ExtensionMessage,
) -> impl Future<Output = Result<(), JmapError>> + Send;
// Provided methods
fn start(&mut self, events: ExtensionSender) { ... }
fn close(&mut self) -> impl Future<Output = ()> + Send { ... }
}server only.Expand description
Handles the client messages of one or more extension @types on one
connection, and sends that extension’s server-to-client messages.
Register it with
Connection::with_extension, one
value per connection, when the Session advertises the capability that
defines the types (for example urn:ietf:params:jmap:chat:websocket
for ChatStreamEnable and ChatStreamDisable). The drafts tie the
types to the advertised capability, not to a Request’s using, so the
driver does no capability check of its own. A message whose @type no
handler registered is answered with notRequest, as before
(“A client-to-server message with an unrecognized @type value is a
request-level error”, draft-atwood-jmap-chat-wss-00 §Handling Unknown
Message Types).
The value is the connection’s extension state: build it with the
connection’s authenticated caller, keep the subscription in it, and
use &mut self freely. The driver calls, in order:
startonce, before reading any message, with theExtensionSenderfor server-to-client messages.handlefor each registered message, one at a time in the order the client sent them. Untilhandlereturns the driver reads no further client message, so a Request sent after a…StreamEnableruns after the subscription is in place; Responses,StateChanges and queued extension messages keep flowing meanwhile. Keep it short: start long work on a task of your own.closeonce whenConnection::runends, however it ends, after the connection’s queue is closed and any runninghandlefinished. Release per-connection resources here (the drafts cancel the subscription “immediately” when the connection closes; a Scene observer stops counting towardobserverCount). It is not called if therunfuture itself is dropped; put cleanup that must run then inDrop.
To let one extension’s control message turn on another’s events (a
ChatStreamEnable with "vtc" in dataTypes), register one handler
for all the types involved.
use jmap_websocket::jmap_types::JmapError;
use jmap_websocket::server::{ExtensionHandler, ExtensionMessage, ExtensionSender};
use serde_json::json;
/// `ToyStreamEnable` turns on `ToyEvent`s; `ToyStreamDisable` turns
/// them off.
#[derive(Default)]
struct Toy {
events: Option<ExtensionSender>,
enabled: bool,
}
impl ExtensionHandler for Toy {
fn message_types(&self) -> &[&str] {
&["ToyStreamEnable", "ToyStreamDisable"]
}
fn start(&mut self, events: ExtensionSender) {
self.events = Some(events);
}
async fn handle(&mut self, message: ExtensionMessage) -> Result<(), JmapError> {
match message.message_type.as_str() {
"ToyStreamEnable" => self.enabled = true,
_ => self.enabled = false,
}
if self.enabled
&& let Some(events) = &self.events
{
// An ephemeral event: drop it rather than wait if the
// client is slow.
let _ = events.try_send(&json!({"@type": "ToyEvent", "hello": true}));
}
Ok(())
}
}Required Methods§
Sourcefn message_types(&self) -> &[&str]
fn message_types(&self) -> &[&str]
The client-to-server @types this handler takes. Read once, by
Connection::with_extension.
Sourcefn handle(
&mut self,
message: ExtensionMessage,
) -> impl Future<Output = Result<(), JmapError>> + Send
fn handle( &mut self, message: ExtensionMessage, ) -> impl Future<Output = Result<(), JmapError>> + Send
Process one message. Success sends nothing (the drafts’ control
messages are not acknowledged: “success is silent and failure
produces a RequestError”). Err is sent as an RFC 8887 §4.3.4
RequestError with the message’s id as
requestId, through
RequestHandler::prepare_problem;
its extra members become problem-details members (for example
the Scene draft’s regionIds on a forbidden error).
Provided Methods§
Sourcefn start(&mut self, events: ExtensionSender)
fn start(&mut self, events: ExtensionSender)
Called once before the first message, with the queue for this connection’s server-to-client extension messages. The default drops it.
Dyn Compatibility§
This trait is not dyn compatible.
In older versions of Rust, dyn compatibility was called "object safety".