Skip to main content

tuwunel_service/appservice/
mod.rs

1mod append;
2mod namespace_regex;
3mod ping;
4pub mod proxy;
5mod registration_info;
6pub(crate) mod request;
7#[cfg(test)]
8mod tests;
9mod thirdparty;
10
11#[cfg(unix)]
12use std::sync::Mutex;
13use std::{
14	collections::{BTreeMap, btree_map::Values},
15	ffi::OsStr,
16	fs::{self, read_dir},
17	iter::Filter,
18	sync::Arc,
19};
20
21use async_trait::async_trait;
22use futures::{FutureExt, Stream, TryStreamExt};
23use reqwest::Client;
24use ruma::{RoomAliasId, RoomId, UserId, api::appservice::Registration};
25use serde_yaml::{from_slice as from_yaml, to_string as to_yaml};
26use tokio::sync::{RwLock, RwLockReadGuard, SetOnce};
27#[cfg(unix)]
28use tuwunel_core::smallstr::SmallString;
29use tuwunel_core::{
30	Err, Result, defer, err, implement,
31	utils::{BoolExt, stream::IterStream},
32	warn,
33};
34use tuwunel_database::Map;
35
36pub use self::{
37	namespace_regex::NamespaceRegex,
38	registration_info::{IS_JOINED_SCOPE, PROXY_PREFIXES, RegistrationInfo, proxy_claim},
39};
40#[cfg(unix)]
41use crate::client::make_appservice_unix;
42
43#[cfg(unix)]
44type SocketPath = SmallString<[u8; 64]>;
45
46pub struct Service {
47	registration_info: RwLock<Registrations>,
48	/// Live client pools indexed by socket path.
49	///
50	/// Entries persist for the service lifetime, including after unregistration.
51	#[cfg(unix)]
52	unix_clients: Mutex<BTreeMap<SocketPath, Client>>,
53	loaded: SetOnce<()>,
54	services: Arc<crate::services::OnceServices>,
55	db: Data,
56}
57
58struct Data {
59	id_appserviceregistrations: Arc<Map>,
60}
61
62type Registrations = BTreeMap<String, RegistrationInfo>;
63
64const KNOWN_SCOPES: [&str; 1] = [IS_JOINED_SCOPE];
65
66/// The registrations [`receivers`] yields.
67///
68/// A named type rather than an opaque one, so a caller may shorten its borrow
69/// of the registry.
70pub type Receivers<'a> =
71	Filter<Values<'a, String, RegistrationInfo>, fn(&&RegistrationInfo) -> bool>;
72
73#[async_trait]
74impl crate::Service for Service {
75	fn build(args: &crate::Args<'_>) -> Result<Arc<Self>> {
76		Ok(Arc::new(Self {
77			registration_info: RwLock::new(BTreeMap::new()),
78			#[cfg(unix)]
79			unix_clients: Mutex::default(),
80			loaded: SetOnce::new(),
81			services: args.services.clone(),
82			db: Data {
83				id_appserviceregistrations: args.db["id_appserviceregistrations"].clone(),
84			},
85		}))
86	}
87
88	async fn worker(self: Arc<Self>) -> Result {
89		defer! {{
90			self.loaded.set(()).ok();
91		}}
92
93		self.load().await
94	}
95
96	fn name(&self) -> &str { crate::service::make_name(std::module_path!()) }
97}
98
99impl Service {
100	/// Loads every registration source into the runtime registry.
101	///
102	/// The configured `appservice` table is read first, then any YAML under
103	/// `appservice_dir`, then the registrations persisted by the admin command.
104	async fn load(&self) -> Result {
105		for (id, mut appservice) in self.services.config.appservice.clone() {
106			if appservice.id.is_empty() {
107				appservice.id = id.clone();
108			}
109
110			if *id != appservice.id {
111				return Err!(Config(
112					"id",
113					"Registration ID {:?} does not match the configured {id:?}",
114					appservice.id
115				));
116			}
117
118			self.load_appservice(appservice.into()).await?;
119		}
120
121		if let Some(appservice_dir) = &self.services.config.appservice_dir {
122			let entries = read_dir(appservice_dir).map_err(|e| {
123				err!(Config("appservice_dir", "Failed to read {appservice_dir:?}: {e}"))
124			})?;
125
126			for dir_entry in entries {
127				let path = dir_entry?.path();
128
129				if !path.is_file()
130					|| !path
131						.extension()
132						.and_then(OsStr::to_str)
133						.is_some_and(|ext| matches!(ext, "yaml" | "yml"))
134				{
135					continue;
136				}
137
138				let bytes = fs::read(path)?;
139				let registration: Registration = from_yaml(&bytes)?;
140
141				self.load_appservice(registration).await?;
142			}
143		}
144
145		self.iter_db_ids()
146			.try_for_each(|registration| self.load_appservice(registration))
147			.await?;
148
149		Ok(())
150	}
151
152	/// Loads one registration into the runtime registry at startup.
153	///
154	/// An id already loaded is refused, as is an `as_token` another id holds,
155	/// and a missing sender user is created. An unknown scope is logged and
156	/// ignored, so a registration written for a later release still loads; so
157	/// is an invalid proxy claim, or one an earlier registration holds.
158	pub async fn load_appservice(&self, registration: Registration) -> Result {
159		let registration_info =
160			RegistrationInfo::new(registration, self.services.globals.server_name())?;
161
162		let id = registration_info.registration.id.clone();
163
164		if let Some(scope) = registration_info.unknown_scope() {
165			warn!(%id, %scope, "Ignoring an unknown scope in the appservice registration");
166		}
167
168		if let Err(error) = proxy_claim(&registration_info.registration) {
169			warn!(%id, %error, "Ignoring the invalid proxy claim in the appservice registration");
170		}
171
172		let mut registrations = self.registration_info.write().await;
173
174		if registrations.contains_key(&id) {
175			return Err!("Duplicate id: {id}");
176		}
177
178		let registration_info = match claim_holder(&registrations, &registration_info) {
179			| None => registration_info,
180			| Some(holder) => {
181				warn!(%id, %holder, "Ignoring a proxy claim another appservice holds");
182				registration_info.without_proxy_claim()
183			},
184		};
185
186		self.admit_registration(&registrations, &registration_info)
187			.await?;
188
189		registrations.insert(id, registration_info);
190
191		Ok(())
192	}
193
194	/// Registers an appservice and persists it for later startups.
195	///
196	/// An id this method registered before is replaced, and its cached room
197	/// participation is dropped. An id loaded from the configuration or
198	/// `appservice_dir` is refused, since both would load at the next startup
199	/// and collide. A scope this server does not know is refused too, as is an
200	/// invalid proxy claim or one another appservice holds.
201	pub async fn register_appservice(&self, registration: Registration) -> Result {
202		self.loaded().await;
203
204		let id = registration.id.clone();
205
206		let yaml = to_yaml(&registration)?;
207
208		let registration_info =
209			RegistrationInfo::new(registration, self.services.globals.server_name())?;
210
211		if let Some(scope) = registration_info.unknown_scope() {
212			return Err!("Unknown scope {scope:?} in appservice {id}");
213		}
214
215		if let Err(error) = proxy_claim(&registration_info.registration) {
216			return Err!("Invalid proxy claim in appservice {id}: {error}");
217		}
218
219		let mut registrations = self.registration_info.write().await;
220
221		if registrations.contains_key(&id) && self.is_persisted(&id).await.is_false() {
222			return Err!("Cannot replace config appservice {id}");
223		}
224
225		if let Some(holder) = claim_holder(&registrations, &registration_info) {
226			return Err!("Appservice {holder} already claims the proxy prefix of {id}");
227		}
228
229		self.admit_registration(&registrations, &registration_info)
230			.await?;
231
232		self.db
233			.id_appserviceregistrations
234			.insert(&id, yaml);
235
236		// Room participation lookups run under a registry read guard, so none
237		// built on the replaced registration outlives this write guard.
238		self.services
239			.state_cache
240			.clear_appservice_in_room_cache_for(&id);
241
242		registrations.insert(id, registration_info);
243
244		Ok(())
245	}
246
247	pub async fn unregister_appservice(&self, appservice_id: &str) -> Result {
248		self.loaded().await;
249
250		let mut registrations = self.registration_info.write().await;
251
252		if !registrations.contains_key(appservice_id) {
253			return Err!("Appservice not found");
254		}
255
256		if self.is_persisted(appservice_id).await.is_false() {
257			return Err!("Cannot unregister config appservice");
258		}
259
260		// removes the appservice registration info
261		registrations
262			.remove(appservice_id)
263			.ok_or_else(|| err!("Appservice not found"))?;
264
265		// remove the appservice from the database
266		self.db
267			.id_appserviceregistrations
268			.remove(appservice_id);
269
270		// deletes all active requests for the appservice if there are any so we stop
271		// sending to the URL
272		self.services
273			.sending
274			.cleanup_events(Some(appservice_id), None, None)
275			.await
276	}
277
278	pub async fn get_registration(&self, id: &str) -> Option<Registration> {
279		self.registration_info
280			.read()
281			.await
282			.get(id)
283			.cloned()
284			.map(|info| info.registration)
285	}
286
287	/// Retrieve a registration with its compiled namespaces (`sender`,
288	/// `is_user_match`), which a bare `Registration` lacks.
289	pub async fn get_registration_info(&self, id: &str) -> Option<RegistrationInfo> {
290		self.registration_info
291			.read()
292			.await
293			.get(id)
294			.cloned()
295	}
296
297	pub async fn find_from_access_token(&self, token: &str) -> Result<RegistrationInfo> {
298		self.read()
299			.await
300			.values()
301			.find(|info| info.registration.as_token == token)
302			.cloned()
303			.ok_or_else(|| err!(Request(NotFound("Missing or invalid appservice token"))))
304	}
305
306	/// MSC4512: the registration whose proxy claim covers a proxied path.
307	///
308	/// `remainder` is the path after its version segments, as
309	/// [`proxy::split_path`] returns it. At most one registration holds a
310	/// prefix, so at most one matches.
311	pub async fn find_proxy_claim(&self, remainder: &str) -> Option<RegistrationInfo> {
312		self.read()
313			.await
314			.values()
315			.find(|info| info.proxy_covers(remainder))
316			.cloned()
317	}
318
319	/// Checks if a given user id matches any exclusive appservice regex
320	pub async fn is_exclusive_user_id(&self, user_id: &UserId) -> bool {
321		self.read()
322			.await
323			.values()
324			.any(|info| info.is_exclusive_user_match(user_id))
325	}
326
327	/// Checks if a given user id matches any appservice's user namespace.
328	pub async fn is_interested_in_user(&self, user_id: &UserId) -> bool {
329		self.read()
330			.await
331			.values()
332			.any(|info| info.is_user_match(user_id))
333	}
334
335	/// Checks if a given room alias matches any exclusive appservice regex
336	pub async fn is_exclusive_alias(&self, alias: &RoomAliasId) -> bool {
337		self.read()
338			.await
339			.values()
340			.any(|info| info.aliases.is_exclusive_match(alias.as_str()))
341	}
342
343	/// Checks if a given room id matches any exclusive appservice regex
344	///
345	/// TODO: use this?
346	pub async fn is_exclusive_room_id(&self, room_id: &RoomId) -> bool {
347		self.read()
348			.await
349			.values()
350			.any(|info| info.rooms.is_exclusive_match(room_id.as_str()))
351	}
352
353	pub fn iter_ids(&self) -> impl Stream<Item = String> + Send {
354		self.read()
355			.map(|info| info.keys().cloned().collect::<Vec<_>>())
356			.map(IntoIterator::into_iter)
357			.map(IterStream::stream)
358			.flatten_stream()
359	}
360
361	pub fn iter_db_ids(&self) -> impl Stream<Item = Result<Registration>> + Send {
362		self.db
363			.id_appserviceregistrations
364			.keys()
365			.and_then(async move |id: &str| Ok(self.get_db_registration(id).await?))
366	}
367
368	pub async fn get_db_registration(&self, id: &str) -> Result<Registration> {
369		self.db
370			.id_appserviceregistrations
371			.get(id)
372			.await
373			.and_then(|ref bytes| from_yaml(bytes).map_err(Into::into))
374			.map_err(|e| err!(Database("Invalid appservice {id:?} registration: {e:?}")))
375	}
376
377	pub fn read(&self) -> impl Future<Output = RwLockReadGuard<'_, Registrations>> + Send {
378		self.registration_info.read()
379	}
380
381	/// Waits for the boot-time registration load to finish.
382	///
383	/// The latch is released on every exit from the worker, a failed or
384	/// panicking load included, so a waiter is never stranded on a load that
385	/// will not complete.
386	#[inline]
387	pub async fn loaded(&self) { self.loaded.wait().await; }
388}
389
390/// The registrations a sender may queue traffic for.
391///
392/// A registration without a URL asked for no traffic, so it is left out.
393pub fn receivers(registrations: &Registrations) -> Receivers<'_> {
394	let has_destination: fn(&&RegistrationInfo) -> bool = |info| info.has_destination();
395
396	registrations.values().filter(has_destination)
397}
398
399/// MSC4502: the first requested scope this server does not know.
400///
401/// Such a scope grants nothing, since `has_scope` is only asked about known
402/// ones; it is most likely a typo the operator should hear about.
403#[implement(RegistrationInfo)]
404#[must_use]
405pub fn unknown_scope(&self) -> Option<&str> {
406	self.registration
407		.scopes
408		.iter()
409		.map(String::as_str)
410		.find(|scope| !KNOWN_SCOPES.contains(scope))
411}
412
413/// MSC4512: the id of another registration holding the same proxy prefix.
414///
415/// The registration's own id is passed over, so re-registering it works.
416fn claim_holder<'a>(
417	registrations: &'a Registrations,
418	registration_info: &RegistrationInfo,
419) -> Option<&'a str> {
420	let prefix = registration_info.proxy_prefix?;
421	let id = &registration_info.registration.id;
422
423	registrations
424		.values()
425		.find(|loaded| loaded.registration.id != *id && loaded.proxy_prefix == Some(prefix))
426		.map(|holder| holder.registration.id.as_str())
427}
428
429/// Refuses an `as_token` another id holds, and creates a missing sender user.
430///
431/// The caller inserts the registration under the same write guard.
432#[implement(Service)]
433async fn admit_registration(
434	&self,
435	registrations: &Registrations,
436	registration_info: &RegistrationInfo,
437) -> Result {
438	//TODO: Check for collisions between exclusive appservice namespaces
439
440	let id = &registration_info.registration.id;
441	let token_holder = registrations
442		.values()
443		.map(|loaded| &loaded.registration)
444		.find(|loaded| {
445			loaded.id != *id && loaded.as_token == registration_info.registration.as_token
446		})
447		.map(|holder| &holder.id);
448
449	if let Some(holder) = token_holder {
450		return Err!("Duplicate as_token: {holder} {id}");
451	}
452
453	let appservice_user = &registration_info.sender;
454
455	if self
456		.services
457		.users
458		.exists(appservice_user)
459		.await
460		.is_false()
461	{
462		self.services
463			.users
464			.create(appservice_user, None, None)
465			.await?;
466	}
467
468	Ok(())
469}
470
471/// Whether `register_appservice` persisted this id, which an id loaded from
472/// the configuration or `appservice_dir` never is.
473#[implement(Service)]
474async fn is_persisted(&self, id: &str) -> bool {
475	self.db
476		.id_appserviceregistrations
477		.exists(id)
478		.await
479		.is_ok()
480}
481
482#[implement(Service)]
483fn transport<'a>(&self, url: &'a str) -> Result<(&'a str, Client)> {
484	match socket_path(url)? {
485		| None => Ok((url, self.services.client.appservice.clone())),
486		#[cfg(not(unix))]
487		| Some(_) => Err!("Unix sockets are not supported on this platform"),
488		#[cfg(unix)]
489		| Some(path) => Ok(("http://localhost", self.unix_client(path)?)),
490	}
491}
492
493#[cfg(unix)]
494#[implement(Service)]
495fn unix_client(&self, path: &str) -> Result<Client> {
496	let mut clients = self.unix_clients.lock().expect("locked");
497
498	match clients.get(path) {
499		| Some(client) => Ok(client.clone()),
500		| None => {
501			let client = make_appservice_unix(&self.services, path)?;
502
503			clients.insert(path.into(), client.clone());
504			Ok(client)
505		},
506	}
507}
508
509/// The registration's URL, absent when it asks for no traffic.
510///
511/// A `null` or empty URL is taken as absent too.
512fn destination(registration: &Registration) -> Option<&str> {
513	registration
514		.url
515		.as_deref()
516		.filter(|url| !url.is_empty() && *url != "null")
517}
518
519fn socket_path(url: &str) -> Result<Option<&str>> {
520	url.split_once(':')
521		.filter(|(scheme, _)| scheme.eq_ignore_ascii_case("unix"))
522		.map(|(_, path)| path.strip_prefix("//").unwrap_or(path))
523		.map(|path| {
524			path.starts_with('/')
525				.then_some(path)
526				.ok_or_else(|| err!("Appservice Unix socket URL must name an absolute path"))
527		})
528		.transpose()
529}