From 4ff7a88df0ef9912b40b11624f4bc575748c03a3 Mon Sep 17 00:00:00 2001 From: renegadespork Date: Wed, 5 Aug 2026 15:04:29 -0700 Subject: [PATCH] docs: Add missing documentation to config parameters. --- conduwuit-example.toml | 161 ++++++++++++++++++++++++++++++++++----- src/core/config/mod.rs | 168 +++++++++++++++++++++++++++++++++++++++++ 2 files changed, 312 insertions(+), 17 deletions(-) diff --git a/conduwuit-example.toml b/conduwuit-example.toml index c761331a0..4ee4845fa 100644 --- a/conduwuit-example.toml +++ b/conduwuit-example.toml @@ -170,43 +170,136 @@ # #db_write_buffer_capacity_mb = varies by system -# This item is undocumented. Please contribute documentation for it. +# The maximum number of Persisted Data Units (PDUs) to cache. +# Accepts any 32-bit integer. +# +# PDUs are events broadcast from one homeserver to any others that have +# joined the same room (identified by Room ID). They are persisted in +# long-term storage and record the history of messages and state +# for a room. +# +# An example of a PDU would be a message or joining a room. +# +# Setting this higher might be useful if the server has a large memory +# capacity and is noticeably I/O limited. +# +# This defaults to 100,000 + (10,000 * CPU core count) # #pdu_cache_capacity = varies by system -# This item is undocumented. Please contribute documentation for it. +# The maximum number of auth chains to cache. +# Accepts any 32-bit integer. +# +# When determining is a user is authorized to send an event, +# the server will first check the auth chain cache. +# If the auth chain is not present in the cache, +# The server will reach out to the origin server for +# authorization. +# +# This defaults to 100,000 + (10,000 * CPU core count) # #auth_chain_cache_capacity = varies by system -# This item is undocumented. Please contribute documentation for it. +# Determines the cache size for eventid data references. +# Accepts any 32-bit integer. +# +# Each matrix event can be referenced in the database via either +# an eventid (string) or a shorteventid (64-bit integer). +# This caps the capacity of cached eventids referenced +# by their shorteventid. +# +# This defaults to 100,000 + (50,000 * CPU core count) # #shorteventid_cache_capacity = varies by system -# This item is undocumented. Please contribute documentation for it. +# Determines the cache size for eventid data references. +# Accepts any 32-bit integer. +# +# Each matrix event can be referenced in the database via either +# an eventid (string) or a shorteventid (64-bit integer). +# This caps the capacity of cached shorteventids referenced +# by their eventid. +# +# This defaults to 100,000 + (25,000 * CPU core count) # #eventidshort_cache_capacity = varies by system -# This item is undocumented. Please contribute documentation for it. +# Determines the cache size for pdu data references. +# Accepts any 32-bit integer. +# +# This caps the capacity of cached pdus referenced +# by their eventid. +# +# This defaults to 100,000 + (25,000 * CPU core count) # #eventid_pdu_cache_capacity = varies by system -# This item is undocumented. Please contribute documentation for it. +# Determines the cache size for state key data references. +# Accepts any 32-bit integer. +# +# State keys are used by the server to verify that a token +# from a third-party invite event was actually generated +# by the server where the room resides. +# +# These state keys can be referenced in the database via either +# a statekey (string) or a shortstatekey (64-bit integer). +# This caps the capacity of cached statekeys referenced +# by shortstatekeys. +# +# This defaults to 100,000 + (10,000 * CPU core count) # #shortstatekey_cache_capacity = varies by system -# This item is undocumented. Please contribute documentation for it. +# Determines the cache size for state key data references. +# Accepts any 32-bit integer. +# +# State keys are used by the server to verify that a token +# from a third-party invite event was actually generated +# by the server where the room resides. +# +# These state keys can be referenced in the database via either +# a statekey (string) or a shortstatekey (64-bit integer). +# This caps the capacity of cached shortstatekeys referenced +# by statekeys. +# +# This defaults to 100,000 + (10,000 * CPU core count) # #statekeyshort_cache_capacity = varies by system -# This item is undocumented. Please contribute documentation for it. +# Determines the cache size for event_data references scoped +# by server_name. +# Accepts any 32-bit integer. +# +# Event data can be referenced in the database by server name. +# This is useful if the server needs to clear all events associated +# with a particular federated server, for example. +# This caps the capacity of cached event_data referenced +# by server_name. +# +# This defaults to 500,000 + (10,000 * CPU core count) # #servernameevent_data_cache_capacity = varies by system -# This item is undocumented. Please contribute documentation for it. +# Determines the cache size for room states. +# Accepts any 32-bit integer. +# +# To ensure data integrity of room events across asynchronous +# requests from federated servers, Matrix tracks the state +# of a room using a statehash and the changes since the +# previous (parent) statehash. +# This caps the capacity of cached room state data. +# +# This defaults to 100 * CPU core count. # #stateinfo_cache_capacity = varies by system -# This item is undocumented. Please contribute documentation for it. +# Determines the cache size for spacehierarchy data. +# Accepts any 32-bit integer. +# +# Each roomid contains info on its place in the space hierarchy. +# This caps the capacity of cached spacehierarchy data. +# +# This defaults to 1,000 * CPU core count. # #roomid_spacehierarchy_cache_capacity = varies by system @@ -347,7 +440,13 @@ # #max_request_size = 20971520 -# This item is undocumented. Please contribute documentation for it. +# Maximum number of prev_events the server will request from +# other servers. +# +# When requesting room events from another server, this server will +# specify a maximum prev_events for the other server to return in its +# response. This can be used for things like backfilling room data and +# getting missing events. # #max_fetch_prev_events = 1024 @@ -732,11 +831,15 @@ # #tracing_flame = false -# This item is undocumented. Please contribute documentation for it. +# Which log level tracing_flame will trace. +# +# See "tracing_flame" for more details. # #tracing_flame_filter = "info" -# This item is undocumented. Please contribute documentation for it. +# The output path for tracing_flame data. +# +# See "tracing_flame" for more details. # #tracing_flame_output_path = "./tracing.folded" @@ -964,7 +1067,7 @@ # #rocksdb_log_level = "error" -# This item is undocumented. Please contribute documentation for it. +# Whether to output RocksDB errors to stderr. # #rocksdb_log_stderr = false @@ -1214,7 +1317,17 @@ # #emergency_password = -# This item is undocumented. Please contribute documentation for it. +# Specifies the path where push notifications will be sent to a +# push gateway. +# +# When a Matrix client registers for push notifications, it will specify +# a push gateway url where notification events will be sent. +# According to the current spec for Matrix Push Gateways, the path should +# always be "/_matrix/push/v1/notify". +# You should only change this if you have configured your own push gateway +# that requires a different path. +# +# For more information on Push Gateways: https://spec.matrix.org/v1.9/push-gateway-api/ # #notification_push_path = "/_matrix/push/v1/notify" @@ -1371,7 +1484,10 @@ # #allow_legacy_media = true -# This item is undocumented. Please contribute documentation for it. +# If set to true, prevents fetching new legacy remote media. +# +# Legacy media may still be accessible if it was already fetched +# previously and allow_legacy_media is true. # #freeze_legacy_media = true @@ -1779,7 +1895,18 @@ # #tokio_console = false -# This item is undocumented. Please contribute documentation for it. +# A list of flags that modify startup behavior. +# Accepts an array of strings. +# +# During startup, the program will check for the presence of certain +# strings in this array. Matching values will modify how the program runs +# those startup tasks. +# +# If this variable is empty or contains no matches, the server will start +# normally. +# +# Currently this only checks for "smoke" which enables "Smoketest mode." +# This mode exits the program after running startup tasks. # #test = false diff --git a/src/core/config/mod.rs b/src/core/config/mod.rs index a2d7f0649..b762c30cd 100644 --- a/src/core/config/mod.rs +++ b/src/core/config/mod.rs @@ -238,42 +238,155 @@ pub struct Config { #[serde(default = "default_db_write_buffer_capacity_mb")] pub db_write_buffer_capacity_mb: f64, + /// The maximum number of Persisted Data Units (PDUs) to cache. + /// Accepts any 32-bit integer. + /// + /// PDUs are events broadcast from one homeserver to any others that have + /// joined the same room (identified by Room ID). They are persisted in + /// long-term storage and record the history of messages and state + /// for a room. + /// + /// An example of a PDU would be a message or joining a room. + /// + /// Setting this higher might be useful if the server has a large memory + /// capacity and is noticeably I/O limited. + /// + /// This defaults to 100,000 + (10,000 * CPU core count) + /// /// default: varies by system #[serde(default = "default_pdu_cache_capacity")] pub pdu_cache_capacity: u32, + /// The maximum number of auth chains to cache. + /// Accepts any 32-bit integer. + /// + /// When determining is a user is authorized to send an event, + /// the server will first check the auth chain cache. + /// If the auth chain is not present in the cache, + /// The server will reach out to the origin server for + /// authorization. + /// + /// This defaults to 100,000 + (10,000 * CPU core count) + /// /// default: varies by system #[serde(default = "default_auth_chain_cache_capacity")] pub auth_chain_cache_capacity: u32, + /// Determines the cache size for eventid data references. + /// Accepts any 32-bit integer. + /// + /// Each matrix event can be referenced in the database via either + /// an eventid (string) or a shorteventid (64-bit integer). + /// This caps the capacity of cached eventids referenced + /// by their shorteventid. + /// + /// This defaults to 100,000 + (50,000 * CPU core count) + /// /// default: varies by system #[serde(default = "default_shorteventid_cache_capacity")] pub shorteventid_cache_capacity: u32, + /// Determines the cache size for eventid data references. + /// Accepts any 32-bit integer. + /// + /// Each matrix event can be referenced in the database via either + /// an eventid (string) or a shorteventid (64-bit integer). + /// This caps the capacity of cached shorteventids referenced + /// by their eventid. + /// + /// This defaults to 100,000 + (25,000 * CPU core count) + /// /// default: varies by system #[serde(default = "default_eventidshort_cache_capacity")] pub eventidshort_cache_capacity: u32, + /// Determines the cache size for pdu data references. + /// Accepts any 32-bit integer. + /// + /// This caps the capacity of cached pdus referenced + /// by their eventid. + /// + /// This defaults to 100,000 + (25,000 * CPU core count) + /// /// default: varies by system #[serde(default = "default_eventid_pdu_cache_capacity")] pub eventid_pdu_cache_capacity: u32, + /// Determines the cache size for state key data references. + /// Accepts any 32-bit integer. + /// + /// State keys are used by the server to verify that a token + /// from a third-party invite event was actually generated + /// by the server where the room resides. + /// + /// These state keys can be referenced in the database via either + /// a statekey (string) or a shortstatekey (64-bit integer). + /// This caps the capacity of cached statekeys referenced + /// by shortstatekeys. + /// + /// This defaults to 100,000 + (10,000 * CPU core count) + /// /// default: varies by system #[serde(default = "default_shortstatekey_cache_capacity")] pub shortstatekey_cache_capacity: u32, + /// Determines the cache size for state key data references. + /// Accepts any 32-bit integer. + /// + /// State keys are used by the server to verify that a token + /// from a third-party invite event was actually generated + /// by the server where the room resides. + /// + /// These state keys can be referenced in the database via either + /// a statekey (string) or a shortstatekey (64-bit integer). + /// This caps the capacity of cached shortstatekeys referenced + /// by statekeys. + /// + /// This defaults to 100,000 + (10,000 * CPU core count) + /// /// default: varies by system #[serde(default = "default_statekeyshort_cache_capacity")] pub statekeyshort_cache_capacity: u32, + /// Determines the cache size for event_data references scoped + /// by server_name. + /// Accepts any 32-bit integer. + /// + /// Event data can be referenced in the database by server name. + /// This is useful if the server needs to clear all events associated + /// with a particular federated server, for example. + /// This caps the capacity of cached event_data referenced + /// by server_name. + /// + /// This defaults to 500,000 + (10,000 * CPU core count) + /// /// default: varies by system #[serde(default = "default_servernameevent_data_cache_capacity")] pub servernameevent_data_cache_capacity: u32, + /// Determines the cache size for room states. + /// Accepts any 32-bit integer. + /// + /// To ensure data integrity of room events across asynchronous + /// requests from federated servers, Matrix tracks the state + /// of a room using a statehash and the changes since the + /// previous (parent) statehash. + /// This caps the capacity of cached room state data. + /// + /// This defaults to 100 * CPU core count. + /// /// default: varies by system #[serde(default = "default_stateinfo_cache_capacity")] pub stateinfo_cache_capacity: u32, + /// Determines the cache size for spacehierarchy data. + /// Accepts any 32-bit integer. + /// + /// Each roomid contains info on its place in the space hierarchy. + /// This caps the capacity of cached spacehierarchy data. + /// + /// This defaults to 1,000 * CPU core count. + /// /// default: varies by system #[serde(default = "default_roomid_spacehierarchy_cache_capacity")] pub roomid_spacehierarchy_cache_capacity: u32, @@ -431,6 +544,14 @@ pub struct Config { #[serde(default = "default_max_request_size")] pub max_request_size: usize, + /// Maximum number of prev_events the server will request from + /// other servers. + /// + /// When requesting room events from another server, this server will + /// specify a maximum prev_events for the other server to return in its + /// response. This can be used for things like backfilling room data and + /// getting missing events. + /// /// default: 1024 #[serde(default = "default_max_fetch_prev_events")] pub max_fetch_prev_events: u16, @@ -890,13 +1011,23 @@ pub struct Config { /// /// [1]: https://github.com/jonhoo/inferno /// [2]: www.speedscope.app + /// + /// default: false #[serde(default)] pub tracing_flame: bool, + /// Which log level tracing_flame will trace. + /// + /// See "tracing_flame" for more details. + /// /// default: "info" #[serde(default = "default_tracing_flame_filter")] pub tracing_flame_filter: String, + /// The output path for tracing_flame data. + /// + /// See "tracing_flame" for more details. + /// /// default: "./tracing.folded" #[serde(default = "default_tracing_flame_output_path")] pub tracing_flame_output_path: String, @@ -1158,6 +1289,9 @@ pub struct Config { #[serde(default = "default_rocksdb_log_level")] pub rocksdb_log_level: String, + /// Whether to output RocksDB errors to stderr. + /// + /// default: false #[serde(default)] pub rocksdb_log_stderr: bool, @@ -1430,6 +1564,18 @@ pub struct Config { /// display: sensitive pub emergency_password: Option, + /// Specifies the path where push notifications will be sent to a + /// push gateway. + /// + /// When a Matrix client registers for push notifications, it will specify + /// a push gateway url where notification events will be sent. + /// According to the current spec for Matrix Push Gateways, the path should + /// always be "/_matrix/push/v1/notify". + /// You should only change this if you have configured your own push gateway + /// that requires a different path. + /// + /// For more information on Push Gateways: https://spec.matrix.org/v1.9/push-gateway-api/ + /// /// default: "/_matrix/push/v1/notify" #[serde(default = "default_notification_push_path")] pub notification_push_path: String, @@ -1596,9 +1742,17 @@ pub struct Config { /// /// Defaults to true for now, but this is highly subject to change, likely /// in the next release. + /// + /// default: true #[serde(default = "true_fn")] pub allow_legacy_media: bool, + /// If set to true, prevents fetching new legacy remote media. + /// + /// Legacy media may still be accessible if it was already fetched + /// previously and allow_legacy_media is true. + /// + /// default: true #[serde(default = "true_fn")] pub freeze_legacy_media: bool, @@ -2058,6 +2212,20 @@ pub struct Config { #[serde(default)] pub tokio_console: bool, + /// A list of flags that modify startup behavior. + /// Accepts an array of strings. + /// + /// During startup, the program will check for the presence of certain + /// strings in this array. Matching values will modify how the program runs + /// those startup tasks. + /// + /// If this variable is empty or contains no matches, the server will start + /// normally. + /// + /// Currently this only checks for "smoke" which enables "Smoketest mode." + /// This mode exits the program after running startup tasks. + /// + /// default: false #[serde(default)] pub test: BTreeSet,