Skip to main content

tuwunel_service/media/
remote.rs

1use std::{fmt::Debug, time::Duration};
2
3use http::header::{CONTENT_DISPOSITION, CONTENT_TYPE, HeaderValue};
4use ruma::{
5	Mxc, ServerName,
6	api::{
7		OutgoingRequest,
8		client::media,
9		error::ErrorKind::{NotFound, Unrecognized},
10		federation,
11		federation::authenticated_media::{Content, FileOrLocation},
12	},
13	http_headers::ContentDisposition,
14};
15use tuwunel_core::{
16	Err, Error, Result, debug_warn, err, implement,
17	utils::content_disposition::make_content_disposition,
18};
19use url::Url;
20
21use super::{Animate, Dim, Fetched, Media, preview::Agent, thumbnail::sequence};
22use crate::{
23	client::read_response_capped,
24	federation::scheme::{FedAuth, FedPath},
25};
26
27/// Which client fetches a media location, and as whom.
28///
29/// The client and the agent are not independent, so they travel together:
30/// only preview media carries a configured agent, and only the extern client
31/// serves federation and remote-media downloads.
32pub(super) enum Fetch {
33	Extern,
34	Preview(Agent),
35}
36
37/// Fetches a thumbnail at this dimension from the origin server.
38///
39/// The authenticated endpoint is asked first, falling back to the legacy one
40/// only where the peer answers no such media and this server is configured to
41/// ask. What the walk filing the answer settled travels back with it, so a
42/// caller deciding whether the picture may be served reads no bytes again.
43#[implement(super::Service)]
44#[tracing::instrument(level = "debug", skip(self))]
45pub async fn fetch_remote_thumbnail(
46	&self,
47	mxc: &Mxc<'_>,
48	server: Option<&ServerName>,
49	timeout_ms: Duration,
50	dim: &Dim,
51	animate: Animate,
52) -> Result<Fetched> {
53	self.check_fetch_authorized(mxc)?;
54
55	let result = self
56		.fetch_thumbnail_authenticated(mxc, server, timeout_ms, dim, animate)
57		.await;
58
59	if let Err(Error::Request(NotFound, ..)) = &result
60		&& self.services.server.config.media.request_legacy
61	{
62		return self
63			.fetch_thumbnail_unauthenticated(mxc, server, timeout_ms, dim, animate)
64			.await;
65	}
66
67	result
68}
69
70/// Fetches the original file from the origin server.
71///
72/// The authenticated endpoint is asked first, falling back to the legacy one
73/// only where the peer answers no such media and this server is configured to
74/// ask. What the walk filing the answer settled travels back with it, so a
75/// caller deciding whether the picture may be served reads no bytes again.
76#[implement(super::Service)]
77#[tracing::instrument(level = "debug", skip(self))]
78pub async fn fetch_remote_content(
79	&self,
80	mxc: &Mxc<'_>,
81	server: Option<&ServerName>,
82	timeout_ms: Duration,
83) -> Result<Fetched> {
84	self.check_fetch_authorized(mxc)?;
85
86	let result = self
87		.fetch_content_authenticated(mxc, server, timeout_ms)
88		.await;
89
90	if let Err(Error::Request(NotFound, ..)) = &result
91		&& self.services.server.config.media.request_legacy
92	{
93		return self
94			.fetch_content_unauthenticated(mxc, server, timeout_ms)
95			.await;
96	}
97
98	result
99}
100
101#[implement(super::Service)]
102async fn fetch_thumbnail_authenticated(
103	&self,
104	mxc: &Mxc<'_>,
105	server: Option<&ServerName>,
106	timeout_ms: Duration,
107	dim: &Dim,
108	animate: Animate,
109) -> Result<Fetched> {
110	use federation::authenticated_media::get_content_thumbnail::v1::{Request, Response};
111
112	let request = Request {
113		media_id: mxc.media_id.into(),
114		method: dim.method.clone().into(),
115		width: dim.width.into(),
116		height: dim.height.into(),
117		animated: animate.into(),
118		timeout_ms,
119	};
120
121	let Response { content, .. } = self
122		.federation_request(mxc, server, request)
123		.await?;
124
125	match content {
126		| FileOrLocation::File(content) =>
127			self.handle_thumbnail_file(mxc, dim, content)
128				.await,
129		| FileOrLocation::Location(location) => self.handle_location(mxc, &location).await,
130	}
131}
132
133#[implement(super::Service)]
134async fn fetch_content_authenticated(
135	&self,
136	mxc: &Mxc<'_>,
137	server: Option<&ServerName>,
138	timeout_ms: Duration,
139) -> Result<Fetched> {
140	use federation::authenticated_media::get_content::v1::{Request, Response};
141
142	let request = Request {
143		media_id: mxc.media_id.into(),
144		timeout_ms,
145	};
146
147	let Response { content, .. } = self
148		.federation_request(mxc, server, request)
149		.await?;
150
151	match content {
152		| FileOrLocation::File(content) => self.handle_content_file(mxc, content).await,
153		| FileOrLocation::Location(location) => self.handle_location(mxc, &location).await,
154	}
155}
156
157#[expect(deprecated)]
158#[implement(super::Service)]
159async fn fetch_thumbnail_unauthenticated(
160	&self,
161	mxc: &Mxc<'_>,
162	server: Option<&ServerName>,
163	timeout_ms: Duration,
164	dim: &Dim,
165	animate: Animate,
166) -> Result<Fetched> {
167	use media::get_content_thumbnail::v3::{Request, Response};
168
169	let request = Request {
170		allow_remote: true,
171		allow_redirect: false,
172		animated: animate.into(),
173		method: dim.method.clone().into(),
174		width: dim.width.into(),
175		height: dim.height.into(),
176		server_name: mxc.server_name.into(),
177		media_id: mxc.media_id.into(),
178		timeout_ms,
179	};
180
181	let Response {
182		file, content_type, content_disposition, ..
183	} = self
184		.federation_request(mxc, server, request)
185		.await?;
186
187	let content = Content { file, content_type, content_disposition };
188
189	self.handle_thumbnail_file(mxc, dim, content)
190		.await
191}
192
193#[expect(deprecated)]
194#[implement(super::Service)]
195async fn fetch_content_unauthenticated(
196	&self,
197	mxc: &Mxc<'_>,
198	server: Option<&ServerName>,
199	timeout_ms: Duration,
200) -> Result<Fetched> {
201	use media::get_content::v3::{Request, Response};
202
203	let request = Request {
204		allow_remote: true,
205		allow_redirect: false,
206		server_name: mxc.server_name.into(),
207		media_id: mxc.media_id.into(),
208		timeout_ms,
209	};
210
211	let Response {
212		file, content_type, content_disposition, ..
213	} = self
214		.federation_request(mxc, server, request)
215		.await?;
216
217	let content = Content { file, content_type, content_disposition };
218
219	self.handle_content_file(mxc, content).await
220}
221
222#[implement(super::Service)]
223async fn handle_thumbnail_file(
224	&self,
225	mxc: &Mxc<'_>,
226	dim: &Dim,
227	content: Content,
228) -> Result<Fetched> {
229	let content_disposition = make_content_disposition(
230		content.content_disposition.as_ref(),
231		content.content_type.as_deref(),
232		None,
233	);
234
235	let walk = sequence(&content.file);
236	let content_type = walk.stored_type(content.content_type.as_deref());
237
238	self.upload_thumbnail(mxc, Some(&content_disposition), content_type, dim, &content.file)
239		.await?;
240
241	let animates = Some(walk.animates());
242	let media = fetched_media(content, content_disposition);
243
244	Ok(Fetched { media, animates })
245}
246
247#[implement(super::Service)]
248async fn handle_content_file(&self, mxc: &Mxc<'_>, content: Content) -> Result<Fetched> {
249	let content_disposition = make_content_disposition(
250		content.content_disposition.as_ref(),
251		content.content_type.as_deref(),
252		None,
253	);
254
255	let animates = self
256		.create(
257			mxc,
258			None,
259			Some(&content_disposition),
260			content.content_type.as_deref(),
261			&content.file,
262		)
263		.await
264		.map(Some)?;
265
266	let media = fetched_media(content, content_disposition);
267
268	Ok(Fetched { media, animates })
269}
270
271#[implement(super::Service)]
272async fn handle_location(&self, mxc: &Mxc<'_>, location: &str) -> Result<Fetched> {
273	let limit = self
274		.services
275		.server
276		.config
277		.network
278		.http
279		.max_response_size;
280
281	let media = self
282		.location_request(Fetch::Extern, location, limit)
283		.await
284		.map_err(|error| {
285			err!(Request(NotFound(
286				debug_warn!(%mxc, ?location, ?error, "Fetching media from location failed")
287			)))
288		})?;
289
290	// nothing files a redirected object, so no walk of it has happened and the
291	// one caller that asks pays for its own
292	Ok(Fetched { media, animates: None })
293}
294
295/// Assembles what a peer answered into media under the disposition it was
296/// filed with.
297///
298/// The type reported is the one the peer declared, where the row it was filed
299/// under carries whatever its own container named instead.
300fn fetched_media(content: Content, content_disposition: ContentDisposition) -> Media {
301	Media {
302		content: content.file,
303		content_type: content.content_type.map(Into::into),
304		content_disposition: Some(content_disposition),
305	}
306}
307
308#[implement(super::Service)]
309pub(super) async fn location_request(
310	&self,
311	fetch: Fetch,
312	location: &str,
313	limit: usize,
314) -> Result<Media> {
315	let url = Url::parse(location)
316		.map_err(|e| err!(Request(Unknown("Invalid media location URL: {e}"))))?;
317
318	self.check_url_host(&url)?;
319
320	let request = match fetch {
321		| Fetch::Extern => self
322			.services
323			.client
324			.extern_media
325			.get(url.as_str()),
326		| Fetch::Preview(agent) => {
327			let request = self.services.client.url_preview.get(url.as_str());
328
329			self.preview_headers(request, &url, agent)
330		},
331	};
332
333	let response = request.send().await?;
334
335	// a missing peer address cannot be screened, so fail closed
336	let Some(remote_addr) = response.remote_addr() else {
337		return Err!(Request(Forbidden("Media response has no peer address")));
338	};
339
340	if !self
341		.services
342		.client
343		.valid_cidr_range_remote_addr(response.url(), remote_addr)
344	{
345		return Err!(Request(Forbidden("Requesting from this address is forbidden")));
346	}
347
348	// an upstream error document must not be relayed as media
349	if !response.status().is_success() {
350		return Err!(Request(NotFound(debug_warn!(
351			status = ?response.status(),
352			%url,
353			"Fetching media from location failed"
354		))));
355	}
356
357	let content_type = response
358		.headers()
359		.get(CONTENT_TYPE)
360		.map(HeaderValue::to_str)
361		.and_then(Result::ok)
362		.map(str::to_owned);
363
364	let content_disposition = response
365		.headers()
366		.get(CONTENT_DISPOSITION)
367		.map(HeaderValue::as_bytes)
368		.map(TryFrom::try_from)
369		.and_then(Result::ok);
370
371	let content = read_response_capped(response, limit).await?;
372
373	Ok(Media {
374		content: content.to_vec(),
375		content_type: content_type.clone(),
376		content_disposition: Some(make_content_disposition(
377			content_disposition.as_ref(),
378			content_type.as_deref(),
379			None,
380		)),
381	})
382}
383
384#[implement(super::Service)]
385async fn federation_request<Request>(
386	&self,
387	mxc: &Mxc<'_>,
388	server: Option<&ServerName>,
389	request: Request,
390) -> Result<Request::IncomingResponse>
391where
392	Request: OutgoingRequest + Send + Debug,
393	Request::Authentication: FedAuth,
394	Request::PathBuilder: FedPath,
395{
396	// query-depth firewall
397	let fetch = Box::pin(
398		self.services
399			.federation
400			.execute(server.unwrap_or(mxc.server_name), request),
401	);
402
403	fetch
404		.await
405		.map_err(|error| handle_federation_error(mxc, server, error))
406}
407
408// Handles and adjusts the error for the caller to determine if they should
409// request the fallback endpoint or give up.
410fn handle_federation_error(mxc: &Mxc<'_>, server: Option<&ServerName>, error: Error) -> Error {
411	let fallback =
412		|| err!(Request(NotFound(debug_error!(%mxc, ?server, ?error, "Remote media not found"))));
413
414	// Matrix server responses for fallback always taken.
415	if error.kind() == NotFound || error.kind() == Unrecognized {
416		return fallback();
417	}
418
419	// If we get these from any middleware we'll try the other endpoint rather than
420	// giving up too early.
421	if error.status_code().is_redirection()
422		|| error.status_code().is_client_error()
423		|| error.status_code().is_server_error()
424	{
425		return fallback();
426	}
427
428	// Reached for 5xx errors. This is where we don't fallback given the likelihood
429	// the other endpoint will also be a 5xx and we're wasting time.
430	error
431}
432
433/// Fetches a thumbnail from the origin server over the legacy media API.
434///
435/// The dimension the origin is asked for is the dimension its answer is filed
436/// under, and every later lookup normalizes before it seeks, so the two have
437/// to agree or nothing cached on one request is found on the next. A request
438/// too large for any thumbnail size normalizes to the original file, which is
439/// fetched rather than asked for at a dimension that is not a size.
440#[implement(super::Service)]
441pub async fn fetch_remote_thumbnail_legacy(
442	&self,
443	mxc: &Mxc<'_>,
444	timeout_ms: Duration,
445	dim: &Dim,
446	animate: Animate,
447) -> Result<Media> {
448	self.check_legacy_freeze()?;
449	self.check_fetch_authorized(mxc)?;
450
451	let dim = dim.normalized();
452
453	// both helpers cache what they fetch, so a picture the request forbids is
454	// kept beside the still derived from it rather than shadowed by it later
455	let fetched = match dim.is_original() {
456		| true =>
457			self.fetch_content_unauthenticated(mxc, None, timeout_ms)
458				.await?,
459		| false =>
460			self.fetch_thumbnail_unauthenticated(mxc, None, timeout_ms, &dim, animate)
461				.await?,
462	};
463
464	if animate.accepts_fetched(&fetched) {
465		return Ok(fetched.media);
466	}
467
468	self.store_still(mxc, &dim, fetched.media).await
469}
470
471#[implement(super::Service)]
472#[expect(deprecated)]
473pub async fn fetch_remote_content_legacy(
474	&self,
475	mxc: &Mxc<'_>,
476	timeout_ms: Duration,
477) -> Result<media::get_content::v3::Response, Error> {
478	self.check_legacy_freeze()?;
479	self.check_fetch_authorized(mxc)?;
480	let response = self
481		.services
482		.federation
483		.execute(mxc.server_name, media::get_content::v3::Request {
484			allow_remote: true,
485			server_name: mxc.server_name.into(),
486			media_id: mxc.media_id.into(),
487			timeout_ms,
488			allow_redirect: false,
489		})
490		.await?;
491
492	let content_disposition = make_content_disposition(
493		response.content_disposition.as_ref(),
494		response.content_type.as_deref(),
495		None,
496	);
497
498	self.create(
499		mxc,
500		None,
501		Some(&content_disposition),
502		response.content_type.as_deref(),
503		&response.file,
504	)
505	.await?;
506
507	Ok(response)
508}
509
510#[implement(super::Service)]
511fn check_fetch_authorized(&self, mxc: &Mxc<'_>) -> Result {
512	if self
513		.services
514		.server
515		.config
516		.media
517		.prevent_downloads_from
518		.is_match(mxc.server_name.host())
519		|| self
520			.services
521			.server
522			.config
523			.is_forbidden_remote_server_name(mxc.server_name)
524	{
525		// we'll lie to the client and say the blocked server's media was not found and
526		// log. the client has no way of telling anyways so this is a security bonus.
527		debug_warn!(%mxc, "Received request for media on blocklisted server");
528		return Err!(Request(NotFound("Media not found.")));
529	}
530
531	Ok(())
532}
533
534#[implement(super::Service)]
535fn check_legacy_freeze(&self) -> Result {
536	self.services
537		.server
538		.config
539		.media
540		.freeze_legacy
541		.then_some(())
542		.ok_or(err!(Request(NotFound("Remote media is frozen."))))
543}