use std::net::SocketAddr;
use std::sync::Arc;
use bytes::Bytes;
use http::Version;
use crate::body::RequestBody;
use crate::client::Client;
use crate::error::Result;
use crate::headers::Headers;
use crate::redirect::RedirectPolicy;
use crate::response::Response;
use crate::retry::RetryPolicy;
use crate::timeout::Timeout;
use crate::trace::TraceObserver;
use crate::auth::AuthScheme;
#[cfg(feature = "proxy")]
use crate::proxy::ProxyConfig;
#[derive(Clone, PartialEq, Eq)]
pub struct ResolvedTarget {
addresses: Arc<[SocketAddr]>,
}
impl ResolvedTarget {
pub fn new<I>(addresses: I) -> crate::Result<Self>
where
I: IntoIterator<Item = SocketAddr>,
{
let addresses: Vec<_> = addresses.into_iter().collect();
if addresses.is_empty() {
return Err(crate::Error::InvalidResolvedTarget(
"resolved destination set must not be empty".into(),
));
}
Ok(Self {
addresses: addresses.into(),
})
}
#[must_use]
pub fn addresses(&self) -> &[SocketAddr] {
&self.addresses
}
}
impl std::fmt::Debug for ResolvedTarget {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
f.debug_struct("ResolvedTarget")
.field("address_count", &self.addresses.len())
.finish()
}
}
#[derive(Default, Clone)]
pub struct TransportHints {
pub target: Option<Bytes>,
pub sni_hostname: Option<String>,
pub resolved_target: Option<ResolvedTarget>,
pub trace: Option<Arc<dyn TraceObserver>>,
}
impl std::fmt::Debug for TransportHints {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
f.debug_struct("TransportHints")
.field("target", &self.target)
.field("sni_hostname", &self.sni_hostname)
.field("resolved_target", &self.resolved_target)
.field("trace", &self.trace.as_ref().map(|_| "..."))
.finish()
}
}
#[derive(Debug, Clone, Default)]
#[allow(
clippy::large_enum_variant,
reason = "ProxyConfig is transient and cloning it is cheap; boxing adds unnecessary allocation"
)]
pub enum ProxyOverride {
#[default]
Inherit,
Direct,
#[cfg(feature = "proxy")]
Override(ProxyConfig),
}
pub(crate) struct RequestParts {
pub(crate) method: http::Method,
pub(crate) url: url::Url,
pub(crate) headers: Headers,
pub(crate) body: RequestBody,
pub(crate) version: Version,
pub(crate) timeout: Option<Timeout>,
pub(crate) redirect: Option<RedirectPolicy>,
pub(crate) auth: Option<AuthScheme>,
pub(crate) auth_disabled: bool,
pub(crate) decompress: Option<bool>,
pub(crate) max_decoded_body_size: Option<usize>,
pub(crate) max_decompression_ratio: Option<f64>,
pub(crate) proxy_override: ProxyOverride,
pub(crate) retry: Option<RetryPolicy>,
pub(crate) transport_hints: TransportHints,
}
impl RequestParts {
#[allow(
dead_code,
reason = "exhaustiveness anchor for RequestParts: guarantees new fields fail to compile even though live code uses retry_request"
)]
pub(crate) fn into_request(self) -> Request {
let RequestParts {
method,
url,
headers,
body,
version,
timeout,
redirect,
auth,
auth_disabled,
decompress,
max_decoded_body_size,
max_decompression_ratio,
proxy_override,
retry,
transport_hints,
} = self;
let mut request = Request::new(method, url);
*request.headers_mut() = headers;
request.set_body(body);
request.set_version(version);
request.set_timeout(timeout);
request.set_redirect(redirect);
request.set_auth(auth);
request.set_auth_disabled(auth_disabled);
request.set_decompress(decompress);
request.set_max_decoded_body_size(max_decoded_body_size);
request.set_max_decompression_ratio(max_decompression_ratio);
#[cfg(feature = "proxy")]
request.set_proxy_override(proxy_override);
#[cfg(not(feature = "proxy"))]
let _ = proxy_override;
request.set_retry(retry);
request.set_transport_hints(transport_hints);
request
}
pub(crate) fn retry_request(
&self,
attempt_timeout: Option<Timeout>,
) -> crate::error::Result<Request> {
let replayed = self.body.try_clone_for_retry()?;
let mut request = Request::new(self.method.clone(), self.url.clone());
*request.headers_mut() = self.headers.clone();
request.set_body(replayed);
request.set_version(self.version);
request.set_timeout(attempt_timeout);
request.set_redirect(self.redirect.clone());
request.set_auth(self.auth.clone());
request.set_auth_disabled(self.auth_disabled);
request.set_decompress(self.decompress);
request.set_max_decoded_body_size(self.max_decoded_body_size);
request.set_max_decompression_ratio(self.max_decompression_ratio);
#[cfg(feature = "proxy")]
request.set_proxy_override(self.proxy_override.clone());
request.set_retry(self.retry.clone());
request.set_transport_hints(self.transport_hints.clone());
Ok(request)
}
pub(crate) fn shrink_total_deadline(
timeout: &Timeout,
elapsed: std::time::Duration,
) -> Timeout {
let mut out = *timeout;
if let Some(total) = out.total {
out.total = Some(total.saturating_sub(elapsed));
}
out
}
}
pub struct Request {
method: http::Method,
url: url::Url,
headers: Headers,
body: RequestBody,
version: Version,
timeout: Option<Timeout>,
redirect: Option<RedirectPolicy>,
auth: Option<AuthScheme>,
auth_disabled: bool,
decompress: Option<bool>,
max_decoded_body_size: Option<usize>,
max_decompression_ratio: Option<f64>,
proxy_override: ProxyOverride,
retry: Option<RetryPolicy>,
transport_hints: TransportHints,
}
impl std::fmt::Debug for Request {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
f.debug_struct("Request")
.field("method", &self.method)
.field("url", &crate::redact::redact_url(&self.url))
.field("headers", &self.headers)
.field("body", &self.body)
.field("version", &self.version)
.field("timeout", &self.timeout)
.field("redirect", &self.redirect)
.field("auth", &self.auth)
.field("auth_disabled", &self.auth_disabled)
.field("decompress", &self.decompress)
.field("max_decoded_body_size", &self.max_decoded_body_size)
.field("max_decompression_ratio", &self.max_decompression_ratio)
.field("proxy_override", &self.proxy_override)
.field("retry", &self.retry)
.field("transport_hints", &self.transport_hints)
.finish()
}
}
impl Request {
pub(crate) fn new(method: http::Method, url: url::Url) -> Self {
Self {
method,
url,
headers: Headers::new(),
body: RequestBody::default(),
version: Version::HTTP_11,
timeout: None,
redirect: None,
auth: None,
auth_disabled: false,
decompress: None,
max_decoded_body_size: None,
max_decompression_ratio: None,
proxy_override: ProxyOverride::Inherit,
retry: None,
transport_hints: TransportHints::default(),
}
}
#[must_use]
pub fn method(&self) -> &http::Method {
&self.method
}
#[must_use]
pub fn url(&self) -> &url::Url {
&self.url
}
#[must_use]
pub fn headers(&self) -> &Headers {
&self.headers
}
pub fn headers_mut(&mut self) -> &mut Headers {
&mut self.headers
}
#[must_use]
pub fn body(&self) -> &RequestBody {
&self.body
}
pub fn set_body(&mut self, body: RequestBody) {
self.body = body;
}
#[must_use]
pub fn version(&self) -> Version {
self.version
}
pub fn set_version(&mut self, version: Version) {
self.version = version;
}
#[must_use]
pub fn timeout(&self) -> Option<&Timeout> {
self.timeout.as_ref()
}
pub fn set_timeout(&mut self, timeout: Option<Timeout>) {
self.timeout = timeout;
}
#[must_use]
pub fn redirect(&self) -> Option<&RedirectPolicy> {
self.redirect.as_ref()
}
pub fn set_redirect(&mut self, redirect: Option<RedirectPolicy>) {
self.redirect = redirect;
}
#[must_use]
pub fn auth(&self) -> Option<&AuthScheme> {
self.auth.as_ref()
}
pub fn set_auth(&mut self, auth: Option<AuthScheme>) {
self.auth = auth;
}
#[must_use]
pub fn is_auth_disabled(&self) -> bool {
self.auth_disabled
}
pub fn set_auth_disabled(&mut self, disabled: bool) {
self.auth_disabled = disabled;
}
#[must_use]
pub fn decompress(&self) -> Option<bool> {
self.decompress
}
pub fn set_decompress(&mut self, decompress: Option<bool>) {
self.decompress = decompress;
}
#[must_use]
pub fn max_decoded_body_size(&self) -> Option<usize> {
self.max_decoded_body_size
}
pub fn set_max_decoded_body_size(&mut self, max: Option<usize>) {
self.max_decoded_body_size = max;
}
#[must_use]
pub fn max_decompression_ratio(&self) -> Option<f64> {
self.max_decompression_ratio
}
pub fn set_max_decompression_ratio(&mut self, ratio: Option<f64>) {
self.max_decompression_ratio = ratio;
}
#[cfg(feature = "proxy")]
#[must_use]
pub fn proxy_override(&self) -> &ProxyOverride {
&self.proxy_override
}
#[cfg(feature = "proxy")]
pub fn set_proxy_override(&mut self, proxy: ProxyOverride) {
self.proxy_override = proxy;
}
#[must_use]
pub fn retry(&self) -> Option<&RetryPolicy> {
self.retry.as_ref()
}
pub fn set_retry(&mut self, retry: Option<RetryPolicy>) {
self.retry = retry;
}
#[must_use]
pub fn transport_hints(&self) -> &TransportHints {
&self.transport_hints
}
pub fn set_transport_hints(&mut self, hints: TransportHints) {
self.transport_hints = hints;
}
pub(crate) fn into_parts(self) -> RequestParts {
RequestParts {
method: self.method,
url: self.url,
headers: self.headers,
body: self.body,
version: self.version,
timeout: self.timeout,
redirect: self.redirect,
auth: self.auth,
auth_disabled: self.auth_disabled,
decompress: self.decompress,
max_decoded_body_size: self.max_decoded_body_size,
max_decompression_ratio: self.max_decompression_ratio,
proxy_override: self.proxy_override,
retry: self.retry,
transport_hints: self.transport_hints,
}
}
}
pub struct RequestBuilder {
client: Option<Client>,
method: http::Method,
url: url::Url,
headers: Headers,
body: RequestBody,
timeout: Option<Timeout>,
redirect: Option<RedirectPolicy>,
auth: Option<AuthScheme>,
auth_disabled: bool,
decompress: Option<bool>,
max_decoded_body_size: Option<usize>,
max_decompression_ratio: Option<f64>,
proxy_override: ProxyOverride,
retry: Option<RetryPolicy>,
transport_hints: TransportHints,
error: Option<crate::Error>,
}
impl RequestBuilder {
pub(crate) fn new(client: Client, method: http::Method, url: url::Url) -> Self {
Self {
client: Some(client),
method,
url,
headers: Headers::new(),
body: RequestBody::default(),
timeout: None,
redirect: None,
auth: None,
auth_disabled: false,
decompress: None,
max_decoded_body_size: None,
max_decompression_ratio: None,
proxy_override: ProxyOverride::Inherit,
retry: None,
transport_hints: TransportHints::default(),
error: None,
}
}
#[must_use]
pub fn header(mut self, name: &str, value: &str) -> Self {
if let Err(e) = self.headers.insert(name, value) {
if self.error.is_none() {
self.error = Some(e);
}
}
self
}
#[must_use]
pub fn headers(mut self, headers: Headers) -> Self {
self.headers = headers;
self
}
#[must_use]
pub fn query(mut self, key: &str, value: &str) -> Self {
self.url.query_pairs_mut().append_pair(key, value);
self
}
#[must_use]
pub fn body(mut self, body: impl Into<RequestBody>) -> Self {
self.body = body.into();
self
}
#[must_use]
pub fn bytes(self, data: impl Into<Bytes>) -> Self {
self.body(RequestBody::Bytes(data.into()))
}
#[cfg(feature = "json")]
pub fn json<T: serde::Serialize>(mut self, value: &T) -> Result<Self> {
let bytes = serde_json::to_vec(value)
.map_err(|_| crate::Error::JsonSerialize("failed to serialize JSON value".into()))?;
self.body = RequestBody::Bytes(Bytes::from(bytes));
if !self.headers.contains("content-type") {
self.headers.insert("content-type", "application/json")?;
}
Ok(self)
}
#[must_use]
pub fn timeout(mut self, timeout: Timeout) -> Self {
self.timeout = Some(timeout);
self
}
#[must_use]
pub fn redirect_policy(mut self, policy: RedirectPolicy) -> Self {
self.redirect = Some(policy);
self
}
#[must_use]
pub fn auth(mut self, auth: impl Into<AuthScheme>) -> Self {
self.auth = Some(auth.into());
self.auth_disabled = false;
self
}
#[must_use]
pub fn without_auth(mut self) -> Self {
self.auth_disabled = true;
self.auth = None;
self
}
#[cfg(feature = "proxy")]
#[must_use]
pub fn proxy(mut self, proxy: &crate::proxy::Proxy) -> Self {
self.proxy_override = ProxyOverride::Override(proxy.config());
self
}
#[cfg(feature = "proxy")]
#[must_use]
pub fn without_proxy(mut self) -> Self {
self.proxy_override = ProxyOverride::Direct;
self
}
#[must_use]
pub fn decompress(mut self, decompress: bool) -> Self {
self.decompress = Some(decompress);
self
}
#[must_use]
pub fn max_decoded_body_size(mut self, max: usize) -> Self {
self.max_decoded_body_size = Some(max);
self
}
#[must_use]
pub fn max_decompression_ratio(mut self, ratio: f64) -> Self {
assert!(
ratio.is_finite() && ratio > 0.0,
"max_decompression_ratio must be finite and positive, got {ratio}"
);
self.max_decompression_ratio = Some(ratio);
self
}
#[must_use]
pub fn retry(mut self, policy: RetryPolicy) -> Self {
self.retry = Some(policy);
self
}
#[must_use]
pub fn without_retry(mut self) -> Self {
self.retry = Some(RetryPolicy::default());
self
}
#[must_use]
pub fn transport_hints(mut self, hints: TransportHints) -> Self {
self.transport_hints = hints;
self
}
#[must_use]
pub fn resolved_addresses<I>(mut self, addresses: I) -> Self
where
I: IntoIterator<Item = SocketAddr>,
{
match ResolvedTarget::new(addresses) {
Ok(target) => self.transport_hints.resolved_target = Some(target),
Err(error) => {
if self.error.is_none() {
self.error = Some(error);
}
}
}
self
}
pub fn build(mut self) -> Result<Request> {
if let Some(e) = self.error.take() {
return Err(e);
}
if let Some(target) = &self.transport_hints.resolved_target {
let expected_port = self.url.port_or_known_default().ok_or_else(|| {
crate::Error::InvalidResolvedTarget(
"resolved destinations require an HTTP or HTTPS URL".into(),
)
})?;
if target
.addresses()
.iter()
.any(|address| address.port() != expected_port)
{
return Err(crate::Error::InvalidResolvedTarget(format!(
"all resolved destinations must use the URL's effective port {expected_port}"
)));
}
}
let request_target = self
.transport_hints
.target
.as_deref()
.unwrap_or_else(|| self.url.as_str().as_bytes());
self.headers
.validate_request_size(&self.method, request_target)?;
let mut req = Request::new(self.method, self.url);
req.headers = self.headers;
req.body = self.body;
req.timeout = self.timeout;
req.redirect = self.redirect;
req.auth = self.auth;
req.auth_disabled = self.auth_disabled;
req.decompress = self.decompress;
req.max_decoded_body_size = self.max_decoded_body_size;
req.max_decompression_ratio = self.max_decompression_ratio;
req.proxy_override = self.proxy_override;
req.retry = self.retry;
req.transport_hints = self.transport_hints;
Ok(req)
}
pub async fn send(self) -> Result<Response> {
let client = self.client.clone().ok_or_else(|| {
crate::Error::RequestBuild("no client associated with request builder".into())
})?;
let request = self.build()?;
Box::pin(client.send(request)).await
}
}
#[cfg(test)]
mod tests {
use proptest::prelude::*;
use super::{Request, ResolvedTarget};
use crate::auth::{AuthScheme, BasicAuth};
use bytes::Bytes;
use std::net::SocketAddr;
proptest::proptest! {
#[test]
fn url_parse_round_trip(scheme in "https?", host in "[a-z]{2,10}\\.[a-z]{2,5}", path in "/[a-z]{0,20}") {
let url_str = format!("{scheme}://{host}{path}");
let parsed = url::Url::parse(&url_str).unwrap();
let serialized = parsed.to_string();
prop_assert_eq!(url_str, serialized);
}
#[test]
fn query_pairs_round_trip(key in "[a-z]{1,10}", value in "[a-z0-9]{1,20}") {
let mut url = url::Url::parse("http://example.com/").unwrap();
url.query_pairs_mut().append_pair(&key, &value);
let found = url.query_pairs().find(|(k, _)| k == &key).map(|(_, v)| v.into_owned());
prop_assert_eq!(found, Some(value));
}
#[test]
fn url_with_arbitrary_path(path in "/[a-zA-Z0-9._/-]{0,50}") {
let url_str = format!("http://example.com{path}");
let _ = url::Url::parse(&url_str);
}
}
#[test]
fn request_debug_redacts_secrets() {
let url = url::Url::parse("https://example.com/submit?api_key=top-secret-key").unwrap();
let mut req = Request::new(http::Method::POST, url);
req.headers_mut()
.insert("authorization", "Bearer bearer-secret-token")
.unwrap();
req.headers_mut()
.insert("cookie", "session=cookie-secret")
.unwrap();
req.set_body(crate::body::RequestBody::Bytes(Bytes::from(
"password=form-secret",
)));
req.set_auth(Some(AuthScheme::Basic(
BasicAuth::new("user", "auth-secret").unwrap(),
)));
let debug = format!("{req:?}");
for leaked in [
"top-secret-key",
"bearer-secret-token",
"cookie-secret",
"form-secret",
"auth-secret",
] {
assert!(
!debug.contains(leaked),
"Request Debug must not leak {leaked:?}: {debug}"
);
}
assert!(debug.contains("example.com"), "keeps the host: {debug}");
assert!(debug.contains("POST"), "keeps the method: {debug}");
}
#[test]
fn resolved_target_rejects_empty_and_hides_addresses_in_debug() {
assert!(ResolvedTarget::new(Vec::<SocketAddr>::new()).is_err());
let target = ResolvedTarget::new(["127.0.0.1:443".parse().unwrap()]).unwrap();
let debug = format!("{target:?}");
assert!(debug.contains("address_count: 1"));
assert!(!debug.contains("127.0.0.1"));
}
#[test]
fn request_builder_validates_resolved_target_port() {
let client = crate::client::Client::new();
let request = client
.get("http://example.invalid/")
.unwrap()
.resolved_addresses(["127.0.0.1:80".parse().unwrap()])
.build()
.unwrap();
assert_eq!(
request
.transport_hints()
.resolved_target
.as_ref()
.unwrap()
.addresses()
.len(),
1
);
let error = client
.get("http://example.invalid/")
.unwrap()
.resolved_addresses(["127.0.0.1:443".parse().unwrap()])
.build()
.unwrap_err();
assert_eq!(error.kind(), "invalid_resolved_target");
}
#[cfg(feature = "json")]
#[test]
fn request_json_sets_default_content_type_and_replayable_body() {
let client = crate::client::Client::new();
let request = client
.post("http://example.invalid/")
.unwrap()
.json(&serde_json::json!({"key": "value"}))
.unwrap()
.build()
.unwrap();
assert_eq!(
request.headers().get("content-type").unwrap(),
"application/json"
);
assert!(request.body().is_replayable());
let request = client
.post("http://example.invalid/")
.unwrap()
.header("content-type", "application/vnd.api+json")
.json(&serde_json::json!([1, 2, 3]))
.unwrap()
.build()
.unwrap();
assert_eq!(
request.headers().get("content-type").unwrap(),
"application/vnd.api+json"
);
}
}