use std::{convert::TryFrom, fmt, sync::Arc, time::Duration};
use http::{
HeaderMap, HeaderName, HeaderValue, Method, Uri,
header::{CONTENT_LENGTH, TRANSFER_ENCODING, USER_AGENT},
};
use http_body::Body as _;
use url::Url;
use crate::{
Error, Limits, Request, RequestBuilder, Response, Result, Timeouts,
auth::Authentication,
connection::{Client as ConnectionClient, Settings as ConnectionSettings},
proxy::Policy as ProxyPolicy,
redirect::Policy as RedirectPolicy,
request::validate_absolute_url,
retry::Policy as RetryPolicy,
runtime::{Executor, Runtime},
tls::TlsBuilder,
transport::Transport,
};
const DEFAULT_USER_AGENT: &str = concat!(env!("CARGO_PKG_NAME"), "/", env!("CARGO_PKG_VERSION"));
pub(crate) struct ClientInner {
pub(crate) connection: ConnectionClient,
pub(crate) base_url: Option<Url>,
pub(crate) decompresses_responses: bool,
pub(crate) default_headers: HeaderMap,
pub(crate) auth: Option<Arc<dyn Authentication>>,
pub(crate) https_only: bool,
#[cfg(feature = "cookies")]
pub(crate) cookies: Option<Arc<crate::cookies::CookieJar>>,
pub(crate) redirects: RedirectPolicy,
pub(crate) retry: RetryPolicy,
pub(crate) limits: Limits,
pub(crate) timeouts: Timeouts,
}
#[derive(Clone)]
pub struct Client {
pub(crate) inner: Arc<ClientInner>,
}
pub struct ClientBuilder {
base_url: Option<String>,
decompresses_responses: bool,
default_headers: HeaderMap,
auth: Option<Arc<dyn Authentication>>,
proxy: ProxyPolicy,
#[cfg(feature = "cookies")]
cookie_jar: Option<Arc<crate::CookieJar>>,
redirects: RedirectPolicy,
retry: RetryPolicy,
tls: TlsBuilder,
runtime: Runtime,
connection: ConnectionSettings,
limits: Limits,
timeouts: Timeouts,
user_agent: Option<String>,
error: Option<Error>,
}
impl Client {
pub fn new() -> Result<Self> {
Self::builder().build()
}
#[must_use]
pub fn builder() -> ClientBuilder {
ClientBuilder::default()
}
#[must_use]
pub fn request(&self, method: Method, target: impl AsRef<str>) -> RequestBuilder<'_> {
RequestBuilder::new(self, method, target.as_ref())
}
#[must_use]
pub fn get(&self, target: impl AsRef<str>) -> RequestBuilder<'_> {
self.request(Method::GET, target)
}
#[must_use]
pub fn post(&self, target: impl AsRef<str>) -> RequestBuilder<'_> {
self.request(Method::POST, target)
}
#[must_use]
pub fn put(&self, target: impl AsRef<str>) -> RequestBuilder<'_> {
self.request(Method::PUT, target)
}
#[must_use]
pub fn patch(&self, target: impl AsRef<str>) -> RequestBuilder<'_> {
self.request(Method::PATCH, target)
}
#[must_use]
pub fn delete(&self, target: impl AsRef<str>) -> RequestBuilder<'_> {
self.request(Method::DELETE, target)
}
#[must_use]
pub fn head(&self, target: impl AsRef<str>) -> RequestBuilder<'_> {
self.request(Method::HEAD, target)
}
#[must_use]
pub fn options(&self, target: impl AsRef<str>) -> RequestBuilder<'_> {
self.request(Method::OPTIONS, target)
}
#[must_use]
pub fn trace(&self, target: impl AsRef<str>) -> RequestBuilder<'_> {
self.request(Method::TRACE, target)
}
#[must_use]
pub fn connect(&self, target: impl AsRef<str>) -> RequestBuilder<'_> {
self.request(Method::CONNECT, target)
}
pub async fn send(&self, request: Request) -> Result<Response> {
crate::dispatch::send(&self.inner, request).await
}
}
impl ClientBuilder {
#[must_use]
pub fn base_url(mut self, value: impl AsRef<str>) -> Self {
self.base_url = Some(value.as_ref().to_owned());
self
}
#[must_use]
pub fn default_header<K, V>(mut self, name: K, value: V) -> Self
where
HeaderName: TryFrom<K>,
HeaderValue: TryFrom<V>,
{
if self.error.is_some() {
return self;
}
let result = (|| {
let name = HeaderName::try_from(name)
.map_err(|_| Error::request("client default header name is invalid"))?;
let value = HeaderValue::try_from(value)
.map_err(|_| Error::request("client default header value is invalid"))?;
self.default_headers.insert(name, value);
Ok(())
})();
if let Err(error) = result {
self.error = Some(error);
}
self
}
#[must_use]
pub fn default_headers(mut self, headers: HeaderMap) -> Self {
self.default_headers = headers;
self
}
#[must_use]
pub fn auth(mut self, authentication: impl Authentication + 'static) -> Self {
self.auth = Some(Arc::new(authentication));
self
}
#[must_use]
pub fn user_agent(mut self, value: impl AsRef<str>) -> Self {
self.user_agent = Some(value.as_ref().to_owned());
self
}
#[must_use]
pub fn no_user_agent(mut self) -> Self {
self.user_agent = None;
self
}
#[must_use]
pub fn timeout(mut self, timeout: impl Into<Option<Duration>>) -> Self {
self.timeouts = self.timeouts.total(timeout);
if self.error.is_none()
&& let Err(error) = self.timeouts.validate()
{
self.error = Some(error);
}
self
}
#[must_use]
pub fn timeouts(mut self, timeouts: Timeouts) -> Self {
self.timeouts = timeouts;
if self.error.is_none()
&& let Err(error) = self.timeouts.validate()
{
self.error = Some(error);
}
self
}
#[must_use]
pub fn limits(mut self, limits: Limits) -> Self {
self.limits = limits;
if self.error.is_none()
&& let Err(error) = self.limits.validate()
{
self.error = Some(error);
}
self
}
#[must_use]
pub fn resolver(mut self, resolver: impl crate::dns::Resolver + 'static) -> Self {
self.runtime.set_resolver(resolver);
self
}
#[must_use]
pub fn connection(mut self, settings: ConnectionSettings) -> Self {
self.connection = settings;
if self.error.is_none()
&& let Err(error) = self.connection.validate()
{
self.error = Some(error);
}
self
}
#[must_use]
pub fn redirects(mut self, policy: RedirectPolicy) -> Self {
self.redirects = policy;
self
}
#[must_use]
pub fn retry(mut self, policy: RetryPolicy) -> Self {
self.retry = policy;
self
}
#[must_use]
pub fn proxy(mut self, policy: ProxyPolicy) -> Self {
self.proxy = policy;
self
}
#[must_use]
pub fn executor(mut self, executor: Executor) -> Self {
self.runtime.set_executor(executor);
self
}
#[must_use]
pub fn runtime(mut self, runtime: Runtime) -> Self {
self.runtime = runtime;
self
}
#[must_use]
pub fn disable_compression(mut self) -> Self {
self.decompresses_responses = false;
self
}
#[cfg(feature = "cookies")]
#[must_use]
pub fn cookies(mut self) -> Self {
self.cookie_jar = Some(Arc::new(crate::CookieJar::new()));
self
}
#[cfg(feature = "cookies")]
#[must_use]
pub fn cookie_jar(mut self, jar: Arc<crate::CookieJar>) -> Self {
self.cookie_jar = Some(jar);
self
}
#[must_use]
pub fn trust_pem(mut self, bundle: impl AsRef<[u8]>) -> Self {
self.tls.roots(bundle.as_ref());
self
}
#[must_use]
pub fn add_root_pem(mut self, bundle: impl AsRef<[u8]>) -> Self {
self.tls.add_roots(bundle.as_ref());
self
}
#[must_use]
pub fn identity_pem(mut self, identity: impl AsRef<[u8]>) -> Self {
self.tls.identity(identity.as_ref());
self
}
#[must_use]
pub fn minimum_tls_version(mut self, version: crate::tls::Version) -> Self {
self.tls.minimum_version(version);
self
}
#[must_use]
pub fn maximum_tls_version(mut self, version: crate::tls::Version) -> Self {
self.tls.maximum_version(version);
self
}
#[must_use]
pub fn https_only(mut self) -> Self {
self.tls.require_https();
self
}
pub fn build(self) -> Result<Client> {
if let Some(error) = self.error {
return Err(error);
}
self.limits.validate()?;
self.timeouts.validate()?;
self.connection.validate()?;
let base_url = self.base_url.as_deref().map(parse_base_url).transpose()?;
if self.tls.is_https_only()
&& base_url
.as_ref()
.is_some_and(|base_url| base_url.scheme() != "https")
{
return Err(Error::request("client base URL must use HTTPS"));
}
let mut default_headers = self.default_headers;
default_headers.remove(USER_AGENT);
if let Some(user_agent) = self.user_agent {
let user_agent = user_agent
.parse::<HeaderValue>()
.map_err(|_| Error::request("client user agent is invalid"))?;
default_headers.insert(USER_AGENT, user_agent);
}
let https_only = self.tls.is_https_only();
self.runtime.executor().prepare()?;
let transport =
Transport::new(self.tls, self.proxy, self.runtime.clone(), self.connection)?;
let connection = ConnectionClient::from_parts(
transport,
self.runtime,
self.connection,
self.limits,
self.timeouts,
);
Ok(Client {
inner: Arc::new(ClientInner {
connection,
base_url,
decompresses_responses: self.decompresses_responses,
default_headers,
auth: self.auth,
https_only,
#[cfg(feature = "cookies")]
cookies: self.cookie_jar,
redirects: self.redirects,
retry: self.retry,
limits: self.limits,
timeouts: self.timeouts,
}),
})
}
}
impl Default for ClientBuilder {
fn default() -> Self {
Self {
base_url: None,
decompresses_responses: true,
default_headers: HeaderMap::new(),
auth: None,
proxy: ProxyPolicy::default(),
#[cfg(feature = "cookies")]
cookie_jar: None,
redirects: RedirectPolicy::NoFollow,
retry: RetryPolicy::Never,
tls: TlsBuilder::default(),
runtime: Runtime::default(),
connection: ConnectionSettings::default(),
limits: Limits::default(),
timeouts: Timeouts::default(),
user_agent: Some(DEFAULT_USER_AGENT.to_owned()),
error: None,
}
}
}
impl fmt::Debug for Client {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
let mut debug = formatter.debug_struct("Client");
debug
.field("has_base_url", &self.inner.base_url.is_some())
.field("decompresses_responses", &self.inner.decompresses_responses)
.field("default_header_count", &self.inner.default_headers.len())
.field("has_auth", &self.inner.auth.is_some())
.field("https_only", &self.inner.https_only);
#[cfg(feature = "cookies")]
debug.field("cookie_jar", &self.inner.cookies.is_some());
debug
.field("redirects", &self.inner.redirects)
.field("retry", &self.inner.retry)
.field("limits", &self.inner.limits)
.field("timeouts", &self.inner.timeouts)
.finish_non_exhaustive()
}
}
impl fmt::Debug for ClientBuilder {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
let mut debug = formatter.debug_struct("ClientBuilder");
debug
.field("has_base_url", &self.base_url.is_some())
.field("decompresses_responses", &self.decompresses_responses)
.field("default_header_count", &self.default_headers.len())
.field("has_auth", &self.auth.is_some())
.field("has_error", &self.error.is_some())
.field("has_user_agent", &self.user_agent.is_some())
.field(
"has_custom_user_agent",
&self
.user_agent
.as_deref()
.is_some_and(|value| value != DEFAULT_USER_AGENT),
)
.field("proxy", &self.proxy);
#[cfg(feature = "cookies")]
debug.field("cookie_jar", &self.cookie_jar.is_some());
debug
.field("redirects", &self.redirects)
.field("retry", &self.retry)
.field("has_custom_tls_roots", &self.tls.has_roots())
.field("has_additional_tls_roots", &self.tls.has_extra_roots())
.field("has_tls_client_identity", &self.tls.has_identity())
.field("https_only", &self.tls.is_https_only())
.field("limits", &self.limits)
.field("connection", &self.connection)
.field("timeouts", &self.timeouts)
.finish_non_exhaustive()
}
}
fn parse_base_url(value: &str) -> Result<Url> {
let url = Url::parse(value).map_err(|_| Error::request("client base URL is invalid"))?;
validate_absolute_url(&url).map_err(|_| Error::request("client base URL is invalid"))?;
if url.query().is_some() || url.fragment().is_some() {
return Err(Error::request("client base URL is invalid"));
}
Ok(url)
}
pub(crate) fn resolve_target(base_url: Option<&Url>, target: &Uri) -> Result<Uri> {
if target.scheme().is_some() && target.authority().is_some() {
validate_absolute_uri(target)?;
return Ok(target.clone());
}
let path_and_query = target
.path_and_query()
.ok_or_else(|| Error::request("request path is invalid"))?;
let path = path_and_query.path();
if !path.starts_with('/') || path.starts_with("//") {
return Err(Error::request("request path is invalid"));
}
if path.split('/').any(is_dot_segment) {
return Err(Error::request("request path is invalid"));
}
let base = base_url.ok_or_else(|| Error::request("a client base URL is required for paths"))?;
let prefix = base.as_str().trim_end_matches('/');
let resolved = Url::parse(&format!("{prefix}{path_and_query}"))
.map_err(|_| Error::request("request path is invalid"))?;
let base_path = base.path().trim_end_matches('/');
if !base_path.is_empty()
&& resolved.path() != base_path
&& !resolved
.path()
.strip_prefix(base_path)
.is_some_and(|suffix| suffix.starts_with('/'))
{
return Err(Error::request("request path escapes the client base URL"));
}
resolved
.as_str()
.parse()
.map_err(|_| Error::request("request path is invalid"))
}
pub(crate) fn validate_absolute_uri(uri: &Uri) -> Result<()> {
let authority = uri
.authority()
.ok_or_else(|| Error::request("request URL is invalid"))?;
if !matches!(uri.scheme_str(), Some("http" | "https"))
|| authority.host().is_empty()
|| authority.as_str().contains('@')
{
return Err(Error::request("request URL is invalid"));
}
Ok(())
}
fn is_dot_segment(segment: &str) -> bool {
let mut bytes = segment.as_bytes();
let mut dots = 0;
while !bytes.is_empty() && dots < 2 {
if bytes[0] == b'.' {
bytes = &bytes[1..];
} else if bytes.len() >= 3
&& bytes[0] == b'%'
&& bytes[1] == b'2'
&& bytes[2].eq_ignore_ascii_case(&b'e')
{
bytes = &bytes[3..];
} else {
break;
}
dots += 1;
}
bytes.is_empty() && matches!(dots, 1 | 2)
}
pub(crate) fn merge_default_headers(request: &mut HeaderMap, defaults: &HeaderMap) {
for name in defaults.keys() {
if request.contains_key(name) {
continue;
}
for value in defaults.get_all(name) {
request.append(name.clone(), value.clone());
}
}
}
pub(crate) fn validate_framing(headers: &HeaderMap, body: &crate::Body) -> Result<()> {
if headers.contains_key(TRANSFER_ENCODING) {
return Err(Error::request("request framing headers are invalid"));
}
let mut values = headers.get_all(CONTENT_LENGTH).iter();
let Some(value) = values.next() else {
return Ok(());
};
if values.next().is_some() {
return Err(Error::request("request framing headers are invalid"));
}
let declared = value
.to_str()
.ok()
.and_then(|value| value.parse::<u64>().ok())
.ok_or_else(|| Error::request("request content length is invalid"))?;
let length = body
.size_hint()
.exact()
.ok_or_else(|| Error::request("request content length requires an exactly sized body"))?;
if length != declared {
return Err(Error::request(
"request content length does not match its body",
));
}
Ok(())
}
#[cfg(test)]
mod tests {
use super::*;
use http::HeaderValue;
#[test]
fn resolves_paths_inside_the_base_url_prefix() {
let base = parse_base_url("https://example.com/api/").unwrap();
assert_eq!(
resolve_target(Some(&base), &"/users?active=true".parse().unwrap()).unwrap(),
"https://example.com/api/users?active=true"
);
assert_eq!(
resolve_target(
Some(&base),
&"https://other.example/health".parse().unwrap()
)
.unwrap(),
"https://other.example/health"
);
assert!(resolve_target(Some(&base), &"/../admin".parse().unwrap()).is_err());
for path in [
"/users/./settings",
"/users/../settings",
"/users/%2e/settings",
"/users/%2E%2e/settings",
] {
assert!(resolve_target(Some(&base), &path.parse().unwrap()).is_err());
}
assert!(resolve_target(None, &"/users".parse().unwrap()).is_err());
}
#[test]
fn absolute_targets_are_revalidated_at_the_client_boundary() {
for target in ["ftp://example.com/file", "https://user@example.com/private"] {
let uri = target.parse().expect("syntactically valid URI");
assert!(resolve_target(None, &uri).is_err());
}
}
#[test]
fn request_headers_replace_client_defaults_by_name() {
let mut defaults = HeaderMap::new();
defaults.insert("x-client", HeaderValue::from_static("default"));
defaults.append("x-repeated", HeaderValue::from_static("first"));
defaults.append("x-repeated", HeaderValue::from_static("second"));
let mut request = HeaderMap::new();
request.insert("x-client", HeaderValue::from_static("request"));
merge_default_headers(&mut request, &defaults);
assert_eq!(request["x-client"], "request");
assert_eq!(request.get_all("x-repeated").iter().count(), 2);
}
#[test]
fn manual_framing_requires_one_matching_exact_length() {
let mut headers = HeaderMap::new();
headers.insert(CONTENT_LENGTH, HeaderValue::from_static("3"));
assert!(validate_framing(&headers, &crate::Body::from("tez")).is_ok());
headers.insert(CONTENT_LENGTH, HeaderValue::from_static("2"));
assert!(validate_framing(&headers, &crate::Body::from("tez")).is_err());
headers.insert(TRANSFER_ENCODING, HeaderValue::from_static("chunked"));
assert!(validate_framing(&headers, &crate::Body::from("tez")).is_err());
}
#[test]
fn client_builder_rejects_invalid_configuration_without_echoing_it() {
let timeout = Client::builder()
.timeout(Duration::ZERO)
.default_header("not a header", "secret")
.timeout(None)
.build()
.unwrap_err();
assert!(timeout.is_request());
assert_eq!(
timeout.to_string(),
"client total timeout must be greater than zero"
);
assert!(!format!("{timeout:?}").contains("secret"));
let invalid = Client::builder()
.base_url("https://example.com/api?token=secret")
.build()
.unwrap_err();
assert!(invalid.is_request());
assert!(!invalid.to_string().contains("secret"));
let invalid = Client::builder()
.user_agent("private-agent\nsecret")
.build()
.unwrap_err();
assert!(invalid.is_request());
assert_eq!(invalid.to_string(), "client user agent is invalid");
assert!(!format!("{invalid:?}").contains("private-agent"));
assert!(!format!("{invalid:?}").contains("secret"));
assert!(
Client::builder()
.user_agent("private-agent\nsecret")
.no_user_agent()
.build()
.is_ok()
);
let zero_connections = Client::builder()
.limits(Limits::default().connections_per_origin(0))
.build()
.unwrap_err();
assert_eq!(
zero_connections.to_string(),
"client connection limit must be greater than zero"
);
let excessive_idle = Client::builder()
.limits(
Limits::default()
.connections_per_origin(2)
.idle_connections_per_origin(3),
)
.build()
.unwrap_err();
assert_eq!(
excessive_idle.to_string(),
"client idle connection limit exceeds its connection limit"
);
}
#[test]
fn client_builder_defers_default_header_errors_and_retains_the_first() {
let invalid_name = Client::builder()
.default_header("not a header", "secret")
.build()
.unwrap_err();
assert!(invalid_name.is_request());
assert_eq!(
invalid_name.to_string(),
"client default header name is invalid"
);
assert!(!invalid_name.to_string().contains("secret"));
let first = Client::builder()
.default_header("authorization", "Bearer secret\n")
.default_header("not a header", "secret")
.timeout(Duration::ZERO)
.build()
.unwrap_err();
assert!(first.is_request());
assert_eq!(first.to_string(), "client default header value is invalid");
assert!(!first.to_string().contains("secret"));
}
#[test]
fn client_builder_uses_the_default_or_explicit_total_deadline() {
let default = Client::builder().build().unwrap();
assert_eq!(
default.inner.timeouts.total_timeout(),
Some(Duration::from_secs(30))
);
assert_eq!(default.inner.redirects, RedirectPolicy::NoFollow);
assert_eq!(default.inner.retry, RetryPolicy::Never);
let bounded = Client::builder()
.timeout(Duration::from_secs(5))
.build()
.unwrap();
assert_eq!(
bounded.inner.timeouts.total_timeout(),
Some(Duration::from_secs(5))
);
let unbounded = Client::builder().timeout(None).build().unwrap();
assert_eq!(unbounded.inner.timeouts.total_timeout(), None);
let follows_same_origin = Client::builder()
.redirects(RedirectPolicy::SameOrigin)
.build()
.unwrap();
assert_eq!(
follows_same_origin.inner.redirects,
RedirectPolicy::SameOrigin
);
let retries_idempotent = Client::builder()
.retry(RetryPolicy::Idempotent)
.build()
.unwrap();
assert_eq!(retries_idempotent.inner.retry, RetryPolicy::Idempotent);
}
#[test]
fn client_builder_debug_reports_user_agent_policy_without_its_value() {
let default = format!("{:?}", Client::builder());
assert!(default.contains("has_user_agent: true"));
assert!(default.contains("has_custom_user_agent: false"));
let omitted = format!("{:?}", Client::builder().no_user_agent());
assert!(omitted.contains("has_user_agent: false"));
assert!(omitted.contains("has_custom_user_agent: false"));
let custom = format!("{:?}", Client::builder().user_agent("private-agent/secret"));
assert!(custom.contains("has_user_agent: true"));
assert!(custom.contains("has_custom_user_agent: true"));
assert!(!custom.contains("private-agent"));
assert!(!custom.contains("secret"));
}
}