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 pub url: Option<String>,
80
81 /// A unique token for application services to use to authenticate requests to Homeservers.
82 pub as_token: String,
83
84 /// A unique token for Homeservers to use to authenticate requests to application services.
85 pub hs_token: String,
86
87 /// The localpart of the user associated with the application service.
88 pub sender_localpart: String,
89
90 /// A list of users, aliases and rooms namespaces that the application service controls.
91 pub namespaces: Namespaces,
92
93 /// Whether requests from masqueraded users are rate-limited.
94 ///
95 /// The sender is excluded.
96 #[serde(skip_serializing_if = "Option::is_none")]
97 pub rate_limited: Option<bool>,
98
99 /// The external protocols which the application service provides (e.g. IRC).
100 #[serde(skip_serializing_if = "Option::is_none")]
101 pub protocols: Option<Vec<String>>,
102
103 /// Whether the application service wants to receive ephemeral data.
104 ///
105 /// Defaults to `false`.
106 #[serde(default, skip_serializing_if = "ruma_common::serde::is_default")]
107 pub receive_ephemeral: bool,
108}
109
110/// Initial set of fields of `Registration`.
111///
112/// This struct will not be updated even if additional fields are added to `Registration` in a new
113/// (non-breaking) release of the Matrix specification.
114///
115/// Used for [appservice registration](https://spec.matrix.org/latest/application-service-api/#registration).
116#[derive(Debug)]
117#[allow(clippy::exhaustive_structs)]
118pub struct RegistrationInit {
119 /// A unique, user - defined ID of the application service which will never change.
120 pub id: String,
121
122 /// The URL for the application service.
123 ///
124 /// Optionally set to `null` if no traffic is required.
125 pub url: Option<String>,
126
127 /// A unique token for application services to use to authenticate requests to Homeservers.
128 pub as_token: String,
129
130 /// A unique token for Homeservers to use to authenticate requests to application services.
131 pub hs_token: String,
132
133 /// The localpart of the user associated with the application service.
134 pub sender_localpart: String,
135
136 /// A list of users, aliases and rooms namespaces that the application service controls.
137 pub namespaces: Namespaces,
138
139 /// Whether requests from masqueraded users are rate-limited.
140 ///
141 /// The sender is excluded.
142 pub rate_limited: Option<bool>,
143
144 /// The external protocols which the application service provides (e.g. IRC).
145 pub protocols: Option<Vec<String>>,
146}
147
148impl From<RegistrationInit> for Registration {
149 fn from(init: RegistrationInit) -> Self {
150 let RegistrationInit {
151 id,
152 url,
153 as_token,
154 hs_token,
155 sender_localpart,
156 namespaces,
157 rate_limited,
158 protocols,
159 } = init;
160 Self {
161 id,
162 url,
163 as_token,
164 hs_token,
165 sender_localpart,
166 namespaces,
167 rate_limited,
168 protocols,
169 receive_ephemeral: false,
170 }
171 }
172}