Skip to main content

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}