Skip to main content

tuwunel_service/federation/
execute.rs

1//! Resolves, signs, sends, and decodes one outbound federation request.
2//!
3//! Entry points select an HTTP client plus peer-status posture. Destination
4//! validation and resolver-cache eviction remain shared across those postures.
5
6use std::{fmt::Debug, mem, time::Duration};
7
8use bytes::Bytes;
9use http::{Request as HttpRequest, StatusCode, header::CONTENT_TYPE};
10use reqwest::{Method, Request, Response, Url};
11use ruma::{
12	ServerName,
13	api::{
14		EndpointError, IncomingResponse, MatrixVersion, OutgoingRequest, OutgoingRequestExt,
15		SupportedVersions,
16		auth_scheme::AuthScheme,
17		error::{Error as RumaError, ErrorBody, ErrorKind},
18		federation::authentication::{ServerSignatures, ServerSignaturesInput},
19	},
20};
21use tokio::time::timeout;
22use tuwunel_core::{
23	Err, Error, Result, debug, debug::INFO_SPAN_LEVEL, debug_error, debug_warn, err, implement,
24	trace,
25};
26
27use super::{
28	ShouldAttempt,
29	peer::classify_error,
30	scheme::{FedAuth, FedPath},
31};
32use crate::{
33	client::{Federation, read_response_capped},
34	resolver::actual::ActualDest,
35};
36
37type RawRequest = HttpRequest<Vec<u8>>;
38
39/// Sends a federation request with the standard federation client.
40///
41/// The destination is validated and resolved before the request is signed and
42/// sent. Success clears peer failures and classifiable errors record a failure,
43/// except a local refusal; this entry point does not itself consult peer
44/// backoff.
45#[implement(super::Service)]
46#[tracing::instrument(skip_all, name = "request", level = "debug")]
47pub async fn execute<T>(&self, dest: &ServerName, request: T) -> Result<T::IncomingResponse>
48where
49	T: OutgoingRequest + Debug + Send,
50	T::Authentication: FedAuth,
51	T::PathBuilder: FedPath,
52{
53	let client = &self.services.client.federation;
54	self.execute_on(client, dest, request).await
55}
56
57/// Sends a bounded, backoff-aware client key lookup over federation.
58///
59/// `/keys/query` and `/keys/claim` requests skip servers already in backoff and
60/// are limited by `federation_keys_timeout`. The uncounted send path
61/// deliberately records neither success, failure, nor timeout, so a slow key
62/// lookup does not suppress unrelated outbound traffic to the server.
63#[implement(super::Service)]
64#[tracing::instrument(skip_all, name = "keys", level = "debug")]
65pub async fn execute_keys<T>(&self, dest: &ServerName, request: T) -> Result<T::IncomingResponse>
66where
67	T: OutgoingRequest + Debug + Send,
68	T::Authentication: FedAuth,
69	T::PathBuilder: FedPath,
70{
71	if matches!(self.should_attempt(dest).await, ShouldAttempt::No { .. }) {
72		return Err!("{dest} is in federation backoff; skipping key lookup");
73	}
74
75	let timeout_secs = self
76		.services
77		.server
78		.config
79		.federation
80		.transport
81		.keys_timeout;
82
83	let timeout_dur = Duration::from_secs(timeout_secs);
84
85	let client = &self.services.client.federation;
86
87	match timeout(timeout_dur, self.execute_uncounted(client, dest, request)).await {
88		| Ok(result) => result,
89		| Err(_elapsed) => Err!("{dest} key lookup exceeded {}s", timeout_dur.as_secs()),
90	}
91}
92
93/// Sends a federation request with the long-timeout Synapse client.
94///
95/// Resolution, signing, response decoding, and peer-status recording match
96/// [`super::Service::execute`]; only the selected HTTP client differs.
97#[implement(super::Service)]
98#[tracing::instrument(skip_all, name = "synapse", level = "debug")]
99pub async fn execute_synapse<T>(
100	&self,
101	dest: &ServerName,
102	request: T,
103) -> Result<T::IncomingResponse>
104where
105	T: OutgoingRequest + Debug + Send,
106	T::Authentication: FedAuth,
107	T::PathBuilder: FedPath,
108{
109	let client = &self.services.client.synapse;
110	self.execute_on(client, dest, request).await
111}
112
113/// Sends through a supplied client and records the peer outcome.
114///
115/// The destination's resolved route picks the direct or SRV half of the client.
116/// A successful response clears every stored failure row for the destination.
117/// A request refused because federation is disabled or the server is forbidden
118/// records nothing; other errors are recorded only when classified as peer
119/// failures, and no backoff gate is consulted before sending.
120#[implement(super::Service)]
121pub async fn execute_on<T>(
122	&self,
123	client: &Federation,
124	dest: &ServerName,
125	request: T,
126) -> Result<T::IncomingResponse>
127where
128	T: OutgoingRequest + Send,
129	T::Authentication: FedAuth,
130	T::PathBuilder: FedPath,
131{
132	let result = self
133		.execute_uncounted(client, dest, request)
134		.await;
135
136	self.record_outcome(dest, result.as_ref().err())
137		.await;
138
139	result
140}
141
142#[implement(super::Service)]
143async fn record_outcome(&self, dest: &ServerName, error: Option<&Error>) {
144	if error.is_some_and(is_local_refusal) {
145		return;
146	}
147
148	match error.map(classify_error) {
149		| None => self.record_success(dest).await,
150		| Some(Some(class)) => self.record_failure(dest, class),
151		| Some(None) => {},
152	}
153}
154
155// Only `require_remote_permitted` raises this on the send path; a peer's 403 is `Federation`.
156fn is_local_refusal(error: &Error) -> bool {
157	matches!(error, Error::Request(ErrorKind::Forbidden, ..))
158}
159
160/// Executes one Feds request while permitting only this server as a
161/// self-destination and preserving ordinary peer-status recording.
162///
163/// Other federation entry points retain the configured loopback gate. A request
164/// refused because federation is disabled or the server is forbidden records
165/// nothing.
166#[implement(super::Service)]
167pub(super) async fn execute_on_allow_self<T>(
168	&self,
169	client: &Federation,
170	dest: &ServerName,
171	request: T,
172) -> Result<T::IncomingResponse>
173where
174	T: OutgoingRequest + Send,
175	T::Authentication: FedAuth,
176	T::PathBuilder: FedPath,
177{
178	let result = self
179		.execute_uncounted_allow_self(client, dest, request)
180		.await;
181
182	self.record_outcome(dest, result.as_ref().err())
183		.await;
184
185	result
186}
187
188/// Sends through a supplied client without changing peer status.
189///
190/// Callers that gate separately can honor existing backoff without adding
191/// success or failure records.
192#[implement(super::Service)]
193#[tracing::instrument(
194	name = "fed",
195	level = INFO_SPAN_LEVEL,
196	skip(self, client, request),
197)]
198pub(super) async fn execute_uncounted<T>(
199	&self,
200	client: &Federation,
201	dest: &ServerName,
202	request: T,
203) -> Result<T::IncomingResponse>
204where
205	T: OutgoingRequest + Send,
206	T::Authentication: FedAuth,
207	T::PathBuilder: FedPath,
208{
209	self.validate_request_destination(dest)?;
210	let actual = self
211		.services
212		.resolver
213		.get_actual_dest(dest)
214		.await?;
215	let request = self.prepare(&actual, dest, request)?;
216
217	self.perform::<T>(&actual, dest, request, client)
218		.await
219}
220
221/// Executes one Feds request while permitting only this server as a
222/// self-destination and leaving peer status untouched.
223///
224/// Other federation entry points retain the configured loopback gate.
225#[implement(super::Service)]
226#[tracing::instrument(name = "fed", level = "debug", skip(self, client, request))]
227pub(super) async fn execute_uncounted_allow_self<T>(
228	&self,
229	client: &Federation,
230	dest: &ServerName,
231	request: T,
232) -> Result<T::IncomingResponse>
233where
234	T: OutgoingRequest + Send,
235	T::Authentication: FedAuth,
236	T::PathBuilder: FedPath,
237{
238	self.validate_request_destination(dest)?;
239	let actual = self
240		.services
241		.resolver
242		.get_actual_dest_allow_self(dest)
243		.await?;
244	let request = self.prepare(&actual, dest, request)?;
245
246	self.perform::<T>(&actual, dest, request, client)
247		.await
248}
249
250/// MSC4512: sends a signed federation request built from a raw method, path
251/// and body.
252///
253/// The destination is validated and resolved as for a typed request, and the
254/// request signed as this server. The remote's status and body come back
255/// whatever the status, the body read up to the response size limit. No
256/// backoff is consulted and no outcome recorded, as for an appservice's
257/// request no peer state should rest on.
258#[implement(super::Service)]
259#[tracing::instrument(name = "fed_raw", level = "debug", skip(self, body))]
260pub async fn execute_raw(
261	&self,
262	dest: &ServerName,
263	method: Method,
264	path_and_query: &str,
265	body: Option<Vec<u8>>,
266) -> Result<(StatusCode, Bytes)> {
267	self.validate_request_destination(dest)?;
268	let actual = self
269		.services
270		.resolver
271		.get_actual_dest(dest)
272		.await?;
273
274	let request = self.raw_request(&actual, dest, method, path_and_query, body)?;
275	let request = Request::try_from(request)?;
276
277	self.validate_url(request.url())?;
278	self.services.server.check_running()?;
279
280	let url = request.url().clone();
281	let method = request.method().clone();
282	let client = &self.services.client.federation;
283	let response = match client.for_srv(actual.srv).execute(request).await {
284		| Ok(response) => response,
285		| Err(error) =>
286			return Err(self
287				.handle_error(dest, &actual, &method, &url, error)
288				.expect_err("always returns error")),
289	};
290
291	let limit = self
292		.services
293		.server
294		.config
295		.network
296		.http
297		.max_response_size;
298
299	let status = response.status();
300	let body = read_response_capped(response, limit).await?;
301
302	Ok((status, body))
303}
304
305#[implement(super::Service)]
306fn raw_request(
307	&self,
308	actual: &ActualDest,
309	dest: &ServerName,
310	method: Method,
311	path_and_query: &str,
312	body: Option<Vec<u8>>,
313) -> Result<RawRequest> {
314	let builder = HttpRequest::builder()
315		.method(method)
316		.uri(format!("{}{path_and_query}", actual.to_string()));
317
318	let request = match body {
319		| None => builder.body(Vec::new())?,
320		| Some(body) => builder
321			.header(CONTENT_TYPE, "application/json")
322			.body(body)?,
323	};
324
325	let input = ServerSignaturesInput::new(
326		self.services.server.name.clone(),
327		dest.to_owned(),
328		self.services.server_keys.keypair(),
329	);
330
331	signed(request, input)
332}
333
334fn signed(mut request: RawRequest, input: ServerSignaturesInput<'_>) -> Result<RawRequest> {
335	ServerSignatures::add_authentication(&mut request, input)
336		.map_err(|e| err!(BadServerResponse("Failed to sign the federation request: {e}")))?;
337
338	Ok(request)
339}
340
341#[implement(super::Service)]
342fn validate_request_destination(&self, dest: &ServerName) -> Result {
343	self.services
344		.server
345		.config
346		.require_remote_permitted(dest)
347}
348
349#[implement(super::Service)]
350async fn perform<T>(
351	&self,
352	actual: &ActualDest,
353	dest: &ServerName,
354	request: Request,
355	client: &Federation,
356) -> Result<T::IncomingResponse>
357where
358	T: OutgoingRequest + Send,
359	T::Authentication: FedAuth,
360	T::PathBuilder: FedPath,
361{
362	let url = request.url().clone();
363	let method = request.method().clone();
364
365	debug!(?method, ?url, "Sending request");
366	let limit = self
367		.services
368		.server
369		.config
370		.network
371		.http
372		.max_response_size;
373
374	match client.for_srv(actual.srv).execute(request).await {
375		| Ok(response) => handle_response::<T>(actual, dest, &method, &url, response, limit)
376			.await
377			.inspect_err(|error| self.evict_misrouted(dest, actual, error)),
378		| Err(error) => Err(self
379			.handle_error(dest, actual, &method, &url, error)
380			.expect_err("always returns error")),
381	}
382}
383
384#[implement(super::Service)]
385pub(super) fn prepare<T>(
386	&self,
387	actual: &ActualDest,
388	dest: &ServerName,
389	request: T,
390) -> Result<Request>
391where
392	T: OutgoingRequest + Send,
393	T::Authentication: FedAuth,
394	T::PathBuilder: FedPath,
395{
396	let request = self.to_http_request::<T>(actual, dest, request)?;
397	let request = Request::try_from(request)?;
398	self.validate_url(request.url())?;
399	self.services.server.check_running()?;
400
401	Ok(request)
402}
403
404#[implement(super::Service)]
405pub(super) fn validate_url(&self, url: &Url) -> Result {
406	if !self.services.client.valid_cidr_range_url(url) {
407		return Err!(BadServerResponse("Not allowed to send requests to this IP"));
408	}
409
410	Ok(())
411}
412
413async fn handle_response<T>(
414	actual: &ActualDest,
415	dest: &ServerName,
416	method: &Method,
417	url: &Url,
418	response: Response,
419	limit: usize,
420) -> Result<T::IncomingResponse>
421where
422	T: OutgoingRequest + Send,
423	T::Authentication: FedAuth,
424	T::PathBuilder: FedPath,
425{
426	let response = into_http_response(dest, actual, method, url, response, limit).await?;
427
428	T::IncomingResponse::try_from_http_response(response)
429		.map_err(|e| err!(BadServerResponse("Server returned bad 200 response: {e:?}")))
430}
431
432async fn into_http_response(
433	dest: &ServerName,
434	actual: &ActualDest,
435	method: &Method,
436	url: &Url,
437	mut response: Response,
438	limit: usize,
439) -> Result<http::Response<Bytes>> {
440	let status = response.status();
441	trace!(
442		?status, ?method,
443		request_url = ?url,
444		response_url = ?response.url(),
445		"Received response from {}",
446		actual.to_string(),
447	);
448
449	let mut http_response_builder = http::Response::builder()
450		.status(status)
451		.version(response.version());
452
453	mem::swap(
454		response.headers_mut(),
455		http_response_builder
456			.headers_mut()
457			.expect("http::response::Builder is usable"),
458	);
459
460	// TODO: handle timeout
461	trace!("Waiting for response body...");
462	let body = read_response_capped(response, limit).await?;
463
464	let http_response = http_response_builder
465		.body(body)
466		.expect("reqwest body is valid http body");
467
468	debug!("Got {status:?} for {method} {url}");
469	if !status.is_success() {
470		return Err(Error::Federation(
471			dest.to_owned(),
472			RumaError::from_http_response(http_response),
473		));
474	}
475
476	Ok(http_response)
477}
478
479#[implement(super::Service)]
480fn handle_error(
481	&self,
482	dest: &ServerName,
483	actual: &ActualDest,
484	method: &Method,
485	url: &Url,
486	mut e: reqwest::Error,
487) -> Result {
488	if e.is_timeout() || e.is_connect() {
489		e = e.without_url();
490		debug_warn!("{e:?}");
491	} else if e.is_redirect() {
492		debug_error!(
493			method = ?method,
494			url = ?url,
495			final_url = ?e.url(),
496			"Redirect loop {}: {}",
497			actual.host,
498			e,
499		);
500	} else {
501		debug_error!("{e:?}");
502	}
503
504	self.evict_route(dest, actual);
505
506	Err(e.into())
507}
508
509// A non-JSON federation response means a proxy or CDN answered, not the
510// homeserver, so the cached route is stale; evict it as transport errors do.
511#[implement(super::Service)]
512fn evict_misrouted(&self, dest: &ServerName, actual: &ActualDest, error: &Error) {
513	let Error::Federation(_, response) = error else {
514		return;
515	};
516
517	if matches!(response.body, ErrorBody::NotJson { .. }) {
518		self.evict_route(dest, actual);
519	}
520}
521
522// Only an SRV route resolves through an override, keyed by the hostname it was
523// written under (`actual.dest.hostname()`), not the origin name.
524#[implement(super::Service)]
525fn evict_route(&self, dest: &ServerName, actual: &ActualDest) {
526	let cache = &self.services.resolver.cache;
527
528	cache.del_destination(dest);
529	if actual.srv {
530		cache.del_override(&actual.dest.hostname());
531	}
532}
533
534#[implement(super::Service)]
535fn to_http_request<T>(
536	&self,
537	actual: &ActualDest,
538	dest: &ServerName,
539	request: T,
540) -> Result<http::Request<Vec<u8>>>
541where
542	T: OutgoingRequest + Send,
543	T::Authentication: FedAuth,
544	T::PathBuilder: FedPath,
545{
546	const VERSIONS: [MatrixVersion; 1] = [MatrixVersion::V1_11];
547	let supported = SupportedVersions {
548		versions: VERSIONS.into(),
549		features: Default::default(),
550	};
551
552	let auth = T::Authentication::input(
553		self.services.server.name.clone(),
554		dest.to_owned(),
555		self.services.server_keys.keypair(),
556	);
557	let path = T::PathBuilder::input(&supported);
558
559	request
560		.try_into_http_request::<Vec<u8>>(actual.to_string().as_str(), auth, path)
561		.map_err(|e| err!(BadServerResponse("Invalid destination: {e:?}")))
562}