Skip to main content

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 }