use std::{
convert::TryFrom,
fmt,
sync::Arc,
time::{Duration, Instant},
};
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, Request, RequestBuilder, Response, Result,
auth::Authentication,
backend::{Backend, BackendConfig, TlsPolicy},
proxy::Policy as ProxyPolicy,
redirect::Policy as RedirectPolicy,
request::{resolve_timeout, validate_absolute_url},
retry::{self, Policy as RetryPolicy},
};
const DEFAULT_TIMEOUT: Duration = Duration::from_secs(30);
const DEFAULT_USER_AGENT: &str = concat!(env!("CARGO_PKG_NAME"), "/", env!("CARGO_PKG_VERSION"));
struct ClientInner {
backend: Backend,
base_url: Option<Url>,
decompresses_responses: bool,
default_headers: HeaderMap,
auth: Option<Arc<dyn Authentication>>,
https_only: bool,
cookie_jar: bool,
redirects: RedirectPolicy,
retry: RetryPolicy,
timeout: Option<Duration>,
}
#[derive(Clone)]
pub struct Client {
inner: Arc<ClientInner>,
}
pub struct ClientBuilder {
base_url: Option<String>,
decompresses_responses: bool,
default_headers: HeaderMap,
auth: Option<Arc<dyn Authentication>>,
proxy: ProxyPolicy,
cookie_jar: bool,
redirects: RedirectPolicy,
retry: RetryPolicy,
tls: TlsPolicy,
timeout: Option<Duration>,
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)
}
pub async fn send(&self, request: Request) -> Result<Response> {
let timeout = resolve_timeout(&request, self.inner.timeout);
let started = Instant::now();
let request = self.prepare(request).await?;
match retry::Plan::new(self.inner.retry, request) {
retry::Plan::Once(request) => {
self.inner
.backend
.execute(request, remaining(started, timeout)?)
.await
}
retry::Plan::Repeat(request) => self.send_repeated(request, started, timeout).await,
}
}
async fn send_repeated(
&self,
request: retry::RepeatableRequest,
started: Instant,
timeout: Option<Duration>,
) -> Result<Response> {
let mut attempts = 0;
loop {
attempts += 1;
let attempt_timeout = remaining(started, timeout)?;
match self
.inner
.backend
.execute(request.request(), attempt_timeout)
.await
{
Ok(response) => {
let Some(delay) = retry::retry_after_response(&response, attempts) else {
return Ok(response);
};
response.discard().await?;
wait(delay, started, timeout).await?;
}
Err(error) => {
let Some(delay) = retry::retry_after_error(&error, attempts) else {
return Err(error);
};
wait(delay, started, timeout).await?;
}
}
}
}
async fn prepare(&self, request: Request) -> Result<Request> {
let (mut parts, body) = request.into_parts();
parts.uri = resolve_target(self.inner.base_url.as_ref(), &parts.uri)?;
if self.inner.https_only && parts.uri.scheme_str() != Some("https") {
return Err(Error::request("request URL must use HTTPS"));
}
let request_auth = parts.extensions.remove::<Arc<dyn Authentication>>();
merge_default_headers(&mut parts.headers, &self.inner.default_headers);
let mut request = http::Request::from_parts(parts, body);
let authentication = request_auth
.as_deref()
.or_else(|| self.inner.auth.as_deref());
if let Some(authentication) = authentication {
authentication.authenticate(&mut request).await?;
}
validate_framing(request.headers(), request.body())?;
Ok(request)
}
}
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 {
if self.error.is_none() {
match timeout.into() {
Some(duration) if duration.is_zero() => {
self.error = Some(Error::request("client timeout must be greater than zero"));
}
timeout => self.timeout = timeout,
}
}
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 disable_compression(mut self) -> Self {
self.decompresses_responses = false;
self
}
#[cfg(feature = "cookies")]
#[must_use]
pub fn cookies(mut self) -> Self {
self.cookie_jar = true;
self
}
#[must_use]
pub fn trust_pem(mut self, bundle: impl AsRef<[u8]>) -> Self {
self.tls.set_root_certificates_pem(bundle.as_ref());
self
}
#[must_use]
pub fn identity_pem(mut self, identity: impl AsRef<[u8]>) -> Self {
self.tls.set_client_identity_pem(identity.as_ref());
self
}
#[must_use]
pub fn https_only(mut self) -> Self {
self.tls.enable_https_only();
self
}
pub fn build(self) -> Result<Client> {
if let Some(error) = self.error {
return Err(error);
}
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();
let backend = Backend::new(BackendConfig::new(
self.decompresses_responses,
self.cookie_jar,
self.redirects,
self.proxy,
self.tls,
))?;
Ok(Client {
inner: Arc::new(ClientInner {
backend,
base_url,
decompresses_responses: self.decompresses_responses,
default_headers,
auth: self.auth,
https_only,
cookie_jar: self.cookie_jar,
redirects: self.redirects,
retry: self.retry,
timeout: self.timeout,
}),
})
}
}
impl Default for ClientBuilder {
fn default() -> Self {
Self {
base_url: None,
decompresses_responses: true,
default_headers: HeaderMap::new(),
auth: None,
proxy: ProxyPolicy::default(),
cookie_jar: false,
redirects: RedirectPolicy::NoFollow,
retry: RetryPolicy::Never,
tls: TlsPolicy::default(),
timeout: Some(DEFAULT_TIMEOUT),
user_agent: Some(DEFAULT_USER_AGENT.to_owned()),
error: None,
}
}
}
impl fmt::Debug for Client {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
formatter
.debug_struct("Client")
.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)
.field("cookie_jar", &self.inner.cookie_jar)
.field("redirects", &self.inner.redirects)
.field("retry", &self.inner.retry)
.field("timeout", &self.inner.timeout)
.finish()
}
}
impl fmt::Debug for ClientBuilder {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
formatter
.debug_struct("ClientBuilder")
.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)
.field("cookie_jar", &self.cookie_jar)
.field("redirects", &self.redirects)
.field("retry", &self.retry)
.field("has_custom_tls_roots", &self.tls.has_custom_roots())
.field("has_tls_client_identity", &self.tls.has_client_identity())
.field("https_only", &self.tls.is_https_only())
.field("timeout", &self.timeout)
.finish()
}
}
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)
}
fn resolve_target(base_url: Option<&Url>, target: &Uri) -> Result<Uri> {
if target.scheme().is_some() && target.authority().is_some() {
let url = Url::parse(&target.to_string())
.map_err(|_| Error::request("request URL is invalid"))?;
validate_absolute_url(&url)?;
return url
.as_str()
.parse()
.map_err(|_| Error::request("request URL is invalid"));
}
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"))
}
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)
}
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());
}
}
}
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(())
}
fn remaining(started: Instant, timeout: Option<Duration>) -> Result<Option<Duration>> {
timeout
.map(|timeout| {
timeout
.checked_sub(started.elapsed())
.filter(|remaining| !remaining.is_zero())
.ok_or_else(Error::timeout)
})
.transpose()
}
async fn wait(delay: Duration, started: Instant, timeout: Option<Duration>) -> Result<()> {
if let Some(remaining) = remaining(started, timeout)?
&& delay >= remaining
{
return Err(Error::timeout());
}
tokio::time::sleep(delay).await;
remaining(started, timeout).map(|_| ())
}
#[cfg(test)]
mod tests {
use super::*;
use {
http::HeaderValue,
std::{
future::Future as _,
task::{Context, Poll, Waker},
},
};
#[tokio::test]
async fn retry_wait_that_reaches_the_deadline_fails_without_sleeping() {
let mut wait = Box::pin(wait(
Duration::from_secs(2),
Instant::now(),
Some(Duration::from_secs(1)),
));
let mut context = Context::from_waker(Waker::noop());
let Poll::Ready(Err(error)) = wait.as_mut().poll(&mut context) else {
panic!("a retry wait that cannot fit must fail immediately");
};
assert!(error.is_timeout());
}
#[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 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 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()
);
}
#[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.timeout, Some(DEFAULT_TIMEOUT));
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.timeout, Some(Duration::from_secs(5)));
let unbounded = Client::builder().timeout(None).build().unwrap();
assert_eq!(unbounded.inner.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"));
}
}