Skip to main content

tuwunel_service/migrations/
token_expiry.rs

1use std::{pin::pin, sync::Arc};
2
3use futures::{TryFutureExt, TryStreamExt};
4use ruma::{DeviceId, UserId};
5use tuwunel_core::{Result, debug_warn, err, info, warn};
6use tuwunel_database::Map;
7
8use crate::{
9	Services,
10	integrity::token_expiry::{Row, Token, origin, rows, token},
11};
12
13/// Stamped once every origin expiry has been adopted.
14///
15/// Withheld while no OIDC provider is configured and a row is still adoptable,
16/// and cleared by the restore before it walks.
17pub(super) const ADOPT_MARKER: &str = "adopt_foreign_token_expiry";
18
19/// Stamped once every expiry adopted without a provider has been restored.
20///
21/// Withheld while a provider is configured, so a provider removed later still
22/// gets the restore.
23pub(super) const RESTORE_MARKER: &str = "restore_foreign_token_expiry";
24
25/// Counts of what one walk of the origin column did.
26///
27/// A skipped row and an unreadable one are counted apart because only the
28/// second withholds the marker, and withholding it retries the whole pass on the
29/// next boot.
30#[derive(Default)]
31struct Tally {
32	applied: usize,
33	skipped: usize,
34	unreadable: usize,
35}
36
37/// What a walk does to the token an origin row names.
38///
39/// One walk serves every pass over the column, resolving each row through the
40/// same lookups and the same provenance guard before the mode decides what, if
41/// anything, is written.
42#[derive(Clone, Copy)]
43enum Mode {
44	/// Reports whether the row could be adopted, without writing.
45	Probe,
46
47	/// Stamps the origin expiry onto the token.
48	Adopt,
49
50	/// Puts a token carrying the stamped expiry back into the foreign shape.
51	Restore,
52}
53
54/// Whether the restore of adopted expiries has work on this boot.
55///
56/// The ladder hands the adoption's stamp back only when the restore walks, so it
57/// needs to know which case holds before the walk begins.
58pub(super) enum Restore {
59	/// The database holds no origin column, so nothing was adopted from one.
60	Finished,
61
62	/// A provider is configured, against which an adopted expiry refreshes.
63	Waiting,
64
65	/// The origin column, whose adopted expiries go back to the foreign shape.
66	Due(Arc<Map>),
67}
68
69/// Adopts the access-token expiry a foreign database keeps in a column of its
70/// own, returning whether the pass is finished with that column.
71///
72/// That column is keyed by device while this server keeps the expiry alongside
73/// the owner in the shared token column, so a migrated session keeps
74/// authenticating while its expiry does not.
75///
76/// Every row names an OAuth session whose client can only recover from the
77/// expiry by refreshing against an OIDC provider here, so without one the pass
78/// waits, unfinished, rather than stranding sessions. With one it adopts once,
79/// since this server writes the same column afterward and a second pass would
80/// resurrect a replaced expiry.
81#[tracing::instrument(level = "debug", skip_all)]
82pub(super) async fn migrate(services: &Services) -> Result<bool> {
83	let Some(tokenexpires) = origin(services)? else {
84		return Ok(true);
85	};
86
87	adopt(services, &tokenexpires).await
88}
89
90/// Adopts the expiries an opened origin column records, returning whether the
91/// pass is finished with it.
92///
93/// Without an OIDC provider nothing is written, and the pass is finished only
94/// once no row is left that the adoption could still carry.
95#[tracing::instrument(level = "debug", skip_all)]
96pub(super) async fn adopt(services: &Services, tokenexpires: &Arc<Map>) -> Result<bool> {
97	if services.oauth.get_server().is_err() {
98		let waiting = probe(services, tokenexpires).await?;
99
100		if waiting {
101			info!("Migrated OAuth sessions keep their origin lifetime; no OIDC provider");
102		}
103
104		return Ok(!waiting);
105	}
106
107	let Tally { applied: adopted, skipped, .. } =
108		walk(services, tokenexpires, Mode::Adopt).await?;
109
110	// A skipped row is usually a device this pass correctly left alone, so the
111	// summary counts them without implying a loss; a real loss logs per row.
112	if adopted > 0 || skipped > 0 {
113		info!(%adopted, %skipped, "Adopted token expiry from a foreign database");
114	}
115
116	Ok(true)
117}
118
119/// Decides whether the restore walks on this boot, opening the origin column if
120/// so.
121///
122/// Before the adoption waited for a provider it stamped every origin expiry,
123/// each long past, so a session that has not authenticated since is refused on
124/// its next request while its client, with nothing to refresh against, never
125/// signs out. With a provider an adopted expiry can be refreshed and stays, so
126/// the pass waits rather than finishing, and a provider removed later still gets
127/// the restore.
128pub(super) fn restore_due(services: &Services) -> Result<Restore> {
129	let Some(tokenexpires) = origin(services)? else {
130		return Ok(Restore::Finished);
131	};
132
133	if services.oauth.get_server().is_ok() {
134		return Ok(Restore::Waiting);
135	}
136
137	Ok(Restore::Due(tokenexpires))
138}
139
140/// Restores the origin lifetime of each session an earlier release adopted with
141/// no provider to refresh it against.
142///
143/// The origin column still names every adopted device with the value stamped,
144/// so a token carrying exactly that value goes back to the foreign shape, for
145/// the adoption to carry again once a provider is configured.
146#[tracing::instrument(level = "debug", skip_all)]
147pub(super) async fn restore(services: &Services, tokenexpires: &Arc<Map>) -> Result {
148	let Tally { applied: restored, skipped, .. } =
149		walk(services, tokenexpires, Mode::Restore).await?;
150
151	if restored > 0 || skipped > 0 {
152		info!(
153			%restored,
154			%skipped,
155			"Restored the origin lifetime of adopted OAuth sessions; no OIDC provider"
156		);
157	}
158
159	Ok(())
160}
161
162/// Whether the origin column holds a row the adoption could still carry.
163///
164/// The first adoptable row answers, so a column of rows this server can never
165/// adopt is walked whole while one with work waiting costs a single hit.
166async fn probe(services: &Services, tokenexpires: &Arc<Map>) -> Result<bool> {
167	let mut adoptable = pin!(rows(services, tokenexpires).try_filter_map(|row| {
168		apply_one(services, row, Mode::Probe).map_ok(|adoptable| adoptable.then_some(()))
169	}));
170
171	adoptable
172		.try_next()
173		.map_ok(|hit| hit.is_some())
174		.await
175}
176
177/// Walks the origin column once, applying the mode to every row.
178///
179/// One row at a time: each is read before it is rewritten, so a concurrent walk
180/// could let two rows naming one token both clear the provenance guard. A
181/// cursor error ends the walk rather than being counted, because the status is
182/// sticky and the iterator cannot advance past it. An unreadable row fails the
183/// walk too, since leaving the marker unstamped is what makes an engine failure
184/// recoverable: the pass is idempotent, so the next boot retries it whole.
185async fn walk(services: &Services, tokenexpires: &Arc<Map>, mode: Mode) -> Result<Tally> {
186	let cork = services.db.cork_and_sync();
187
188	let tally = rows(services, tokenexpires)
189		.try_fold(Tally::default(), async |tally, row| {
190			let result = apply_one(services, row, mode)
191				.inspect_err(|e| warn!(error = %e, "a token expiry could not be read"))
192				.await;
193
194			Ok(tally.record(&result))
195		})
196		.await?;
197
198	drop(cork);
199
200	let unreadable = tally.unreadable;
201
202	unreadable
203		.eq(&0)
204		.then_some(tally)
205		.ok_or_else(|| err!(Database("{unreadable} token expiries could not be read")))
206}
207
208impl Tally {
209	fn record(mut self, result: &Result<bool>) -> Self {
210		let count = match result {
211			| Ok(true) => &mut self.applied,
212			| Ok(false) => &mut self.skipped,
213			| Err(_) => &mut self.unreadable,
214		};
215
216		*count = count.saturating_add(1);
217		self
218	}
219}
220
221/// Applies the mode to the token one origin row names, reporting whether the
222/// row was acted on.
223///
224/// A `false` return is a row with nothing to do: one this pass cannot make
225/// sense of, a device holding no token here, a token this server does not hold,
226/// or a stored value the mode leaves as it is. Only a failed lookup returns an
227/// error, because a row that will never decode would otherwise refuse every
228/// later boot as well.
229async fn apply_one(services: &Services, row: Row, mode: Mode) -> Result<bool> {
230	let (user_id, device_id, expires) = match row {
231		| Row::Expiry { user_id, device_id, expires, .. } => (user_id, device_id, expires),
232		| Row::UnparsableDevice { .. } => {
233			warn!("skipping a foreign token expiry whose device could not be read");
234			return Ok(false);
235		},
236		| Row::UnparsableExpiry { user_id, device_id } => {
237			warn!(%user_id, %device_id, "skipping a foreign token expiry that could not be read");
238			return Ok(false);
239		},
240	};
241
242	let held = match (token(services, &user_id, &device_id, expires).await?, mode) {
243		| (Token::Adoptable(held), Mode::Probe | Mode::Adopt)
244		| (Token::Adopted(held), Mode::Restore) => held,
245		| (token, _) => {
246			skip(&token, &user_id, &device_id);
247			return Ok(false);
248		},
249	};
250
251	let token_owners = &services.db["token_userdeviceid"];
252	let (owner, device) = (&*held.user_id, &*held.device_id);
253
254	match mode {
255		| Mode::Probe => {},
256		| Mode::Adopt => {
257			token_owners.raw_put(held.token.as_str(), (owner, device, Some(expires)));
258			info!(%user_id, %device_id, "adopted the origin expiry of an access token");
259		},
260		| Mode::Restore => {
261			token_owners.raw_put(held.token.as_str(), (owner, device));
262			info!(%user_id, %device_id, "restored the origin lifetime of an access token");
263		},
264	}
265
266	Ok(true)
267}
268
269fn skip(token: &Token, user_id: &UserId, device_id: &DeviceId) {
270	match token {
271		| Token::Absent => {
272			debug_warn!(%user_id, %device_id, "skipping a device holding no access token here");
273		},
274		| Token::Unparsable => {
275			warn!(%user_id, %device_id, "skipping a device whose stored token could not be read");
276		},
277		| Token::Unheld => {
278			debug_warn!(%user_id, %device_id, "skipping an access token this server does not hold");
279		},
280		| Token::UnparsableValue => {
281			warn!(%user_id, %device_id, "skipping a token value that could not be read");
282		},
283		| Token::Adoptable(_) | Token::Adopted(_) | Token::Kept => {
284			debug_warn!(%user_id, %device_id, "skipping a token value this pass leaves as stored");
285		},
286	}
287}