Skip to main content

ExtensionHandler

Trait ExtensionHandler 

Source
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 { ... }
}
Available on crate feature 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:

  1. start once, before reading any message, with the ExtensionSender for server-to-client messages.
  2. handle for each registered message, one at a time in the order the client sent them. Until handle returns the driver reads no further client message, so a Request sent after a …StreamEnable runs 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.
  3. close once when Connection::run ends, however it ends, after the connection’s queue is closed and any running handle finished. Release per-connection resources here (the drafts cancel the subscription “immediately” when the connection closes; a Scene observer stops counting toward observerCount). It is not called if the run future itself is dropped; put cleanup that must run then in Drop.

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§

Source

fn message_types(&self) -> &[&str]

The client-to-server @types this handler takes. Read once, by Connection::with_extension.

Source

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§

Source

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.

Source

fn close(&mut self) -> impl Future<Output = ()> + Send

Called once when the connection ends. The default does nothing.

Dyn Compatibility§

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors§