Skip to main content

tuwunel_service/presence/
pipeline.rs

1//! Presence update pipeline.
2//!
3//! This module centralizes the write path for presence updates. It keeps the
4//! aggregation and timer logic in one place so the public `Service` surface
5//! remains small and the update flow is easy to review.
6
7use std::time::Duration;
8
9use futures::TryFutureExt;
10use ruma::{
11	DeviceId, OwnedUserId, UInt, UserId, events::presence::PresenceEvent, presence::PresenceState,
12};
13use tokio::time::sleep;
14use tuwunel_core::{
15	Error, Result, debug,
16	debug::INFO_SPAN_LEVEL,
17	error,
18	result::LogErr,
19	trace,
20	utils::{future::OptionFutureExt, option::OptionExt},
21};
22
23use super::{
24	Ping, Service, TimerFired,
25	aggregate::{self, StatusMsg},
26};
27
28impl Service {
29	fn device_key(device_id: Option<&DeviceId>, is_remote: bool) -> aggregate::DeviceKey {
30		if is_remote {
31			return aggregate::DeviceKey::Remote;
32		}
33
34		match device_id {
35			| Some(device_id) => aggregate::DeviceKey::Device(device_id.to_owned()),
36			| None => aggregate::DeviceKey::UnknownLocal,
37		}
38	}
39
40	fn schedule_presence_timer(
41		&self,
42		user_id: &UserId,
43		presence_state: &PresenceState,
44		count: u64,
45	) -> Result {
46		if !(self.timeout_remote_users || self.services.globals.user_is_local(user_id))
47			|| user_id == self.services.globals.server_user
48		{
49			return Ok(());
50		}
51
52		let timeout = match presence_state {
53			| PresenceState::Online =>
54				self.services
55					.server
56					.config
57					.presence
58					.idle_timeout_s,
59			| _ =>
60				self.services
61					.server
62					.config
63					.presence
64					.offline_timeout_s,
65		};
66
67		self.timer_channel
68			.0
69			.send((user_id.to_owned(), Duration::from_secs(timeout), count))
70			.map_err(|e| {
71				error!("Failed to add presence timer: {}", e);
72				Error::bad_database("Failed to add presence timer")
73			})
74	}
75
76	fn refresh_skip_decision(
77		refresh_window_ms: Option<u64>,
78		last_event: Option<&PresenceEvent>,
79		last_count: Option<u64>,
80	) -> Option<(u64, u64)> {
81		let (Some(refresh_ms), Some(event), Some(count)) =
82			(refresh_window_ms, last_event, last_count)
83		else {
84			return None;
85		};
86
87		let last_last_active_ago: u64 = event.content.last_active_ago?.into();
88
89		(last_last_active_ago < refresh_ms).then_some((count, last_last_active_ago))
90	}
91
92	fn timer_is_stale(expected_count: u64, current_count: u64) -> bool {
93		expected_count != current_count
94	}
95
96	#[tracing::instrument(
97		name = "presence",
98		level = INFO_SPAN_LEVEL,
99		skip_all,
100		fields(
101			%user_id,
102			?device_key,
103			%state,
104			?currently_active,
105		),
106	)]
107	#[expect(clippy::too_many_arguments)]
108	async fn apply_device_presence_update(
109		&self,
110		user_id: &UserId,
111		device_key: aggregate::DeviceKey,
112		state: &PresenceState,
113		currently_active: Option<bool>,
114		last_active_ago: Option<UInt>,
115		status_msg: StatusMsg,
116		refresh_window_ms: Option<u64>,
117	) -> Result {
118		let now = tuwunel_core::utils::millis_since_unix_epoch();
119		let preserve_status = matches!(status_msg, StatusMsg::Unchanged);
120
121		// 1) Capture per-device presence snapshot for aggregation.
122		debug!(
123			?user_id,
124			?device_key,
125			?state,
126			currently_active,
127			last_active_ago = last_active_ago.map(u64::from),
128			"Presence update received"
129		);
130
131		self.device_presence
132			.update(
133				user_id,
134				device_key,
135				state,
136				currently_active,
137				last_active_ago,
138				status_msg,
139				now,
140			)
141			.await;
142
143		// 2) Compute the aggregated presence across all devices.
144		let aggregated = self
145			.device_presence
146			.aggregate(user_id, now, self.idle_timeout, self.offline_timeout)
147			.await;
148
149		debug!(
150			?user_id,
151			agg_state = ?aggregated.state,
152			agg_currently_active = aggregated.currently_active,
153			agg_last_active_ts = aggregated.last_active_ts,
154			agg_device_count = aggregated.device_count,
155			"Presence aggregate computed"
156		);
157
158		// 3) Load the last persisted presence to decide whether to skip or merge.
159		let last_presence = self.db.get_presence(user_id).await;
160		let (last_count, last_event) = match last_presence {
161			| Ok((count, event)) => (Some(count), Some(event)),
162			| Err(_) => (None, None),
163		};
164
165		let last_state = last_event
166			.as_ref()
167			.map(|event| event.content.presence.clone());
168
169		let state_changed = match &last_event {
170			| Some(event) => event.content.presence != aggregated.state,
171			| None => true,
172		};
173
174		// 4) For rapid pings with no state change, skip writes and reschedule.
175		if !state_changed
176			&& let Some((count, last_last_active_ago)) =
177				Self::refresh_skip_decision(refresh_window_ms, last_event.as_ref(), last_count)
178		{
179			let presence = last_event
180				.as_ref()
181				.map(|event| &event.content.presence)
182				.unwrap_or(state);
183
184			self.schedule_presence_timer(user_id, presence, count)
185				.log_err()
186				.ok();
187
188			debug!(
189				?user_id,
190				?state,
191				last_last_active_ago,
192				"Skipping presence update: refresh window (timer rescheduled)"
193			);
194
195			return Ok(());
196		}
197
198		// 5) If we just transitioned away from online, flush suppressed pushes.
199		if matches!(last_state, Some(PresenceState::Online))
200			&& aggregated.state != PresenceState::Online
201		{
202			debug!(
203				?user_id,
204				from = ?PresenceState::Online,
205				to = ?aggregated.state,
206				"Presence went inactive; flushing suppressed pushes"
207			);
208
209			self.services
210				.sending
211				.schedule_flush_suppressed_for_user(
212					user_id.to_owned(),
213					"presence->inactive (aggregate)",
214				);
215		}
216
217		// 6) Unchanged preserves the last non-empty status; explicit None clears it.
218		let fallback_status = || {
219			last_event
220				.and_then(|event| event.content.status_msg)
221				.filter(|msg| !msg.is_empty())
222		};
223
224		let status_msg = aggregated
225			.status_msg
226			.or_else(|| preserve_status.then(fallback_status).flatten());
227
228		let last_active_ago =
229			Some(UInt::new_saturating(now.saturating_sub(aggregated.last_active_ts)));
230
231		self.set_presence(
232			user_id,
233			&aggregated.state,
234			Some(aggregated.currently_active),
235			last_active_ago,
236			status_msg,
237		)
238		.await
239	}
240
241	/// Pings the presence of the given user, defaulting the state to online.
242	///
243	/// Requests authenticated with an appservice token do not imply user
244	/// activity. In particular, they must not update presence or device
245	/// last-seen data. Explicit appservice presence updates use
246	/// [`Self::set_presence_for_device`] instead.
247	pub async fn maybe_ping_presence(&self, user_id: &UserId, args: Ping<'_>) -> Result {
248		const REFRESH_TIMEOUT: u64 = 30 * 1000;
249
250		if args.appservice.is_some()
251			|| !self.services.server.config.presence.allow_local
252			|| self.services.db.is_read_only()
253		{
254			return Ok(());
255		}
256
257		let update_device_seen = args.device_id.map_async(|device_id| {
258			self.services
259				.users
260				.update_device_last_seen(user_id, device_id, args.client_ip, None)
261		});
262
263		let new_state = args.new_state.unwrap_or(&PresenceState::Online);
264		let currently_active = *new_state == PresenceState::Online;
265		let set_presence = self.apply_device_presence_update(
266			user_id,
267			Self::device_key(args.device_id, false),
268			new_state,
269			Some(currently_active),
270			UInt::new(0),
271			StatusMsg::Unchanged,
272			Some(REFRESH_TIMEOUT),
273		);
274
275		debug!(?user_id, ?new_state, currently_active, "Presence ping accepted");
276
277		futures::future::try_join(set_presence, update_device_seen.unwrap_or(Ok(())))
278			.map_ok(|_| ())
279			.await
280	}
281
282	/// Applies an explicit presence update for a local device.
283	pub async fn set_presence_for_device(
284		&self,
285		user_id: &UserId,
286		device_id: Option<&DeviceId>,
287		state: &PresenceState,
288		status_msg: Option<String>,
289	) -> Result {
290		let currently_active = *state == PresenceState::Online;
291		self.apply_device_presence_update(
292			user_id,
293			Self::device_key(device_id, false),
294			state,
295			Some(currently_active),
296			None,
297			StatusMsg::Set(status_msg),
298			None,
299		)
300		.await
301	}
302
303	/// Applies a presence update received over federation.
304	pub async fn set_presence_from_federation(
305		&self,
306		user_id: &UserId,
307		state: &PresenceState,
308		currently_active: bool,
309		last_active_ago: UInt,
310		status_msg: Option<String>,
311	) -> Result {
312		self.apply_device_presence_update(
313			user_id,
314			Self::device_key(None, true),
315			state,
316			Some(currently_active),
317			Some(last_active_ago),
318			StatusMsg::Set(status_msg),
319			None,
320		)
321		.await
322	}
323
324	/// Adds a presence event which will be saved until a new event replaces it.
325	pub async fn set_presence(
326		&self,
327		user_id: &UserId,
328		state: &PresenceState,
329		currently_active: Option<bool>,
330		last_active_ago: Option<UInt>,
331		status_msg: Option<String>,
332	) -> Result {
333		let presence_state = match state.as_str() {
334			| "" => &PresenceState::Offline, // default an empty string to 'offline'
335			| &_ => state,
336		};
337
338		let count = self
339			.db
340			.set_presence(user_id, presence_state, currently_active, last_active_ago, status_msg)
341			.await?;
342
343		if let Some(count) = count {
344			let is_local = self.services.globals.user_is_local(user_id);
345			let is_server_user = user_id == self.services.globals.server_user;
346			let allow_timeout = self.timeout_remote_users || is_local;
347
348			if allow_timeout && !is_server_user {
349				self.schedule_presence_timer(user_id, presence_state, count)?;
350			}
351		}
352
353		Ok(())
354	}
355
356	pub(super) async fn process_presence_timer(
357		&self,
358		user_id: &OwnedUserId,
359		expected_count: u64,
360	) -> Result {
361		let Ok((current_count, presence)) = self.db.get_presence_raw(user_id).await else {
362			return Ok(());
363		};
364
365		if Self::timer_is_stale(expected_count, current_count) {
366			trace!(?user_id, expected_count, current_count, "Skipping stale presence timer");
367			return Ok(());
368		}
369
370		let presence_state = presence.state.clone();
371		let now = tuwunel_core::utils::millis_since_unix_epoch();
372		let aggregated = self
373			.device_presence
374			.aggregate(user_id, now, self.idle_timeout, self.offline_timeout)
375			.await;
376
377		if aggregated.device_count == 0 {
378			let last_active_ago =
379				Some(UInt::new_saturating(now.saturating_sub(presence.last_active_ts)));
380			let status_msg = presence.status_msg;
381
382			let new_state = match (&presence_state, last_active_ago.map(u64::from)) {
383				| (PresenceState::Online, Some(ago)) if ago >= self.idle_timeout =>
384					Some(PresenceState::Unavailable),
385				| (PresenceState::Unavailable, Some(ago)) if ago >= self.offline_timeout =>
386					Some(PresenceState::Offline),
387				| _ => None,
388			};
389
390			debug!(
391				"Processed presence timer for user '{user_id}': Old state = {presence_state}, \
392				 New state = {new_state:?}"
393			);
394
395			if let Some(new_state) = new_state {
396				if matches!(new_state, PresenceState::Unavailable | PresenceState::Offline) {
397					self.services
398						.sending
399						.schedule_flush_suppressed_for_user(
400							user_id.to_owned(),
401							"presence->inactive",
402						);
403				}
404				self.set_presence(user_id, &new_state, Some(false), last_active_ago, status_msg)
405					.await?;
406			}
407
408			return Ok(());
409		}
410
411		if aggregated.state == presence_state {
412			self.schedule_presence_timer(user_id, &presence_state, current_count)
413				.log_err()
414				.ok();
415			return Ok(());
416		}
417
418		if matches!(aggregated.state, PresenceState::Unavailable | PresenceState::Offline) {
419			self.services
420				.sending
421				.schedule_flush_suppressed_for_user(user_id.to_owned(), "presence->inactive");
422		}
423
424		let status_msg = aggregated.status_msg.or(presence.status_msg);
425		let last_active_ago =
426			Some(UInt::new_saturating(now.saturating_sub(aggregated.last_active_ts)));
427
428		self.set_presence(
429			user_id,
430			&aggregated.state,
431			Some(aggregated.currently_active),
432			last_active_ago,
433			status_msg,
434		)
435		.await?;
436
437		Ok(())
438	}
439}
440
441pub(super) async fn presence_timer(
442	user_id: OwnedUserId,
443	timeout: Duration,
444	count: u64,
445) -> TimerFired {
446	sleep(timeout).await;
447
448	(user_id, count)
449}
450
451#[cfg(test)]
452mod tests {
453	use ruma::{uint, user_id};
454
455	use super::*;
456
457	#[test]
458	fn refresh_window_skip_decision() {
459		let user_id = user_id!("@alice:example.com");
460		let event = PresenceEvent {
461			sender: user_id.to_owned(),
462			content: ruma::events::presence::PresenceEventContent {
463				presence: PresenceState::Online,
464				status_msg: None,
465				currently_active: Some(true),
466				last_active_ago: Some(uint!(10)),
467				avatar_url: None,
468				displayname: None,
469			},
470		};
471
472		let decision = Service::refresh_skip_decision(Some(20), Some(&event), Some(5));
473		assert_eq!(decision, Some((5, 10)));
474
475		let decision = Service::refresh_skip_decision(Some(5), Some(&event), Some(5));
476		assert_eq!(decision, None);
477
478		let event_missing_ago = PresenceEvent {
479			sender: user_id.to_owned(),
480			content: ruma::events::presence::PresenceEventContent {
481				presence: PresenceState::Online,
482				status_msg: None,
483				currently_active: Some(true),
484				last_active_ago: None,
485				avatar_url: None,
486				displayname: None,
487			},
488		};
489
490		let decision =
491			Service::refresh_skip_decision(Some(20), Some(&event_missing_ago), Some(5));
492		assert_eq!(decision, None);
493
494		let decision = Service::refresh_skip_decision(Some(20), None, Some(5));
495		assert_eq!(decision, None);
496	}
497
498	#[test]
499	fn timer_stale_detection() {
500		assert!(Service::timer_is_stale(2, 3));
501		assert!(!Service::timer_is_stale(2, 2));
502	}
503}