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;