Skip to main content

rushls_common/outbound/
mod.rs

1//! Requests this node makes to services an administrator configured.
2//!
3//! Inbound HTTP serving remains the responsibility of each application.
4//! Both admission and lifecycle hooks talk to operator-supplied endpoints, and
5//! they share exactly this much: a pooled connection, bounded time, a bounded
6//! response, and a bearer credential. What they do with the answer is entirely
7//! different — admission fails closed and never retries, hooks queue and retry
8//! — so none of that is here.
9//!
10//! Two properties come from what is *not* enabled rather than from code, and
11//! both are load-bearing. `hyper-util`'s client does not follow redirects, so a
12//! bearer token can never be replayed to another origin by a redirecting
13//! endpoint. Its `client-proxy` feature is off, so no environment variable can
14//! silently route these requests through a third party.
15//!
16//! Cleartext endpoints are permitted. Whether a hop is protected is not
17//! knowable from the URL — a service mesh or a private network may be doing it
18//! — so [`Endpoint::is_encrypted`] reports the scheme and leaves the judgement
19//! to the operator who chose the address.
20
21mod client_tls;
22pub use client_tls::{ClientTls, ClientTlsError, ClientTlsFiles};
23
24use std::{sync::Arc, time::Duration};
25
26use bytes::Bytes;
27use http::{HeaderMap, HeaderValue, Request, StatusCode, Uri, header};
28use http_body_util::{BodyExt, Full, Limited};
29use hyper_util::{
30    client::legacy::{Client, connect::HttpConnector},
31    rt::TokioExecutor,
32};
33use rustls::client::ResolvesClientCert;
34use rustls::pki_types::CertificateDer;
35use thiserror::Error;
36
37/// A validated destination.
38///
39/// Parsed once at start-up so a malformed endpoint stops the process rather
40/// than failing at the first publisher, and so the checks below happen where an
41/// operator can still act on them.
42#[derive(Clone, Debug, Eq, PartialEq)]
43pub struct Endpoint(Uri);
44
45impl Endpoint {
46    pub fn parse(value: &str) -> Result<Self, EndpointError> {
47        let uri: Uri = value
48            .parse()
49            .map_err(|_| EndpointError::Malformed(value.to_owned()))?;
50        let scheme = uri.scheme_str().unwrap_or_default();
51        if !matches!(scheme, "http" | "https") {
52            return Err(EndpointError::Scheme(value.to_owned()));
53        }
54        // Cleartext is permitted anywhere. A sidecar reached over a private
55        // network or a service mesh that terminates its own TLS is the ordinary
56        // deployment, and `http://auth-sidecar:8081` is not a loopback address
57        // — refusing it would reject the common case to catch the careless one.
58        uri.host().ok_or(EndpointError::NoHost(value.to_owned()))?;
59        Ok(Self(uri))
60    }
61
62    pub fn uri(&self) -> &Uri {
63        &self.0
64    }
65
66    /// Whether credentials sent here are protected in transit by this node.
67    ///
68    /// Cleartext may still be entirely appropriate, so this is a fact to report
69    /// rather than a verdict: what protects the hop may be a mesh or a private
70    /// network that this process cannot see.
71    pub fn is_encrypted(&self) -> bool {
72        self.0.scheme_str() == Some("https")
73    }
74}
75
76impl std::fmt::Display for Endpoint {
77    fn fmt(&self, output: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
78        write!(output, "{}", self.0)
79    }
80}
81
82#[derive(Clone, Debug, Eq, PartialEq, Error)]
83pub enum EndpointError {
84    #[error("`{0}` is not a URL")]
85    Malformed(String),
86    #[error("`{0}` must use http or https")]
87    Scheme(String),
88    #[error("`{0}` names no host")]
89    NoHost(String),
90}
91
92/// A bearer credential, kept out of anything that prints.
93#[derive(Clone, derive_more::Debug)]
94#[debug("BearerToken([REDACTED])")]
95pub struct BearerToken(#[debug(skip)] HeaderValue);
96
97impl BearerToken {
98    pub fn new(token: &str) -> Result<Self, InvalidToken> {
99        let mut value =
100            HeaderValue::try_from(format!("Bearer {token}")).map_err(|_| InvalidToken)?;
101        // Marks the value for redaction in hyper's own logging, which would
102        // otherwise print it whenever request tracing is turned on.
103        value.set_sensitive(true);
104        Ok(Self(value))
105    }
106}
107
108#[derive(Clone, Copy, Debug, Eq, PartialEq, Error)]
109#[error("a bearer token must be printable ASCII without control characters")]
110pub struct InvalidToken;
111
112#[derive(Clone, Copy, Debug, Eq, PartialEq)]
113pub struct ClientConfig {
114    pub connect_timeout: Duration,
115    /// Covers connect, send, and reading the whole response.
116    pub request_timeout: Duration,
117    /// Refused past this, so a misbehaving endpoint cannot exhaust memory.
118    pub maximum_response_bytes: usize,
119}
120
121impl Default for ClientConfig {
122    fn default() -> Self {
123        Self {
124            connect_timeout: Duration::from_millis(500),
125            request_timeout: Duration::from_secs(2),
126            maximum_response_bytes: 64 * 1024,
127        }
128    }
129}
130
131/// What an endpoint answered.
132///
133/// Reported, not interpreted: whether a status is success, worth retrying, or
134/// permanent is the caller's policy, and it differs between admission and
135/// hooks. The one exception is [`Self::retry_after`], which parses a header
136/// rather than deciding anything with it.
137#[derive(Clone, Debug, Eq, PartialEq)]
138pub struct Response {
139    pub status: StatusCode,
140    pub headers: HeaderMap,
141    pub body: Bytes,
142}
143
144impl Response {
145    /// `Retry-After` in its delta-seconds form, capped by the caller.
146    ///
147    /// Only the seconds form. The HTTP-date alternative needs a parsed clock to
148    /// mean anything, and an endpoint that answers an event POST with an
149    /// absolute date is not a case worth carrying a date parser for; treating
150    /// it as absent falls back to the caller's own backoff, which is safe.
151    pub fn retry_after(&self, maximum: Duration) -> Option<Duration> {
152        let seconds: u64 = self
153            .headers
154            .get(header::RETRY_AFTER)?
155            .to_str()
156            .ok()?
157            .trim()
158            .parse()
159            .ok()?;
160        Some(Duration::from_secs(seconds).min(maximum))
161    }
162}
163
164#[derive(Clone, Debug, Eq, PartialEq, Error)]
165pub enum OutboundError {
166    #[error("the request did not complete within its deadline")]
167    Timeout,
168    #[error("could not reach the endpoint: {0}")]
169    Unreachable(String),
170    #[error("the response was not readable: {0}")]
171    Response(String),
172    #[error("the response exceeded {limit} bytes")]
173    ResponseTooLarge { limit: usize },
174}
175
176/// Builds at most one outbound client, and only if something needs it.
177///
178/// Reading the platform trust store and building a TLS configuration is real
179/// work, and a node that calls nothing out should not pay for it — nor should
180/// the tests covering those configurations. Callers ask for their own deadline
181/// and response ceiling, which are per-request and so cost nothing to vary;
182/// what they share is the connector underneath.
183#[derive(Default)]
184pub struct LazyHttpClient(Option<HttpClient>);
185
186impl LazyHttpClient {
187    /// A client with the caller's limits, over the shared connector.
188    pub fn with_limits(
189        &mut self,
190        request_timeout: Duration,
191        maximum_response_bytes: usize,
192    ) -> Result<HttpClient, OutboundError> {
193        let shared = match &mut self.0 {
194            Some(client) => client,
195            slot @ None => slot.insert(HttpClient::new(ClientConfig::default())?),
196        };
197        Ok(shared.with_limits(request_timeout, maximum_response_bytes))
198    }
199}
200
201/// A pooled HTTP client shared by everything that calls out.
202///
203/// Cloning shares the connection pool, which is the point: a per-publisher
204/// client would pay a TCP and TLS handshake on every admission.
205#[derive(Clone, derive_more::Debug)]
206pub struct HttpClient {
207    #[debug(skip)]
208    inner: Client<hyper_rustls::HttpsConnector<HttpConnector>, Full<Bytes>>,
209    config: ClientConfig,
210}
211
212impl HttpClient {
213    /// The same connection pool under different per-request limits.
214    ///
215    /// A deadline and a response ceiling are properties of a request, not of a
216    /// pool, and admission and hooks want different ones: admission runs inside
217    /// a publisher's handshake, while a hook is free to wait. Sharing the
218    /// client keeps the platform trust store read once and the TLS
219    /// configuration built once, which is the part worth sharing.
220    ///
221    /// `connect_timeout` is fixed when the connector is built and so is not
222    /// overridable here.
223    #[must_use]
224    pub fn with_limits(&self, request_timeout: Duration, maximum_response_bytes: usize) -> Self {
225        Self {
226            inner: self.inner.clone(),
227            config: ClientConfig {
228                request_timeout,
229                maximum_response_bytes,
230                ..self.config
231            },
232        }
233    }
234
235    /// Builds a client that also presents an identity, and may pin its trust.
236    ///
237    /// Separate from [`Self::new`] rather than an option on it, because the
238    /// two answer different questions: `new` is "who do I trust", this is
239    /// additionally "who am I". A caller that needs neither should not have to
240    /// say so.
241    ///
242    /// `identity` resolves per handshake, so a rotated certificate is picked up
243    /// without rebuilding this client or restarting the process. `roots`
244    /// replaces the platform store when present: a deployment pinning the
245    /// authority that signed its own services wants exactly that authority and
246    /// not every public one as well.
247    pub fn with_identity(
248        config: ClientConfig,
249        identity: Option<Arc<dyn ResolvesClientCert>>,
250        roots: Option<Vec<CertificateDer<'static>>>,
251    ) -> Result<Self, OutboundError> {
252        let mut connector = HttpConnector::new();
253        connector.set_connect_timeout(Some(config.connect_timeout));
254        // The TLS layer wraps this one, so it must not reject an https URL
255        // before ever seeing it.
256        connector.enforce_http(false);
257
258        let builder = rustls::ClientConfig::builder();
259        let builder = match roots {
260            Some(roots) => {
261                let mut store = rustls::RootCertStore::empty();
262                for root in roots {
263                    store
264                        .add(root)
265                        .map_err(|error| OutboundError::Unreachable(error.to_string()))?;
266                }
267                builder.with_root_certificates(store)
268            }
269            // The platform store, so an endpoint behind an internal authority
270            // works once that authority is installed the way everything else
271            // on the host already expects.
272            None => {
273                let mut store = rustls::RootCertStore::empty();
274                let loaded = rustls_native_certs::load_native_certs();
275                if loaded.certs.is_empty() {
276                    let reason = loaded
277                        .errors
278                        .iter()
279                        .map(ToString::to_string)
280                        .collect::<Vec<_>>()
281                        .join("; ");
282                    return Err(OutboundError::Unreachable(format!(
283                        "no platform trust roots could be loaded: {reason}"
284                    )));
285                }
286                store.add_parsable_certificates(loaded.certs);
287                builder.with_root_certificates(store)
288            }
289        };
290
291        let tls = match identity {
292            Some(resolver) => builder.with_client_cert_resolver(resolver),
293            None => builder.with_no_client_auth(),
294        };
295
296        let connector = hyper_rustls::HttpsConnectorBuilder::new()
297            .with_tls_config(tls)
298            .https_or_http()
299            .enable_http1()
300            .wrap_connector(connector);
301
302        Ok(Self {
303            inner: Client::builder(TokioExecutor::new()).build(connector),
304            config,
305        })
306    }
307
308    /// Builds a client trusting the platform's certificate store.
309    ///
310    /// The platform store rather than a bundled root set, so an endpoint behind
311    /// an internal certificate authority works once that authority is installed
312    /// the way everything else on the host already expects.
313    pub fn new(config: ClientConfig) -> Result<Self, OutboundError> {
314        Self::with_identity(config, None, None)
315    }
316
317    /// Fetches one URL and reads the whole response.
318    ///
319    /// Used for rotating key sets: the body is JSON, not a form, and there is
320    /// nothing to POST. Redirects are still not followed — a JWKS URL that
321    /// 30x's the origin elsewhere would be a configuration error, not a hop
322    /// this client should take on its own.
323    pub async fn get(&self, endpoint: &Endpoint) -> Result<Response, OutboundError> {
324        let request = Request::get(endpoint.uri())
325            .body(Full::new(Bytes::new()))
326            .map_err(|error| OutboundError::Unreachable(error.to_string()))?;
327        tokio::time::timeout(self.config.request_timeout, self.send(request))
328            .await
329            .map_err(|_| OutboundError::Timeout)?
330    }
331
332    /// Sends one request and reads the whole response.
333    pub async fn post(
334        &self,
335        endpoint: &Endpoint,
336        content_type: &'static str,
337        bearer: Option<&BearerToken>,
338        body: Bytes,
339    ) -> Result<Response, OutboundError> {
340        self.post_with_headers(endpoint, content_type, bearer, body, &HeaderMap::new())
341            .await
342    }
343
344    /// Sends application headers alongside the ordinary content type and credential.
345    /// The latter remain authoritative even if the supplied map contains them.
346    pub async fn post_with_headers(
347        &self,
348        endpoint: &Endpoint,
349        content_type: &'static str,
350        bearer: Option<&BearerToken>,
351        body: Bytes,
352        headers: &HeaderMap,
353    ) -> Result<Response, OutboundError> {
354        let mut request = Request::post(endpoint.uri())
355            .header(header::CONTENT_TYPE, HeaderValue::from_static(content_type))
356            .body(Full::new(body))
357            .map_err(|error| OutboundError::Unreachable(error.to_string()))?;
358        request.headers_mut().extend(headers.clone());
359        request
360            .headers_mut()
361            .insert(header::CONTENT_TYPE, HeaderValue::from_static(content_type));
362        request.headers_mut().remove(header::AUTHORIZATION);
363        if let Some(bearer) = bearer {
364            request
365                .headers_mut()
366                .insert(header::AUTHORIZATION, bearer.0.clone());
367        }
368
369        tokio::time::timeout(self.config.request_timeout, self.send(request))
370            .await
371            .map_err(|_| OutboundError::Timeout)?
372    }
373
374    async fn send(&self, request: Request<Full<Bytes>>) -> Result<Response, OutboundError> {
375        let response = self
376            .inner
377            .request(request)
378            .await
379            .map_err(|error| OutboundError::Unreachable(error.to_string()))?;
380        let status = response.status();
381        let headers = response.headers().clone();
382        let limit = self.config.maximum_response_bytes;
383        // Bounded while it is read rather than checked afterwards: a
384        // Content-Length is only a claim, and by the time an oversized body has
385        // been collected the memory is already spent.
386        let body = Limited::new(response.into_body(), limit)
387            .collect()
388            .await
389            .map_err(|error| {
390                if error.is::<http_body_util::LengthLimitError>() {
391                    OutboundError::ResponseTooLarge { limit }
392                } else {
393                    OutboundError::Response(error.to_string())
394                }
395            })?
396            .to_bytes();
397
398        Ok(Response {
399            status,
400            headers,
401            body,
402        })
403    }
404}
405
406#[cfg(test)]
407mod tests;