Skip to main content

tuwunel_service/client/
mod.rs

1use std::{
2	net::{IpAddr, SocketAddr},
3	ops::Deref,
4	sync::{Arc, LazyLock},
5	time::Duration,
6};
7
8use bytes::{Bytes, BytesMut};
9use ipaddress::{IPAddress, ipv4::from_u32 as ipv4_from_u32};
10use reqwest::{Client, ClientBuilder, Url, dns::Resolve, header::HeaderValue, redirect::Policy};
11use tuwunel_core::{
12	Config, Err, Result, config::proxy::ProxySnapshot, debug, either::Either, err,
13	error::error_chain, implement, trace, utils::math::u64_from_usize_saturating,
14};
15use url::Host;
16
17use crate::{Services, resolver::Validating, service};
18
19#[cfg(test)]
20mod tests;
21
22type DisableEncoding = fn(ClientBuilder) -> ClientBuilder;
23
24/// The outbound HTTP clients, one per purpose.
25///
26/// Built once on first use for the service's proxy snapshot; each carries its
27/// own resolver, timeouts and connection pool.
28pub struct Clients {
29	/// General HTTP requests using ordinary DNS resolution.
30	pub default: Client,
31
32	/// URL previews with interface selection and address validation.
33	pub url_preview: Client,
34
35	/// External media downloads with address and redirect validation.
36	pub extern_media: Client,
37
38	/// Server discovery through well-known documents with bounded timeouts.
39	pub well_known: Client,
40
41	/// Federation requests with the configured federation timeout and idle pool.
42	pub federation: Federation,
43
44	/// Federation requests with the extended Synapse read timeout.
45	pub synapse: Federation,
46
47	/// Outbound federation transactions with the sender timeout and one idle
48	/// connection per host.
49	pub sender: Federation,
50
51	/// Application service requests using their configured resolver and timeouts.
52	pub appservice: Client,
53
54	/// Push gateway requests with address and redirect validation.
55	pub pusher: Client,
56
57	/// OAuth provider requests with redirects disabled.
58	pub oauth: Client,
59}
60
61/// Separate DNS resolvers and connection pools for direct and SRV routes.
62///
63/// Route selection keeps requests with identical URL authorities from reusing
64/// a connection opened for the other DNS route.
65pub struct Federation {
66	direct: Client,
67	srv: Client,
68}
69
70pub struct Service {
71	pub clients: LazyLock<Clients, Box<dyn FnOnce() -> Clients + Send>>,
72
73	/// Effective proxy policy for this generation of clients.
74	///
75	/// The snapshot keeps client routing, DNS exemptions, and response checks
76	/// aligned even if configuration or environment values later change.
77	pub proxy: Arc<ProxySnapshot>,
78	pub cidr_range_denylist: Arc<[IPAddress]>,
79}
80
81impl Deref for Service {
82	type Target = Clients;
83
84	fn deref(&self) -> &Self::Target { &self.clients }
85}
86
87impl crate::Service for Service {
88	fn build(args: &crate::Args<'_>) -> Result<Arc<Self>> {
89		let config = &args.server.config;
90		let proxy = Arc::new(ProxySnapshot::new(&config.proxy)?);
91
92		probe_tls(config, &proxy)?;
93
94		let cidr_range_denylist = config
95			.network
96			.http
97			.ip_range_denylist
98			.iter()
99			.map(IPAddress::parse)
100			.inspect(|cidr| trace!("Denied CIDR range: {cidr:?}"))
101			.collect::<Result<Vec<_>, String>>()
102			.map(Arc::from)
103			.map_err(|e| err!(Config("network.http.ip_range_denylist", e)))?;
104
105		Ok(Arc::new(Self {
106			clients: LazyLock::new(Box::new({
107				let services = args.services.clone();
108
109				move || make_clients(&services).expect("failed to construct clients")
110			})),
111
112			proxy,
113			cidr_range_denylist,
114		}))
115	}
116
117	fn name(&self) -> &str { service::make_name(std::module_path!()) }
118}
119
120impl Federation {
121	#[inline]
122	pub(crate) fn for_srv(&self, srv: bool) -> &Client {
123		if srv { &self.srv } else { &self.direct }
124	}
125}
126
127/// Fails startup when an HTTPS client cannot be constructed.
128///
129/// The clients are built lazily on first use, so a platform trust store that
130/// yields no roots surfaces as a panic inside whichever worker reaches for a
131/// client first. Probing once at startup turns that into a legible boot error.
132fn probe_tls(config: &Config, proxy: &ProxySnapshot) -> Result {
133	base(config, proxy, None)?
134		.build()
135		.map(drop)
136		.map_err(|e| {
137			err!(error!(
138				chain = %error_chain(&e),
139				"Failed to construct an HTTPS client. If the system trust store is empty, \
140				 install a CA bundle (ca-certificates on Debian and Ubuntu) or point \
141				 SSL_CERT_FILE at one.",
142			))
143		})
144}
145
146fn make_clients(services: &Services) -> Result<Clients> {
147	macro_rules! with {
148		($builder:ident => $make:expr) => {{
149			let $builder = base(&services.config, &services.client.proxy, None)?;
150
151			$make.build()?
152		}};
153		($name:literal, $builder:ident => $make:expr) => {{
154			let $builder = base(&services.config, &services.client.proxy, Some($name))?;
155
156			$make.build()?
157		}};
158	}
159
160	let federation = make_federation(services, |cb| {
161		let transport = &services.config.federation.transport;
162
163		cb.read_timeout(Duration::from_secs(transport.timeout))
164			.pool_max_idle_per_host(transport.idle_per_host.into())
165			.pool_idle_timeout(Duration::from_secs(transport.idle_timeout))
166			.redirect(Policy::none())
167	})?;
168
169	let synapse = make_federation(services, |cb| {
170		cb.read_timeout(Duration::from_secs(305))
171			.pool_max_idle_per_host(0)
172			.redirect(Policy::none())
173	})?;
174
175	let sender = make_federation(services, |cb| {
176		cb.read_timeout(Duration::from_secs(services.config.sending.timeout))
177			.timeout(Duration::from_secs(services.config.sending.timeout))
178			.pool_max_idle_per_host(1)
179			.pool_idle_timeout(Duration::from_secs(services.config.sending.idle_timeout))
180			.redirect(Policy::none())
181	})?;
182
183	let default = with!(cb => cb.dns_resolver(Arc::clone(&services.resolver.resolver)));
184
185	let url_preview = with!("preview", cb => preview_builder(services, cb)?);
186
187	let extern_media = with!(cb => cb
188			.dns_resolver(Validating::new(
189				Arc::clone(&services.resolver.resolver),
190				Arc::clone(&services.client.cidr_range_denylist),
191				services.client.proxy.shared_hosts(),
192			))
193			.redirect(guarded_redirect(services, 3)));
194
195	let well_known = with!(cb => cb
196			.dns_resolver(Arc::clone(&services.resolver.resolver))
197			.connect_timeout(Duration::from_secs(
198				services.config.network.discovery.conn_timeout,
199			))
200			.read_timeout(Duration::from_secs(services.config.network.discovery.timeout))
201			.timeout(Duration::from_secs(services.config.network.discovery.timeout))
202			.pool_max_idle_per_host(0)
203			// Discovery always starts over HTTPS; this refuses redirects to plain HTTP.
204			.https_only(true)
205			.redirect(guarded_redirect(services, 4)));
206
207	Ok(Clients {
208		default,
209		url_preview,
210		extern_media,
211
212		well_known,
213
214		federation,
215		synapse,
216		sender,
217
218		appservice: with!(cb => appservice_builder(services, cb)),
219
220		pusher: with!(cb => cb
221			.dns_resolver(Validating::new(
222				Arc::clone(&services.resolver.resolver),
223				Arc::clone(&services.client.cidr_range_denylist),
224				services.client.proxy.shared_hosts(),
225			))
226			.pool_max_idle_per_host(1)
227			.pool_idle_timeout(Duration::from_secs(
228				services.config.push.idle_timeout,
229			))
230			.redirect(guarded_redirect(services, 2))),
231
232		oauth: with!(cb => cb
233			.dns_resolver(Arc::clone(&services.resolver.resolver))
234			.redirect(Policy::limited(0))
235			.pool_max_idle_per_host(1)),
236	})
237}
238
239#[cfg(unix)]
240pub(crate) fn make_appservice_unix(services: &Services, path: &str) -> Result<Client> {
241	let builder = base(&services.config, &services.client.proxy, None)?;
242	let client = appservice_builder(services, builder)
243		.no_proxy()
244		.unix_socket(path)
245		.build()?;
246
247	Ok(client)
248}
249
250fn appservice_builder(services: &Services, builder: ClientBuilder) -> ClientBuilder {
251	builder
252		.dns_resolver(appservice_resolver(services))
253		.connect_timeout(Duration::from_secs(5))
254		.read_timeout(Duration::from_secs(services.config.appservice_client.timeout))
255		.timeout(Duration::from_secs(services.config.appservice_client.timeout))
256		.pool_max_idle_per_host(1)
257		.pool_idle_timeout(Duration::from_secs(services.config.appservice_client.idle_timeout))
258		.redirect(Policy::limited(2))
259}
260
261fn make_federation(
262	services: &Services,
263	configure: impl Fn(ClientBuilder) -> ClientBuilder,
264) -> Result<Federation> {
265	let builder = || base(&services.config, &services.client.proxy, None);
266	let direct = builder()?.dns_resolver(Arc::clone(&services.resolver.resolver));
267	let srv = builder()?.dns_resolver(Arc::clone(&services.resolver.resolver.hooked));
268
269	Ok(Federation {
270		direct: configure(direct).build()?,
271		srv: configure(srv).build()?,
272	})
273}
274
275/// Construction for the URL preview client: bound to the configured
276/// interface and resolving through the CIDR-validating resolver.
277///
278/// The configured User-Agent is applied per request rather than here, so a
279/// configuration reload takes effect without rebuilding the client.
280fn preview_builder(services: &Services, builder: ClientBuilder) -> Result<ClientBuilder> {
281	let interface = &services.config.media.url_preview.bound_interface;
282
283	let bind_addr = interface.clone().and_then(Either::left);
284	let bind_iface = interface.clone().and_then(Either::right);
285
286	let resolver = Validating::new(
287		Arc::clone(&services.resolver.resolver),
288		Arc::clone(&services.client.cidr_range_denylist),
289		services.client.proxy.shared_hosts(),
290	);
291
292	Ok(builder_interface(builder, bind_iface.as_deref())?
293		.local_address(bind_addr)
294		.dns_resolver(resolver)
295		.redirect(guarded_redirect(services, 3)))
296}
297
298fn guarded_redirect(services: &Services, max: usize) -> Policy {
299	let proxy = Arc::clone(&services.client.proxy);
300	let denylist = Arc::clone(&services.client.cidr_range_denylist);
301	let limited = Policy::limited(max);
302
303	Policy::custom(move |attempt| {
304		if proxy.resolver_alias(attempt.url()) || !valid_cidr_range_url(&denylist, attempt.url())
305		{
306			attempt.error("redirect destination is not allowed")
307		} else {
308			limited.redirect(attempt)
309		}
310	})
311}
312
313fn valid_cidr_range_url(denylist: &[IPAddress], url: &Url) -> bool {
314	let ip = match url.host() {
315		| Some(Host::Ipv4(ip)) => IpAddr::V4(ip),
316		| Some(Host::Ipv6(ip)) => IpAddr::V6(ip),
317		| Some(Host::Domain(_)) | None => return true,
318	};
319
320	valid_cidr_range_ip(denylist, ip)
321}
322
323/// Checks an address against a CIDR denylist.
324///
325/// An IPv4-mapped IPv6 address (`::ffff:a.b.c.d`) connects to its embedded
326/// IPv4 address, so it must pass the IPv4 ranges as well as the IPv6 ones.
327pub(crate) fn valid_cidr_range_ip(denylist: &[IPAddress], ip: IpAddr) -> bool {
328	let allowed = |ip: IpAddr| {
329		let ip = ipaddress_from_std(ip);
330
331		denylist.iter().all(|cidr| !cidr.includes(&ip))
332	};
333
334	let canonical = ip.to_canonical();
335
336	allowed(ip) && (canonical == ip || allowed(canonical))
337}
338
339fn base(config: &Config, proxy: &ProxySnapshot, name: Option<&str>) -> Result<ClientBuilder> {
340	let user_agent = tuwunel_core::version::user_agent();
341	let user_agent: HeaderValue = name
342		.map(|name| format!("{user_agent} {name}").try_into())
343		.unwrap_or_else(|| user_agent.try_into())?;
344
345	let builder = Client::builder()
346		.connect_timeout(Duration::from_secs(config.network.http.conn_timeout))
347		.read_timeout(Duration::from_secs(config.network.http.timeout))
348		.timeout(Duration::from_secs(config.network.http.total_timeout))
349		.pool_idle_timeout(Duration::from_secs(config.network.http.idle_timeout))
350		.pool_max_idle_per_host(config.network.http.idle_per_host.into())
351		.user_agent(user_agent)
352		.redirect(Policy::limited(6))
353		.danger_accept_invalid_certs(config.network.http.allow_invalid_tls_certificates)
354		.connection_verbose(cfg!(debug_assertions))
355		// Check if env var is set to avoid locking the keyfile mutex on every connection open
356		.tls_sslkeylogfile(std::env::var_os("SSLKEYLOGFILE").is_some());
357
358	let encodings: [(bool, DisableEncoding); 3] = [
359		(config.network.http.gzip, ClientBuilder::no_gzip),
360		(config.network.http.brotli, ClientBuilder::no_brotli),
361		(config.network.http.zstd, ClientBuilder::no_zstd),
362	];
363
364	let builder = encodings
365		.into_iter()
366		.filter(|(enabled, _)| !enabled)
367		.fold(builder, |builder, (_, disable)| disable(builder));
368
369	Ok(proxy.configure(builder))
370}
371
372/// Prevents a remote peer from forcing unbounded response-body allocation.
373///
374/// An advertised `Content-Length` above `limit` is rejected before the body
375/// buffer is allocated. The streaming loop enforces the same bound when the
376/// length is absent or inaccurate.
377pub async fn read_response_capped(
378	mut response: reqwest::Response,
379	limit: usize,
380) -> Result<Bytes> {
381	let mut body = match response.content_length() {
382		| Some(len) if len > u64_from_usize_saturating(limit) => {
383			debug!(%len, %limit, "rejecting response: advertised body exceeds limit");
384			return Err!(BadServerResponse(
385				"Response body length {len} exceeds the {limit} byte limit"
386			));
387		},
388		| Some(len) => BytesMut::with_capacity(usize::try_from(len).unwrap_or(limit)),
389		| None => BytesMut::new(),
390	};
391	while let Some(chunk) = response.chunk().await? {
392		if body.len().saturating_add(chunk.len()) > limit {
393			debug!(%limit, "rejecting response: streamed body exceeds limit");
394			return Err!(BadServerResponse("Response body exceeds the {limit} byte limit"));
395		}
396
397		body.extend_from_slice(&chunk);
398	}
399
400	Ok(body.freeze())
401}
402
403#[cfg(any(
404	target_os = "android",
405	target_os = "fuchsia",
406	target_os = "linux"
407))]
408fn builder_interface(builder: ClientBuilder, config: Option<&str>) -> Result<ClientBuilder> {
409	if let Some(iface) = config {
410		Ok(builder.interface(iface))
411	} else {
412		Ok(builder)
413	}
414}
415
416#[cfg(not(any(
417	target_os = "android",
418	target_os = "fuchsia",
419	target_os = "linux"
420)))]
421fn builder_interface(builder: ClientBuilder, config: Option<&str>) -> Result<ClientBuilder> {
422	use tuwunel_core::Err;
423
424	config.map_or_else(
425		|| Ok(builder),
426		|iface| {
427			Err!(
428				"Binding to network-interface {iface:?} by name is not supported on this \
429				 platform."
430			)
431		},
432	)
433}
434
435fn appservice_resolver(services: &Services) -> Arc<dyn Resolve> {
436	if services
437		.server
438		.config
439		.network
440		.dns
441		.passthru_appservices
442	{
443		services.resolver.resolver.passthru.clone()
444	} else {
445		services.resolver.resolver.clone()
446	}
447}
448
449/// Checks a response peer against the CIDR policy used by guarded clients.
450///
451/// A proxied response is screened at the proxy route instead; direct responses
452/// remain subject to the destination denylist.
453#[implement(Service)]
454#[inline]
455#[must_use]
456pub fn valid_cidr_range_remote_addr(&self, url: &Url, remote_addr: SocketAddr) -> bool {
457	self.valid_cidr_range_ip(remote_addr.ip()) || self.proxied(url)
458}
459
460#[inline]
461#[must_use]
462#[implement(Service)]
463pub fn valid_cidr_range(&self, ip: &IPAddress) -> bool {
464	self.cidr_range_denylist
465		.iter()
466		.all(|cidr| !cidr.includes(ip))
467}
468
469#[implement(Service)]
470#[inline]
471#[must_use]
472pub fn valid_cidr_range_ip(&self, ip: IpAddr) -> bool {
473	valid_cidr_range_ip(&self.cidr_range_denylist, ip)
474}
475
476/// Checks an HTTP URL against the CIDR denylist when its host is an IP literal.
477///
478/// Domain names pass here and remain subject to each consumer's resolution
479/// policy.
480#[implement(Service)]
481#[inline]
482#[must_use]
483pub fn valid_cidr_range_url(&self, url: &Url) -> bool {
484	valid_cidr_range_url(&self.cidr_range_denylist, url)
485}
486
487/// Reports whether this client generation proxies a request URL.
488///
489/// The result uses the same snapshotted configured or environment route that
490/// was applied when the clients were built.
491#[implement(Service)]
492#[inline]
493#[must_use]
494pub fn proxied(&self, url: &Url) -> bool { self.proxy.intercepts(url) }
495
496#[must_use]
497pub(crate) fn ipaddress_from_std(ip: IpAddr) -> IPAddress {
498	match ip {
499		| IpAddr::V4(v4) =>
500			ipv4_from_u32(u32::from(v4), 32).expect("/32 is always a valid prefix"),
501		// ipv6::from_int would skip the regex parser but pulls in num-bigint.
502		| IpAddr::V6(v6) =>
503			IPAddress::parse(v6.to_string()).expect("Ipv6Addr Display output parses"),
504	}
505}