Widget API: initial skeleton

crates/matrix-sdk/Cargo.toml

@@ -55,6 +55,7 @@ experimental-sliding-sync = [
     "reqwest/gzip",
     "dep:eyeball-im-util",
 ]
+experimental-widget-api = []
 
 docsrs = ["e2e-encryption", "sqlite", "sso-login", "qrcode", "image-proc"]
 

crates/matrix-sdk/src/lib.rs

@@ -44,12 +44,13 @@ pub mod notification_settings;
 pub mod oidc;
 pub mod room;
 pub mod sync;
-
 #[cfg(feature = "experimental-sliding-sync")]
 pub mod sliding_sync;
-
+#[cfg(feature = "widget-api")]
+pub mod widget_api;
 #[cfg(feature = "e2e-encryption")]
 pub mod encryption;
+
 pub use account::Account;
 pub use authentication::{AuthApi, AuthSession};
 pub use client::{Client, ClientBuildError, ClientBuilder, LoopCtrl, SendRequest, UnknownToken};

crates/matrix-sdk/src/widget_api/mod.rs

@@ -0,0 +1,23 @@
+//! Client widget API implementation.
+
+use crate::room::Room as JoinedRoom;
+
+mod permissions;
+mod widget;
+
+pub use self::{
+    permissions::{Permissions, PermissionsProvider},
+    widget::{Comm, Info, Widget},
+};
+
+/// Starts a client widget API state machine for a given `widget` in a given joined `room`.
+/// The function returns once the widget is disconnected or any terminal error occurs.
+///
+/// Not implemented yet, currently always panics.
+pub async fn run_widget_api(
+    _room: JoinedRoom,
+    _widget: widget::Widget,
+    _permissions_provider: impl permissions::PermissionsProvider,
+) -> Result<(), ()> {
+    todo!()
+}

crates/matrix-sdk/src/widget_api/permissions.rs

@@ -0,0 +1,24 @@
+//! Types and traits related to the permissions that a widget can request from a client.
+
+use async_trait::async_trait;
+
+/// Must be implemented by a component that provides functionality of deciding whether
+/// a widget is allowed to use certain capabilities (typically by providing a prompt to the user).
+#[async_trait]
+pub trait PermissionsProvider: Send + Sync + 'static {
+    /// Receives a request for given permissions and returns the actual permissions that
+    /// the clients grants to a given widget (usually by prompting the user).
+    async fn acquire_permissions(&self, permissions: Permissions) -> Permissions;
+}
+
+/// Permissions that a widget can request from a client.
+#[derive(Debug)]
+pub struct Permissions {
+    /// Types of the messages that a widget wants to be able to fetch.
+    pub read: Vec<MessageType>,
+    /// Types of the messages that a widget wants to be able to send.
+    pub send: Vec<MessageType>,
+}
+
+/// An alias for an actual type of the messages that is going to be used with a permission request.
+pub type MessageType = String;

crates/matrix-sdk/src/widget_api/widget.rs

@@ -0,0 +1,31 @@
+//! The description of a widget.
+
+use tokio::sync::mpsc::{Receiver, Sender};
+
+/// Describes a widget.
+#[derive(Debug)]
+pub struct Widget {
+    /// Information about the widget.
+    pub info: Info,
+    /// Communication channels with a widget.
+    pub comm: Comm,
+}
+
+/// Information about a widget.
+#[derive(Debug)]
+pub struct Info {
+    /// Widget's unique identifier.
+    pub id: String,
+    /// Whether or not the widget should be initialized on load message (`ContentLoad` message),
+    /// or upon creation/attaching of the widget to the SDK's state machine that drives the API.
+    pub init_on_load: bool,
+}
+
+/// Communication "pipes" with a widget.
+#[derive(Debug)]
+pub struct Comm {
+    /// Raw incoming messages from the widget (normally, formatted as JSON).
+    pub from: Receiver<String>,
+    /// Raw outgoing messages from the client (SDK) to the widget (normally formatted as JSON).
+    pub to: Sender<String>,
+}