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 }