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

ruma_appservice_api/
lib.rs
