mas_matrix/
lib.rs

1// Copyright 2024, 2025 New Vector Ltd.
2// Copyright 2023, 2024 The Matrix.org Foundation C.I.C.
3//
4// SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial
5// Please see LICENSE files in the repository root for full details.
6
7mod mock;
8mod readonly;
9
10use std::{collections::HashSet, sync::Arc};
11
12use ruma_common::UserId;
13
14pub use self::{
15    mock::HomeserverConnection as MockHomeserverConnection, readonly::ReadOnlyHomeserverConnection,
16};
17
18#[derive(Debug)]
19pub struct MatrixUser {
20    pub displayname: Option<String>,
21    pub avatar_url: Option<String>,
22    pub deactivated: bool,
23}
24
25#[derive(Debug, Default)]
26enum FieldAction<T> {
27    #[default]
28    DoNothing,
29    Set(T),
30    Unset,
31}
32
33pub struct ProvisionRequest {
34    localpart: String,
35    sub: String,
36    displayname: FieldAction<String>,
37    avatar_url: FieldAction<String>,
38    emails: FieldAction<Vec<String>>,
39}
40
41impl ProvisionRequest {
42    /// Create a new [`ProvisionRequest`].
43    ///
44    /// # Parameters
45    ///
46    /// * `localpart` - The localpart of the user to provision.
47    /// * `sub` - The `sub` of the user, aka the internal ID.
48    #[must_use]
49    pub fn new(localpart: impl Into<String>, sub: impl Into<String>) -> Self {
50        Self {
51            localpart: localpart.into(),
52            sub: sub.into(),
53            displayname: FieldAction::DoNothing,
54            avatar_url: FieldAction::DoNothing,
55            emails: FieldAction::DoNothing,
56        }
57    }
58
59    /// Get the `sub` of the user to provision, aka the internal ID.
60    #[must_use]
61    pub fn sub(&self) -> &str {
62        &self.sub
63    }
64
65    /// Get the localpart of the user to provision.
66    #[must_use]
67    pub fn localpart(&self) -> &str {
68        &self.localpart
69    }
70
71    /// Ask to set the displayname of the user.
72    ///
73    /// # Parameters
74    ///
75    /// * `displayname` - The displayname to set.
76    #[must_use]
77    pub fn set_displayname(mut self, displayname: String) -> Self {
78        self.displayname = FieldAction::Set(displayname);
79        self
80    }
81
82    /// Ask to unset the displayname of the user.
83    #[must_use]
84    pub fn unset_displayname(mut self) -> Self {
85        self.displayname = FieldAction::Unset;
86        self
87    }
88
89    /// Call the given callback if the displayname should be set or unset.
90    ///
91    /// # Parameters
92    ///
93    /// * `callback` - The callback to call.
94    pub fn on_displayname<F>(&self, callback: F) -> &Self
95    where
96        F: FnOnce(Option<&str>),
97    {
98        match &self.displayname {
99            FieldAction::Unset => callback(None),
100            FieldAction::Set(displayname) => callback(Some(displayname)),
101            FieldAction::DoNothing => {}
102        }
103
104        self
105    }
106
107    /// Ask to set the avatar URL of the user.
108    ///
109    /// # Parameters
110    ///
111    /// * `avatar_url` - The avatar URL to set.
112    #[must_use]
113    pub fn set_avatar_url(mut self, avatar_url: String) -> Self {
114        self.avatar_url = FieldAction::Set(avatar_url);
115        self
116    }
117
118    /// Ask to unset the avatar URL of the user.
119    #[must_use]
120    pub fn unset_avatar_url(mut self) -> Self {
121        self.avatar_url = FieldAction::Unset;
122        self
123    }
124
125    /// Call the given callback if the avatar URL should be set or unset.
126    ///
127    /// # Parameters
128    ///
129    /// * `callback` - The callback to call.
130    pub fn on_avatar_url<F>(&self, callback: F) -> &Self
131    where
132        F: FnOnce(Option<&str>),
133    {
134        match &self.avatar_url {
135            FieldAction::Unset => callback(None),
136            FieldAction::Set(avatar_url) => callback(Some(avatar_url)),
137            FieldAction::DoNothing => {}
138        }
139
140        self
141    }
142
143    /// Ask to set the emails of the user.
144    ///
145    /// # Parameters
146    ///
147    /// * `emails` - The list of emails to set.
148    #[must_use]
149    pub fn set_emails(mut self, emails: Vec<String>) -> Self {
150        self.emails = FieldAction::Set(emails);
151        self
152    }
153
154    /// Ask to unset the emails of the user.
155    #[must_use]
156    pub fn unset_emails(mut self) -> Self {
157        self.emails = FieldAction::Unset;
158        self
159    }
160
161    /// Call the given callback if the emails should be set or unset.
162    ///
163    /// # Parameters
164    ///
165    /// * `callback` - The callback to call.
166    pub fn on_emails<F>(&self, callback: F) -> &Self
167    where
168        F: FnOnce(Option<&[String]>),
169    {
170        match &self.emails {
171            FieldAction::Unset => callback(None),
172            FieldAction::Set(emails) => callback(Some(emails)),
173            FieldAction::DoNothing => {}
174        }
175
176        self
177    }
178}
179
180#[async_trait::async_trait]
181pub trait HomeserverConnection: Send + Sync {
182    /// Get the homeserver URL.
183    fn homeserver(&self) -> &str;
184
185    /// Get the Matrix ID of the user with the given localpart.
186    ///
187    /// # Parameters
188    ///
189    /// * `localpart` - The localpart of the user.
190    fn mxid(&self, localpart: &str) -> String {
191        format!("@{}:{}", localpart, self.homeserver())
192    }
193
194    /// Get the localpart of a Matrix ID if it has the right server name
195    ///
196    /// Returns [`None`] if the input isn't a valid MXID, or if the server name
197    /// doesn't match
198    ///
199    /// # Parameters
200    ///
201    /// * `mxid` - The MXID of the user
202    fn localpart<'a>(&self, mxid: &'a str) -> Option<&'a str> {
203        let mxid = <&UserId>::try_from(mxid).ok()?;
204        if mxid.server_name() != self.homeserver() {
205            return None;
206        }
207        Some(mxid.localpart())
208    }
209
210    /// Verify a bearer token coming from the homeserver for homeserver to MAS
211    /// interactions
212    ///
213    /// Returns `true` if the token is valid, `false` otherwise.
214    ///
215    /// # Parameters
216    ///
217    /// * `token` - The token to verify.
218    ///
219    /// # Errors
220    ///
221    /// Returns an error if the token failed to verify.
222    async fn verify_token(&self, token: &str) -> Result<bool, anyhow::Error>;
223
224    /// Query the state of a user on the homeserver.
225    ///
226    /// # Parameters
227    ///
228    /// * `localpart` - The localpart of the user to query.
229    ///
230    /// # Errors
231    ///
232    /// Returns an error if the homeserver is unreachable or the user does not
233    /// exist.
234    async fn query_user(&self, localpart: &str) -> Result<MatrixUser, anyhow::Error>;
235
236    /// Provision a user on the homeserver.
237    ///
238    /// # Parameters
239    ///
240    /// * `request` - a [`ProvisionRequest`] containing the details of the user
241    ///   to provision.
242    ///
243    /// # Errors
244    ///
245    /// Returns an error if the homeserver is unreachable or the user could not
246    /// be provisioned.
247    async fn provision_user(&self, request: &ProvisionRequest) -> Result<bool, anyhow::Error>;
248
249    /// Check whether a given username is available on the homeserver.
250    ///
251    /// # Parameters
252    ///
253    /// * `localpart` - The localpart to check.
254    ///
255    /// # Errors
256    ///
257    /// Returns an error if the homeserver is unreachable.
258    async fn is_localpart_available(&self, localpart: &str) -> Result<bool, anyhow::Error>;
259
260    /// Create a device for a user on the homeserver.
261    ///
262    /// # Parameters
263    ///
264    /// * `localpart` - The localpart of the user to create a device for.
265    /// * `device_id` - The device ID to create.
266    ///
267    /// # Errors
268    ///
269    /// Returns an error if the homeserver is unreachable or the device could
270    /// not be created.
271    async fn upsert_device(
272        &self,
273        localpart: &str,
274        device_id: &str,
275        initial_display_name: Option<&str>,
276    ) -> Result<(), anyhow::Error>;
277
278    /// Update the display name of a device for a user on the homeserver.
279    ///
280    /// # Parameters
281    ///
282    /// * `localpart` - The localpart of the user to update a device for.
283    /// * `device_id` - The device ID to update.
284    /// * `display_name` - The new display name to set
285    ///
286    /// # Errors
287    ///
288    /// Returns an error if the homeserver is unreachable or the device could
289    /// not be updated.
290    async fn update_device_display_name(
291        &self,
292        localpart: &str,
293        device_id: &str,
294        display_name: &str,
295    ) -> Result<(), anyhow::Error>;
296
297    /// Delete a device for a user on the homeserver.
298    ///
299    /// # Parameters
300    ///
301    /// * `localpart` - The localpart of the user to delete a device for.
302    /// * `device_id` - The device ID to delete.
303    ///
304    /// # Errors
305    ///
306    /// Returns an error if the homeserver is unreachable or the device could
307    /// not be deleted.
308    async fn delete_device(&self, localpart: &str, device_id: &str) -> Result<(), anyhow::Error>;
309
310    /// Sync the list of devices of a user with the homeserver.
311    ///
312    /// # Parameters
313    ///
314    /// * `localpart` - The localpart of the user to sync the devices for.
315    /// * `devices` - The list of devices to sync.
316    ///
317    /// # Errors
318    ///
319    /// Returns an error if the homeserver is unreachable or the devices could
320    /// not be synced.
321    async fn sync_devices(
322        &self,
323        localpart: &str,
324        devices: HashSet<String>,
325    ) -> Result<(), anyhow::Error>;
326
327    /// Delete a user on the homeserver.
328    ///
329    /// # Parameters
330    ///
331    /// * `localpart` - The localpart of the user to delete.
332    /// * `erase` - Whether to ask the homeserver to erase the user's data.
333    ///
334    /// # Errors
335    ///
336    /// Returns an error if the homeserver is unreachable or the user could not
337    /// be deleted.
338    async fn delete_user(&self, localpart: &str, erase: bool) -> Result<(), anyhow::Error>;
339
340    /// Reactivate a user on the homeserver.
341    ///
342    /// # Parameters
343    ///
344    /// * `localpart` - The localpart of the user to reactivate.
345    ///
346    /// # Errors
347    ///
348    /// Returns an error if the homeserver is unreachable or the user could not
349    /// be reactivated.
350    async fn reactivate_user(&self, localpart: &str) -> Result<(), anyhow::Error>;
351
352    /// Set the displayname of a user on the homeserver.
353    ///
354    /// # Parameters
355    ///
356    /// * `localpart` - The localpart of the user to set the displayname for.
357    /// * `displayname` - The displayname to set.
358    ///
359    /// # Errors
360    ///
361    /// Returns an error if the homeserver is unreachable or the displayname
362    /// could not be set.
363    async fn set_displayname(
364        &self,
365        localpart: &str,
366        displayname: &str,
367    ) -> Result<(), anyhow::Error>;
368
369    /// Unset the displayname of a user on the homeserver.
370    ///
371    /// # Parameters
372    ///
373    /// * `localpart` - The localpart of the user to unset the displayname for.
374    ///
375    /// # Errors
376    ///
377    /// Returns an error if the homeserver is unreachable or the displayname
378    /// could not be unset.
379    async fn unset_displayname(&self, localpart: &str) -> Result<(), anyhow::Error>;
380
381    /// Temporarily allow a user to reset their cross-signing keys.
382    ///
383    /// # Parameters
384    ///
385    /// * `localpart` - The localpart of the user to allow cross-signing key
386    ///   reset
387    ///
388    /// # Errors
389    ///
390    /// Returns an error if the homeserver is unreachable or the cross-signing
391    /// reset could not be allowed.
392    async fn allow_cross_signing_reset(&self, localpart: &str) -> Result<(), anyhow::Error>;
393}
394
395#[async_trait::async_trait]
396impl<T: HomeserverConnection + Send + Sync + ?Sized> HomeserverConnection for &T {
397    fn homeserver(&self) -> &str {
398        (**self).homeserver()
399    }
400
401    async fn verify_token(&self, token: &str) -> Result<bool, anyhow::Error> {
402        (**self).verify_token(token).await
403    }
404
405    async fn query_user(&self, localpart: &str) -> Result<MatrixUser, anyhow::Error> {
406        (**self).query_user(localpart).await
407    }
408
409    async fn provision_user(&self, request: &ProvisionRequest) -> Result<bool, anyhow::Error> {
410        (**self).provision_user(request).await
411    }
412
413    async fn is_localpart_available(&self, localpart: &str) -> Result<bool, anyhow::Error> {
414        (**self).is_localpart_available(localpart).await
415    }
416
417    async fn upsert_device(
418        &self,
419        localpart: &str,
420        device_id: &str,
421        initial_display_name: Option<&str>,
422    ) -> Result<(), anyhow::Error> {
423        (**self)
424            .upsert_device(localpart, device_id, initial_display_name)
425            .await
426    }
427
428    async fn update_device_display_name(
429        &self,
430        localpart: &str,
431        device_id: &str,
432        display_name: &str,
433    ) -> Result<(), anyhow::Error> {
434        (**self)
435            .update_device_display_name(localpart, device_id, display_name)
436            .await
437    }
438
439    async fn delete_device(&self, localpart: &str, device_id: &str) -> Result<(), anyhow::Error> {
440        (**self).delete_device(localpart, device_id).await
441    }
442
443    async fn sync_devices(
444        &self,
445        localpart: &str,
446        devices: HashSet<String>,
447    ) -> Result<(), anyhow::Error> {
448        (**self).sync_devices(localpart, devices).await
449    }
450
451    async fn delete_user(&self, localpart: &str, erase: bool) -> Result<(), anyhow::Error> {
452        (**self).delete_user(localpart, erase).await
453    }
454
455    async fn reactivate_user(&self, localpart: &str) -> Result<(), anyhow::Error> {
456        (**self).reactivate_user(localpart).await
457    }
458
459    async fn set_displayname(
460        &self,
461        localpart: &str,
462        displayname: &str,
463    ) -> Result<(), anyhow::Error> {
464        (**self).set_displayname(localpart, displayname).await
465    }
466
467    async fn unset_displayname(&self, localpart: &str) -> Result<(), anyhow::Error> {
468        (**self).unset_displayname(localpart).await
469    }
470
471    async fn allow_cross_signing_reset(&self, localpart: &str) -> Result<(), anyhow::Error> {
472        (**self).allow_cross_signing_reset(localpart).await
473    }
474}
475
476// Implement for Arc<T> where T: HomeserverConnection
477#[async_trait::async_trait]
478impl<T: HomeserverConnection + ?Sized> HomeserverConnection for Arc<T> {
479    fn homeserver(&self) -> &str {
480        (**self).homeserver()
481    }
482
483    async fn verify_token(&self, token: &str) -> Result<bool, anyhow::Error> {
484        (**self).verify_token(token).await
485    }
486
487    async fn query_user(&self, localpart: &str) -> Result<MatrixUser, anyhow::Error> {
488        (**self).query_user(localpart).await
489    }
490
491    async fn provision_user(&self, request: &ProvisionRequest) -> Result<bool, anyhow::Error> {
492        (**self).provision_user(request).await
493    }
494
495    async fn is_localpart_available(&self, localpart: &str) -> Result<bool, anyhow::Error> {
496        (**self).is_localpart_available(localpart).await
497    }
498
499    async fn upsert_device(
500        &self,
501        localpart: &str,
502        device_id: &str,
503        initial_display_name: Option<&str>,
504    ) -> Result<(), anyhow::Error> {
505        (**self)
506            .upsert_device(localpart, device_id, initial_display_name)
507            .await
508    }
509
510    async fn update_device_display_name(
511        &self,
512        localpart: &str,
513        device_id: &str,
514        display_name: &str,
515    ) -> Result<(), anyhow::Error> {
516        (**self)
517            .update_device_display_name(localpart, device_id, display_name)
518            .await
519    }
520
521    async fn delete_device(&self, localpart: &str, device_id: &str) -> Result<(), anyhow::Error> {
522        (**self).delete_device(localpart, device_id).await
523    }
524
525    async fn sync_devices(
526        &self,
527        localpart: &str,
528        devices: HashSet<String>,
529    ) -> Result<(), anyhow::Error> {
530        (**self).sync_devices(localpart, devices).await
531    }
532
533    async fn delete_user(&self, localpart: &str, erase: bool) -> Result<(), anyhow::Error> {
534        (**self).delete_user(localpart, erase).await
535    }
536
537    async fn reactivate_user(&self, localpart: &str) -> Result<(), anyhow::Error> {
538        (**self).reactivate_user(localpart).await
539    }
540
541    async fn set_displayname(
542        &self,
543        localpart: &str,
544        displayname: &str,
545    ) -> Result<(), anyhow::Error> {
546        (**self).set_displayname(localpart, displayname).await
547    }
548
549    async fn unset_displayname(&self, localpart: &str) -> Result<(), anyhow::Error> {
550        (**self).unset_displayname(localpart).await
551    }
552
553    async fn allow_cross_signing_reset(&self, localpart: &str) -> Result<(), anyhow::Error> {
554        (**self).allow_cross_signing_reset(localpart).await
555    }
556}
mas_matrix/lib.rs

mas_matrix/
lib.rs
