Skip to main content

tuwunel_core/config/
client.rs

1//! Configures client-facing protocol behavior.
2//!
3//! Sync settings bound long-polling timeouts. Room-summary controls select
4//! sync calculations.
5
6use serde::Deserialize;
7use tuwunel_macros::config_example_generator;
8
9use super::true_fn;
10
11/// Client API
12///
13/// Groups settings for how the server answers client requests.
14/// `[global.client.sync]` bounds sync long polling and turns room hero
15/// calculation on or off.
16#[expect(rustdoc::broken_intra_doc_links, rustdoc::bare_urls)]
17#[derive(Clone, Copy, Debug, Deserialize, Default)]
18#[config_example_generator(
19	filename = "tuwunel-example.toml",
20	section = "global.client",
21	group = "true",
22	ignore = "sync"
23)]
24pub struct Client {
25	/// Settings for client sync.
26	///
27	/// display: section
28	#[serde(default)]
29	pub sync: Sync,
30}
31
32/// Client sync long polling
33///
34/// Bounds how long a client's sync request may wait for new events before
35/// the server answers anyway, and whether sync computes room heroes.
36///
37/// Tips:
38/// - Sliding sync honors only `timeout_max`; `timeout_min` and
39///   `timeout_default` apply to legacy `/sync` and to `/events`.
40/// - Keep `timeout_max` (milliseconds) below `request_timeout` in
41///   `[global.http]` (seconds) and below the read timeout of any reverse
42///   proxy in front of the server, or long polls fail instead of returning.
43#[expect(rustdoc::broken_intra_doc_links, rustdoc::bare_urls)]
44#[derive(Clone, Copy, Debug, Deserialize)]
45#[config_example_generator(
46	filename = "tuwunel-example.toml",
47	section = "global.client.sync",
48	group = "true"
49)]
50pub struct Sync {
51	/// Sets the minimum requested timeout for long-polling sync.
52	///
53	/// Smaller client requests are clamped up to this value.
54	///
55	/// reloadable: yes
56	/// default: 5000
57	/// legacy: client_sync_timeout_min
58	#[serde(default = "default_timeout_min")]
59	pub timeout_min: u64,
60
61	/// Sets the long-polling sync timeout when the client supplies none in its
62	/// query string.
63	///
64	/// reloadable: yes
65	/// default: 30000
66	/// legacy: client_sync_timeout_default
67	#[serde(default = "default_timeout_default")]
68	pub timeout_default: u64,
69
70	/// Sets the maximum requested timeout for long-polling sync.
71	///
72	/// Larger client requests are clamped down to this value.
73	///
74	/// reloadable: yes
75	/// default: 90000
76	/// legacy: client_sync_timeout_max
77	#[serde(default = "default_timeout_max")]
78	pub timeout_max: u64,
79
80	/// Calculates room heroes in sliding and legacy client sync.
81	///
82	/// The Matrix specification requires this calculation, so clients may
83	/// malfunction when it is disabled. Disabling is intended for custom
84	/// software minimizing unused resources; otherwise the savings are
85	/// negligible.
86	///
87	/// reloadable: yes
88	/// legacy: calculate_heroes
89	#[serde(default = "true_fn")]
90	pub calculate_heroes: bool,
91}
92
93impl Default for Sync {
94	fn default() -> Self {
95		Self {
96			timeout_min: default_timeout_min(),
97			timeout_default: default_timeout_default(),
98			timeout_max: default_timeout_max(),
99			calculate_heroes: true_fn(),
100		}
101	}
102}
103
104fn default_timeout_min() -> u64 { 5000 }
105
106fn default_timeout_default() -> u64 { 30000 }
107
108fn default_timeout_max() -> u64 { 90000 }