ruma_client_api/
push.rs

1//! Endpoints for push notifications.
2use std::{error::Error, fmt};
3
4pub use ruma_common::push::RuleKind;
5use ruma_common::{
6    push::{
7        Action, AnyPushRule, AnyPushRuleRef, ConditionalPushRule, ConditionalPushRuleInit,
8        HttpPusherData, PatternedPushRule, PatternedPushRuleInit, PushCondition, SimplePushRule,
9        SimplePushRuleInit,
10    },
11    serde::JsonObject,
12};
13use serde::{Deserialize, Serialize};
14
15pub mod delete_pushrule;
16pub mod get_notifications;
17pub mod get_pushers;
18pub mod get_pushrule;
19pub mod get_pushrule_actions;
20pub mod get_pushrule_enabled;
21pub mod get_pushrules_all;
22pub mod get_pushrules_global_scope;
23mod pusher_serde;
24pub mod set_pusher;
25pub mod set_pushrule;
26pub mod set_pushrule_actions;
27pub mod set_pushrule_enabled;
28
29/// Like `SimplePushRule`, but may represent any kind of push rule thanks to `pattern` and
30/// `conditions` being optional.
31///
32/// To create an instance of this type, use one of its `From` implementations.
33#[derive(Clone, Debug, Serialize, Deserialize)]
34#[cfg_attr(not(ruma_unstable_exhaustive_types), non_exhaustive)]
35pub struct PushRule {
36    /// The actions to perform when this rule is matched.
37    pub actions: Vec<Action>,
38
39    /// Whether this is a default rule, or has been set explicitly.
40    pub default: bool,
41
42    /// Whether the push rule is enabled or not.
43    pub enabled: bool,
44
45    /// The ID of this rule.
46    pub rule_id: String,
47
48    /// The conditions that must hold true for an event in order for a rule to be applied to an
49    /// event.
50    ///
51    /// A rule with no conditions always matches. Only applicable to underride and override rules.
52    #[serde(skip_serializing_if = "Option::is_none")]
53    pub conditions: Option<Vec<PushCondition>>,
54
55    /// The glob-style pattern to match against.
56    ///
57    /// Only applicable to content rules.
58    #[serde(skip_serializing_if = "Option::is_none")]
59    pub pattern: Option<String>,
60}
61
62impl<T> From<SimplePushRule<T>> for PushRule
63where
64    T: Into<String>,
65{
66    fn from(push_rule: SimplePushRule<T>) -> Self {
67        let SimplePushRule { actions, default, enabled, rule_id, .. } = push_rule;
68        let rule_id = rule_id.into();
69        Self { actions, default, enabled, rule_id, conditions: None, pattern: None }
70    }
71}
72
73impl From<PatternedPushRule> for PushRule {
74    fn from(push_rule: PatternedPushRule) -> Self {
75        let PatternedPushRule { actions, default, enabled, rule_id, pattern, .. } = push_rule;
76        Self { actions, default, enabled, rule_id, conditions: None, pattern: Some(pattern) }
77    }
78}
79
80impl From<ConditionalPushRule> for PushRule {
81    fn from(push_rule: ConditionalPushRule) -> Self {
82        let ConditionalPushRule { actions, default, enabled, rule_id, conditions, .. } = push_rule;
83        Self { actions, default, enabled, rule_id, conditions: Some(conditions), pattern: None }
84    }
85}
86
87impl<T> From<SimplePushRuleInit<T>> for PushRule
88where
89    T: Into<String>,
90{
91    fn from(init: SimplePushRuleInit<T>) -> Self {
92        let SimplePushRuleInit { actions, default, enabled, rule_id } = init;
93        let rule_id = rule_id.into();
94        Self { actions, default, enabled, rule_id, pattern: None, conditions: None }
95    }
96}
97
98impl From<ConditionalPushRuleInit> for PushRule {
99    fn from(init: ConditionalPushRuleInit) -> Self {
100        let ConditionalPushRuleInit { actions, default, enabled, rule_id, conditions } = init;
101        Self { actions, default, enabled, rule_id, pattern: None, conditions: Some(conditions) }
102    }
103}
104
105impl From<PatternedPushRuleInit> for PushRule {
106    fn from(init: PatternedPushRuleInit) -> Self {
107        let PatternedPushRuleInit { actions, default, enabled, rule_id, pattern } = init;
108        Self { actions, default, enabled, rule_id, pattern: Some(pattern), conditions: None }
109    }
110}
111
112impl From<AnyPushRule> for PushRule {
113    fn from(push_rule: AnyPushRule) -> Self {
114        // The catch-all is unreachable if the "ruma_unstable_exhaustive_types" cfg setting is
115        // enabled.
116        #[allow(unreachable_patterns)]
117        match push_rule {
118            AnyPushRule::Override(r) => r.into(),
119            AnyPushRule::Content(r) => r.into(),
120            AnyPushRule::Room(r) => r.into(),
121            AnyPushRule::Sender(r) => r.into(),
122            AnyPushRule::Underride(r) => r.into(),
123            _ => unreachable!(),
124        }
125    }
126}
127
128impl<'a> From<AnyPushRuleRef<'a>> for PushRule {
129    fn from(push_rule: AnyPushRuleRef<'a>) -> Self {
130        push_rule.to_owned().into()
131    }
132}
133
134impl<T> TryFrom<PushRule> for SimplePushRule<T>
135where
136    T: TryFrom<String>,
137{
138    type Error = <T as TryFrom<String>>::Error;
139
140    fn try_from(push_rule: PushRule) -> Result<Self, Self::Error> {
141        let PushRule { actions, default, enabled, rule_id, .. } = push_rule;
142        let rule_id = T::try_from(rule_id)?;
143        Ok(SimplePushRuleInit { actions, default, enabled, rule_id }.into())
144    }
145}
146
147/// An error that happens when `PushRule` cannot
148/// be converted into `PatternedPushRule`
149#[derive(Debug)]
150#[cfg_attr(not(ruma_unstable_exhaustive_types), non_exhaustive)]
151pub struct MissingPatternError;
152
153impl fmt::Display for MissingPatternError {
154    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
155        write!(f, "Push rule does not have a pattern.")
156    }
157}
158
159impl Error for MissingPatternError {}
160
161impl TryFrom<PushRule> for PatternedPushRule {
162    type Error = MissingPatternError;
163
164    fn try_from(push_rule: PushRule) -> Result<Self, Self::Error> {
165        if let PushRule { actions, default, enabled, rule_id, pattern: Some(pattern), .. } =
166            push_rule
167        {
168            Ok(PatternedPushRuleInit { actions, default, enabled, rule_id, pattern }.into())
169        } else {
170            Err(MissingPatternError)
171        }
172    }
173}
174
175impl From<PushRule> for ConditionalPushRule {
176    fn from(push_rule: PushRule) -> Self {
177        let PushRule { actions, default, enabled, rule_id, conditions, .. } = push_rule;
178
179        ConditionalPushRuleInit {
180            actions,
181            default,
182            enabled,
183            rule_id,
184            conditions: conditions.unwrap_or_default(),
185        }
186        .into()
187    }
188}
189
190/// Which kind a pusher is, and the information for that kind.
191#[derive(Clone, Debug)]
192#[non_exhaustive]
193pub enum PusherKind {
194    /// A pusher that sends HTTP pokes.
195    Http(HttpPusherData),
196
197    /// A pusher that emails the user with unread notifications.
198    Email(EmailPusherData),
199
200    #[doc(hidden)]
201    _Custom(CustomPusherData),
202}
203
204/// Defines a pusher.
205///
206/// To create an instance of this type, first create a `PusherInit` and convert it via
207/// `Pusher::from` / `.into()`.
208#[derive(Clone, Debug, Serialize)]
209#[cfg_attr(not(ruma_unstable_exhaustive_types), non_exhaustive)]
210pub struct Pusher {
211    /// Identifiers for this pusher.
212    #[serde(flatten)]
213    pub ids: PusherIds,
214
215    /// The kind of the pusher and the information for that kind.
216    #[serde(flatten)]
217    pub kind: PusherKind,
218
219    /// A string that will allow the user to identify what application owns this pusher.
220    pub app_display_name: String,
221
222    /// A string that will allow the user to identify what device owns this pusher.
223    pub device_display_name: String,
224
225    /// Determines which set of device specific rules this pusher executes.
226    #[serde(skip_serializing_if = "Option::is_none")]
227    pub profile_tag: Option<String>,
228
229    /// The preferred language for receiving notifications (e.g. 'en' or 'en-US')
230    pub lang: String,
231}
232
233/// Initial set of fields of `Pusher`.
234///
235/// This struct will not be updated even if additional fields are added to `Pusher` in a new
236/// (non-breaking) release of the Matrix specification.
237#[derive(Debug)]
238#[allow(clippy::exhaustive_structs)]
239pub struct PusherInit {
240    /// Identifiers for this pusher.
241    pub ids: PusherIds,
242
243    /// The kind of the pusher.
244    pub kind: PusherKind,
245
246    /// A string that will allow the user to identify what application owns this pusher.
247    pub app_display_name: String,
248
249    /// A string that will allow the user to identify what device owns this pusher.
250    pub device_display_name: String,
251
252    /// Determines which set of device-specific rules this pusher executes.
253    pub profile_tag: Option<String>,
254
255    /// The preferred language for receiving notifications (e.g. 'en' or 'en-US').
256    pub lang: String,
257}
258
259impl From<PusherInit> for Pusher {
260    fn from(init: PusherInit) -> Self {
261        let PusherInit { ids, kind, app_display_name, device_display_name, profile_tag, lang } =
262            init;
263        Self { ids, kind, app_display_name, device_display_name, profile_tag, lang }
264    }
265}
266
267/// Strings to uniquely identify a `Pusher`.
268#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
269#[cfg_attr(not(ruma_unstable_exhaustive_types), non_exhaustive)]
270pub struct PusherIds {
271    /// A unique identifier for the pusher.
272    ///
273    /// The maximum allowed length is 512 bytes.
274    pub pushkey: String,
275
276    /// A reverse-DNS style identifier for the application.
277    ///
278    /// The maximum allowed length is 64 bytes.
279    pub app_id: String,
280}
281
282impl PusherIds {
283    /// Creates a new `PusherIds` with the given pushkey and application ID.
284    pub fn new(pushkey: String, app_id: String) -> Self {
285        Self { pushkey, app_id }
286    }
287}
288
289/// Information for an email pusher.
290#[derive(Clone, Debug, Default, Serialize, Deserialize)]
291#[cfg_attr(not(ruma_unstable_exhaustive_types), non_exhaustive)]
292#[serde(transparent, default)]
293pub struct EmailPusherData {
294    /// Custom data for the pusher.
295    pub data: JsonObject,
296}
297
298impl EmailPusherData {
299    /// Creates a new empty `EmailPusherData`.
300    pub fn new() -> Self {
301        Self::default()
302    }
303}
304
305#[doc(hidden)]
306#[derive(Clone, Debug, Deserialize)]
307#[non_exhaustive]
308pub struct CustomPusherData {
309    kind: String,
310    data: JsonObject,
311}
ruma_client_api/push.rs

ruma_client_api/
push.rs
