matrix_sdk/config/
sync.rs

1// Copyright 2021 The Matrix.org Foundation C.I.C.
2//
3// Licensed under the Apache License, Version 2.0 (the "License");
4// you may not use this file except in compliance with the License.
5// You may obtain a copy of the License at
6//
7//     http://www.apache.org/licenses/LICENSE-2.0
8//
9// Unless required by applicable law or agreed to in writing, software
10// distributed under the License is distributed on an "AS IS" BASIS,
11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12// See the License for the specific language governing permissions and
13// limitations under the License.
14
15use std::{fmt, time::Duration};
16
17use matrix_sdk_common::debug::DebugStructExt;
18use ruma::{api::client::sync::sync_events, presence::PresenceState};
19
20const DEFAULT_SYNC_TIMEOUT: Duration = Duration::from_secs(30);
21
22/// Token to be used in the next sync request.
23#[derive(Clone, Default, Debug)]
24pub enum SyncToken {
25    /// Provide a specific token.
26    Specific(String),
27    /// Enforce no tokens at all.
28    NoToken,
29    /// Use a previous token if the client saw one in the past, and none
30    /// otherwise.
31    ///
32    /// This is the default value.
33    #[default]
34    ReusePrevious,
35}
36
37impl<T> From<T> for SyncToken
38where
39    T: Into<String>,
40{
41    fn from(token: T) -> SyncToken {
42        SyncToken::Specific(token.into())
43    }
44}
45
46impl SyncToken {
47    /// Convert a token that may exist into a [`SyncToken`]
48    pub fn from_optional_token(maybe_token: Option<String>) -> SyncToken {
49        match maybe_token {
50            Some(token) => SyncToken::Specific(token),
51            None => SyncToken::default(),
52        }
53    }
54}
55
56/// Settings for a sync call.
57#[derive(Clone)]
58pub struct SyncSettings {
59    // Filter is pretty big at 1000 bytes, box it to reduce stack size
60    pub(crate) filter: Option<Box<sync_events::v3::Filter>>,
61    pub(crate) timeout: Option<Duration>,
62    pub(crate) ignore_timeout_on_first_sync: bool,
63    pub(crate) token: SyncToken,
64    pub(crate) full_state: bool,
65    pub(crate) set_presence: PresenceState,
66}
67
68impl Default for SyncSettings {
69    fn default() -> Self {
70        Self::new()
71    }
72}
73
74#[cfg(not(tarpaulin_include))]
75impl fmt::Debug for SyncSettings {
76    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
77        let Self {
78            filter,
79            timeout,
80            ignore_timeout_on_first_sync,
81            token: _,
82            full_state,
83            set_presence,
84        } = self;
85        f.debug_struct("SyncSettings")
86            .maybe_field("filter", filter)
87            .maybe_field("timeout", timeout)
88            .field("ignore_timeout_on_first_sync", ignore_timeout_on_first_sync)
89            .field("full_state", full_state)
90            .field("set_presence", set_presence)
91            .finish()
92    }
93}
94
95impl SyncSettings {
96    /// Create new default sync settings.
97    #[must_use]
98    pub fn new() -> Self {
99        Self {
100            filter: None,
101            timeout: Some(DEFAULT_SYNC_TIMEOUT),
102            ignore_timeout_on_first_sync: false,
103            token: SyncToken::default(),
104            full_state: false,
105            set_presence: PresenceState::Online,
106        }
107    }
108
109    /// Set the sync token.
110    ///
111    /// # Arguments
112    ///
113    /// * `token` - The sync token that should be used for the sync call.
114    #[must_use]
115    pub fn token(mut self, token: impl Into<SyncToken>) -> Self {
116        self.token = token.into();
117        self
118    }
119
120    /// Set the maximum time the server can wait, in milliseconds, before
121    /// responding to the sync request.
122    ///
123    /// # Arguments
124    ///
125    /// * `timeout` - The time the server is allowed to wait.
126    #[must_use]
127    pub fn timeout(mut self, timeout: Duration) -> Self {
128        self.timeout = Some(timeout);
129        self
130    }
131
132    /// Whether to ignore the `timeout` the first time that the `/sync` endpoint
133    /// is called.
134    ///
135    /// If there is no new data to show, the server will wait until the end of
136    /// `timeout` before returning a response. It can be an undesirable
137    /// behavior when starting a client and informing the user that we are
138    /// "catching up" while waiting for the first response.
139    ///
140    /// By not setting a `timeout` on the first request to `/sync`, the
141    /// homeserver should reply immediately, whether the response is empty or
142    /// not.
143    ///
144    /// Note that this setting is ignored when calling [`Client::sync_once()`],
145    /// because there is no loop happening.
146    ///
147    /// # Arguments
148    ///
149    /// * `ignore` - Whether to ignore the `timeout` the first time that the
150    ///   `/sync` endpoint is called.
151    ///
152    /// [`Client::sync_once()`]: crate::Client::sync_once
153    #[must_use]
154    pub fn ignore_timeout_on_first_sync(mut self, ignore: bool) -> Self {
155        self.ignore_timeout_on_first_sync = ignore;
156        self
157    }
158
159    /// Set the sync filter.
160    /// It can be either the filter ID, or the definition for the filter.
161    ///
162    /// # Arguments
163    ///
164    /// * `filter` - The filter configuration that should be used for the sync
165    ///   call.
166    #[must_use]
167    pub fn filter(mut self, filter: sync_events::v3::Filter) -> Self {
168        self.filter = Some(Box::new(filter));
169        self
170    }
171
172    /// Should the server return the full state from the start of the timeline.
173    ///
174    /// This does nothing if no sync token is set.
175    ///
176    /// # Arguments
177    /// * `full_state` - A boolean deciding if the server should return the full
178    ///   state or not.
179    #[must_use]
180    pub fn full_state(mut self, full_state: bool) -> Self {
181        self.full_state = full_state;
182        self
183    }
184
185    /// Set the presence state
186    ///
187    /// `PresenceState::Online` - The client is marked as being online. This is
188    /// the default preset.
189    ///
190    /// `PresenceState::Offline` - The client is not marked as being online.
191    ///
192    /// `PresenceState::Unavailable` - The client is marked as being idle.
193    ///
194    /// # Arguments
195    /// * `set_presence` - The `PresenceState` that the server should set for
196    ///   the client.
197    #[must_use]
198    pub fn set_presence(mut self, presence: PresenceState) -> Self {
199        self.set_presence = presence;
200        self
201    }
202}
matrix_sdk/config/sync.rs

matrix_sdk/config/
sync.rs
