use std::{fmt, net::IpAddr, time::Duration};
use reqwest::Url;
use thiserror::Error;
const MEBIBYTE: usize = 1024 * 1024;
#[derive(Clone, Eq, PartialEq)]
pub struct ProviderEndpoint {
base: Url,
transport: EndpointTransport,
}
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
enum EndpointTransport {
Https,
LoopbackHttp,
}
impl ProviderEndpoint {
pub fn https(value: &str) -> Result<Self, ProviderEndpointError> {
Self::parse(value, EndpointTransport::Https)
}
pub fn loopback_http(value: &str) -> Result<Self, ProviderEndpointError> {
Self::parse(value, EndpointTransport::LoopbackHttp)
}
fn parse(value: &str, transport: EndpointTransport) -> Result<Self, ProviderEndpointError> {
let mut base = Url::parse(value).map_err(|_| ProviderEndpointError::InvalidUrl)?;
if !base.username().is_empty() || base.password().is_some() {
return Err(ProviderEndpointError::EmbeddedCredentials);
}
if base.query().is_some() || base.fragment().is_some() {
return Err(ProviderEndpointError::QueryOrFragment);
}
let host = base.host_str().ok_or(ProviderEndpointError::MissingHost)?;
match transport {
EndpointTransport::Https if base.scheme() != "https" => {
return Err(ProviderEndpointError::HttpsRequired);
}
EndpointTransport::LoopbackHttp => {
if base.scheme() != "http" {
return Err(ProviderEndpointError::LoopbackHttpRequired);
}
let address = host
.parse::<IpAddr>()
.map_err(|_| ProviderEndpointError::LiteralLoopbackRequired)?;
if !address.is_loopback() {
return Err(ProviderEndpointError::LiteralLoopbackRequired);
}
}
EndpointTransport::Https => {}
}
if !base.path().ends_with('/') {
let mut path = base.path().to_owned();
path.push('/');
base.set_path(&path);
}
Ok(Self { base, transport })
}
pub(crate) fn join(&self, relative: &str) -> Result<Url, ProviderEndpointError> {
self.base
.join(relative)
.map_err(|_| ProviderEndpointError::InvalidRelativePath)
}
#[must_use]
pub const fn is_https(&self) -> bool {
matches!(self.transport, EndpointTransport::Https)
}
}
impl fmt::Debug for ProviderEndpoint {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
formatter
.debug_struct("ProviderEndpoint")
.field("transport", &self.transport)
.field("host", &"[REDACTED]")
.finish_non_exhaustive()
}
}
#[derive(Clone, Copy, Debug, Eq, Error, PartialEq)]
#[non_exhaustive]
pub enum ProviderEndpointError {
#[error("provider endpoint is not an absolute URL")]
InvalidUrl,
#[error("provider endpoint must use HTTPS")]
HttpsRequired,
#[error("loopback provider endpoint must use HTTP")]
LoopbackHttpRequired,
#[error("loopback provider endpoint must use a literal loopback IP address")]
LiteralLoopbackRequired,
#[error("provider endpoint must include a host")]
MissingHost,
#[error("provider endpoint must not contain embedded credentials")]
EmbeddedCredentials,
#[error("provider endpoint must not contain a query or fragment")]
QueryOrFragment,
#[error("provider API path could not be joined to the configured endpoint")]
InvalidRelativePath,
}
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub struct ProviderHttpOptions {
connect_timeout: Duration,
pool_idle_timeout: Duration,
maximum_request_bytes: usize,
maximum_response_bytes: usize,
maximum_sse_line_bytes: usize,
maximum_sse_event_bytes: usize,
maximum_sse_total_bytes: usize,
}
impl ProviderHttpOptions {
pub const HARD_MAXIMUM_REQUEST_BYTES: usize = 32 * MEBIBYTE;
pub const HARD_MAXIMUM_RESPONSE_BYTES: usize = 128 * MEBIBYTE;
pub const HARD_MAXIMUM_SSE_LINE_BYTES: usize = 128 * MEBIBYTE;
pub const HARD_MAXIMUM_SSE_EVENT_BYTES: usize = 128 * MEBIBYTE;
pub const HARD_MAXIMUM_SSE_TOTAL_BYTES: usize = 256 * MEBIBYTE;
#[allow(clippy::too_many_arguments)]
pub const fn new(
connect_timeout: Duration,
pool_idle_timeout: Duration,
maximum_request_bytes: usize,
maximum_response_bytes: usize,
maximum_sse_line_bytes: usize,
maximum_sse_event_bytes: usize,
maximum_sse_total_bytes: usize,
) -> Result<Self, ProviderHttpOptionsError> {
if connect_timeout.is_zero() || pool_idle_timeout.is_zero() {
return Err(ProviderHttpOptionsError::ZeroDuration);
}
if maximum_request_bytes == 0
|| maximum_response_bytes == 0
|| maximum_sse_line_bytes == 0
|| maximum_sse_event_bytes == 0
|| maximum_sse_total_bytes == 0
{
return Err(ProviderHttpOptionsError::ZeroBytes);
}
if maximum_request_bytes > Self::HARD_MAXIMUM_REQUEST_BYTES
|| maximum_response_bytes > Self::HARD_MAXIMUM_RESPONSE_BYTES
|| maximum_sse_line_bytes > Self::HARD_MAXIMUM_SSE_LINE_BYTES
|| maximum_sse_event_bytes > Self::HARD_MAXIMUM_SSE_EVENT_BYTES
|| maximum_sse_total_bytes > Self::HARD_MAXIMUM_SSE_TOTAL_BYTES
{
return Err(ProviderHttpOptionsError::AboveHardMaximum);
}
if maximum_sse_event_bytes < maximum_sse_line_bytes {
return Err(ProviderHttpOptionsError::EventBelowLine);
}
if maximum_sse_total_bytes < maximum_sse_event_bytes {
return Err(ProviderHttpOptionsError::TotalBelowEvent);
}
Ok(Self {
connect_timeout,
pool_idle_timeout,
maximum_request_bytes,
maximum_response_bytes,
maximum_sse_line_bytes,
maximum_sse_event_bytes,
maximum_sse_total_bytes,
})
}
#[must_use]
pub const fn connect_timeout(self) -> Duration {
self.connect_timeout
}
#[must_use]
pub const fn pool_idle_timeout(self) -> Duration {
self.pool_idle_timeout
}
#[must_use]
pub const fn maximum_request_bytes(self) -> usize {
self.maximum_request_bytes
}
#[must_use]
pub const fn maximum_response_bytes(self) -> usize {
self.maximum_response_bytes
}
#[must_use]
pub const fn maximum_sse_line_bytes(self) -> usize {
self.maximum_sse_line_bytes
}
#[must_use]
pub const fn maximum_sse_event_bytes(self) -> usize {
self.maximum_sse_event_bytes
}
#[must_use]
pub const fn maximum_sse_total_bytes(self) -> usize {
self.maximum_sse_total_bytes
}
}
impl Default for ProviderHttpOptions {
fn default() -> Self {
Self {
connect_timeout: Duration::from_secs(10),
pool_idle_timeout: Duration::from_secs(90),
maximum_request_bytes: 16 * MEBIBYTE,
maximum_response_bytes: 2 * MEBIBYTE,
maximum_sse_line_bytes: 512 * 1024,
maximum_sse_event_bytes: 2 * MEBIBYTE,
maximum_sse_total_bytes: 64 * MEBIBYTE,
}
}
}
#[derive(Clone, Copy, Debug, Eq, Error, PartialEq)]
#[non_exhaustive]
pub enum ProviderHttpOptionsError {
#[error("provider HTTP timeouts must be positive")]
ZeroDuration,
#[error("provider HTTP byte ceilings must be positive")]
ZeroBytes,
#[error("provider HTTP byte ceiling exceeds the implementation maximum")]
AboveHardMaximum,
#[error("provider SSE event ceiling must be at least its line ceiling")]
EventBelowLine,
#[error("provider SSE total ceiling must be at least its event ceiling")]
TotalBelowEvent,
}
pub(crate) fn build_client(
options: ProviderHttpOptions,
) -> Result<reqwest::Client, reqwest::Error> {
reqwest::Client::builder()
.connect_timeout(options.connect_timeout())
.pool_idle_timeout(options.pool_idle_timeout())
.redirect(reqwest::redirect::Policy::none())
.retry(reqwest::retry::never())
.user_agent(concat!(
"stateknot-integrations/",
env!("CARGO_PKG_VERSION")
))
.build()
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn endpoints_fail_closed_on_transport_and_authority_ambiguity() {
assert_eq!(
ProviderEndpoint::https("http://api.example.com/v1/"),
Err(ProviderEndpointError::HttpsRequired)
);
assert_eq!(
ProviderEndpoint::https("https://user:secret@api.example.com/v1/"),
Err(ProviderEndpointError::EmbeddedCredentials)
);
assert_eq!(
ProviderEndpoint::https("https://api.example.com/v1/?tenant=secret"),
Err(ProviderEndpointError::QueryOrFragment)
);
assert_eq!(
ProviderEndpoint::loopback_http("http://localhost:8080/v1/"),
Err(ProviderEndpointError::LiteralLoopbackRequired)
);
assert_eq!(
ProviderEndpoint::loopback_http("http://10.0.0.1:8080/v1/"),
Err(ProviderEndpointError::LiteralLoopbackRequired)
);
let endpoint = ProviderEndpoint::https("https://private.example.com/tenant-a").unwrap();
let debug = format!("{endpoint:?}");
assert!(!debug.contains("private.example.com"));
assert!(!debug.contains("tenant-a"));
}
#[test]
fn transport_limits_are_positive_nested_and_hard_bounded() {
assert_eq!(
ProviderHttpOptions::new(Duration::ZERO, Duration::from_secs(1), 1, 1, 1, 1, 1,),
Err(ProviderHttpOptionsError::ZeroDuration)
);
assert_eq!(
ProviderHttpOptions::new(
Duration::from_secs(1),
Duration::from_secs(1),
1,
1,
2,
1,
2,
),
Err(ProviderHttpOptionsError::EventBelowLine)
);
}
}