tuwunel_core/config/directory.rs
1//! Configures room and user discovery.
2//!
3//! Room-directory settings govern publication and searching. User-directory
4//! settings govern which local users can appear.
5
6use serde::Deserialize;
7use tuwunel_macros::config_example_generator;
8
9use super::{RegexSet, true_fn};
10
11/// Room and user directories
12///
13/// Groups the two discovery directories. `[global.directory.rooms]` covers
14/// the public room directory: who can list it, who can publish to it, and
15/// how it is searched. `[global.directory.users]` covers which accounts a
16/// user search returns.
17#[expect(rustdoc::broken_intra_doc_links, rustdoc::bare_urls)]
18#[derive(Clone, Debug, Deserialize, Default)]
19#[config_example_generator(
20 filename = "tuwunel-example.toml",
21 section = "global.directory",
22 group = "true",
23 ignore = "rooms users"
24)]
25pub struct Directory {
26 /// Settings for directory rooms.
27 ///
28 /// display: section
29 #[serde(default)]
30 pub rooms: Rooms,
31
32 /// Settings for directory users.
33 ///
34 /// display: section
35 #[serde(default)]
36 pub users: Users,
37}
38
39/// Public room directory
40///
41/// Controls who can read this server's public room directory, who can
42/// publish rooms to it, and how searches behave. By default only clients
43/// with an access token can list it, other servers cannot query it over
44/// federation, and any user whose power level in a room allows changing its
45/// history visibility can publish that room (guests cannot).
46///
47/// Tips:
48/// - `lockdown` limits publishing to server admins and appservices, both
49/// when a room is created and afterwards.
50/// - Servers that `[global.federation]` already blocks, through its
51/// `forbidden_remote_server_names` or its allowlist, are refused here
52/// too; this section's `forbidden_remote_server_names` adds blocks that
53/// apply only to browsing a remote server's directory.
54/// - `forbidden_remote_server_names` takes regular expressions; startup
55/// warns about a plain dotted name such as `example.com`, whose dots
56/// match any character.
57#[expect(rustdoc::broken_intra_doc_links, rustdoc::bare_urls)]
58#[derive(Clone, Debug, Deserialize)]
59#[config_example_generator(
60 filename = "tuwunel-example.toml",
61 section = "global.directory.rooms",
62 group = "true"
63)]
64pub struct Rooms {
65 /// Allows federation access to the public room directory.
66 ///
67 /// Disabling this protects against `/publicRooms` spiders but prevents
68 /// external users from viewing the directory. This is inherently false
69 /// when `federation.enable` is disabled.
70 ///
71 /// reloadable: yes
72 /// legacy: allow_public_room_directory_over_federation
73 #[serde(default)]
74 pub allow_over_federation: bool,
75
76 /// Allows client API queries of the public room directory without an
77 /// access token, exposing it to unauthenticated `/publicRooms` spiders.
78 ///
79 /// reloadable: yes
80 /// legacy: allow_public_room_directory_without_auth
81 #[serde(default)]
82 pub allow_without_auth: bool,
83
84 /// Allows directory searches to match partial room IDs when the search
85 /// starts with "!".
86 ///
87 /// reloadable: yes
88 /// default: true
89 /// legacy: allow_public_room_search_by_id
90 #[serde(default = "true_fn")]
91 pub allow_public_search_by_id: bool,
92
93 /// Allows room-ID searches to return joinable rooms absent from public
94 /// listings.
95 ///
96 /// The default true lets users paste room IDs into search boxes to join,
97 /// matching their expectations even when rooms opt out of public listings.
98 /// Set false to restrict results to rooms discoverable through aliases or
99 /// other queries, specifically those in the public directory. To prevent
100 /// abuse, several room-ID characters must be known before results are
101 /// returned.
102 ///
103 /// reloadable: yes
104 /// default: true
105 /// legacy: allow_unlisted_room_search_by_id
106 #[serde(default = "true_fn")]
107 pub allow_unlisted_search_by_id: bool,
108
109 /// Restricts publishing rooms in the public directory to admins.
110 ///
111 /// All users can still unpublish rooms when this is enabled.
112 ///
113 /// reloadable: yes
114 /// legacy: lockdown_public_room_directory
115 #[serde(default)]
116 pub lockdown: bool,
117
118 /// Blocks outgoing federated room-directory requests to server names
119 /// matching listed regular expressions to prevent users from wandering
120 /// into unwanted servers or spaces.
121 ///
122 /// reloadable: yes
123 /// example: ['badserver\.tld$', 'badphrase', '19dollarfortnitecards']
124 ///
125 /// default: []
126 /// legacy: forbidden_remote_room_directory_server_names
127 #[serde(default, with = "serde_regex")]
128 pub forbidden_remote_server_names: RegexSet,
129}
130
131/// User directory
132///
133/// Controls which accounts a local user's directory search can find. The
134/// search covers local accounts and the remote users this server has seen
135/// in its rooms. By default it returns only users who are in a room with a
136/// public join rule or share a room with the searcher, and it hides users
137/// that belong exclusively to an appservice. Other servers cannot query
138/// it; federation profile lookups are set in `[global.profile]`.
139///
140/// Tips:
141/// - `show_all_local` lifts the room filter for every account the server
142/// knows, including those remote users, not only local accounts.
143#[expect(rustdoc::broken_intra_doc_links, rustdoc::bare_urls)]
144#[derive(Clone, Copy, Debug, Deserialize, Default)]
145#[config_example_generator(
146 filename = "tuwunel-example.toml",
147 section = "global.directory.users",
148 group = "true"
149)]
150pub struct Users {
151 /// Shows all local users in directory searches.
152 ///
153 /// When false, only users in public rooms or rooms shared with the
154 /// searcher appear. Appservice senders and users in exclusive appservice
155 /// namespaces remain hidden unless `directory.users.show_appservice` is
156 /// also enabled.
157 ///
158 /// reloadable: yes
159 /// default: false
160 /// legacy: show_all_local_users_in_user_directory
161 #[serde(default)]
162 pub show_all_local: bool,
163
164 /// Includes appservice senders and users in exclusive appservice
165 /// namespaces in directory searches.
166 ///
167 /// Normal room-visibility rules still apply unless
168 /// `directory.users.show_all_local` is also enabled.
169 ///
170 /// reloadable: yes
171 /// default: false
172 /// legacy: show_appservice_users_in_user_directory
173 #[serde(default)]
174 pub show_appservice: bool,
175}
176
177impl Default for Rooms {
178 fn default() -> Self {
179 Self {
180 allow_over_federation: Default::default(),
181 allow_without_auth: Default::default(),
182 allow_public_search_by_id: true_fn(),
183 allow_unlisted_search_by_id: true_fn(),
184 lockdown: Default::default(),
185 forbidden_remote_server_names: Default::default(),
186 }
187 }
188}