Skip to main content

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 }