use std::{
collections::{HashSet, hash_map::RandomState},
fmt,
future::Future,
hash::BuildHasher,
panic::{AssertUnwindSafe, catch_unwind},
pin::Pin,
sync::{
Arc, OnceLock,
atomic::{AtomicU64, Ordering},
},
task::{Context, Poll},
time::{Duration, SystemTime},
};
use http::{HeaderMap, HeaderName, HeaderValue, Method, StatusCode, header::USER_AGENT};
use tokio::time::Instant;
use url::Url;
#[cfg(feature = "cookies")]
use crate::Jar;
#[cfg(test)]
use crate::retry::retry_after_at;
use crate::{
Auth, Error, ErrorKind, Proxy, Redirect, RedirectError, Request, RequestBuilder, Response,
Result, Retry, Tls,
redirect::redirect_request,
request::{
is_credential_header, query_method, reference_scheme, same_origin,
validate_http_authority_syntax,
},
response::DEFAULT_BODY_LIMIT,
retry::{is_retry_status, is_transient_error, retry_after},
transport::{ReqwestConfig, ReqwestTransport, Transport},
};
#[cfg(feature = "cookies")]
use http::header::{COOKIE, SET_COOKIE};
#[cfg(test)]
use http::header::{LOCATION, RETRY_AFTER};
const DEFAULT_CONNECT_TIMEOUT: Duration = Duration::from_secs(10);
const DEFAULT_TOTAL_TIMEOUT: Duration = Duration::from_secs(30);
const DEFAULT_READ_TIMEOUT: Duration = Duration::from_secs(30);
const REDIRECT_DRAIN_LIMIT: usize = 8 * 1024;
#[derive(Clone)]
pub struct Client {
transport: Arc<dyn Transport>,
default_transport: bool,
total_timeout: Duration,
read_timeout: Duration,
body_limit: usize,
base_url: Option<Url>,
auth: Option<Auth>,
default_headers: HeaderMap,
redirect: Redirect,
retry: Retry,
identity_origin: Option<Url>,
#[cfg(feature = "cookies")]
jar: Option<Jar>,
}
pub struct ClientBuilder {
connect_timeout: Option<Duration>,
total_timeout: Duration,
read_timeout: Duration,
body_limit: usize,
base_url: Option<String>,
auth: Option<Auth>,
default_headers: HeaderMap,
redirect: Redirect,
retry: Retry,
tls: Tls,
proxies: Vec<Proxy>,
#[cfg(feature = "cookies")]
jar: Option<Jar>,
transport: Option<Arc<dyn Transport>>,
}
impl Default for ClientBuilder {
fn default() -> Self {
Self {
connect_timeout: None,
total_timeout: DEFAULT_TOTAL_TIMEOUT,
read_timeout: DEFAULT_READ_TIMEOUT,
body_limit: DEFAULT_BODY_LIMIT,
base_url: None,
auth: None,
default_headers: HeaderMap::new(),
redirect: Redirect::NoFollow,
retry: Retry::default(),
tls: Tls::default(),
proxies: Vec::new(),
#[cfg(feature = "cookies")]
jar: None,
transport: None,
}
}
}
impl Client {
pub fn new() -> Result<Self> {
Self::builder().build()
}
#[must_use]
pub fn builder() -> ClientBuilder {
ClientBuilder::default()
}
#[must_use]
pub fn base_url(&self) -> Option<&Url> {
self.base_url.as_ref()
}
pub async fn send(&self, request: Request) -> Result<Response> {
self.execute(request, false).await
}
pub async fn request(
&self,
method: Method,
input: impl Into<RequestBuilder>,
) -> Result<Response> {
let builder = input.into();
let raw_url = builder
.url_str()
.ok_or(Error::invalid_request("request URL is required"))?;
let url = resolve_url(self.base_url.as_ref(), raw_url)?;
let request = builder.method(method).url(url.to_string()).build()?;
self.execute(request, true).await
}
pub async fn get(&self, input: impl Into<RequestBuilder>) -> Result<Response> {
self.request(Method::GET, input).await
}
pub async fn post(&self, input: impl Into<RequestBuilder>) -> Result<Response> {
self.request(Method::POST, input).await
}
pub async fn put(&self, input: impl Into<RequestBuilder>) -> Result<Response> {
self.request(Method::PUT, input).await
}
pub async fn patch(&self, input: impl Into<RequestBuilder>) -> Result<Response> {
self.request(Method::PATCH, input).await
}
pub async fn delete(&self, input: impl Into<RequestBuilder>) -> Result<Response> {
self.request(Method::DELETE, input).await
}
pub async fn head(&self, input: impl Into<RequestBuilder>) -> Result<Response> {
self.request(Method::HEAD, input).await
}
pub async fn options(&self, input: impl Into<RequestBuilder>) -> Result<Response> {
self.request(Method::OPTIONS, input).await
}
pub async fn trace(&self, input: impl Into<RequestBuilder>) -> Result<Response> {
self.request(Method::TRACE, input).await
}
pub async fn query(&self, input: impl Into<RequestBuilder>) -> Result<Response> {
self.request(query_method(), input).await
}
async fn execute(&self, mut request: Request, with_defaults: bool) -> Result<Response> {
ensure_runtime()?;
if let Some(origin) = &self.identity_origin
&& !same_origin(origin, request.url())
{
return Err(Error::new(
ErrorKind::Tls,
"the mutual-TLS identity is bound to the configured base origin",
));
}
let total_timeout = request.timeout().unwrap_or(self.total_timeout);
let deadline = Instant::now()
.checked_add(total_timeout)
.ok_or_else(|| Error::timeout("request deadline is too large"))?;
if with_defaults {
self.apply_defaults(&mut request)?;
}
let max_hops = self.redirect.max_hops()?;
let mut followed = 0u32;
let mut visited = HashSet::new();
let mut apply_defaults = with_defaults;
visited.insert(visit_key(request.method(), request.url()));
loop {
let (response, sent, replay) = self.send_with_retries(request, deadline).await?;
if response.status().is_informational() {
let message = if response.status() == StatusCode::SWITCHING_PROTOCOLS {
"protocol upgrades require an owned connection API"
} else {
"transport returned interim headers instead of a final response"
};
return Err(Error::new(ErrorKind::Transport, message));
}
self.store_response_cookies(&response, sent.url());
let Some(mut next) = redirect_request(&response, &sent, replay)? else {
return Ok(self.finish_response(response, followed));
};
if max_hops == 0 {
return Ok(self.finish_response(response, followed));
}
if sent.url().scheme() == "https" && next.url().scheme() == "http" {
return Ok(self.finish_response(response, followed));
}
let cross_origin = !same_origin(sent.url(), next.url());
if cross_origin && self.identity_origin.is_some() {
return Ok(self.finish_response(response, followed));
}
next.remove_routing_headers();
if cross_origin {
next.strip_cross_origin_headers();
apply_defaults = false;
}
if apply_defaults {
self.apply_defaults(&mut next)?;
}
let key = visit_key(next.method(), next.url());
if visited.contains(&key) {
return Err(Error::redirect(
RedirectError::Cycle { followed },
next.url(),
));
}
if followed >= max_hops {
return Err(Error::redirect(
RedirectError::TooManyHops {
limit: max_hops,
followed,
},
next.url(),
));
}
let remaining = remaining(deadline)?;
let _ = tokio::time::timeout(
remaining,
response.discard_for_redirect(REDIRECT_DRAIN_LIMIT),
)
.await;
followed += 1;
visited.insert(key);
request = next;
}
}
async fn send_with_retries(
&self,
mut request: Request,
deadline: Instant,
) -> Result<(Response, Request, Option<Request>)> {
let mut attempt = 1u8;
loop {
self.apply_cookie_header(&mut request)?;
request.validate_for_send()?;
let attempt_remaining = remaining(deadline)?;
request.set_timeout(attempt_remaining);
let sent = request.clone_without_body();
let replay = request.try_clone();
let retry_eligible = sent.is_idempotent() && replay.is_some();
let transport = self.transport.send(request);
let transport = async {
if self.default_transport {
CatchRuntimePanic::new(transport).await.unwrap_or_else(|_| {
Err(Error::new(
ErrorKind::Runtime,
"the asynchronous runtime I/O driver is unavailable",
))
})
} else {
transport.await
}
};
let result = tokio::time::timeout(attempt_remaining, transport).await;
let result = match result {
Ok(result) => result,
Err(_) => Err(Error::timeout("total request deadline exceeded")),
};
let mut response = match result {
Ok(response) => response,
Err(error)
if retry_eligible
&& attempt < self.retry.max_attempts()
&& is_transient_error(&error) =>
{
let mut next = replay.expect("retry eligibility requires replay");
let delay = self.retry.full_jitter(attempt, jitter_sample());
if delay >= remaining(deadline)? {
return Err(error);
}
let wait = remaining(deadline)?;
tokio::time::timeout(wait, tokio::time::sleep(delay))
.await
.map_err(|_| Error::timeout("total request deadline exceeded"))?;
attempt += 1;
next.set_timeout(remaining(deadline)?);
request = next;
continue;
}
Err(error) => {
if retry_eligible
&& self.retry.max_attempts() > 1
&& attempt >= self.retry.max_attempts()
&& is_transient_error(&error)
{
return Err(Error::retry_exhausted(attempt, error.kind(), sent.url()));
}
return Err(error);
}
};
if response.effective_url() != sent.url() {
return Err(Error::new(
ErrorKind::Transport,
"transport response URL did not match the request URL",
));
}
response.enforce_body_timeouts(deadline, self.read_timeout);
if retry_eligible
&& attempt < self.retry.max_attempts()
&& is_retry_status(response.status())
{
let status_remaining = remaining(deadline)?;
let delay = retry_after(response.headers())
.unwrap_or_else(|| self.retry.full_jitter(attempt, jitter_sample()));
if delay >= status_remaining {
return Ok((response, sent, replay));
}
let wake_at = Instant::now()
.checked_add(delay)
.ok_or_else(|| Error::timeout("retry delay is too large"))?;
self.store_response_cookies(&response, sent.url());
let _ = tokio::time::timeout(
status_remaining,
response.discard_for_redirect(REDIRECT_DRAIN_LIMIT),
)
.await;
let wait = remaining(deadline)?;
let remaining_delay = wake_at.saturating_duration_since(Instant::now());
if remaining_delay >= wait {
return Err(Error::timeout("total request deadline exceeded"));
}
if !remaining_delay.is_zero() {
tokio::time::timeout(wait, tokio::time::sleep(remaining_delay))
.await
.map_err(|_| Error::timeout("total request deadline exceeded"))?;
}
request = replay.expect("retry eligibility requires replay");
attempt += 1;
continue;
}
return Ok((response, sent, replay));
}
}
fn apply_defaults(&self, request: &mut Request) -> Result<()> {
let defaults_allowed = self
.base_url
.as_ref()
.is_none_or(|base| same_origin(base, request.url()));
if !defaults_allowed {
return Ok(());
}
let trace = request.method() == Method::TRACE;
if !trace && let Some(auth) = &self.auth {
request.apply_default_auth(auth)?;
}
for name in self.default_headers.keys() {
if request.headers().contains_key(name) || (trace && is_credential_header(name)) {
continue;
}
for value in self.default_headers.get_all(name) {
if !trace || !value.is_sensitive() {
request.insert_client_header(name.clone(), value.clone());
}
}
}
Ok(())
}
fn finish_response(&self, mut response: Response, followed: u32) -> Response {
response.set_redirect_count(followed);
response.set_body_limit(self.body_limit);
response
}
#[cfg(feature = "cookies")]
fn apply_cookie_header(&self, request: &mut Request) -> Result<()> {
let Some(jar) = &self.jar else {
return Ok(());
};
request.remove_client_header(&COOKIE);
if request.method() == Method::TRACE || request.headers().contains_key(COOKIE) {
return Ok(());
}
if let Some(mut value) = jar.cookies(request.url())? {
value.set_sensitive(true);
request.insert_client_header(COOKIE, value);
}
Ok(())
}
#[cfg(not(feature = "cookies"))]
fn apply_cookie_header(&self, _request: &mut Request) -> Result<()> {
Ok(())
}
#[cfg(feature = "cookies")]
fn store_response_cookies(&self, response: &Response, request_url: &Url) {
let Some(jar) = &self.jar else {
return;
};
jar.set_cookies(
&mut response.headers().get_all(SET_COOKIE).iter(),
request_url,
);
}
#[cfg(not(feature = "cookies"))]
fn store_response_cookies(&self, _response: &Response, _request_url: &Url) {}
}
impl ClientBuilder {
#[must_use]
pub fn base_url(mut self, url: impl Into<String>) -> Self {
self.base_url = Some(url.into());
self
}
#[must_use]
pub fn auth(mut self, auth: impl Into<Auth>) -> Self {
self.auth = Some(auth.into());
self
}
pub fn default_header<K, V>(mut self, name: K, value: V) -> Result<Self>
where
K: TryInto<HeaderName>,
K::Error: Into<Error>,
V: TryInto<HeaderValue>,
V::Error: Into<Error>,
{
self.default_headers.insert(
name.try_into().map_err(Into::into)?,
value.try_into().map_err(Into::into)?,
);
Ok(self)
}
#[must_use]
pub fn default_headers(mut self, headers: HeaderMap) -> Self {
self.default_headers.extend(headers);
self
}
pub fn user_agent<V>(mut self, value: V) -> Result<Self>
where
V: TryInto<HeaderValue>,
V::Error: Into<Error>,
{
self.default_headers
.insert(USER_AGENT, value.try_into().map_err(Into::into)?);
Ok(self)
}
#[must_use]
pub fn timeout(mut self, timeout: Duration) -> Self {
self.total_timeout = timeout;
self
}
#[must_use]
pub fn connect_timeout(mut self, timeout: Duration) -> Self {
self.connect_timeout = Some(timeout);
self
}
#[must_use]
pub fn read_timeout(mut self, timeout: Duration) -> Self {
self.read_timeout = timeout;
self
}
#[must_use]
pub fn body_limit(mut self, limit: usize) -> Self {
self.body_limit = limit;
self
}
#[must_use]
pub fn redirect(mut self, redirect: Redirect) -> Self {
self.redirect = redirect;
self
}
#[must_use]
pub fn retry(mut self, retry: Retry) -> Self {
self.retry = retry;
self
}
#[must_use]
pub fn tls(mut self, tls: Tls) -> Self {
self.tls = tls;
self
}
#[must_use]
pub fn proxy(mut self, proxy: Proxy) -> Self {
self.proxies.push(proxy);
self
}
#[cfg(feature = "cookies")]
#[must_use]
pub fn jar(mut self, jar: Jar) -> Self {
self.jar = Some(jar);
self
}
#[cfg(test)]
#[must_use]
fn transport(mut self, transport: impl Transport) -> Self {
self.transport = Some(Arc::new(transport));
self
}
pub fn build(self) -> Result<Client> {
if self
.connect_timeout
.is_some_and(|timeout| timeout.is_zero())
|| self.total_timeout.is_zero()
|| self.read_timeout.is_zero()
{
return Err(Error::invalid_request("timeouts must be greater than zero"));
}
if self.body_limit == 0 {
return Err(Error::invalid_request(
"body limit must be greater than zero",
));
}
self.redirect.max_hops()?;
if self.transport.is_some() && (!self.proxies.is_empty() || !self.tls.is_default()) {
return Err(Error::invalid_request(
"proxy and TLS settings belong to the default transport",
));
}
if self.transport.is_some() && self.connect_timeout.is_some() {
return Err(Error::invalid_request(
"connect_timeout belongs to the default transport",
));
}
let base_url = self.base_url.map(parse_base_url).transpose()?;
if base_url.is_none() && self.auth.is_some() {
return Err(Error::invalid_request(
"client authentication requires a base URL to bind its origin",
));
}
if base_url.is_none()
&& self
.default_headers
.iter()
.any(|(name, value)| value.is_sensitive() || is_credential_header(name))
{
return Err(Error::invalid_request(
"sensitive client defaults require a base URL to bind their origin",
));
}
if let Some(auth) = &self.auth {
auth.validate()?;
}
if self
.default_headers
.keys()
.any(is_transport_managed_default_header)
{
return Err(Error::invalid_request(
"client defaults cannot set routing, framing, hop-by-hop, or upgrade fields",
));
}
#[cfg(feature = "cookies")]
if self.jar.is_some() && self.default_headers.contains_key(COOKIE) {
return Err(Error::invalid_request(
"a default Cookie header cannot be combined with a cookie jar",
));
}
let identity_origin = if self.tls.has_identity() {
let origin = base_url.as_ref().ok_or(Error::invalid_request(
"a mutual-TLS identity requires a base URL to bind its origin",
))?;
if origin.scheme() != "https" {
return Err(Error::invalid_request(
"a mutual-TLS identity requires an HTTPS base URL",
));
}
if !self.proxies.is_empty() {
return Err(Error::invalid_request(
"mutual TLS cannot be combined with a proxy",
));
}
Some(origin.clone())
} else {
None
};
let default_transport = self.transport.is_none();
let transport = match self.transport {
Some(transport) => transport,
None => Arc::new(ReqwestTransport::new(ReqwestConfig {
proxies: self.proxies,
connect_timeout: self.connect_timeout.unwrap_or(DEFAULT_CONNECT_TIMEOUT),
read_timeout: self.read_timeout,
tls: self.tls,
})?),
};
Ok(Client {
transport,
default_transport,
total_timeout: self.total_timeout,
read_timeout: self.read_timeout,
body_limit: self.body_limit,
base_url,
auth: self.auth,
default_headers: self.default_headers,
redirect: self.redirect,
retry: self.retry,
identity_origin,
#[cfg(feature = "cookies")]
jar: self.jar,
})
}
}
impl fmt::Debug for Client {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
formatter
.debug_struct("Client")
.field("total_timeout", &self.total_timeout)
.field("read_timeout", &self.read_timeout)
.field("body_limit", &self.body_limit)
.field("base_url", &self.base_url)
.field("has_auth", &self.auth.is_some())
.field("default_header_count", &self.default_headers.len())
.field("redirect", &self.redirect)
.field("retry", &self.retry)
.finish_non_exhaustive()
}
}
impl fmt::Debug for ClientBuilder {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
formatter
.debug_struct("ClientBuilder")
.field(
"connect_timeout",
&self.connect_timeout.unwrap_or(DEFAULT_CONNECT_TIMEOUT),
)
.field("total_timeout", &self.total_timeout)
.field("read_timeout", &self.read_timeout)
.field("body_limit", &self.body_limit)
.field("has_base_url", &self.base_url.is_some())
.field("has_auth", &self.auth.is_some())
.field("default_header_count", &self.default_headers.len())
.field("redirect", &self.redirect)
.field("retry", &self.retry)
.field("tls", &self.tls)
.field("proxy_count", &self.proxies.len())
.finish()
}
}
fn parse_base_url(raw: String) -> Result<Url> {
validate_http_authority_syntax(&raw)?;
let url = Url::parse(&raw)?;
if !matches!(url.scheme(), "http" | "https") || url.host_str().is_none() {
return Err(Error::url("base URL must be an absolute HTTP or HTTPS URL"));
}
if !url.username().is_empty() || url.password().is_some() {
return Err(Error::url("base URL cannot contain userinfo"));
}
if url.query().is_some() || url.fragment().is_some() {
return Err(Error::url("base URL cannot include a query or fragment"));
}
Ok(url)
}
pub(crate) fn resolve_url(base: Option<&Url>, reference: &str) -> Result<Url> {
validate_http_authority_syntax(reference)?;
if reference_scheme(reference).is_some() {
return Ok(Url::parse(reference)?);
}
match base {
Some(base) => Ok(base.join(reference)?),
None => Ok(Url::parse(reference)?),
}
}
fn visit_key(method: &Method, url: &Url) -> (Method, String) {
let mut url = url.clone();
url.set_fragment(None);
(method.clone(), url.to_string())
}
fn remaining(deadline: Instant) -> Result<Duration> {
deadline
.checked_duration_since(Instant::now())
.filter(|duration| !duration.is_zero())
.ok_or_else(|| Error::timeout("total request deadline exceeded"))
}
fn jitter_sample() -> u64 {
static STATE: OnceLock<AtomicU64> = OnceLock::new();
let state = STATE.get_or_init(|| {
let seed = RandomState::new().hash_one((
SystemTime::now(),
std::process::id(),
&STATE as *const _ as usize,
));
AtomicU64::new(seed)
});
let value = state.fetch_add(0x9e37_79b9_7f4a_7c15, Ordering::Relaxed);
value ^ value.rotate_left(17) ^ value.rotate_right(11)
}
fn ensure_runtime() -> Result<()> {
if tokio::runtime::Handle::try_current().is_err() {
return Err(Error::new(
ErrorKind::Runtime,
"client execution requires the supported asynchronous runtime",
));
}
if catch_unwind(AssertUnwindSafe(|| tokio::time::sleep(Duration::ZERO))).is_err() {
return Err(Error::new(
ErrorKind::Runtime,
"the asynchronous runtime time driver is unavailable",
));
}
Ok(())
}
struct CatchRuntimePanic<F> {
future: Pin<Box<F>>,
}
impl<F> CatchRuntimePanic<F> {
fn new(future: F) -> Self {
Self {
future: Box::pin(future),
}
}
}
impl<F: Future> Future for CatchRuntimePanic<F> {
type Output = std::thread::Result<F::Output>;
fn poll(mut self: Pin<&mut Self>, context: &mut Context<'_>) -> Poll<Self::Output> {
match catch_unwind(AssertUnwindSafe(|| self.future.as_mut().poll(context))) {
Ok(Poll::Ready(output)) => Poll::Ready(Ok(output)),
Ok(Poll::Pending) => Poll::Pending,
Err(payload) => Poll::Ready(Err(payload)),
}
}
}
fn is_transport_managed_default_header(name: &HeaderName) -> bool {
matches!(
name.as_str(),
"connection"
| "content-length"
| "host"
| "keep-alive"
| "proxy-authenticate"
| "proxy-authorization"
| "proxy-connection"
| "te"
| "trailer"
| "transfer-encoding"
| "upgrade"
)
}
#[cfg(test)]
mod describe_client {
use std::pin::Pin;
use std::task::{Context, Poll};
use std::{
collections::VecDeque,
sync::{
Mutex,
atomic::{AtomicUsize, Ordering as AtomicOrdering},
},
};
use crate::{Body, Version, transport::BoxFuture};
use super::*;
#[derive(Debug)]
struct Recorded {
method: Method,
url: Url,
headers: HeaderMap,
body: Option<Vec<u8>>,
}
struct ScriptTransport {
requests: Mutex<Vec<Recorded>>,
responses: Mutex<VecDeque<(StatusCode, HeaderMap, Body)>>,
}
impl ScriptTransport {
fn new(responses: impl IntoIterator<Item = (StatusCode, HeaderMap, Body)>) -> Self {
Self {
requests: Mutex::new(Vec::new()),
responses: Mutex::new(responses.into_iter().collect()),
}
}
}
impl Transport for ScriptTransport {
fn send(&self, request: Request) -> BoxFuture<'_, Result<Response>> {
Box::pin(async move {
let url = request.url().clone();
self.requests.lock().unwrap().push(Recorded {
method: request.method().clone(),
url: url.clone(),
headers: request.headers().clone(),
body: request.body().as_bytes().map(<[u8]>::to_vec),
});
let (status, headers, body) = self
.responses
.lock()
.unwrap()
.pop_front()
.expect("scripted response");
Response::builder()
.status(status)
.version(Version::HTTP_11)
.headers(headers)
.effective_url(url)
.body(body)
.build()
})
}
}
fn redirect(location: &'static str) -> (StatusCode, HeaderMap, Body) {
let mut headers = HeaderMap::new();
headers.insert(LOCATION, HeaderValue::from_static(location));
(StatusCode::FOUND, headers, Body::text("redirect"))
}
fn ok() -> (StatusCode, HeaderMap, Body) {
(StatusCode::OK, HeaderMap::new(), Body::text("ok"))
}
#[tokio::test]
async fn it_send_preserves_an_owned_request_method() {
let transport = ScriptTransport::new([ok()]);
let client = Client::builder().transport(transport).build().unwrap();
let request = Request::patch("https://example.com/items")
.body("value")
.build()
.unwrap();
let response = client.send(request).await.unwrap();
assert_eq!(response.status(), StatusCode::OK);
}
#[tokio::test]
async fn it_custom_transport_response_url_must_match_the_sent_request() {
struct MismatchedUrl;
impl Transport for MismatchedUrl {
fn send(&self, _request: Request) -> BoxFuture<'_, Result<Response>> {
Box::pin(async {
Response::builder()
.status(StatusCode::OK)
.version(Version::HTTP_11)
.effective_url(Url::parse("https://unexpected.example/").unwrap())
.build()
})
}
}
let client = Client::builder().transport(MismatchedUrl).build().unwrap();
let error = client.get("https://expected.example/").await.unwrap_err();
assert_eq!(error.kind(), ErrorKind::Transport);
assert!(std::error::Error::source(&error).is_none());
assert_eq!(
error.to_string(),
"transport error: transport response URL did not match the request URL"
);
}
#[tokio::test]
async fn it_arc_transport_can_be_shared_between_clients() {
let transport: Arc<dyn Transport> = Arc::new(ScriptTransport::new([ok(), ok()]));
let first = Client::builder()
.transport(transport.clone())
.build()
.unwrap();
let second = Client::builder().transport(transport).build().unwrap();
assert_eq!(
first.get("https://example.com/one").await.unwrap().status(),
StatusCode::OK
);
assert_eq!(
second
.get("https://example.com/two")
.await
.unwrap()
.status(),
StatusCode::OK
);
}
#[tokio::test]
async fn it_send_preserves_the_owned_url_without_applying_client_context() {
let transport = Arc::new(ScriptTransport::new([ok()]));
let client = Client::builder()
.base_url("https://api.example.com/")
.auth(crate::ApiKey::query("client_key", "secret").unwrap())
.default_header("x-client-default", "default")
.unwrap()
.transport(transport.clone())
.build()
.unwrap();
let request = Request::get("https://api.example.com/items?caller=kept")
.build()
.unwrap();
client.send(request).await.unwrap();
let requests = transport.requests.lock().unwrap();
assert_eq!(
requests[0].url.as_str(),
"https://api.example.com/items?caller=kept"
);
assert!(!requests[0].headers.contains_key("x-client-default"));
}
#[tokio::test]
async fn it_custom_transports_must_return_final_response_headers() {
for status in [StatusCode::EARLY_HINTS, StatusCode::SWITCHING_PROTOCOLS] {
let client = Client::builder()
.transport(ScriptTransport::new([(
status,
HeaderMap::new(),
Body::default(),
)]))
.build()
.unwrap();
let error = client.get("https://example.com").await.unwrap_err();
assert_eq!(error.kind(), ErrorKind::Transport, "status {status}");
}
}
#[test]
fn it_resolves_normal_and_abnormal_reference_vectors() {
let base = Url::parse("http://a/b/c/d;p?q").unwrap();
let vectors = [
("g:h", "g:h"),
("g", "http://a/b/c/g"),
("./g", "http://a/b/c/g"),
("g/", "http://a/b/c/g/"),
("/g", "http://a/g"),
("//g", "http://g/"),
("?y", "http://a/b/c/d;p?y"),
("g?y", "http://a/b/c/g?y"),
("#s", "http://a/b/c/d;p?q#s"),
("g#s", "http://a/b/c/g#s"),
("g?y#s", "http://a/b/c/g?y#s"),
(";x", "http://a/b/c/;x"),
("g;x", "http://a/b/c/g;x"),
("g;x?y#s", "http://a/b/c/g;x?y#s"),
("", "http://a/b/c/d;p?q"),
(".", "http://a/b/c/"),
("./", "http://a/b/c/"),
("..", "http://a/b/"),
("../", "http://a/b/"),
("../g", "http://a/b/g"),
("../..", "http://a/"),
("../../", "http://a/"),
("../../g", "http://a/g"),
("../../../g", "http://a/g"),
("../../../../g", "http://a/g"),
("/./g", "http://a/g"),
("/../g", "http://a/g"),
("g.", "http://a/b/c/g."),
(".g", "http://a/b/c/.g"),
("g..", "http://a/b/c/g.."),
("..g", "http://a/b/c/..g"),
("./../g", "http://a/b/g"),
("./g/.", "http://a/b/c/g/"),
("g/./h", "http://a/b/c/g/h"),
("g/../h", "http://a/b/c/h"),
("g;x=1/./y", "http://a/b/c/g;x=1/y"),
("g;x=1/../y", "http://a/b/c/y"),
("g?y/./x", "http://a/b/c/g?y/./x"),
("g?y/../x", "http://a/b/c/g?y/../x"),
("g#s/./x", "http://a/b/c/g#s/./x"),
("g#s/../x", "http://a/b/c/g#s/../x"),
];
for (reference, expected) in vectors {
assert_eq!(
resolve_url(Some(&base), reference).unwrap().as_str(),
expected,
"reference {reference:?}"
);
}
assert_eq!(reference_scheme("http:g"), Some(("http", "g")));
}
#[test]
fn it_absolute_http_references_require_a_non_empty_authority() {
let base = Url::parse("http://a/b/c/d;p?q").unwrap();
for reference in ["http:g", "HTTP:g", "http:/g", "http:///g"] {
assert!(
resolve_url(Some(&base), reference).is_err(),
"reference {reference:?}"
);
}
}
#[tokio::test]
async fn it_cross_origin_absolute_request_does_not_inherit_client_secrets() {
let transport = Arc::new(ScriptTransport::new([ok()]));
let mut secret = HeaderValue::from_static("secret");
secret.set_sensitive(true);
let client = Client::builder()
.base_url("https://api.example.com/")
.auth(crate::BearerToken::new("bearer-secret"))
.default_header("x-api-key", secret)
.unwrap()
.transport(transport.clone())
.build()
.unwrap();
client.get("https://other.example/items").await.unwrap();
let request = &transport.requests.lock().unwrap()[0];
assert!(!request.headers.contains_key("authorization"));
assert!(!request.headers.contains_key("x-api-key"));
}
#[tokio::test]
async fn it_repeated_client_default_values_are_preserved() {
let transport = Arc::new(ScriptTransport::new([ok()]));
let mut defaults = HeaderMap::new();
defaults.append("x-mode", HeaderValue::from_static("first"));
defaults.append("x-mode", HeaderValue::from_static("second"));
let client = Client::builder()
.default_headers(defaults)
.transport(transport.clone())
.build()
.unwrap();
client.get("https://example.com").await.unwrap();
let requests = transport.requests.lock().unwrap();
let values = requests[0]
.headers
.get_all("x-mode")
.iter()
.map(|value| value.to_str().unwrap())
.collect::<Vec<_>>();
assert_eq!(values, ["first", "second"]);
}
#[tokio::test]
async fn it_trace_omits_inherited_credentials_and_sensitive_defaults() {
let transport = Arc::new(ScriptTransport::new([ok()]));
let mut sensitive = HeaderValue::from_static("private");
sensitive.set_sensitive(true);
let client = Client::builder()
.base_url("https://example.com/")
.auth(crate::BearerToken::new("bearer-secret"))
.default_header("x-api-key", "api-secret")
.unwrap()
.default_header("x-private", sensitive)
.unwrap()
.default_header("x-visible", "public")
.unwrap()
.transport(transport.clone())
.build()
.unwrap();
client.trace("https://example.com/trace").await.unwrap();
let requests = transport.requests.lock().unwrap();
let headers = &requests[0].headers;
assert!(!headers.contains_key("authorization"));
assert!(!headers.contains_key("x-api-key"));
assert!(!headers.contains_key("x-private"));
assert_eq!(headers["x-visible"], "public");
}
#[cfg(feature = "cookies")]
#[tokio::test]
async fn it_trace_omits_cookie_jar_values() {
let mut cookie_headers = HeaderMap::new();
cookie_headers.insert(
SET_COOKIE,
HeaderValue::from_static("session=secret; Path=/; Secure"),
);
let transport = Arc::new(ScriptTransport::new([
(StatusCode::OK, cookie_headers, Body::default()),
ok(),
]));
let client = Client::builder()
.base_url("https://example.com/")
.jar(Jar::new())
.transport(transport.clone())
.build()
.unwrap();
client.get("https://example.com/set-cookie").await.unwrap();
client.trace("https://example.com/trace").await.unwrap();
let requests = transport.requests.lock().unwrap();
assert!(!requests[1].headers.contains_key(COOKIE));
}
#[tokio::test]
async fn it_redirect_limit_one_follows_exactly_one_hop() {
let transport = Arc::new(ScriptTransport::new([redirect("/two"), redirect("/three")]));
let client = Client::builder()
.redirect(Redirect::Limit(1))
.transport(transport.clone())
.build()
.unwrap();
let error = client.get("https://example.com/one").await.unwrap_err();
assert_eq!(error.kind(), ErrorKind::Redirect);
assert_eq!(
error.redirect_error(),
Some(RedirectError::TooManyHops {
limit: 1,
followed: 1
})
);
assert_eq!(transport.requests.lock().unwrap().len(), 2);
}
#[tokio::test]
async fn it_redirect_self_loop_is_detected_before_following() {
let transport = Arc::new(ScriptTransport::new([redirect("/a")]));
let client = Client::builder()
.redirect(Redirect::FollowAll)
.transport(transport)
.build()
.unwrap();
let error = client.get("https://example.com/a").await.unwrap_err();
assert_eq!(
error.redirect_error(),
Some(RedirectError::Cycle { followed: 0 })
);
}
#[tokio::test]
async fn it_multi_hop_redirect_cycle_is_distinct_from_a_self_loop_and_hop_limit() {
let transport = Arc::new(ScriptTransport::new([redirect("/b"), redirect("/a")]));
let client = Client::builder()
.redirect(Redirect::FollowAll)
.transport(transport.clone())
.build()
.unwrap();
let error = client.get("https://example.com/a").await.unwrap_err();
assert_eq!(
error.redirect_error(),
Some(RedirectError::Cycle { followed: 1 })
);
assert_eq!(transport.requests.lock().unwrap().len(), 2);
}
#[tokio::test]
async fn it_redirect_cycles_ignore_fragments_but_distinguish_methods() {
let mut see_other = HeaderMap::new();
see_other.insert(LOCATION, HeaderValue::from_static("#first"));
let mut found = HeaderMap::new();
found.insert(LOCATION, HeaderValue::from_static("#second"));
let transport = Arc::new(ScriptTransport::new([
(StatusCode::SEE_OTHER, see_other, Body::text("redirect")),
(StatusCode::FOUND, found, Body::text("redirect")),
]));
let client = Client::builder()
.redirect(Redirect::FollowAll)
.transport(transport.clone())
.build()
.unwrap();
let error = client
.post(
Request::builder()
.url("https://example.com/resource")
.body("body"),
)
.await
.unwrap_err();
assert_eq!(
error.redirect_error(),
Some(RedirectError::Cycle { followed: 1 })
);
let requests = transport.requests.lock().unwrap();
assert_eq!(requests.len(), 2);
assert_eq!(requests[0].method, Method::POST);
assert_eq!(requests[1].method, Method::GET);
assert_eq!(requests[0].url.as_str(), "https://example.com/resource");
assert_eq!(requests[1].url.as_str(), "https://example.com/resource");
}
#[tokio::test]
async fn it_303_rewrites_post_to_bodyless_get() {
let mut headers = HeaderMap::new();
headers.insert(LOCATION, HeaderValue::from_static("/result"));
let transport = Arc::new(ScriptTransport::new([
(StatusCode::SEE_OTHER, headers, Body::text("redirect")),
ok(),
]));
let client = Client::builder()
.redirect(Redirect::FollowAll)
.transport(transport.clone())
.build()
.unwrap();
client
.post(
Request::builder()
.url("https://example.com/start")
.body("secret"),
)
.await
.unwrap();
let requests = transport.requests.lock().unwrap();
assert_eq!(requests[1].method, Method::GET);
assert_eq!(requests[1].body, None);
assert!(!requests[1].headers.contains_key("content-type"));
}
#[tokio::test]
async fn it_https_to_http_redirect_returns_readable_3xx() {
let transport = ScriptTransport::new([redirect("http://example.com/plain")]);
let client = Client::builder()
.redirect(Redirect::FollowAll)
.transport(transport)
.build()
.unwrap();
let response = client.get("https://example.com/secure").await.unwrap();
assert_eq!(response.status(), StatusCode::FOUND);
assert_eq!(response.text().await.unwrap(), "redirect");
}
#[tokio::test]
async fn it_follows_cross_origin_redirects_without_sending_credentials() {
let mut redirect_headers = HeaderMap::new();
redirect_headers.insert(
LOCATION,
HeaderValue::from_static("https://other.example/final"),
);
let transport = Arc::new(ScriptTransport::new([
(
StatusCode::TEMPORARY_REDIRECT,
redirect_headers,
Body::text("redirect"),
),
ok(),
]));
let mut caller_secret = HeaderValue::from_static("caller-secret");
caller_secret.set_sensitive(true);
let client = Client::builder()
.base_url("https://api.example/")
.auth(crate::BearerToken::new("client-secret"))
.default_header("x-client-secret", "default-secret")
.unwrap()
.redirect(Redirect::FollowAll)
.transport(transport.clone())
.build()
.unwrap();
let response = client
.post(
Request::builder()
.url("start")
.header("x-caller-secret", caller_secret)
.unwrap()
.header("referer", "https://api.example/private?secret=value")
.unwrap()
.header("origin", "https://api.example")
.unwrap()
.header("x-request-visible", "preserved")
.unwrap()
.body("replayable"),
)
.await
.unwrap();
assert_eq!(response.status(), StatusCode::OK);
let requests = transport.requests.lock().unwrap();
assert_eq!(requests.len(), 2);
assert_eq!(requests[1].url.as_str(), "https://other.example/final");
for name in ["authorization", "x-client-secret", "x-caller-secret"] {
assert!(!requests[1].headers.contains_key(name));
}
assert!(!requests[1].headers.contains_key("origin"));
assert_eq!(requests[1].body.as_deref(), Some(&b"replayable"[..]));
assert_eq!(requests[1].headers["x-request-visible"], "preserved");
assert!(requests[0].headers.contains_key("referer"));
assert!(!requests[1].headers.contains_key("referer"));
}
#[tokio::test]
async fn it_cross_origin_redirect_does_not_reapply_unscoped_client_defaults() {
let mut headers = HeaderMap::new();
headers.insert(
LOCATION,
HeaderValue::from_static("https://other.example/final"),
);
let transport = Arc::new(ScriptTransport::new([
(StatusCode::FOUND, headers, Body::text("redirect")),
ok(),
]));
let client = Client::builder()
.default_header("x-signature", "client-generated")
.unwrap()
.redirect(Redirect::FollowAll)
.transport(transport.clone())
.build()
.unwrap();
client.get("https://origin.example/start").await.unwrap();
let requests = transport.requests.lock().unwrap();
assert_eq!(requests[0].headers["x-signature"], "client-generated");
assert!(!requests[1].headers.contains_key("x-signature"));
}
#[tokio::test]
async fn it_returns_the_redirect_response_for_non_replayable_bodies() {
struct OneShot;
impl crate::BodySource for OneShot {
fn poll_frame(
self: Pin<&mut Self>,
_context: &mut Context<'_>,
) -> Poll<Result<Option<crate::BodyFrame>>> {
let _ = self;
Poll::Ready(Ok(None))
}
}
let mut headers = HeaderMap::new();
headers.insert(LOCATION, HeaderValue::from_static("/final"));
let transport = Arc::new(ScriptTransport::new([(
StatusCode::TEMPORARY_REDIRECT,
headers,
Body::text("not followed"),
)]));
let client = Client::builder()
.redirect(Redirect::FollowAll)
.transport(transport.clone())
.build()
.unwrap();
let response = client
.post(
Request::builder()
.url("https://example.com/start")
.body(Body::stream(OneShot)),
)
.await
.unwrap();
assert_eq!(response.status(), StatusCode::TEMPORARY_REDIRECT);
assert_eq!(response.text().await.unwrap(), "not followed");
assert_eq!(transport.requests.lock().unwrap().len(), 1);
}
#[tokio::test]
async fn it_does_not_generate_referer_headers_for_redirects() {
let transport = Arc::new(ScriptTransport::new([redirect("/final"), ok()]));
let client = Client::builder()
.redirect(Redirect::FollowAll)
.transport(transport.clone())
.build()
.unwrap();
client
.get("https://example.com/start?token=query-secret")
.await
.unwrap();
let requests = transport.requests.lock().unwrap();
assert!(!requests[0].headers.contains_key("referer"));
assert!(!requests[1].headers.contains_key("referer"));
}
#[tokio::test]
async fn it_exposes_effective_urls_and_redirect_counts() {
let transport = ScriptTransport::new([redirect("/final"), ok()]);
let client = Client::builder()
.redirect(Redirect::FollowAll)
.transport(transport)
.build()
.unwrap();
let response = client.get("https://example.com/start").await.unwrap();
assert_eq!(
response.effective_url().as_str(),
"https://example.com/final"
);
assert_eq!(response.redirect_count(), 1);
}
#[tokio::test]
async fn it_same_origin_redirect_reapplies_client_query_auth() {
let transport = Arc::new(ScriptTransport::new([
redirect("/final?from=redirect"),
ok(),
]));
let client = Client::builder()
.base_url("https://example.com/")
.auth(crate::ApiKey::query("api_key", "secret").unwrap())
.redirect(Redirect::FollowAll)
.transport(transport.clone())
.build()
.unwrap();
client.get("start").await.unwrap();
let requests = transport.requests.lock().unwrap();
let second = &requests[1].url;
assert!(
second
.query_pairs()
.any(|(name, value)| { name == "api_key" && value == "secret" })
);
assert!(
second
.query_pairs()
.any(|(name, value)| { name == "from" && value == "redirect" })
);
}
#[tokio::test]
async fn it_redirect_hard_ceiling_is_ten_followed_hops() {
let responses = (1..=11).map(|hop| {
let mut headers = HeaderMap::new();
headers.insert(
LOCATION,
HeaderValue::from_str(&format!("/hop{}", hop + 1)).unwrap(),
);
(StatusCode::FOUND, headers, Body::text("redirect"))
});
let transport = Arc::new(ScriptTransport::new(responses));
let client = Client::builder()
.redirect(Redirect::FollowAll)
.transport(transport.clone())
.build()
.unwrap();
let error = client.get("https://example.com/hop1").await.unwrap_err();
assert_eq!(
error.redirect_error(),
Some(RedirectError::TooManyHops {
limit: 10,
followed: 10,
})
);
assert_eq!(transport.requests.lock().unwrap().len(), 11);
}
#[test]
fn it_redirect_decision_table_covers_every_status_method_and_body_capability() {
struct OneShot;
impl crate::BodySource for OneShot {
fn poll_frame(
self: Pin<&mut Self>,
_context: &mut Context<'_>,
) -> Poll<Result<Option<crate::BodyFrame>>> {
let _ = self;
Poll::Ready(Ok(None))
}
}
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
enum BodyCapability {
Absent,
Replayable,
NonReplayable,
}
#[derive(Debug)]
enum Action {
Preserve,
Bodyless(Method),
}
let decisions = [
(StatusCode::MOVED_PERMANENTLY, Method::GET, Action::Preserve),
(
StatusCode::MOVED_PERMANENTLY,
Method::HEAD,
Action::Preserve,
),
(
StatusCode::MOVED_PERMANENTLY,
Method::POST,
Action::Bodyless(Method::GET),
),
(StatusCode::MOVED_PERMANENTLY, Method::PUT, Action::Preserve),
(StatusCode::FOUND, Method::GET, Action::Preserve),
(StatusCode::FOUND, Method::HEAD, Action::Preserve),
(
StatusCode::FOUND,
Method::POST,
Action::Bodyless(Method::GET),
),
(StatusCode::FOUND, Method::PUT, Action::Preserve),
(
StatusCode::SEE_OTHER,
Method::GET,
Action::Bodyless(Method::GET),
),
(
StatusCode::SEE_OTHER,
Method::HEAD,
Action::Bodyless(Method::HEAD),
),
(
StatusCode::SEE_OTHER,
Method::POST,
Action::Bodyless(Method::GET),
),
(
StatusCode::SEE_OTHER,
Method::PUT,
Action::Bodyless(Method::GET),
),
(
StatusCode::TEMPORARY_REDIRECT,
Method::GET,
Action::Preserve,
),
(
StatusCode::TEMPORARY_REDIRECT,
Method::HEAD,
Action::Preserve,
),
(
StatusCode::TEMPORARY_REDIRECT,
Method::POST,
Action::Preserve,
),
(
StatusCode::TEMPORARY_REDIRECT,
Method::PUT,
Action::Preserve,
),
(
StatusCode::PERMANENT_REDIRECT,
Method::GET,
Action::Preserve,
),
(
StatusCode::PERMANENT_REDIRECT,
Method::HEAD,
Action::Preserve,
),
(
StatusCode::PERMANENT_REDIRECT,
Method::POST,
Action::Preserve,
),
(
StatusCode::PERMANENT_REDIRECT,
Method::PUT,
Action::Preserve,
),
];
for (status, method, action) in decisions {
for body_capability in [
BodyCapability::Absent,
BodyCapability::Replayable,
BodyCapability::NonReplayable,
] {
let body = match body_capability {
BodyCapability::Absent => Body::default(),
BodyCapability::Replayable => Body::text("body"),
BodyCapability::NonReplayable => Body::from_source(OneShot),
};
let original = Request::builder()
.method(method.clone())
.url("https://example.com/start")
.body(body)
.build()
.unwrap();
let sent = original.clone_without_body();
let replay = original.try_clone();
assert_eq!(
replay.is_some(),
body_capability != BodyCapability::NonReplayable
);
let mut headers = HeaderMap::new();
headers.insert(LOCATION, HeaderValue::from_static("/next"));
let response = Response::builder()
.status(status)
.version(Version::HTTP_11)
.headers(headers)
.effective_url(sent.url().clone())
.build()
.unwrap();
let next = redirect_request(&response, &sent, replay).unwrap();
let expected_follow = !matches!(&action, Action::Preserve)
|| body_capability != BodyCapability::NonReplayable;
assert_eq!(
next.is_some(),
expected_follow,
"status={status}, method={method}, body={body_capability:?}"
);
if let Some(next) = next {
let expected_method = match &action {
Action::Preserve => &method,
Action::Bodyless(method) => method,
};
let expected_body = matches!(&action, Action::Preserve)
&& body_capability == BodyCapability::Replayable;
assert_eq!(
next.method(),
expected_method,
"status={status}, method={method}, body={body_capability:?}"
);
assert_eq!(
!next.body().is_absent(),
expected_body,
"status={status}, method={method}, body={body_capability:?}"
);
if expected_body {
assert_eq!(next.body().as_bytes(), Some(&b"body"[..]));
}
}
}
}
}
#[test]
fn it_bodyless_redirect_rewrites_remove_content_fields() {
for status in [
StatusCode::MOVED_PERMANENTLY,
StatusCode::FOUND,
StatusCode::SEE_OTHER,
] {
let original = Request::post("https://example.com/start")
.header("content-encoding", "custom")
.unwrap()
.header("content-language", "en")
.unwrap()
.header("content-location", "/old")
.unwrap()
.header("content-type", "text/plain")
.unwrap()
.body("body")
.build()
.unwrap();
let sent = original.clone_without_body();
let mut headers = HeaderMap::new();
headers.insert(LOCATION, HeaderValue::from_static("/next"));
let response = Response::builder()
.status(status)
.version(Version::HTTP_11)
.headers(headers)
.effective_url(Url::parse("https://example.com/start").unwrap())
.build()
.unwrap();
let next = redirect_request(&response, &sent, original.try_clone())
.unwrap()
.unwrap();
for name in [
"content-encoding",
"content-language",
"content-length",
"content-location",
"content-type",
"trailer",
"transfer-encoding",
] {
assert!(
!next.headers().contains_key(name),
"status {status} retained {name}"
);
}
}
}
#[test]
fn it_redirect_locations_resolve_relative_dot_query_and_fragment_references() {
let request = Request::get("https://example.com/a/b/start?old=1")
.build()
.unwrap();
let sent = request.clone_without_body();
for (location, expected) in [
("../next", "https://example.com/a/next"),
("./next", "https://example.com/a/b/next"),
("?fresh=2", "https://example.com/a/b/start?fresh=2"),
("/root#section", "https://example.com/root"),
("#section", "https://example.com/a/b/start?old=1"),
] {
let mut headers = HeaderMap::new();
headers.insert(LOCATION, HeaderValue::from_str(location).unwrap());
let response = Response::builder()
.status(StatusCode::FOUND)
.version(Version::HTTP_11)
.headers(headers)
.effective_url(sent.url().clone())
.build()
.unwrap();
let next = redirect_request(&response, &sent, request.try_clone())
.unwrap()
.expect("usable Location");
assert_eq!(next.url().as_str(), expected, "Location: {location}");
}
}
#[test]
fn it_unusable_redirect_locations_return_the_current_response() {
let request = Request::get("https://example.com/start").build().unwrap();
let sent = request.clone_without_body();
for location in [
None,
Some("http://[invalid"),
Some("ftp://example.com/file"),
Some("https://user:pass@example.com/"),
] {
let mut headers = HeaderMap::new();
if let Some(location) = location {
headers.insert(LOCATION, HeaderValue::from_str(location).unwrap());
}
let response = Response::builder()
.status(StatusCode::FOUND)
.version(Version::HTTP_11)
.headers(headers)
.effective_url(sent.url().clone())
.build()
.unwrap();
assert!(
redirect_request(&response, &sent, request.try_clone())
.unwrap()
.is_none()
);
}
let mut duplicate = HeaderMap::new();
duplicate.append(LOCATION, HeaderValue::from_static("/one"));
duplicate.append(LOCATION, HeaderValue::from_static("/two"));
let response = Response::builder()
.status(StatusCode::FOUND)
.version(Version::HTTP_11)
.headers(duplicate)
.effective_url(sent.url().clone())
.build()
.unwrap();
assert!(
redirect_request(&response, &sent, request.try_clone())
.unwrap()
.is_none()
);
}
#[tokio::test]
async fn it_unusable_redirect_locations_leave_a_readable_current_response() {
let mut cases = Vec::new();
cases.push(HeaderMap::new());
for location in [
"http://[invalid",
"ftp://example.com/file",
"https://user:pass@example.com/",
"http:g",
] {
let mut headers = HeaderMap::new();
headers.insert(LOCATION, HeaderValue::from_str(location).unwrap());
cases.push(headers);
}
let mut non_text = HeaderMap::new();
non_text.insert(LOCATION, HeaderValue::from_bytes(b"\xff").unwrap());
cases.push(non_text);
let mut duplicate = HeaderMap::new();
duplicate.append(LOCATION, HeaderValue::from_static("/one"));
duplicate.append(LOCATION, HeaderValue::from_static("/two"));
cases.push(duplicate);
for headers in cases {
let client = Client::builder()
.redirect(Redirect::FollowAll)
.transport(ScriptTransport::new([(
StatusCode::FOUND,
headers,
Body::text("readable redirect"),
)]))
.build()
.unwrap();
let response = client.get("https://example.com/start").await.unwrap();
assert_eq!(response.status(), StatusCode::FOUND);
assert_eq!(response.text().await.unwrap(), "readable redirect");
}
}
#[tokio::test]
async fn it_mutual_tls_identity_never_crosses_origins() {
let mut headers = HeaderMap::new();
headers.insert(
LOCATION,
HeaderValue::from_static("https://other.example/final"),
);
let transport = Arc::new(ScriptTransport::new([(
StatusCode::TEMPORARY_REDIRECT,
headers,
Body::text("stopped"),
)]));
let mut client = Client::builder()
.redirect(Redirect::FollowAll)
.transport(transport.clone())
.build()
.unwrap();
client.identity_origin = Some(Url::parse("https://secure.example/").unwrap());
let response = client.get("https://secure.example/start").await.unwrap();
assert_eq!(response.status(), StatusCode::TEMPORARY_REDIRECT);
assert_eq!(response.text().await.unwrap(), "stopped");
assert_eq!(transport.requests.lock().unwrap().len(), 1);
let error = client
.get("https://other.example/direct")
.await
.unwrap_err();
assert_eq!(error.kind(), ErrorKind::Tls);
}
#[test]
fn it_mutual_tls_identity_requires_a_secure_bound_origin_and_no_proxy() {
let identity = crate::Identity::from_pem(
b"-----BEGIN CERTIFICATE-----\na\n-----END CERTIFICATE-----\n-----BEGIN PRIVATE KEY-----\na\n-----END PRIVATE KEY-----",
)
.unwrap();
assert!(
Client::builder()
.tls(Tls::new().identity(identity.clone()))
.build()
.is_err()
);
assert!(
Client::builder()
.base_url("http://example.com/")
.tls(Tls::new().identity(identity.clone()))
.build()
.is_err()
);
assert!(
Client::builder()
.base_url("https://example.com/")
.tls(Tls::new().identity(identity))
.proxy(Proxy::all("http://127.0.0.1:8080").unwrap())
.build()
.is_err()
);
}
#[test]
fn it_production_timeout_and_collection_defaults_are_stable() {
let builder = ClientBuilder::default();
assert_eq!(DEFAULT_CONNECT_TIMEOUT, Duration::from_secs(10));
assert_eq!(builder.total_timeout, Duration::from_secs(30));
assert_eq!(builder.read_timeout, Duration::from_secs(30));
assert_eq!(DEFAULT_BODY_LIMIT, 16 * 1024 * 1024);
assert_eq!(builder.body_limit, DEFAULT_BODY_LIMIT);
}
#[test]
fn it_client_defaults_require_safe_scope_and_fields() {
for base in ["http:g", "HTTP:g", "http:///g"] {
assert!(Client::builder().base_url(base).build().is_err());
}
assert!(
Client::builder()
.auth(crate::BearerToken::new("secret"))
.build()
.is_err()
);
let mut sensitive = HeaderValue::from_static("secret");
sensitive.set_sensitive(true);
assert!(
Client::builder()
.default_header("x-secret", sensitive)
.unwrap()
.build()
.is_err()
);
assert!(
Client::builder()
.default_header("host", "other.example")
.unwrap()
.build()
.is_err()
);
assert!(
Client::builder()
.connect_timeout(Duration::from_secs(1))
.transport(ScriptTransport::new([ok()]))
.build()
.is_err()
);
assert!(
Client::builder()
.proxy(Proxy::http("http://proxy.example:8080").unwrap())
.transport(ScriptTransport::new([ok()]))
.build()
.is_err()
);
assert!(
Client::builder()
.tls(Tls::new().https_only())
.transport(ScriptTransport::new([ok()]))
.build()
.is_err()
);
}
#[test]
fn it_retry_status_decision_includes_only_the_documented_statuses() {
let retryable = [
StatusCode::REQUEST_TIMEOUT,
StatusCode::TOO_EARLY,
StatusCode::TOO_MANY_REQUESTS,
StatusCode::INTERNAL_SERVER_ERROR,
StatusCode::BAD_GATEWAY,
StatusCode::SERVICE_UNAVAILABLE,
StatusCode::GATEWAY_TIMEOUT,
];
for code in 100..=599 {
let status = StatusCode::from_u16(code).unwrap();
assert_eq!(
is_retry_status(status),
retryable.contains(&status),
"status {status}"
);
}
}
#[test]
fn it_transient_pre_header_error_decision_covers_every_error_kind() {
for kind in [
ErrorKind::Dns,
ErrorKind::Connect,
ErrorKind::Timeout,
ErrorKind::Transport,
] {
assert!(is_transient_error(&Error::from_kind(kind)), "kind {kind:?}");
}
for kind in [
ErrorKind::Request,
ErrorKind::Url,
ErrorKind::Runtime,
ErrorKind::Tls,
ErrorKind::Proxy,
ErrorKind::Redirect,
ErrorKind::Retry,
ErrorKind::BodyIo,
ErrorKind::BodyLimit,
ErrorKind::Decoding,
] {
assert!(
!is_transient_error(&Error::from_kind(kind)),
"kind {kind:?}"
);
}
}
#[tokio::test]
async fn it_retry_statuses_require_idempotency_and_replayability() {
let transport = Arc::new(ScriptTransport::new([
(
StatusCode::SERVICE_UNAVAILABLE,
HeaderMap::new(),
Body::text("retry"),
),
ok(),
]));
let client = Client::builder()
.retry(Retry::new(2).unwrap())
.transport(transport.clone())
.build()
.unwrap();
let response = client.get("https://example.com/retry").await.unwrap();
assert_eq!(response.status(), StatusCode::OK);
assert_eq!(transport.requests.lock().unwrap().len(), 2);
}
#[tokio::test]
async fn it_retries_only_transient_pre_header_failures() {
struct FailsOnce {
calls: AtomicUsize,
kind: ErrorKind,
}
impl Transport for FailsOnce {
fn send(&self, request: Request) -> BoxFuture<'_, Result<Response>> {
Box::pin(async move {
if self.calls.fetch_add(1, AtomicOrdering::SeqCst) == 0 {
return Err(Error::new(self.kind, "scripted pre-header failure"));
}
Response::builder()
.status(StatusCode::OK)
.version(Version::HTTP_11)
.effective_url(request.url().clone())
.build()
})
}
}
let retrying = Client::builder()
.retry(Retry::new(2).unwrap())
.transport(FailsOnce {
calls: AtomicUsize::new(0),
kind: ErrorKind::Connect,
})
.build()
.unwrap();
assert_eq!(
retrying.get("https://example.com").await.unwrap().status(),
StatusCode::OK
);
let not_retrying = Client::builder()
.retry(Retry::new(2).unwrap())
.transport(FailsOnce {
calls: AtomicUsize::new(0),
kind: ErrorKind::Tls,
})
.build()
.unwrap();
assert_eq!(
not_retrying
.get("https://example.com")
.await
.unwrap_err()
.kind(),
ErrorKind::Tls
);
#[derive(Clone)]
struct AlwaysFails(Arc<AtomicUsize>);
impl Transport for AlwaysFails {
fn send(&self, _request: Request) -> BoxFuture<'_, Result<Response>> {
Box::pin(async move {
self.0.fetch_add(1, AtomicOrdering::SeqCst);
Err(Error::from_kind(ErrorKind::Connect))
})
}
}
let calls = Arc::new(AtomicUsize::new(0));
let exhausted = Client::builder()
.retry(Retry::new(2).unwrap())
.transport(AlwaysFails(calls.clone()))
.build()
.unwrap();
let error = exhausted
.get("https://example.com/path?secret=value")
.await
.unwrap_err();
assert_eq!(error.kind(), ErrorKind::Retry);
assert_eq!(
error.retry_error(),
Some(crate::RetryError::Exhausted {
attempts: 2,
last: ErrorKind::Connect,
})
);
assert_eq!(error.sanitized_url(), Some("https://example.com/path"));
assert_eq!(calls.load(AtomicOrdering::SeqCst), 2);
}
#[tokio::test]
async fn it_status_retries_require_idempotency_and_replayable_content() {
let post_transport = Arc::new(ScriptTransport::new([
(
StatusCode::SERVICE_UNAVAILABLE,
HeaderMap::new(),
Body::text("not retried"),
),
ok(),
]));
let post_client = Client::builder()
.retry(Retry::new(2).unwrap())
.transport(post_transport.clone())
.build()
.unwrap();
let response = post_client
.post(Request::builder().url("https://example.com").body("body"))
.await
.unwrap();
assert_eq!(response.status(), StatusCode::SERVICE_UNAVAILABLE);
assert_eq!(post_transport.requests.lock().unwrap().len(), 1);
let explicit_transport = Arc::new(ScriptTransport::new([
(
StatusCode::SERVICE_UNAVAILABLE,
HeaderMap::new(),
Body::text("retry"),
),
ok(),
]));
let explicit_client = Client::builder()
.retry(Retry::new(2).unwrap())
.transport(explicit_transport.clone())
.build()
.unwrap();
let response = explicit_client
.post(
Request::builder()
.url("https://example.com")
.body("body")
.idempotent(),
)
.await
.unwrap();
assert_eq!(response.status(), StatusCode::OK);
let requests = explicit_transport.requests.lock().unwrap();
assert_eq!(requests.len(), 2);
assert_eq!(requests[0].body.as_deref(), Some(&b"body"[..]));
assert_eq!(requests[1].body.as_deref(), Some(&b"body"[..]));
}
#[tokio::test]
async fn it_never_retries_non_replayable_content_or_post_header_body_errors() {
struct OneShot;
impl crate::BodySource for OneShot {
fn poll_frame(
self: Pin<&mut Self>,
_context: &mut Context<'_>,
) -> Poll<Result<Option<crate::BodyFrame>>> {
let _ = self;
Poll::Ready(Ok(None))
}
}
let transport = Arc::new(ScriptTransport::new([
(
StatusCode::SERVICE_UNAVAILABLE,
HeaderMap::new(),
Body::text("not retried"),
),
ok(),
]));
let client = Client::builder()
.retry(Retry::new(2).unwrap())
.transport(transport.clone())
.build()
.unwrap();
let response = client
.send(
Request::get("https://example.com")
.body(Body::stream(OneShot))
.build()
.unwrap(),
)
.await
.unwrap();
assert_eq!(response.status(), StatusCode::SERVICE_UNAVAILABLE);
assert_eq!(transport.requests.lock().unwrap().len(), 1);
struct BodyFailure;
impl crate::BodySource for BodyFailure {
fn poll_frame(
self: Pin<&mut Self>,
_context: &mut Context<'_>,
) -> Poll<Result<Option<crate::BodyFrame>>> {
let _ = self;
Poll::Ready(Err(Error::new(ErrorKind::BodyIo, "response body failed")))
}
}
let transport = Arc::new(ScriptTransport::new([(
StatusCode::OK,
HeaderMap::new(),
Body::stream(BodyFailure),
)]));
let client = Client::builder()
.retry(Retry::new(2).unwrap())
.transport(transport.clone())
.build()
.unwrap();
let response = client.get("https://example.com").await.unwrap();
assert_eq!(
response.bytes().await.unwrap_err().kind(),
ErrorKind::BodyIo
);
assert_eq!(transport.requests.lock().unwrap().len(), 1);
}
#[tokio::test(start_paused = true)]
async fn it_retry_after_wait_includes_intermediate_body_drain_time() {
use std::future::Future as _;
struct DelayedEof(Pin<Box<tokio::time::Sleep>>);
impl crate::BodySource for DelayedEof {
fn poll_frame(
mut self: Pin<&mut Self>,
context: &mut Context<'_>,
) -> Poll<Result<Option<crate::BodyFrame>>> {
self.0.as_mut().poll(context).map(|()| Ok(None))
}
}
let mut headers = HeaderMap::new();
headers.insert(RETRY_AFTER, HeaderValue::from_static("1"));
let transport = Arc::new(ScriptTransport::new([
(
StatusCode::SERVICE_UNAVAILABLE,
headers,
Body::stream(DelayedEof(Box::pin(tokio::time::sleep(
Duration::from_millis(600),
)))),
),
ok(),
]));
let client = Client::builder()
.retry(Retry::new(2).unwrap())
.transport(transport.clone())
.build()
.unwrap();
let task = tokio::spawn(async move { client.get("https://example.com").await });
tokio::task::yield_now().await;
tokio::time::advance(Duration::from_millis(999)).await;
tokio::task::yield_now().await;
assert!(!task.is_finished());
tokio::time::advance(Duration::from_millis(1)).await;
let response = task.await.unwrap().unwrap();
assert_eq!(response.status(), StatusCode::OK);
assert_eq!(transport.requests.lock().unwrap().len(), 2);
}
#[tokio::test]
async fn it_retry_after_never_sleeps_past_the_total_deadline() {
let mut headers = HeaderMap::new();
headers.insert(RETRY_AFTER, HeaderValue::from_static("60"));
let transport = Arc::new(ScriptTransport::new([
(
StatusCode::SERVICE_UNAVAILABLE,
headers,
Body::text("current response"),
),
ok(),
]));
let client = Client::builder()
.retry(Retry::new(2).unwrap())
.transport(transport.clone())
.build()
.unwrap();
let response = client
.get(
Request::builder()
.url("https://example.com")
.timeout(Duration::from_millis(10)),
)
.await
.unwrap();
assert_eq!(response.status(), StatusCode::SERVICE_UNAVAILABLE);
assert_eq!(response.text().await.unwrap(), "current response");
assert_eq!(transport.requests.lock().unwrap().len(), 1);
}
#[tokio::test(start_paused = true)]
async fn it_one_deadline_spans_retry_redirect_and_body_reads() {
use std::future::Future as _;
struct DelayedData {
delay: Pin<Box<tokio::time::Sleep>>,
sent: bool,
}
impl crate::BodySource for DelayedData {
fn poll_frame(
mut self: Pin<&mut Self>,
context: &mut Context<'_>,
) -> Poll<Result<Option<crate::BodyFrame>>> {
if self.sent {
return Poll::Ready(Ok(None));
}
match self.delay.as_mut().poll(context) {
Poll::Ready(()) => {
self.sent = true;
Poll::Ready(Ok(Some(crate::BodyFrame::Data(crate::BodyChunk::new(
b"late",
)))))
}
Poll::Pending => Poll::Pending,
}
}
}
let mut retry_headers = HeaderMap::new();
retry_headers.insert(RETRY_AFTER, HeaderValue::from_static("1"));
let mut redirect_headers = HeaderMap::new();
redirect_headers.insert(LOCATION, HeaderValue::from_static("/final"));
let transport = Arc::new(ScriptTransport::new([
(
StatusCode::SERVICE_UNAVAILABLE,
retry_headers,
Body::text("retry"),
),
(StatusCode::FOUND, redirect_headers, Body::text("redirect")),
(
StatusCode::OK,
HeaderMap::new(),
Body::stream(DelayedData {
delay: Box::pin(tokio::time::sleep(Duration::from_secs(2))),
sent: false,
}),
),
]));
let client = Client::builder()
.retry(Retry::new(2).unwrap())
.redirect(Redirect::FollowAll)
.transport(transport.clone())
.build()
.unwrap();
let task = tokio::spawn(async move {
client
.get(
Request::builder()
.url("https://example.com/start")
.timeout(Duration::from_millis(1_500)),
)
.await?
.bytes()
.await
});
tokio::task::yield_now().await;
tokio::time::advance(Duration::from_millis(1_000)).await;
tokio::task::yield_now().await;
assert_eq!(transport.requests.lock().unwrap().len(), 3);
tokio::time::advance(Duration::from_millis(500)).await;
let error = task.await.unwrap().unwrap_err();
assert_eq!(error.kind(), ErrorKind::Timeout);
}
#[tokio::test]
async fn it_total_deadline_applies_above_custom_transports() {
struct SlowTransport;
impl Transport for SlowTransport {
fn send(&self, request: Request) -> BoxFuture<'_, Result<Response>> {
Box::pin(async move {
tokio::time::sleep(Duration::from_secs(1)).await;
Response::builder()
.status(StatusCode::OK)
.version(Version::HTTP_11)
.effective_url(request.url().clone())
.build()
})
}
}
let client = Client::builder()
.timeout(Duration::from_millis(10))
.transport(SlowTransport)
.build()
.unwrap();
assert_eq!(
client.get("https://example.com").await.unwrap_err().kind(),
ErrorKind::Timeout
);
}
#[cfg(feature = "cookies")]
#[tokio::test]
async fn it_cookie_policy_uses_the_sent_url_above_custom_transports() {
struct CookieTransport {
calls: AtomicUsize,
requests: Mutex<Vec<Recorded>>,
}
impl Transport for CookieTransport {
fn send(&self, request: Request) -> BoxFuture<'_, Result<Response>> {
Box::pin(async move {
let call = self.calls.fetch_add(1, AtomicOrdering::SeqCst);
let url = request.url().clone();
self.requests.lock().unwrap().push(Recorded {
method: request.method().clone(),
url: url.clone(),
headers: request.headers().clone(),
body: None,
});
let mut builder = Response::builder()
.status(StatusCode::OK)
.version(Version::HTTP_11)
.effective_url(url);
if call == 0 {
let mut headers = HeaderMap::new();
headers.insert(
SET_COOKIE,
HeaderValue::from_static("sid=good; Path=/; Secure"),
);
builder = builder.headers(headers);
}
builder.build()
})
}
}
let transport = Arc::new(CookieTransport {
calls: AtomicUsize::new(0),
requests: Mutex::new(Vec::new()),
});
let client = Client::builder()
.jar(Jar::new())
.transport(transport.clone())
.build()
.unwrap();
client.get("https://good.example/set").await.unwrap();
client.get("https://good.example/check").await.unwrap();
client
.get("https://misleading.example/check")
.await
.unwrap();
let requests = transport.requests.lock().unwrap();
assert_eq!(requests[1].headers[COOKIE], "sid=good");
assert!(!requests[2].headers.contains_key(COOKIE));
}
#[cfg(feature = "cookies")]
#[tokio::test]
async fn it_reselects_cookie_scope_for_every_redirect_hop() {
let mut to_other = HeaderMap::new();
to_other.insert(
LOCATION,
HeaderValue::from_static("https://other.example/next"),
);
to_other.insert(
SET_COOKIE,
HeaderValue::from_static("origin=one; Path=/; Secure"),
);
let mut to_origin = HeaderMap::new();
to_origin.insert(
LOCATION,
HeaderValue::from_static("https://origin.example/final"),
);
to_origin.insert(
SET_COOKIE,
HeaderValue::from_static("other=two; Path=/; Secure"),
);
let transport = Arc::new(ScriptTransport::new([
(StatusCode::FOUND, to_other, Body::text("first")),
(StatusCode::FOUND, to_origin, Body::text("second")),
ok(),
]));
let client = Client::builder()
.jar(Jar::new())
.redirect(Redirect::FollowAll)
.transport(transport.clone())
.build()
.unwrap();
client.get("https://origin.example/start").await.unwrap();
let requests = transport.requests.lock().unwrap();
assert!(!requests[0].headers.contains_key(COOKIE));
assert!(!requests[1].headers.contains_key(COOKIE));
assert_eq!(requests[2].headers[COOKIE], "origin=one");
assert_ne!(requests[2].headers[COOKIE], "other=two");
}
#[tokio::test]
async fn it_applies_client_body_limits_to_responses() {
let client = Client::builder()
.body_limit(4)
.transport(ScriptTransport::new([(
StatusCode::OK,
HeaderMap::new(),
Body::text("fives"),
)]))
.build()
.unwrap();
let response = client.get("https://example.com/limit").await.unwrap();
assert_eq!(
response.bytes().await.unwrap_err().kind(),
ErrorKind::BodyLimit
);
}
#[test]
fn it_retry_after_supports_seconds_and_dates() {
let mut headers = HeaderMap::new();
headers.insert(RETRY_AFTER, HeaderValue::from_static("3"));
assert_eq!(retry_after(&headers), Some(Duration::from_secs(3)));
let now = SystemTime::UNIX_EPOCH + Duration::from_secs(1_000_000);
let future = now + Duration::from_secs(45);
headers.insert(
RETRY_AFTER,
HeaderValue::from_str(&httpdate::fmt_http_date(future)).unwrap(),
);
assert_eq!(retry_after_at(&headers, now), Some(Duration::from_secs(45)));
let past = now - Duration::from_secs(1);
headers.insert(
RETRY_AFTER,
HeaderValue::from_str(&httpdate::fmt_http_date(past)).unwrap(),
);
assert_eq!(retry_after_at(&headers, now), Some(Duration::ZERO));
}
#[test]
fn it_missing_runtime_is_a_typed_error_not_a_panic() {
use std::{future::Future as _, task::Waker};
let client = Client::builder()
.transport(ScriptTransport::new([ok()]))
.build()
.unwrap();
let mut future = Box::pin(client.get("https://example.com"));
let waker = Waker::noop();
let mut context = Context::from_waker(waker);
let Poll::Ready(Err(error)) = future.as_mut().poll(&mut context) else {
panic!("missing runtime should be reported on the first poll");
};
assert_eq!(error.kind(), ErrorKind::Runtime);
let rendered = format!("{error:?} {error}").to_ascii_lowercase();
for backend in ["tokio", "reqwest", "hyper"] {
assert!(!rendered.contains(backend));
}
}
#[test]
fn it_missing_runtime_drivers_are_typed_errors() {
let no_drivers = tokio::runtime::Builder::new_current_thread()
.build()
.unwrap();
let client = Client::builder()
.transport(ScriptTransport::new([ok()]))
.build()
.unwrap();
let error = no_drivers
.block_on(client.get("https://example.com"))
.unwrap_err();
assert_eq!(error.kind(), ErrorKind::Runtime);
let time_only = tokio::runtime::Builder::new_current_thread()
.enable_time()
.build()
.unwrap();
let client = Client::new().unwrap();
let error = time_only
.block_on(client.get("http://127.0.0.1:9"))
.unwrap_err();
assert_eq!(error.kind(), ErrorKind::Runtime);
}
}