tuwunel_core/config/presence.rs
1//! Configures local and federated presence.
2//!
3//! Incoming and outgoing updates have separate controls. Idle and offline
4//! timers determine how inactivity changes presence.
5
6use serde::Deserialize;
7use tuwunel_macros::config_example_generator;
8
9use super::true_fn;
10
11/// Presence
12///
13/// Controls online, idle and offline status for local users and how it is
14/// exchanged with other servers. Presence is on by default, both locally and
15/// over federation, where a local user's status goes only to servers that
16/// share a room with them.
17///
18/// Tips:
19/// - To turn presence off, set `allow_local`, `allow_incoming` and
20/// `allow_outgoing` all to false; startup and reload refuse
21/// `allow_outgoing` without `allow_local`.
22/// - With `allow_local` off, sync and other client activity stop refreshing
23/// each device's last-seen time and IP address.
24/// - To keep presence between local users but cut its federation traffic,
25/// turn off `allow_incoming` and `allow_outgoing` instead.
26#[expect(rustdoc::broken_intra_doc_links, rustdoc::bare_urls)]
27#[derive(Clone, Copy, Debug, Deserialize)]
28#[config_example_generator(
29 filename = "tuwunel-example.toml",
30 section = "global.presence",
31 group = "true"
32)]
33pub struct Presence {
34 /// Allows local presence updates and requests.
35 ///
36 /// This must be enabled when using `presence.allow_outgoing`.
37 ///
38 /// reloadable: yes
39 /// legacy: allow_local_presence
40 #[serde(default = "true_fn")]
41 pub allow_local: bool,
42
43 /// Allows incoming federated presence updates and requests.
44 ///
45 /// This receives updates but sends none unless `presence.allow_outgoing`
46 /// is enabled.
47 ///
48 /// reloadable: yes
49 /// legacy: allow_incoming_presence
50 #[serde(default = "true_fn")]
51 pub allow_incoming: bool,
52
53 /// Allows outgoing federated presence updates and requests.
54 ///
55 /// This sends updates but receives none unless `presence.allow_incoming`
56 /// is enabled, and it requires `presence.allow_local`.
57 ///
58 /// reloadable: yes
59 /// legacy: allow_outgoing_presence
60 #[serde(default = "true_fn")]
61 pub allow_outgoing: bool,
62
63 /// Sets the seconds without presence updates before a user becomes idle,
64 /// defaulting to five minutes.
65 ///
66 /// default: 300
67 /// legacy: presence_idle_timeout_s
68 #[serde(default = "default_idle_timeout_s")]
69 pub idle_timeout_s: u64,
70
71 /// Sets the seconds without presence updates before a user becomes
72 /// offline, defaulting to thirty minutes.
73 ///
74 /// default: 1800
75 /// legacy: presence_offline_timeout_s
76 #[serde(default = "default_offline_timeout_s")]
77 pub offline_timeout_s: u64,
78
79 /// Enables the presence idle timer for remote users.
80 ///
81 /// Disabling it can reduce resource use on servers participating in many
82 /// large rooms or with limited resources. Some remote users may then show
83 /// incorrect presence states, such as remaining online indefinitely.
84 ///
85 /// legacy: presence_timeout_remote_users
86 #[serde(default = "true_fn")]
87 pub timeout_remote_users: bool,
88}
89
90impl Default for Presence {
91 fn default() -> Self {
92 Self {
93 allow_local: true_fn(),
94 allow_incoming: true_fn(),
95 allow_outgoing: true_fn(),
96 idle_timeout_s: default_idle_timeout_s(),
97 offline_timeout_s: default_offline_timeout_s(),
98 timeout_remote_users: true_fn(),
99 }
100 }
101}
102
103fn default_idle_timeout_s() -> u64 { 5 * 60 }
104
105fn default_offline_timeout_s() -> u64 { 30 * 60 }