Skip to main content

tuwunel_database/engine/
cf_opts.rs

1use rocksdb::{
2	BlockBasedIndexType, BlockBasedOptions, BlockBasedPinningTier, Cache,
3	DBCompressionType as CompressionType, DataBlockIndexType, FifoCompactOptions,
4	LruCacheOptions, Options, SliceTransform, UniversalCompactOptions,
5	UniversalCompactionStopStyle,
6};
7use tuwunel_core::{Config, Result, err, utils::math::Expected};
8
9use super::{
10	context::{ColCache, ColCaches, SHARED_POOL},
11	descriptor::{AccessPattern, CacheDisp, Descriptor},
12};
13use crate::{Context, util::map_err};
14
15pub(super) const SENTINEL_COMPRESSION_LEVEL: i32 = 32767;
16
17/// Adjust options for the specific column by name. Provide the result of
18/// db_options() as the argument to this function and use the return value in
19/// the arguments to open the specific column.
20pub(crate) fn cf_options(ctx: &Context, opts: Options, desc: &Descriptor) -> Result<Options> {
21	let cache = get_cache(ctx, desc);
22	let config = &ctx.server.config;
23	descriptor_cf_options(opts, *desc, config, cache.as_ref())
24}
25
26fn descriptor_cf_options(
27	mut opts: Options,
28	mut desc: Descriptor,
29	config: &Config,
30	cache: Option<&Cache>,
31) -> Result<Options> {
32	set_compression(&mut desc, config);
33	set_preview_retention(&mut desc, config.media.url_preview.cache_ttl);
34	set_table_options(&mut opts, &desc, cache)?;
35
36	opts.set_min_write_buffer_number(1);
37	opts.set_max_write_buffer_number(2);
38	opts.set_write_buffer_size(desc.write_size);
39
40	opts.set_target_file_size_base(desc.file_size);
41	opts.set_target_file_size_multiplier(desc.file_shape);
42
43	opts.set_max_compaction_bytes(desc.compaction_size);
44	opts.set_level_zero_file_num_compaction_trigger(desc.level0_width);
45	opts.set_level_compaction_dynamic_level_bytes(false);
46	opts.set_ttl(desc.ttl);
47
48	opts.set_max_bytes_for_level_base(desc.level_size);
49	opts.set_max_bytes_for_level_multiplier(1.0);
50	opts.set_max_bytes_for_level_multiplier_additional(&desc.level_shape);
51
52	opts.set_disable_auto_compactions(desc.ignored);
53	opts.set_compaction_style(desc.compaction);
54	opts.set_compaction_pri(desc.compaction_pri);
55	opts.set_universal_compaction_options(&uc_options(&desc));
56	opts.set_fifo_compaction_options(&fifo_options(&desc));
57
58	let compression_shape: Vec<_> = desc
59		.compression_shape
60		.into_iter()
61		.map(|val| (val > 0).then_some(desc.compression))
62		.map(|val| val.unwrap_or(CompressionType::None))
63		.collect();
64
65	opts.set_compression_type(desc.compression);
66	opts.set_compression_per_level(compression_shape.as_slice());
67	opts.set_compression_options(-14, desc.compression_level, 0, 0); // -14 w_bits used by zlib.
68	if let Some(&bottommost_level) = desc.bottommost_level.as_ref() {
69		opts.set_bottommost_compression_type(desc.compression);
70		opts.set_bottommost_zstd_max_train_bytes(0, true);
71		opts.set_bottommost_compression_options(
72			-14, // -14 w_bits is only read by zlib.
73			bottommost_level,
74			0,
75			0,
76			true,
77		);
78	}
79
80	if desc.prefix_size > 0 {
81		opts.set_prefix_extractor(SliceTransform::create_fixed_prefix(desc.prefix_size));
82	}
83
84	opts.set_options_from_string("{{arena_block_size=2097152;}}")
85		.map_err(map_err)?;
86
87	#[cfg(debug_assertions)]
88	opts.set_options_from_string(
89		"{{paranoid_checks=true;paranoid_file_checks=true;force_consistency_checks=true;\
90		 verify_sst_unique_id_in_manifest=true;}}",
91	)
92	.map_err(map_err)?;
93
94	Ok(opts)
95}
96
97fn set_table_options(opts: &mut Options, desc: &Descriptor, cache: Option<&Cache>) -> Result {
98	let mut table = table_options(desc, cache.is_some());
99
100	if let Some(cache) = cache {
101		table.set_block_cache(cache);
102	} else {
103		table.disable_cache();
104	}
105
106	let prepopulate = if desc.write_to_cache { "kFlushOnly" } else { "kDisable" };
107
108	let string = format!(
109		"{{block_based_table_factory={{num_file_reads_for_auto_readahead={0};\
110		 max_auto_readahead_size={1};initial_auto_readahead_size={2};\
111		 enable_index_compression={3};prepopulate_block_cache={4}}}}}",
112		desc.auto_readahead_thresh,
113		desc.auto_readahead_max,
114		desc.auto_readahead_init,
115		desc.compressed_index,
116		prepopulate,
117	);
118
119	// The options string amends the installed table factory, so install it first.
120	opts.set_block_based_table_factory(&table);
121
122	opts.set_options_from_string(&string)
123		.map_err(map_err)?;
124
125	Ok(())
126}
127
128fn set_compression(desc: &mut Descriptor, config: &Config) {
129	// A column opting out of compression is never overridden by the config.
130	if desc.compression == CompressionType::None {
131		return;
132	}
133
134	desc.compression = match config.rocksdb.compression_algo.as_ref() {
135		| "snappy" => CompressionType::Snappy,
136		| "zlib" => CompressionType::Zlib,
137		| "bz2" => CompressionType::Bz2,
138		| "lz4" => CompressionType::Lz4,
139		| "lz4hc" => CompressionType::Lz4hc,
140		| "none" => CompressionType::None,
141		| _ => CompressionType::Zstd,
142	};
143
144	let can_override_level = config.rocksdb.compression_level == SENTINEL_COMPRESSION_LEVEL
145		&& desc.compression == CompressionType::Zstd;
146
147	if !can_override_level {
148		desc.compression_level = config.rocksdb.compression_level;
149	}
150
151	let can_override_bottom = config.rocksdb.bottommost_compression_level
152		== SENTINEL_COMPRESSION_LEVEL
153		&& desc.compression == CompressionType::Zstd;
154
155	if !can_override_bottom {
156		desc.bottommost_level = Some(config.rocksdb.bottommost_compression_level);
157	}
158
159	if !config.rocksdb.bottommost_compression {
160		desc.bottommost_level = None;
161	}
162}
163
164/// Raise the preview columns' FIFO ttl to the configured preview lifetime
165/// when it exceeds their floor.
166///
167/// A preview evicted before it expires is fetched from the origin again, and
168/// one whose lazy media mapping went with it serves an `mxc://` URI that no
169/// longer resolves, so the configured lifetime raises both columns. Only the
170/// time arm moves: `limit_size` still caps each column, and evicts oldest
171/// first once reached.
172pub(super) fn set_preview_retention(desc: &mut Descriptor, configured: u64) {
173	if matches!(desc.name, "url_preview" | "mediaid_lazy") {
174		desc.ttl = desc.ttl.max(configured);
175	}
176}
177
178fn fifo_options(desc: &Descriptor) -> FifoCompactOptions {
179	let mut opts = FifoCompactOptions::default();
180	opts.set_max_table_files_size(desc.limit_size);
181	opts.set_allow_compaction(true);
182
183	opts
184}
185
186fn uc_options(desc: &Descriptor) -> UniversalCompactOptions {
187	let mut opts = UniversalCompactOptions::default();
188	opts.set_stop_style(UniversalCompactionStopStyle::Total);
189	opts.set_min_merge_width(desc.merge_width.0);
190	opts.set_max_merge_width(desc.merge_width.1);
191	opts.set_max_size_amplification_percent(10000);
192	opts.set_compression_size_percent(-1);
193	opts.set_size_ratio(1);
194
195	opts
196}
197
198fn table_options(desc: &Descriptor, has_cache: bool) -> BlockBasedOptions {
199	let mut opts = BlockBasedOptions::default();
200
201	opts.set_block_size(desc.block_size);
202	opts.set_metadata_block_size(desc.index_size);
203
204	opts.set_cache_index_and_filter_blocks(has_cache);
205	opts.set_pin_top_level_index_and_filter(false);
206	opts.set_pin_l0_filter_and_index_blocks_in_cache(false);
207	opts.set_partition_pinning_tier(BlockBasedPinningTier::None);
208	opts.set_unpartitioned_pinning_tier(BlockBasedPinningTier::None);
209	opts.set_top_level_index_pinning_tier(BlockBasedPinningTier::None);
210
211	opts.set_partition_filters(true);
212	opts.set_use_delta_encoding(false);
213
214	opts.set_index_type(match desc.access_pattern {
215		| AccessPattern::ShortScan | AccessPattern::FromScan =>
216			BlockBasedIndexType::TwoLevelIndexSearch,
217		| AccessPattern::RandomScan | AccessPattern::FastScan =>
218			BlockBasedIndexType::BinarySearch,
219		| AccessPattern::PointQuery | AccessPattern::PrefixScan =>
220			BlockBasedIndexType::HashSearch,
221	});
222
223	opts.set_data_block_index_type(match desc.access_pattern {
224		| AccessPattern::PrefixScan | AccessPattern::FromScan | AccessPattern::FastScan =>
225			DataBlockIndexType::BinarySearch,
226		| AccessPattern::PointQuery | AccessPattern::ShortScan | AccessPattern::RandomScan =>
227			DataBlockIndexType::BinaryAndHash,
228	});
229
230	opts
231}
232
233fn get_cache(ctx: &Context, desc: &Descriptor) -> Option<Cache> {
234	if desc.dropped {
235		return None;
236	}
237
238	// Capacity is configured in entries, converted to bytes against the
239	// descriptor's size hints; the lookup by column name is legacy-compat.
240	let config = &ctx.server.config;
241	let cap = match desc.name {
242		| "eventid_pduid" => Some(config.cache.eventid_pdu_capacity),
243		| "eventid_shorteventid" => Some(config.cache.eventidshort_capacity),
244		| "eventid_backoff" => Some(config.cache.eventid_backoff_capacity),
245		| "shorteventid_eventid" => Some(config.cache.shorteventid_capacity),
246		| "shortstatekey_statekey" => Some(config.cache.shortstatekey_capacity),
247		| "statekey_shortstatekey" => Some(config.cache.statekeyshort_capacity),
248		| "servernameevent_data" => Some(config.cache.servernameevent_data_capacity),
249		| "servername_destination" | "servername_override" =>
250			Some(config.cache.resolver_capacity),
251		| "servername_status" => Some(config.cache.servername_status_capacity),
252		| "mediaid_lazycontent" => Some(config.cache.mediaid_lazycontent_capacity),
253		| "pduid_pdu" | "eventid_outlierpdu" => Some(config.cache.pdu_capacity),
254		| "authchainkey_authchain" => Some(config.cache.auth_chain_capacity),
255		| _ => None,
256	}
257	.map(TryInto::try_into)
258	.transpose()
259	.expect("u32 to usize");
260
261	let ent_size: usize = desc
262		.key_size_hint
263		.unwrap_or_default()
264		.expected_add(desc.val_size_hint.unwrap_or_default());
265
266	let size = match cap {
267		// Whole MiB, so reported capacities stay round and divide evenly across the shards.
268		| Some(cap) => cache_size(config, cap, ent_size).next_multiple_of(1 << 20),
269		| _ => desc.cache_size,
270	};
271
272	let shard_bits: i32 = desc
273		.cache_shards
274		.ilog2()
275		.try_into()
276		.expect("u32 to i32 conversion");
277
278	debug_assert!(shard_bits <= 10, "cache shards probably too large");
279	let mut cache_opts = LruCacheOptions::default();
280	cache_opts.set_num_shard_bits(shard_bits);
281	cache_opts.set_capacity(size);
282
283	let mut caches = ctx.col_cache.lock().expect("locked");
284	register_pool(&mut caches, desc, || Cache::new_lru_cache_opts(&cache_opts))
285}
286
287/// Returns the cache for `desc`'s pool; `build_cache` is invoked only when a
288/// new pool must be created.
289pub(crate) fn register_pool(
290	caches: &mut ColCaches,
291	desc: &Descriptor,
292	build_cache: impl FnOnce() -> Cache,
293) -> Option<Cache> {
294	match desc.cache_disp {
295		| CacheDisp::Unique if desc.cache_size == 0 => None,
296		| CacheDisp::Unique => {
297			let cache = build_cache();
298			caches.insert(desc.name, ColCache {
299				cache: cache.clone(),
300				participants: vec![desc.name],
301			});
302
303			Some(cache)
304		},
305
306		| CacheDisp::SharedWith(other) => Some(match caches.get_mut(other) {
307			| Some(pool) => {
308				pool.participants.push(desc.name);
309				pool.cache.clone()
310			},
311			| None => {
312				let new = build_cache();
313				caches.insert(desc.name, ColCache {
314					cache: new.clone(),
315					participants: vec![desc.name],
316				});
317
318				new
319			},
320		}),
321
322		| CacheDisp::Shared => {
323			let pool = caches
324				.get_mut(SHARED_POOL)
325				.expect("shared cache must already exist");
326
327			pool.participants.push(desc.name);
328			Some(pool.cache.clone())
329		},
330	}
331}
332
333pub(crate) fn cache_size(config: &Config, base_size: u32, entity_size: usize) -> usize {
334	cache_size_f64(config, f64::from(base_size), entity_size)
335}
336
337#[expect(
338	clippy::as_conversions,
339	clippy::cast_sign_loss,
340	clippy::cast_possible_truncation
341)]
342pub(crate) fn cache_size_f64(config: &Config, base_size: f64, entity_size: usize) -> usize {
343	let ents = base_size * config.cache.capacity_modifier;
344
345	(ents as usize)
346		.checked_mul(entity_size)
347		.ok_or_else(|| err!(Config("cache.capacity_modifier", "Cache size is too large.")))
348		.expect("invalid cache size")
349}