Skip to main content

graphrt_http/
client.rs

1//! Policy-enforcing HTTP client service.
2
3use std::net::SocketAddr;
4use std::sync::{Arc, Once, OnceLock};
5use std::time::Duration;
6
7use reqwest::dns::{Addrs, Name, Resolve, Resolving};
8use reqwest::redirect;
9
10use crate::policy::{EgressError, EgressPolicy};
11
12/// Error building an [`HttpClient`].
13#[derive(Clone, Debug, thiserror::Error)]
14#[non_exhaustive]
15pub enum ClientError {
16    #[error("invalid proxy `{0}`: {1}")]
17    Proxy(String, String),
18    #[error("cannot build HTTP client: {0}")]
19    Build(String),
20}
21
22/// HTTP client shared by HTTP-calling nodes. Register it in
23/// [`graphrt_core::Services`]; when absent, nodes use a client with the default
24/// (restrictive) [`EgressPolicy`].
25///
26/// Every connection goes through the policy:
27/// - literal-IP URLs and every redirect hop are validated before connecting;
28/// - host names are resolved by a guarded resolver that refuses non-public
29///   addresses, and the connection is made to exactly the addresses it returned
30///   (so DNS rebinding cannot swap in a private address afterwards);
31/// - environment proxy variables are ignored.
32#[derive(Clone, Debug)]
33pub struct HttpClient {
34    policy: Arc<EgressPolicy>,
35    clients: Arc<Clients>,
36}
37
38/// The four reqwest clients, each built on first use: building one loads the
39/// system trust store, and most runs need one variant or none at all.
40#[derive(Debug, Default)]
41struct Clients {
42    verified: OnceLock<Result<reqwest::Client, ClientError>>,
43    unverified: OnceLock<Result<reqwest::Client, ClientError>>,
44    /// Clients that never follow redirects; the `http-request` node follows them
45    /// itself so it can strip credentials on cross-origin hops.
46    manual_verified: OnceLock<Result<reqwest::Client, ClientError>>,
47    manual_unverified: OnceLock<Result<reqwest::Client, ClientError>>,
48}
49
50impl HttpClient {
51    /// Build a client enforcing `policy`. The proxy setting is validated here;
52    /// the underlying connections are set up on first use.
53    ///
54    /// @throws `ClientError::Proxy` when `policy.proxy` is not a valid proxy URL.
55    pub fn new(policy: EgressPolicy) -> Result<Self, ClientError> {
56        install_crypto_provider();
57        if let Some(proxy_url) = &policy.proxy {
58            reqwest::Proxy::all(proxy_url).map_err(|e| ClientError::Proxy(proxy_url.clone(), e.to_string()))?;
59        }
60        Ok(Self { policy: Arc::new(policy), clients: Arc::default() })
61    }
62
63    /// Client with [`EgressPolicy::trusted`], for operator-configured endpoints.
64    pub fn trusted() -> Result<Self, ClientError> {
65        Self::new(EgressPolicy::trusted())
66    }
67
68    pub fn policy(&self) -> &EgressPolicy {
69        &self.policy
70    }
71
72    /// Underlying client, built on first use. `verify_tls = false` disables
73    /// certificate verification.
74    ///
75    /// Redirects are followed automatically (each hop re-validated). reqwest strips only
76    /// `authorization`, `cookie` and `proxy-authorization` on cross-host hops, so callers
77    /// sending other credential headers should use [`HttpClient::manual_redirect_client`].
78    ///
79    /// @throws `ClientError::Build` when the TLS backend cannot be initialised.
80    pub fn client(&self, verify_tls: bool) -> Result<&reqwest::Client, ClientError> {
81        let cell = if verify_tls { &self.clients.verified } else { &self.clients.unverified };
82        self.get(cell, verify_tls, true)
83    }
84
85    /// Client that never follows redirects: 3xx responses are returned to the caller.
86    ///
87    /// @throws `ClientError::Build` when the TLS backend cannot be initialised.
88    pub fn manual_redirect_client(&self, verify_tls: bool) -> Result<&reqwest::Client, ClientError> {
89        let cell = if verify_tls { &self.clients.manual_verified } else { &self.clients.manual_unverified };
90        self.get(cell, verify_tls, false)
91    }
92
93    fn get<'a>(
94        &self,
95        cell: &'a OnceLock<Result<reqwest::Client, ClientError>>,
96        verify_tls: bool,
97        follow_redirects: bool,
98    ) -> Result<&'a reqwest::Client, ClientError> {
99        cell.get_or_init(|| build(&self.policy, verify_tls, follow_redirects)).as_ref().map_err(Clone::clone)
100    }
101
102    /// Validate a URL against the policy (scheme, host lists, literal addresses).
103    pub fn check_url(&self, url: &reqwest::Url) -> Result<(), EgressError> {
104        self.policy.check_url(url)
105    }
106}
107
108/// Use the small `ring` crypto backend. Installing fails harmlessly if the
109/// process already chose a provider.
110fn install_crypto_provider() {
111    static ONCE: Once = Once::new();
112    ONCE.call_once(|| {
113        let _already_installed = rustls::crypto::ring::default_provider().install_default();
114    });
115}
116
117fn build(policy: &Arc<EgressPolicy>, verify_tls: bool, follow_redirects: bool) -> Result<reqwest::Client, ClientError> {
118    let redirect_policy = if !follow_redirects {
119        redirect::Policy::none()
120    } else {
121        let policy = Arc::clone(policy);
122        redirect::Policy::custom(move |attempt| {
123            if attempt.previous().len() >= policy.max_redirects {
124                return attempt.error(format!("too many redirects (limit {})", policy.max_redirects));
125            }
126            match policy.check_url(attempt.url()) {
127                Ok(()) => attempt.follow(),
128                Err(e) => attempt.error(format!("redirect blocked: {e}")),
129            }
130        })
131    };
132    let mut builder = reqwest::Client::builder()
133        .no_proxy()
134        .redirect(redirect_policy)
135        .dns_resolver(Arc::new(GuardedResolver { policy: Arc::clone(policy) }))
136        .connect_timeout(policy.connect_timeout)
137        .read_timeout(policy.read_timeout)
138        .pool_idle_timeout(Duration::from_secs(90))
139        .tls_danger_accept_invalid_certs(!verify_tls);
140    if let Some(proxy_url) = &policy.proxy {
141        // The proxy resolves target hosts itself; it is expected to enforce its own egress rules.
142        let proxy = reqwest::Proxy::all(proxy_url).map_err(|e| ClientError::Proxy(proxy_url.clone(), e.to_string()))?;
143        builder = builder.proxy(proxy);
144    }
145    builder.build().map_err(|e| ClientError::Build(e.to_string()))
146}
147
148/// DNS resolver that refuses names resolving to non-public addresses.
149#[derive(Debug)]
150pub(crate) struct GuardedResolver {
151    policy: Arc<EgressPolicy>,
152}
153
154impl Resolve for GuardedResolver {
155    fn resolve(&self, name: Name) -> Resolving {
156        let policy = Arc::clone(&self.policy);
157        let host = name.as_str().to_owned();
158        Box::pin(async move {
159            policy.check_host_name(&host)?;
160            let resolved: Vec<SocketAddr> = tokio::net::lookup_host((host.as_str(), 0)).await?.collect();
161            let allowed = filter_addresses(&policy, &host, resolved)?;
162            Ok(Box::new(allowed.into_iter()) as Addrs)
163        })
164    }
165}
166
167/// Keep only permitted addresses. If any resolved address is blocked the whole
168/// name is refused: a name mixing public and private records is suspicious.
169pub(crate) fn filter_addresses(
170    policy: &EgressPolicy,
171    host: &str,
172    resolved: Vec<SocketAddr>,
173) -> Result<Vec<SocketAddr>, EgressError> {
174    if resolved.is_empty() {
175        return Err(EgressError::InvalidUrl(format!("`{host}` did not resolve to any address")));
176    }
177    for addr in &resolved {
178        policy.check_ip(addr.ip())?;
179    }
180    Ok(resolved)
181}
182
183#[cfg(test)]
184mod tests {
185    use super::*;
186
187    fn addr(s: &str) -> SocketAddr {
188        SocketAddr::new(s.parse().unwrap(), 0)
189    }
190
191    #[test]
192    fn resolver_filter_blocks_private_records() {
193        let p = EgressPolicy::default();
194        assert!(filter_addresses(&p, "h", vec![addr("93.184.216.34")]).is_ok());
195        assert!(filter_addresses(&p, "h", vec![addr("127.0.0.1")]).is_err());
196        assert!(filter_addresses(&p, "h", vec![addr("93.184.216.34"), addr("10.0.0.1")]).is_err());
197        assert!(filter_addresses(&p, "h", vec![addr("::ffff:192.168.0.1")]).is_err());
198        assert!(filter_addresses(&p, "h", vec![]).is_err());
199        assert!(filter_addresses(&EgressPolicy::trusted(), "h", vec![addr("127.0.0.1")]).is_ok());
200    }
201
202    #[tokio::test]
203    async fn resolver_refuses_localhost_name() {
204        let r = GuardedResolver { policy: Arc::new(EgressPolicy::default()) };
205        let name: Name = "localhost".parse().unwrap();
206        assert!(r.resolve(name).await.is_err());
207    }
208
209    #[tokio::test]
210    async fn resolver_respects_denied_hosts() {
211        let policy = EgressPolicy { denied_hosts: vec!["localhost".into()], ..EgressPolicy::trusted() };
212        let r = GuardedResolver { policy: Arc::new(policy) };
213        let name: Name = "localhost".parse().unwrap();
214        assert!(r.resolve(name).await.is_err());
215    }
216
217    #[test]
218    fn builds() {
219        assert!(HttpClient::new(EgressPolicy::default()).is_ok());
220    }
221}