ruma_appservice_api/
lib.rs

1#![doc(html_favicon_url = "https://ruma.dev/favicon.ico")]
2#![doc(html_logo_url = "https://ruma.dev/images/logo.png")]
3//! (De)serializable types for the [Matrix Application Service API][appservice-api].
4//! These types can be shared by application service and server code.
5//!
6//! [appservice-api]: https://spec.matrix.org/latest/application-service-api/
7
8#![warn(missing_docs)]
9
10use serde::{Deserialize, Serialize};
11
12pub mod event;
13pub mod ping;
14pub mod query;
15pub mod thirdparty;
16
17/// A namespace defined by an application service.
18///
19/// Used for [appservice registration](https://spec.matrix.org/latest/application-service-api/#registration).
20#[derive(Clone, Debug, Serialize, Deserialize)]
21#[cfg_attr(not(ruma_unstable_exhaustive_types), non_exhaustive)]
22pub struct Namespace {
23    /// Whether this application service has exclusive access to events within this namespace.
24    pub exclusive: bool,
25
26    /// A regular expression defining which values this namespace includes.
27    pub regex: String,
28}
29
30impl Namespace {
31    /// Creates a new `Namespace` with the given exclusivity and regex pattern.
32    pub fn new(exclusive: bool, regex: String) -> Self {
33        Namespace { exclusive, regex }
34    }
35}
36
37/// Namespaces defined by an application service.
38///
39/// Used for [appservice registration](https://spec.matrix.org/latest/application-service-api/#registration).
40#[derive(Clone, Debug, Default, Serialize, Deserialize)]
41#[cfg_attr(not(ruma_unstable_exhaustive_types), non_exhaustive)]
42pub struct Namespaces {
43    /// Events which are sent from certain users.
44    #[serde(default, skip_serializing_if = "Vec::is_empty")]
45    pub users: Vec<Namespace>,
46
47    /// Events which are sent in rooms with certain room aliases.
48    #[serde(default, skip_serializing_if = "Vec::is_empty")]
49    pub aliases: Vec<Namespace>,
50
51    /// Events which are sent in rooms with certain room IDs.
52    #[serde(default, skip_serializing_if = "Vec::is_empty")]
53    pub rooms: Vec<Namespace>,
54}
55
56impl Namespaces {
57    /// Creates a new `Namespaces` instance with empty namespaces for `users`,  `aliases` and
58    /// `rooms` (none of them are explicitly required)
59    pub fn new() -> Self {
60        Self::default()
61    }
62}
63
64/// Information required in the registration yaml file that a homeserver needs.
65///
66/// To create an instance of this type, first create a `RegistrationInit` and convert it via
67/// `Registration::from` / `.into()`.
68///
69/// Used for [appservice registration](https://spec.matrix.org/latest/application-service-api/#registration).
70#[derive(Clone, Debug, Serialize, Deserialize)]
71#[cfg_attr(not(ruma_unstable_exhaustive_types), non_exhaustive)]
72pub struct Registration {
73    /// A unique, user - defined ID of the application service which will never change.
74    pub id: String,
75
76    /// The URL for the application service.
77    ///
78    /// Optionally set to `null` if no traffic is required.
79    #[serde(deserialize_with = "Option::deserialize")]
80    pub url: Option<String>,
81
82    /// A unique token for application services to use to authenticate requests to Homeservers.
83    pub as_token: String,
84
85    /// A unique token for Homeservers to use to authenticate requests to application services.
86    pub hs_token: String,
87
88    /// The localpart of the user associated with the application service.
89    pub sender_localpart: String,
90
91    /// A list of users, aliases and rooms namespaces that the application service controls.
92    pub namespaces: Namespaces,
93
94    /// Whether requests from masqueraded users are rate-limited.
95    ///
96    /// The sender is excluded.
97    #[serde(skip_serializing_if = "Option::is_none")]
98    pub rate_limited: Option<bool>,
99
100    /// The external protocols which the application service provides (e.g. IRC).
101    #[serde(skip_serializing_if = "Option::is_none")]
102    pub protocols: Option<Vec<String>>,
103
104    /// Whether the application service wants to receive ephemeral data.
105    ///
106    /// Defaults to `false`.
107    #[serde(default, skip_serializing_if = "ruma_common::serde::is_default")]
108    pub receive_ephemeral: bool,
109}
110
111/// Initial set of fields of `Registration`.
112///
113/// This struct will not be updated even if additional fields are added to `Registration` in a new
114/// (non-breaking) release of the Matrix specification.
115///
116/// Used for [appservice registration](https://spec.matrix.org/latest/application-service-api/#registration).
117#[derive(Debug)]
118#[allow(clippy::exhaustive_structs)]
119pub struct RegistrationInit {
120    /// A unique, user - defined ID of the application service which will never change.
121    pub id: String,
122
123    /// The URL for the application service.
124    ///
125    /// Optionally set to `null` if no traffic is required.
126    pub url: Option<String>,
127
128    /// A unique token for application services to use to authenticate requests to Homeservers.
129    pub as_token: String,
130
131    /// A unique token for Homeservers to use to authenticate requests to application services.
132    pub hs_token: String,
133
134    /// The localpart of the user associated with the application service.
135    pub sender_localpart: String,
136
137    /// A list of users, aliases and rooms namespaces that the application service controls.
138    pub namespaces: Namespaces,
139
140    /// Whether requests from masqueraded users are rate-limited.
141    ///
142    /// The sender is excluded.
143    pub rate_limited: Option<bool>,
144
145    /// The external protocols which the application service provides (e.g. IRC).
146    pub protocols: Option<Vec<String>>,
147}
148
149impl From<RegistrationInit> for Registration {
150    fn from(init: RegistrationInit) -> Self {
151        let RegistrationInit {
152            id,
153            url,
154            as_token,
155            hs_token,
156            sender_localpart,
157            namespaces,
158            rate_limited,
159            protocols,
160        } = init;
161        Self {
162            id,
163            url,
164            as_token,
165            hs_token,
166            sender_localpart,
167            namespaces,
168            rate_limited,
169            protocols,
170            receive_ephemeral: false,
171        }
172    }
173}
ruma_appservice_api/lib.rs

ruma_appservice_api/
lib.rs
