tuwunel_core/config/cache.rs
1//! Configures cache capacities and space hierarchy retention.
2//!
3//! Capacity settings cover RocksDB block caches and the in-memory state cache.
4//! Space hierarchy settings bound how long cached room summaries remain valid.
5
6use serde::Deserialize;
7use tuwunel_macros::config_example_generator;
8
9use super::parallelism_scaled_u32;
10
11/// Cache sizes
12///
13/// Sizes the RocksDB block caches reserved for specific database columns,
14/// and the in-memory room state cache (`stateinfo_capacity`). Capacities
15/// count entries, not bytes. Most columns without a key here share one
16/// cache carved from `rocksdb.cache_capacity_mb`. Sizes are fixed at
17/// startup.
18///
19/// Tips:
20/// - `capacity_modifier` also scales `rocksdb.write_buffer_capacity_mb`,
21/// but not `rocksdb.cache_capacity_mb`.
22#[expect(rustdoc::broken_intra_doc_links, rustdoc::bare_urls)]
23#[derive(Clone, Copy, Debug, Deserialize)]
24#[config_example_generator(
25 filename = "tuwunel-example.toml",
26 section = "global.cache",
27 group = "true",
28 ignore = "space_hierarchy"
29)]
30pub struct Cache {
31 /// Multiplies cache capacities by a floating-point factor.
32 ///
33 /// Increase this value to use spare memory for performance, or reduce it
34 /// when memory is limited. Individual capacities such as
35 /// `cache.auth_chain_capacity` scale with the CPU core count by default.
36 ///
37 /// default: 1.0
38 /// legacy: cache_capacity_modifier conduit_cache_capacity_modifier
39 #[serde(
40 default = "default_capacity_modifier",
41 alias = "conduit_cache_capacity_modifier"
42 )]
43 pub capacity_modifier: f64,
44
45 /// Maximum number of entries in the RocksDB block cache shared by the
46 /// `pduid_pdu` and `eventid_outlierpdu` column families: a PDU's full
47 /// body, keyed by its PDU ID, and the same body keyed by event ID when
48 /// the PDU is an outlier.
49 ///
50 /// This is an entry count, not a byte size. The cache's actual capacity
51 /// in bytes is this value multiplied by an internal per-column-family
52 /// key+value size estimate, then multiplied by `cache.capacity_modifier`.
53 /// Scaled by your CPU core count by default; see
54 /// `cache.capacity_modifier` to scale this along with the other
55 /// individual LRU caches at once.
56 ///
57 /// default: varies by system
58 /// legacy: pdu_cache_capacity
59 #[serde(default = "default_pdu_capacity")]
60 pub pdu_capacity: u32,
61
62 /// Maximum number of entries in the RocksDB block cache for the
63 /// `authchainkey_authchain` column family: a room event's full auth
64 /// chain, keyed by the set of events the chain was derived from.
65 ///
66 /// Same entry-count semantics as `cache.pdu_capacity` above; see there
67 /// for how this becomes a byte capacity and how
68 /// `cache.capacity_modifier` applies.
69 ///
70 /// default: varies by system
71 /// legacy: auth_chain_cache_capacity
72 #[serde(default = "default_auth_chain_capacity")]
73 pub auth_chain_capacity: u32,
74
75 /// Maximum number of entries in the RocksDB block cache for the
76 /// `shorteventid_eventid` column family: an event's full event ID,
77 /// looked up from its short event ID.
78 ///
79 /// Same entry-count semantics as `cache.pdu_capacity`.
80 ///
81 /// default: varies by system
82 /// legacy: shorteventid_cache_capacity
83 #[serde(default = "default_shorteventid_capacity")]
84 pub shorteventid_capacity: u32,
85
86 /// Maximum number of entries in the RocksDB block cache for the
87 /// `eventid_shorteventid` column family: an event's short event ID,
88 /// looked up from its full event ID.
89 ///
90 /// This is the reverse lookup of `cache.shorteventid_capacity`.
91 /// Same entry-count semantics as `cache.pdu_capacity`.
92 ///
93 /// default: varies by system
94 /// legacy: eventidshort_cache_capacity
95 #[serde(default = "default_eventidshort_capacity")]
96 pub eventidshort_capacity: u32,
97
98 /// Maximum number of entries in the RocksDB block cache for the
99 /// `eventid_pduid` column family: an event's PDU ID, looked up from its
100 /// full event ID.
101 ///
102 /// Same entry-count semantics as `cache.pdu_capacity`.
103 ///
104 /// default: varies by system
105 /// legacy: eventid_pdu_cache_capacity
106 #[serde(default = "default_eventid_pdu_capacity")]
107 pub eventid_pdu_capacity: u32,
108
109 /// Maximum number of entries in the RocksDB block cache for the
110 /// `eventid_backoff` column family: the recent fetch, auth, upgrade, and
111 /// delivery outcomes an event is rate-gated against, keyed by federation
112 /// step, event ID, and time bucket.
113 ///
114 /// Same entry-count semantics as `cache.pdu_capacity`. A server working
115 /// through a large missing-ancestry gap reads this column heavily.
116 ///
117 /// default: varies by system
118 /// legacy: eventid_backoff_cache_capacity
119 #[serde(default = "default_eventid_backoff_capacity")]
120 pub eventid_backoff_capacity: u32,
121
122 /// Maximum number of entries in the RocksDB block cache for the
123 /// `shortstatekey_statekey` column family: a state event's full state
124 /// key, looked up from its short state key.
125 ///
126 /// Same entry-count semantics as `cache.pdu_capacity`.
127 ///
128 /// default: varies by system
129 /// legacy: shortstatekey_cache_capacity
130 #[serde(default = "default_shortstatekey_capacity")]
131 pub shortstatekey_capacity: u32,
132
133 /// Maximum number of entries in the RocksDB block cache for the
134 /// `statekey_shortstatekey` column family: a state event's short state
135 /// key, looked up from its full state key.
136 ///
137 /// This is the reverse lookup of `cache.shortstatekey_capacity`.
138 /// Same entry-count semantics as `cache.pdu_capacity`.
139 ///
140 /// default: varies by system
141 /// legacy: statekeyshort_cache_capacity
142 #[serde(default = "default_statekeyshort_capacity")]
143 pub statekeyshort_capacity: u32,
144
145 /// Maximum number of entries in the RocksDB block cache for the
146 /// `servernameevent_data` column family: outbound federation events
147 /// (PDUs and EDUs) queued for delivery, keyed by destination server
148 /// name.
149 ///
150 /// Same entry-count semantics as `cache.pdu_capacity`.
151 ///
152 /// default: varies by system
153 /// legacy: servernameevent_data_cache_capacity
154 #[serde(default = "default_servernameevent_data_capacity")]
155 pub servernameevent_data_capacity: u32,
156
157 /// Maximum number of entries in the RocksDB block cache for the
158 /// `mediaid_lazycontent` column family: preview images staged by the URL
159 /// preview fetcher, keyed by media ID, until a download promotes the row.
160 ///
161 /// Same entry-count semantics as `cache.pdu_capacity`, against a modal
162 /// 256 KiB entry. Staged rows are read once and deleted at promotion, so
163 /// this mostly holds index blocks, and a single outsized preview can
164 /// exceed the whole pool.
165 ///
166 /// default: 128
167 /// legacy: mediaid_lazycontent_cache_capacity
168 #[serde(default = "default_mediaid_lazycontent_capacity")]
169 pub mediaid_lazycontent_capacity: u32,
170
171 /// Maximum number of entries in the RocksDB block cache pool shared by the
172 /// `servername_destination` and `servername_override` column families: a
173 /// remote server's resolved federation destination, keyed by server name,
174 /// and the address override for a resolved hostname.
175 ///
176 /// Same entry-count semantics as `cache.pdu_capacity`, counted across the
177 /// pool rather than per column.
178 ///
179 /// default: varies by system
180 /// legacy: resolver_cache_capacity
181 #[serde(default = "default_resolver_capacity")]
182 pub resolver_capacity: u32,
183
184 /// Maximum number of entries in the RocksDB block cache for the
185 /// `servername_status` column family: a remote server's recent
186 /// reachability outcome, keyed by server name and time bucket.
187 ///
188 /// Same entry-count semantics as `cache.pdu_capacity`.
189 ///
190 /// default: varies by system
191 /// legacy: servername_status_cache_capacity
192 #[serde(default = "default_servername_status_capacity")]
193 pub servername_status_capacity: u32,
194
195 /// Maximum number of entries in the in-memory LRU cache of decompressed
196 /// room state (a list of short state-info entries per state hash), used
197 /// by the state compressor to avoid re-walking
198 /// `shortstatehash_statediff` on every lookup.
199 ///
200 /// Unlike the other caches on this page, this one is not backed by
201 /// RocksDB: it is a plain in-process cache sized directly in entries,
202 /// with no per-entry byte-size conversion. `cache.capacity_modifier`
203 /// still applies to it.
204 ///
205 /// default: varies by system
206 /// legacy: stateinfo_cache_capacity
207 #[serde(default = "default_stateinfo_capacity")]
208 pub stateinfo_capacity: u32,
209
210 /// Settings for cache space hierarchy.
211 ///
212 /// display: section
213 #[serde(default)]
214 pub space_hierarchy: SpaceHierarchy,
215}
216
217/// Space hierarchy cache lifetime
218///
219/// How long a room summary used to answer space hierarchy requests is
220/// cached before it is rebuilt or fetched again. Each entry expires at a
221/// random time between `ttl_min` and `ttl_max` seconds, which spreads
222/// refreshes out. Both keys apply on reload.
223///
224/// Tips:
225/// - `ttl_min` must be below `ttl_max`. Startup and reload refuse an equal
226/// or inverted pair.
227#[expect(rustdoc::broken_intra_doc_links, rustdoc::bare_urls)]
228#[derive(Clone, Copy, Debug, Deserialize)]
229#[config_example_generator(
230 filename = "tuwunel-example.toml",
231 section = "global.cache.space_hierarchy",
232 group = "true"
233)]
234pub struct SpaceHierarchy {
235 /// Minimum time-to-live in seconds for room summary entries in the spaces
236 /// cache.
237 ///
238 /// reloadable: yes
239 /// default: 10800
240 /// legacy: spacehierarchy_cache_ttl_min
241 #[serde(default = "default_ttl_min")]
242 pub ttl_min: u64,
243
244 /// Maximum time-to-live in seconds for room summary entries in the spaces
245 /// cache.
246 ///
247 /// reloadable: yes
248 /// default: 64800
249 /// legacy: spacehierarchy_cache_ttl_max
250 #[serde(default = "default_ttl_max")]
251 pub ttl_max: u64,
252}
253
254impl Default for Cache {
255 fn default() -> Self {
256 Self {
257 capacity_modifier: default_capacity_modifier(),
258 pdu_capacity: default_pdu_capacity(),
259 auth_chain_capacity: default_auth_chain_capacity(),
260 shorteventid_capacity: default_shorteventid_capacity(),
261 eventidshort_capacity: default_eventidshort_capacity(),
262 eventid_pdu_capacity: default_eventid_pdu_capacity(),
263 eventid_backoff_capacity: default_eventid_backoff_capacity(),
264 shortstatekey_capacity: default_shortstatekey_capacity(),
265 statekeyshort_capacity: default_statekeyshort_capacity(),
266 servernameevent_data_capacity: default_servernameevent_data_capacity(),
267 mediaid_lazycontent_capacity: default_mediaid_lazycontent_capacity(),
268 resolver_capacity: default_resolver_capacity(),
269 servername_status_capacity: default_servername_status_capacity(),
270 stateinfo_capacity: default_stateinfo_capacity(),
271 space_hierarchy: SpaceHierarchy::default(),
272 }
273 }
274}
275
276impl Default for SpaceHierarchy {
277 fn default() -> Self {
278 Self {
279 ttl_min: default_ttl_min(),
280 ttl_max: default_ttl_max(),
281 }
282 }
283}
284
285fn default_capacity_modifier() -> f64 { 1.0 }
286
287fn default_pdu_capacity() -> u32 { parallelism_scaled_u32(10_000).saturating_add(100_000) }
288
289fn default_auth_chain_capacity() -> u32 {
290 parallelism_scaled_u32(250_000).saturating_add(750_000)
291}
292
293fn default_shorteventid_capacity() -> u32 {
294 parallelism_scaled_u32(200_000).saturating_add(400_000)
295}
296
297fn default_eventidshort_capacity() -> u32 {
298 parallelism_scaled_u32(100_000).saturating_add(400_000)
299}
300
301fn default_eventid_pdu_capacity() -> u32 {
302 parallelism_scaled_u32(100_000).saturating_add(400_000)
303}
304
305fn default_eventid_backoff_capacity() -> u32 {
306 parallelism_scaled_u32(4_000).saturating_add(200_000)
307}
308
309fn default_shortstatekey_capacity() -> u32 {
310 parallelism_scaled_u32(4_000).saturating_add(40_000)
311}
312
313fn default_statekeyshort_capacity() -> u32 {
314 parallelism_scaled_u32(4_000).saturating_add(40_000)
315}
316
317fn default_servernameevent_data_capacity() -> u32 {
318 parallelism_scaled_u32(50_000).saturating_add(200_000)
319}
320
321fn default_mediaid_lazycontent_capacity() -> u32 { 128 }
322
323fn default_resolver_capacity() -> u32 { parallelism_scaled_u32(10_000).saturating_add(100_000) }
324
325fn default_servername_status_capacity() -> u32 {
326 parallelism_scaled_u32(15_000).saturating_add(200_000)
327}
328
329fn default_stateinfo_capacity() -> u32 { parallelism_scaled_u32(100) }
330
331fn default_ttl_min() -> u64 { 60 * 60 * 3 }
332
333fn default_ttl_max() -> u64 { 60 * 60 * 18 }