Skip to main content

tuwunel_service/sending/
data.rs

1#[cfg(test)]
2mod tests;
3
4use std::{
5	fmt::Debug,
6	iter::once,
7	ops::{
8		Bound,
9		Bound::{Excluded, Included, Unbounded},
10	},
11	pin::pin,
12	sync::Arc,
13	time::Duration,
14	vec,
15};
16
17use futures::{
18	Stream, StreamExt,
19	stream::{iter, unfold},
20};
21use ruma::{OwnedServerName, ServerName, UserId};
22use tuwunel_core::{
23	Error, Result, at, implement, utils,
24	utils::{
25		IterStream, ReadyExt, TryReadyExt,
26		bytes::prefix_successor,
27		str_from_bytes,
28		stream::{TryIgnore, WidebandExt},
29		time::now_secs,
30	},
31};
32use tuwunel_database::{Database, Deserialized, Interfix, Map, Txn};
33use tuwunel_matrix::ShortRoomId;
34
35use super::{
36	Destination, EduBuf, SendingEvent, TAG_BADGE_REFRESH, TAG_DEVICE_LIST_CHANGED, TAG_TO_DEVICE,
37};
38
39pub(super) type OutgoingItem = (Key, SendingEvent, Destination);
40pub(super) type SendingItem = (Key, SendingEvent);
41
42/// A queued event paired with its row key.
43///
44/// An empty key marks a synthetic wake that has no durable row.
45pub(super) type QueueItem = (Key, SendingEvent);
46pub(super) type Key = Vec<u8>;
47pub(super) type Keys = Vec<Key>;
48
49const PARK_BASE: Duration = Duration::from_hours(1);
50const PARK_LIMIT: Duration = Duration::from_hours(24);
51
52/// A room held back from a server that keeps rejecting it.
53///
54/// The server's queued rows for the room are skipped until `until` passes,
55/// when the room is retried alone; a delivery ends the park.
56#[derive(Clone, Copy, Debug, Eq, PartialEq)]
57pub struct Park {
58	/// The room's short id.
59	pub room: ShortRoomId,
60
61	/// When the room may be sent again, in seconds since the epoch.
62	pub until: u64,
63
64	/// Consecutive parks without a delivery, each doubling the last.
65	pub count: u64,
66}
67
68type ParkRow<'a> = ((&'a ServerName, ShortRoomId), (u64, u64));
69
70/// The sending service's column families.
71///
72/// Queued rows wait in `servernameevent_data` until a transaction claims them
73/// into `servercurrentevent_data`; `servername_educount` is the per-server EDU
74/// watermark, and `servershortroomid_park` holds rooms a server keeps
75/// rejecting.
76pub struct Data {
77	servercurrentevent_data: Arc<Map>,
78	servernameevent_data: Arc<Map>,
79	servername_educount: Arc<Map>,
80	servershortroomid_park: Arc<Map>,
81	pub(super) db: Arc<Database>,
82	services: Arc<crate::services::OnceServices>,
83}
84
85#[implement(Data)]
86pub(super) fn new(args: &crate::Args<'_>) -> Self {
87	let db = &args.db;
88
89	Self {
90		servercurrentevent_data: db["servercurrentevent_data"].clone(),
91		servernameevent_data: db["servernameevent_data"].clone(),
92		servername_educount: db["servername_educount"].clone(),
93		servershortroomid_park: db["servershortroomid_park"].clone(),
94		db: args.db.clone(),
95		services: args.services.clone(),
96	}
97}
98
99#[implement(Data)]
100#[inline]
101pub(super) fn delete_active_request(&self, key: &[u8]) {
102	self.servercurrentevent_data.remove(key);
103}
104
105/// Acknowledges the active rows one transaction carried.
106///
107/// Empty keys mark synthetic events, which have no row.
108#[implement(Data)]
109pub(super) fn delete_active_requests<'a, I>(&self, keys: I)
110where
111	I: IntoIterator<Item = &'a Key>,
112{
113	keys.into_iter()
114		.filter(|key| !key.is_empty())
115		.fold(self.db.txn(), |mut txn, key| {
116			txn.del_raw(&self.servercurrentevent_data, key);
117			txn
118		})
119		.execute();
120}
121
122#[implement(Data)]
123pub(super) async fn delete_all_requests_for(&self, destination: &Destination) -> Result {
124	let prefix = destination.get_prefix();
125
126	self.servercurrentevent_data
127		.raw_keys_prefix(&prefix)
128		.ready_try_for_each(|key| {
129			self.servercurrentevent_data.remove(key);
130
131			Ok(())
132		})
133		.await?;
134
135	self.servernameevent_data
136		.raw_keys_prefix(&prefix)
137		.ready_try_for_each(|key| {
138			self.servernameevent_data.remove(key);
139
140			Ok(())
141		})
142		.await
143}
144
145#[implement(Data)]
146pub(super) fn mark_as_active<'a, I>(&self, events: I)
147where
148	I: Iterator<Item = &'a QueueItem>,
149{
150	events
151		.filter(|(key, _)| !key.is_empty())
152		.fold(self.db.txn(), |mut txn, (key, val)| {
153			txn.insert_raw(&self.servercurrentevent_data, key, val.value_bytes());
154			txn.del_raw(&self.servernameevent_data, key);
155			txn
156		})
157		.execute();
158}
159
160/// Write composed EDUs straight into the active set, keyed by fresh counts.
161///
162/// Unlike `mark_as_active` there is no queue row to delete. Yields the new
163/// keys in `edus` order for the transaction to acknowledge.
164#[implement(Data)]
165pub(super) fn persist_active_edus(
166	&self,
167	server: &ServerName,
168	edus: &[EduBuf],
169) -> vec::IntoIter<Key> {
170	let dest = Destination::Federation(server.to_owned());
171
172	// The permits retire their counts only once the rows have landed.
173	let permits: Vec<_> = edus
174		.iter()
175		.map(|_| self.services.globals.next_count())
176		.collect();
177
178	let keys: Keys = permits
179		.iter()
180		.map(|permit| dest.count_key(**permit))
181		.collect();
182
183	let items = keys
184		.iter()
185		.map(Vec::as_slice)
186		.zip(edus.iter().map(EduBuf::as_slice));
187
188	Txn::insert(&self.servercurrentevent_data, items).execute();
189
190	keys.into_iter()
191}
192
193/// Streams every active row across all destinations.
194///
195/// Rows are decoded as they are read; a row that fails to decode is a
196/// corrupt database and panics.
197#[implement(Data)]
198#[inline]
199pub fn active_requests(&self) -> impl Stream<Item = OutgoingItem> + Send + '_ {
200	self.servercurrentevent_data
201		.raw_stream()
202		.ignore_err()
203		.map(|(key, val)| {
204			let (dest, event) =
205				parse_servercurrentevent(key, val).expect("invalid servercurrentevent");
206
207			(key.to_vec(), event, dest)
208		})
209}
210
211/// Streams the active rows of one destination.
212///
213/// Rows are decoded as they are read; a row that fails to decode is a
214/// corrupt database and panics.
215#[implement(Data)]
216#[inline]
217pub fn active_requests_for(
218	&self,
219	destination: &Destination,
220) -> impl Stream<Item = SendingItem> + Send + '_ + use<'_> {
221	let prefix = destination.get_prefix();
222
223	self.servercurrentevent_data
224		.raw_stream_from(&prefix)
225		.ignore_err()
226		.ready_take_while(move |(key, _)| key.starts_with(&prefix))
227		.map(queue_item)
228}
229
230#[implement(Data)]
231pub(super) fn queue_requests<'a, I>(&self, requests: I) -> Keys
232where
233	I: Iterator<Item = (&'a SendingEvent, &'a Destination)> + Clone + Debug + Send,
234{
235	// The permits retire their counts only once the rows have landed.
236	let (keys, _permits): (Keys, Vec<_>) = requests
237		.clone()
238		.map(|(event, dest)| match event {
239			| SendingEvent::Pdu(pdu_id) => (dest.event_key(pdu_id), None),
240			| _ => {
241				let permit = self.services.globals.next_count();
242
243				(dest.count_key(*permit), Some(permit))
244			},
245		})
246		.unzip();
247
248	let items = keys
249		.iter()
250		.map(Vec::as_slice)
251		.zip(requests.map(at!(0)))
252		.map(|(key, event)| (key, event.value_bytes()));
253
254	Txn::insert(&self.servernameevent_data, items).execute();
255
256	keys
257}
258
259/// Yields only pending queue items.
260///
261/// Empty-key payload wakes always pass because they have no durable row. A
262/// wake can outlive its row after a completed drain delivered the event.
263#[implement(Data)]
264pub(super) fn retain_queued<'a, I>(
265	&'a self,
266	events: I,
267) -> impl Stream<Item = QueueItem> + Send + 'a
268where
269	I: IntoIterator<Item = QueueItem> + Send + 'a,
270	I::IntoIter: Send,
271{
272	iter(events).wide_filter_map(async |item| {
273		let key = &item.0;
274		let pending = key.is_empty()
275			|| self
276				.servernameevent_data
277				.exists(key)
278				.await
279				.is_ok();
280
281		pending.then_some(item)
282	})
283}
284
285/// Streams the queued rows of one destination.
286///
287/// Rows are decoded as they are read; a row that fails to decode is a
288/// corrupt database and panics.
289#[implement(Data)]
290pub fn queued_requests(
291	&self,
292	destination: &Destination,
293) -> impl Stream<Item = QueueItem> + Send + '_ + use<'_> {
294	let prefix = destination.get_prefix();
295
296	self.queued_range(&prefix, prefix_end(prefix.clone()))
297}
298
299/// Streams the queued PDU rows of one room for a destination.
300///
301/// An EDU row whose count equals the room's short id has exactly the room's
302/// key prefix and is skipped.
303#[implement(Data)]
304pub(super) fn queued_room(
305	&self,
306	destination: &Destination,
307	room: ShortRoomId,
308) -> impl Stream<Item = QueueItem> + Send + '_ + use<'_> {
309	let start = destination.count_key(room);
310	let len = start.len();
311	let end = prefix_end(start.clone());
312
313	self.queued_range(&start, end)
314		.ready_filter(move |(key, _)| key.len() > len)
315}
316
317/// Streams the queued rows of one destination, past the PDU rows of `skip`.
318///
319/// `skip` must be sorted. Each skipped room costs one seek rather than a visit
320/// per row, and the EDU row sharing a skipped room's key bytes is still yielded.
321#[implement(Data)]
322pub(super) fn queued_except<'a>(
323	&'a self,
324	destination: &'a Destination,
325	skip: &'a [ShortRoomId],
326) -> impl Stream<Item = QueueItem> + Send + 'a {
327	debug_assert!(skip.is_sorted(), "skipped rooms must be sorted");
328
329	let resumes = skip
330		.iter()
331		.map(|room| destination.count_key(room.saturating_add(1)));
332
333	let ends = skip
334		.iter()
335		.map(|&room| Included(destination.count_key(room)))
336		.chain(once(prefix_end(destination.get_prefix())));
337
338	once(destination.get_prefix())
339		.chain(resumes)
340		.zip(ends)
341		.stream()
342		.flat_map(|(start, end)| self.queued_range(&start, end))
343}
344
345#[implement(Data)]
346fn queued_range(
347	&self,
348	start: &[u8],
349	end: Bound<Key>,
350) -> impl Stream<Item = QueueItem> + Send + '_ + use<'_> {
351	self.servernameevent_data
352		.raw_stream_from(start)
353		.ignore_err()
354		.ready_take_while(move |&(key, _)| match &end {
355			| Included(end) => key <= end.as_slice(),
356			| Excluded(end) => key < end.as_slice(),
357			| Unbounded => true,
358		})
359		.map(queue_item)
360}
361
362/// Moves a failed transaction's PDU rows back to the queue under their own keys.
363///
364/// EDU rows have no room, so they stay active and ride the next transaction.
365/// A park lands in the same batch as the rows it holds back.
366#[implement(Data)]
367pub(super) fn demote<'a, I>(&self, items: I, park: Option<(&ServerName, Park)>)
368where
369	I: IntoIterator<Item = &'a QueueItem>,
370{
371	let txn = items
372		.into_iter()
373		.filter(|(_, event)| matches!(event, SendingEvent::Pdu(_)))
374		.fold(self.db.txn(), |mut txn, (key, _)| {
375			txn.insert_raw(&self.servernameevent_data, key, []);
376			txn.del_raw(&self.servercurrentevent_data, key);
377			txn
378		});
379
380	park.into_iter()
381		.fold(txn, |mut txn, (server, park)| {
382			txn.put(&self.servershortroomid_park, (server, park.room), (park.until, park.count));
383			txn
384		})
385		.execute();
386}
387
388/// Computes the park for a room that failed again.
389///
390/// Each consecutive park doubles the last hold, up to a day; the caller
391/// writes it.
392#[implement(Data)]
393pub(super) async fn next_park(&self, server: &ServerName, room: ShortRoomId) -> Park {
394	let count = self
395		.servershortroomid_park
396		.qry(&(server, room))
397		.await
398		.deserialized()
399		.map_or(1, |(_, count): (u64, u64)| count.saturating_add(1));
400
401	let doublings = u32::try_from(count.saturating_sub(1)).unwrap_or(u32::MAX);
402	let hold = PARK_BASE
403		.saturating_mul(2_u32.saturating_pow(doublings))
404		.min(PARK_LIMIT);
405
406	Park {
407		room,
408		until: now_secs().saturating_add(hold.as_secs()),
409		count,
410	}
411}
412
413#[implement(Data)]
414pub(super) fn unpark(&self, server: &ServerName, room: ShortRoomId) {
415	self.servershortroomid_park.del((server, room));
416}
417
418/// Streams a server's parked rooms, expired ones included.
419///
420/// Rooms come in short id order, so their ids form a sorted skip list.
421#[implement(Data)]
422pub(super) fn parks<'a>(
423	&'a self,
424	server: &'a ServerName,
425) -> impl Stream<Item = Park> + Send + 'a {
426	self.servershortroomid_park
427		.stream_prefix(&(server, Interfix))
428		.ignore_err()
429		.map(park_row)
430		.map(at!(1))
431}
432
433/// Streams every parked room with its server, expired ones included.
434///
435/// The server is owned, so an item may be kept across polls.
436#[implement(Data)]
437pub fn parked(&self) -> impl Stream<Item = (OwnedServerName, Park)> + Send + '_ {
438	self.servershortroomid_park
439		.stream()
440		.ignore_err()
441		.map(park_row)
442		.map(|(server, park)| (server.to_owned(), park))
443}
444
445fn queue_item((key, val): (&[u8], &[u8])) -> QueueItem {
446	let (_, event) = parse_servercurrentevent(key, val).expect("invalid servercurrentevent");
447
448	(key.to_vec(), event)
449}
450
451fn prefix_end(prefix: Key) -> Bound<Key> { prefix_successor(prefix).map_or(Unbounded, Excluded) }
452
453fn park_row(((server, room), (until, count)): ParkRow<'_>) -> (&ServerName, Park) {
454	(server, Park { room, until, count })
455}
456
457/// Streams queued push destinations with a pending badge refresh.
458///
459/// Returned destinations are owned and may safely cross cursor advances.
460#[implement(Data)]
461pub(super) fn queued_badge_refresh_destinations(
462	&self,
463) -> impl Stream<Item = Destination> + Send + '_ {
464	self.servernameevent_data
465		.raw_stream_from(b"$")
466		.ignore_err()
467		.ready_take_while(|(key, _)| key.starts_with(b"$"))
468		.ready_filter_map(|(key, val)| {
469			val.eq(&[TAG_BADGE_REFRESH]).then(|| {
470				parse_servercurrentevent(key, val)
471					.expect("invalid servercurrentevent")
472					.0
473			})
474		})
475}
476
477/// Streams distinct queued federation destinations belonging to this worker.
478///
479/// Each seek copies one key into the owned cursor and skips its complete
480/// destination prefix. Sigils and other shards are skipped before ownership.
481#[implement(Data)]
482pub(super) fn queued_federation_destinations<'a, F>(
483	&'a self,
484	owns: F,
485) -> impl Stream<Item = Result<Destination>> + Send + 'a
486where
487	F: Fn(&ServerName) -> bool + Copy + Send + 'a,
488{
489	queued_destinations(move |key| self.seek_queued_key(key), owns)
490}
491
492fn queued_destinations<S, F, C>(
493	seek: S,
494	owns: C,
495) -> impl Stream<Item = Result<Destination>> + Send
496where
497	S: Fn(Key) -> F + Send,
498	F: Future<Output = Result<Option<Key>>> + Send,
499	C: Fn(&ServerName) -> bool + Copy + Send,
500{
501	unfold((Some(Key::new()), seek, owns), async move |(lower, seek, owns)| {
502		let lower = lower?;
503		let (item, next) = match seek(lower).await {
504			| Ok(None) => return None,
505			| Err(error) => (Err(error), None),
506			| Ok(Some(key)) => queued_destination(key, owns),
507		};
508
509		Some((item, (next, seek, owns)))
510	})
511	.ready_filter_map(Result::transpose)
512}
513
514fn queued_destination(
515	key: Key,
516	owns: impl Fn(&ServerName) -> bool,
517) -> (Result<Option<Destination>>, Option<Key>) {
518	match key.first() {
519		| Some(b'$') => return (Ok(None), Some(single_key(key, b'%'))),
520		| Some(b'+') => return (Ok(None), Some(single_key(key, b','))),
521		| _ => {},
522	}
523
524	let Some(end) = key.iter().position(|byte| *byte == u8::MAX) else {
525		let error = Error::bad_database("Queued federation key has no destination delimiter");
526
527		return (Err(error), Some(after_key(key)));
528	};
529
530	let prefix = truncate_key(key, end.saturating_add(1));
531	let destination = str_from_bytes(&prefix[..end])
532		.ok()
533		.and_then(|server| <&ServerName>::try_from(server).ok())
534		.ok_or_else(|| Error::bad_database("Invalid queued federation destination"))
535		.map(|server| owns(server).then(|| Destination::Federation(server.to_owned())));
536
537	(destination, prefix_successor(prefix))
538}
539
540fn single_key(mut key: Key, byte: u8) -> Key {
541	key.clear();
542	key.push(byte);
543	key
544}
545
546fn after_key(mut key: Key) -> Key {
547	key.push(0);
548	key
549}
550
551fn truncate_key(mut key: Key, len: usize) -> Key {
552	key.truncate(len);
553	key
554}
555
556#[implement(Data)]
557#[tracing::instrument(level = "trace", skip_all)]
558async fn seek_queued_key(&self, mut key: Key) -> Result<Option<Key>> {
559	// The cursor callback copies into the owned seek buffer before its drop.
560	let found = pin!(
561		self.servernameevent_data
562			.raw_keys_from(&key)
563			.map(|item| item.map(|bytes| replace_key(&mut key, bytes)))
564	)
565	.next()
566	.await
567	.transpose()?
568	.is_some();
569
570	Ok(found.then_some(key))
571}
572
573fn replace_key(key: &mut Key, bytes: &[u8]) {
574	key.clear();
575	key.extend_from_slice(bytes);
576}
577
578#[implement(Data)]
579pub(super) fn set_latest_educount(&self, server_name: &ServerName, last_count: u64) {
580	self.servername_educount
581		.raw_put(server_name, last_count);
582}
583
584/// The count of the newest EDU shipped to a server.
585///
586/// A server never shipped to reads as zero, so its first window starts at the
587/// beginning of the log.
588#[implement(Data)]
589pub async fn get_latest_educount(&self, server_name: &ServerName) -> u64 {
590	self.servername_educount
591		.get(server_name)
592		.await
593		.deserialized()
594		.unwrap_or(0)
595}
596
597impl SendingEvent {
598	/// Return bytes written verbatim as the queue row value.
599	///
600	/// PDUs keep their ID in the row key and flushes are not persisted. EDU
601	/// variants own `[tag][count][body]`; a badge refresh owns only its tag.
602	pub(super) fn value_bytes(&self) -> &[u8] {
603		match self {
604			| Self::Edu(bytes) | Self::ToDevice(bytes) | Self::DeviceListChanged(bytes) => bytes,
605			| Self::BadgeRefresh => &[TAG_BADGE_REFRESH],
606			| Self::Pdu(_) | Self::Flush => &[],
607		}
608	}
609}
610
611pub(super) fn parse_servercurrentevent(
612	key: &[u8],
613	value: &[u8],
614) -> Result<(Destination, SendingEvent)> {
615	// Appservices start with a plus
616	Ok::<_, Error>(if key.starts_with(b"+") {
617		let mut parts = key[1..].splitn(2, |&b| b == 0xFF);
618
619		let server = parts
620			.next()
621			.expect("splitn always returns one element");
622		let event = parts
623			.next()
624			.ok_or_else(|| Error::bad_database("Invalid bytes in servercurrentpdus."))?;
625
626		let server = utils::string_from_bytes(server).map_err(|_| {
627			Error::bad_database("Invalid server bytes in server_currenttransaction")
628		})?;
629
630		let decoded = match value {
631			| [] => SendingEvent::Pdu(event.into()),
632			| [TAG_TO_DEVICE, ..] => SendingEvent::ToDevice(value.into()),
633			| [TAG_DEVICE_LIST_CHANGED, ..] => SendingEvent::DeviceListChanged(value.into()),
634			| _ => SendingEvent::Edu(value.into()),
635		};
636
637		(Destination::Appservice(server), decoded)
638	} else if key.starts_with(b"$") {
639		let mut parts = key[1..].splitn(3, |&b| b == 0xFF);
640
641		let user = parts
642			.next()
643			.expect("splitn always returns one element");
644
645		let user_string = str_from_bytes(user)
646			.map_err(|_| Error::bad_database("Invalid user string in servercurrentevent"))?;
647
648		let user_id = UserId::parse(user_string)
649			.map_err(|_| Error::bad_database("Invalid user id in servercurrentevent"))?;
650
651		let pushkey = parts
652			.next()
653			.ok_or_else(|| Error::bad_database("Invalid bytes in servercurrentpdus."))?;
654		let pushkey_string = utils::string_from_bytes(pushkey)
655			.map_err(|_| Error::bad_database("Invalid pushkey in servercurrentevent"))?;
656
657		let event = parts
658			.next()
659			.ok_or_else(|| Error::bad_database("Invalid bytes in servercurrentpdus."))?;
660
661		(Destination::Push(user_id, pushkey_string), match value {
662			| [] => SendingEvent::Pdu(event.into()),
663			| [tag] if *tag == TAG_BADGE_REFRESH => SendingEvent::BadgeRefresh,
664			| _ => SendingEvent::Edu(value.into()),
665		})
666	} else {
667		let mut parts = key.splitn(2, |&b| b == 0xFF);
668
669		let server = parts
670			.next()
671			.expect("splitn always returns one element");
672		let event = parts
673			.next()
674			.ok_or_else(|| Error::bad_database("Invalid bytes in servercurrentpdus."))?;
675
676		let server = utils::string_from_bytes(server).map_err(|_| {
677			Error::bad_database("Invalid server bytes in server_currenttransaction")
678		})?;
679
680		(
681			Destination::Federation(OwnedServerName::parse(&server).map_err(|_| {
682				Error::bad_database("Invalid server string in server_currenttransaction")
683			})?),
684			if value.is_empty() {
685				SendingEvent::Pdu(event.into())
686			} else {
687				SendingEvent::Edu(value.into())
688			},
689		)
690	})
691}