Widget API: initial skeleton

crates/matrix-sdk/Cargo.toml

@@ -58,6 +58,8 @@ experimental-sliding-sync = [
 
 docsrs = ["e2e-encryption", "sqlite", "sso-login", "qrcode", "image-proc"]
 
+widget-api = []
+
 [dependencies]
 anyhow = { workspace = true, optional = true }
 anymap2 = "0.13.0"

crates/matrix-sdk/src/lib.rs

@@ -48,6 +48,9 @@ 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;

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

@@ -0,0 +1,16 @@
+//! Client widget API implementation.
+
+use crate::room::Room as JoinedRoom;
+
+pub mod permissions;
+pub mod 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.
+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;
+
+/// A trait that must be implemented by an entity that performs the validation / authorization
+/// of the widget's permissions. Typically, it's a native client that "hosts" the widget.
+#[async_trait]
+pub trait PermissionsProvider: Send + Sync + 'static {
+    /// Receives a request for given permissions and returns the actual permissions that
+    /// the user (client) granted to a given widget.
+    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>,
+}