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/// Settings for a sync call.
23#[derive(Clone)]
24pub struct SyncSettings {
25    // Filter is pretty big at 1000 bytes, box it to reduce stack size
26    pub(crate) filter: Option<Box<sync_events::v3::Filter>>,
27    pub(crate) timeout: Option<Duration>,
28    pub(crate) ignore_timeout_on_first_sync: bool,
29    pub(crate) token: Option<String>,
30    pub(crate) full_state: bool,
31    pub(crate) set_presence: PresenceState,
32}
33
34impl Default for SyncSettings {
35    fn default() -> Self {
36        Self::new()
37    }
38}
39
40#[cfg(not(tarpaulin_include))]
41impl fmt::Debug for SyncSettings {
42    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
43        let Self {
44            filter,
45            timeout,
46            ignore_timeout_on_first_sync,
47            token: _,
48            full_state,
49            set_presence,
50        } = self;
51        f.debug_struct("SyncSettings")
52            .maybe_field("filter", filter)
53            .maybe_field("timeout", timeout)
54            .field("ignore_timeout_on_first_sync", ignore_timeout_on_first_sync)
55            .field("full_state", full_state)
56            .field("set_presence", set_presence)
57            .finish()
58    }
59}
60
61impl SyncSettings {
62    /// Create new default sync settings.
63    #[must_use]
64    pub fn new() -> Self {
65        Self {
66            filter: None,
67            timeout: Some(DEFAULT_SYNC_TIMEOUT),
68            ignore_timeout_on_first_sync: false,
69            token: None,
70            full_state: false,
71            set_presence: PresenceState::Online,
72        }
73    }
74
75    /// Set the sync token.
76    ///
77    /// # Arguments
78    ///
79    /// * `token` - The sync token that should be used for the sync call.
80    #[must_use]
81    pub fn token(mut self, token: impl Into<String>) -> Self {
82        self.token = Some(token.into());
83        self
84    }
85
86    /// Set the maximum time the server can wait, in milliseconds, before
87    /// responding to the sync request.
88    ///
89    /// # Arguments
90    ///
91    /// * `timeout` - The time the server is allowed to wait.
92    #[must_use]
93    pub fn timeout(mut self, timeout: Duration) -> Self {
94        self.timeout = Some(timeout);
95        self
96    }
97
98    /// Whether to ignore the `timeout` the first time that the `/sync` endpoint
99    /// is called.
100    ///
101    /// If there is no new data to show, the server will wait until the end of
102    /// `timeout` before returning a response. It can be an undesirable
103    /// behavior when starting a client and informing the user that we are
104    /// "catching up" while waiting for the first response.
105    ///
106    /// By not setting a `timeout` on the first request to `/sync`, the
107    /// homeserver should reply immediately, whether the response is empty or
108    /// not.
109    ///
110    /// Note that this setting is ignored when calling [`Client::sync_once()`],
111    /// because there is no loop happening.
112    ///
113    /// # Arguments
114    ///
115    /// * `ignore` - Whether to ignore the `timeout` the first time that the
116    ///   `/sync` endpoint is called.
117    ///
118    /// [`Client::sync_once()`]: crate::Client::sync_once
119    #[must_use]
120    pub fn ignore_timeout_on_first_sync(mut self, ignore: bool) -> Self {
121        self.ignore_timeout_on_first_sync = ignore;
122        self
123    }
124
125    /// Set the sync filter.
126    /// It can be either the filter ID, or the definition for the filter.
127    ///
128    /// # Arguments
129    ///
130    /// * `filter` - The filter configuration that should be used for the sync
131    ///   call.
132    #[must_use]
133    pub fn filter(mut self, filter: sync_events::v3::Filter) -> Self {
134        self.filter = Some(Box::new(filter));
135        self
136    }
137
138    /// Should the server return the full state from the start of the timeline.
139    ///
140    /// This does nothing if no sync token is set.
141    ///
142    /// # Arguments
143    /// * `full_state` - A boolean deciding if the server should return the full
144    ///   state or not.
145    #[must_use]
146    pub fn full_state(mut self, full_state: bool) -> Self {
147        self.full_state = full_state;
148        self
149    }
150
151    /// Set the presence state
152    ///
153    /// `PresenceState::Online` - The client is marked as being online. This is
154    /// the default preset.
155    ///
156    /// `PresenceState::Offline` - The client is not marked as being online.
157    ///
158    /// `PresenceState::Unavailable` - The client is marked as being idle.
159    ///
160    /// # Arguments
161    /// * `set_presence` - The `PresenceState` that the server should set for
162    ///   the client.
163    #[must_use]
164    pub fn set_presence(mut self, presence: PresenceState) -> Self {
165        self.set_presence = presence;
166        self
167    }
168}
matrix_sdk/config/sync.rs

matrix_sdk/config/
sync.rs
