use std::{convert::TryFrom, error::Error as StdError, sync::Arc, time::Duration};
use futures_util::Stream;
use http::{HeaderMap, HeaderName, HeaderValue, Method, Uri, Version, header::CONTENT_TYPE};
use serde::Serialize;
use url::Url;
use crate::{
Body, Client, Error, Event, Multipart, Request, Response, Result, auth::Authentication,
content::Content,
};
#[derive(Clone, Copy)]
enum TimeoutOverride {
Set(Duration),
Disabled,
}
pub(crate) fn resolve_timeout(
request: &Request,
client_timeout: Option<Duration>,
) -> Option<Duration> {
match request.extensions().get::<TimeoutOverride>().copied() {
Some(TimeoutOverride::Set(duration)) => Some(duration),
Some(TimeoutOverride::Disabled) => None,
None => client_timeout,
}
}
pub struct RequestBuilder<'client> {
client: &'client Client,
request: Result<Request>,
content_type: ContentTypeState,
}
#[derive(Clone, Copy, PartialEq, Eq)]
enum ContentTypeState {
Absent,
Caller,
Generated,
Multipart,
}
impl<'client> RequestBuilder<'client> {
pub(crate) fn new(client: &'client Client, method: Method, target: &str) -> Self {
let request = parse_target(target).and_then(|uri| {
http::Request::builder()
.method(method)
.uri(uri)
.body(Body::empty())
.map_err(Into::into)
});
Self {
client,
request,
content_type: ContentTypeState::Absent,
}
}
#[must_use]
pub fn header<K, V>(self, name: K, value: V) -> Self
where
HeaderName: TryFrom<K>,
HeaderValue: TryFrom<V>,
{
self.apply(move |request, content_type| {
let name = HeaderName::try_from(name)
.map_err(|_| Error::request("request header name is invalid"))?;
let value = HeaderValue::try_from(value)
.map_err(|_| Error::request("request header value is invalid"))?;
if name == CONTENT_TYPE {
if *content_type == ContentTypeState::Multipart {
return Err(Error::request("multipart content type is managed by Tez"));
}
*content_type = ContentTypeState::Caller;
}
request.headers_mut().insert(name, value);
Ok(())
})
}
#[must_use]
pub fn append_header<K, V>(self, name: K, value: V) -> Self
where
HeaderName: TryFrom<K>,
HeaderValue: TryFrom<V>,
{
self.apply(move |request, content_type| {
let name = HeaderName::try_from(name)
.map_err(|_| Error::request("request header name is invalid"))?;
let value = HeaderValue::try_from(value)
.map_err(|_| Error::request("request header value is invalid"))?;
if name == CONTENT_TYPE {
if *content_type == ContentTypeState::Multipart {
return Err(Error::request("multipart content type is managed by Tez"));
}
*content_type = ContentTypeState::Caller;
}
request.headers_mut().append(name, value);
Ok(())
})
}
#[must_use]
pub fn headers(self, headers: HeaderMap) -> Self {
self.apply(move |request, content_type| {
replace_headers(request.headers_mut(), headers, content_type)
})
}
#[must_use]
pub fn auth(self, authentication: impl Authentication + 'static) -> Self {
self.apply(move |request, _| {
request
.extensions_mut()
.insert::<Arc<dyn Authentication>>(Arc::new(authentication));
Ok(())
})
}
#[must_use]
pub fn query<T>(self, query_params: &T) -> Self
where
T: Serialize + ?Sized,
{
self.apply(|request, _| {
let query = serde_urlencoded::to_string(query_params)
.map_err(|_| Error::request("request query could not be encoded"))?;
if query.is_empty() {
return Ok(());
}
let uri = append_query(request.uri(), &query)?;
*request.uri_mut() = uri;
Ok(())
})
}
#[must_use]
pub fn timeout(self, timeout: impl Into<Option<Duration>>) -> Self {
self.apply(move |request, _| {
match timeout.into() {
Some(duration) if duration.is_zero() => {
return Err(Error::request("request timeout must be greater than zero"));
}
Some(duration) => request
.extensions_mut()
.insert(TimeoutOverride::Set(duration)),
None => request.extensions_mut().insert(TimeoutOverride::Disabled),
};
Ok(())
})
}
#[must_use]
pub fn version(self, version: Version) -> Self {
self.apply(move |request, _| {
*request.version_mut() = version;
Ok(())
})
}
#[must_use]
pub fn extension<T>(self, value: T) -> Self
where
T: Clone + Send + Sync + 'static,
{
self.apply(move |request, _| {
request.extensions_mut().insert(value);
Ok(())
})
}
#[must_use]
pub fn body(self, body: impl Into<Body>) -> Self {
self.apply(move |request, content_type| {
replace_body(request, body.into(), None, content_type);
Ok(())
})
}
#[must_use]
pub fn reader<R>(self, reader: R) -> Self
where
R: futures_io::AsyncRead + Send + Unpin + 'static,
{
self.body(Body::reader(reader))
}
#[must_use]
pub fn reader_with_length<R>(self, reader: R, length: u64) -> Self
where
R: futures_io::AsyncRead + Send + Unpin + 'static,
{
self.body(Body::reader_with_length(reader, length))
}
#[must_use]
pub fn stream<S, D, E>(self, stream: S) -> Self
where
S: Stream<Item = std::result::Result<D, E>> + Send + 'static,
D: Into<bytes::Bytes>,
E: StdError + Send + Sync + 'static,
{
self.body(Body::stream(stream))
}
#[must_use]
pub fn stream_with_length<S, D, E>(self, stream: S, length: u64) -> Self
where
S: Stream<Item = std::result::Result<D, E>> + Send + 'static,
D: Into<bytes::Bytes>,
E: StdError + Send + Sync + 'static,
{
self.body(Body::stream_with_length(stream, length))
}
#[must_use]
pub fn text(self, text: impl Into<String>) -> Self {
self.content(Content::text(text))
}
#[must_use]
pub fn html(self, html: impl Into<String>) -> Self {
self.content(Content::html(html))
}
#[must_use]
pub fn json<T>(self, value: &T) -> Self
where
T: Serialize + ?Sized,
{
self.apply(|request, content_type| {
replace_content(request, Content::json(value)?, content_type);
Ok(())
})
}
#[must_use]
pub fn form<T>(self, value: &T) -> Self
where
T: Serialize + ?Sized,
{
self.apply(|request, content_type| {
replace_content(request, Content::form(value)?, content_type);
Ok(())
})
}
#[must_use]
pub fn ndjson<S, T, E>(self, stream: S) -> Self
where
S: Stream<Item = std::result::Result<T, E>> + Send + 'static,
T: Serialize,
E: StdError + Send + Sync + 'static,
{
let item_limit = self.client.inner.limits.stream_item_bytes();
self.apply(move |request, content_type| {
replace_body(
request,
crate::stream::ndjson_body(stream, item_limit),
Some(crate::stream::NDJSON_CONTENT_TYPE),
content_type,
);
Ok(())
})
}
#[must_use]
pub fn json_array<S, T, E>(self, stream: S) -> Self
where
S: Stream<Item = std::result::Result<T, E>> + Send + 'static,
T: Serialize,
E: StdError + Send + Sync + 'static,
{
let item_limit = self.client.inner.limits.stream_item_bytes();
self.apply(move |request, content_type| {
replace_body(
request,
crate::stream::json_array_body(stream, item_limit),
Some(crate::stream::JSON_CONTENT_TYPE),
content_type,
);
Ok(())
})
}
#[must_use]
pub fn sse<S, E>(self, stream: S) -> Self
where
S: Stream<Item = std::result::Result<Event, E>> + Send + 'static,
E: StdError + Send + Sync + 'static,
{
let item_limit = self.client.inner.limits.stream_item_bytes();
self.apply(move |request, content_type| {
replace_body(
request,
crate::stream::sse_body(stream, item_limit),
Some(crate::stream::SSE_CONTENT_TYPE),
content_type,
);
Ok(())
})
}
#[must_use]
pub fn multipart(self, multipart: Multipart) -> Self {
self.apply(move |request, content_type_state| {
let (body, content_type) = multipart.into_body()?;
replace_body(request, body, None, content_type_state);
request.headers_mut().insert(CONTENT_TYPE, content_type);
*content_type_state = ContentTypeState::Multipart;
Ok(())
})
}
pub fn build(self) -> Result<Request> {
self.request
}
pub async fn send(self) -> Result<Response> {
let client = self.client;
client.send(self.build()?).await
}
fn apply(
mut self,
operation: impl FnOnce(&mut Request, &mut ContentTypeState) -> Result<()>,
) -> Self {
if let Ok(request) = &mut self.request
&& let Err(error) = operation(request, &mut self.content_type)
{
self.request = Err(error);
}
self
}
fn content(self, content: Content) -> Self {
self.apply(move |request, content_type| {
replace_content(request, content, content_type);
Ok(())
})
}
}
fn replace_content(request: &mut Request, content: Content, content_type: &mut ContentTypeState) {
let (body, media_type) = content.into_parts();
replace_body(request, body, Some(media_type), content_type);
}
fn replace_headers(
request_headers: &mut HeaderMap,
headers: HeaderMap,
content_type: &mut ContentTypeState,
) -> Result<()> {
if headers.contains_key(CONTENT_TYPE) && *content_type == ContentTypeState::Multipart {
return Err(Error::request("multipart content type is managed by Tez"));
}
for name in headers.keys() {
request_headers.remove(name);
}
let mut previous = None;
for (name, value) in headers {
let name = name.or_else(|| previous.clone()).ok_or_else(|| {
Error::request("request header map contains an invalid repeated value")
})?;
if name == CONTENT_TYPE {
*content_type = ContentTypeState::Caller;
}
request_headers.append(name.clone(), value);
previous = Some(name);
}
Ok(())
}
fn replace_body(
request: &mut Request,
body: Body,
content_type: Option<&'static str>,
content_type_state: &mut ContentTypeState,
) {
if matches!(
*content_type_state,
ContentTypeState::Generated | ContentTypeState::Multipart
) {
request.headers_mut().remove(CONTENT_TYPE);
}
*request.body_mut() = body;
*content_type_state = if request.headers().contains_key(CONTENT_TYPE) {
ContentTypeState::Caller
} else {
ContentTypeState::Absent
};
if request.headers().contains_key(CONTENT_TYPE) {
return;
}
if let Some(content_type) = content_type {
request
.headers_mut()
.insert(CONTENT_TYPE, HeaderValue::from_static(content_type));
*content_type_state = ContentTypeState::Generated;
}
}
fn append_query(uri: &Uri, query: &str) -> Result<Uri> {
let separator = if uri.query().is_some() { '&' } else { '?' };
parse_target(&format!("{uri}{separator}{query}"))
}
fn parse_target(target: &str) -> Result<Uri> {
if target.is_empty() {
return Err(Error::request("request target is required"));
}
if target.contains('#') {
return Err(Error::request(
"request URL fragments are not sent to servers",
));
}
if target.starts_with('/') {
if target.starts_with("//") {
return Err(Error::request("request path is invalid"));
}
return target
.parse()
.map_err(|_| Error::request("request path is invalid"));
}
if let Ok(uri) = target.parse::<Uri>() {
crate::client::validate_absolute_uri(&uri)?;
return Ok(uri);
}
let url = Url::parse(target).map_err(|_| Error::request("request URL is invalid"))?;
validate_absolute_url(&url)?;
url.as_str()
.parse()
.map_err(|_| Error::request("request URL is invalid"))
}
pub(crate) fn validate_absolute_url(url: &Url) -> Result<()> {
if !matches!(url.scheme(), "http" | "https")
|| url.host_str().is_none()
|| !url.username().is_empty()
|| url.password().is_some()
|| url.fragment().is_some()
{
return Err(Error::request("request URL is invalid"));
}
Ok(())
}
#[cfg(test)]
mod tests {
use super::*;
#[derive(Serialize)]
struct User<'a> {
name: &'a str,
}
struct FailingValue;
impl Serialize for FailingValue {
fn serialize<S>(&self, _serializer: S) -> std::result::Result<S::Ok, S::Error>
where
S: serde::Serializer,
{
Err(serde::ser::Error::custom("deliberately not serializable"))
}
}
#[test]
fn accepts_only_unambiguous_targets() {
let client = Client::new().unwrap();
assert!(
client
.get("https://example.com/users?active=true")
.build()
.is_ok()
);
assert!(client.get("/users?active=true").build().is_ok());
for target in [
"users",
"//example.com/users",
"ftp://example.com/users",
"https://user:secret@example.com/users",
"https://example.com/users#profile",
] {
let result = client.get(target).build();
assert!(matches!(result, Err(error) if error.is_request()));
}
}
#[test]
fn request_builder_modifies_the_owned_request() {
let client = Client::new().unwrap();
let request = client
.post("https://example.com/users")
.header(CONTENT_TYPE, "application/custom")
.json(&User { name: "Ada" })
.append_header("x-mode", "first")
.append_header("x-mode", "second")
.header("x-mode", "replacement")
.form(&[("ignored", "because body is replaced")])
.body(Body::from("final"))
.build()
.unwrap();
assert_eq!(request.method(), Method::POST);
assert_eq!(
request.headers().get(CONTENT_TYPE).unwrap(),
"application/custom"
);
assert_eq!(request.headers().get_all("x-mode").iter().count(), 1);
assert_eq!(request.headers().get("x-mode").unwrap(), "replacement");
}
#[test]
fn generated_content_type_does_not_survive_a_raw_body() {
let client = Client::new().unwrap();
let request = client
.post("https://example.com/users")
.json(&User { name: "Ada" })
.body("raw")
.build()
.unwrap();
assert!(request.headers().get(CONTENT_TYPE).is_none());
}
#[test]
fn header_map_replaces_only_the_names_it_contains() {
let client = Client::new().unwrap();
let mut headers = HeaderMap::new();
headers.append("x-mode", HeaderValue::from_static("first"));
headers.append("x-mode", HeaderValue::from_static("second"));
let request = client
.post("https://example.com/users")
.header("x-mode", "old")
.header("x-untouched", "value")
.headers(headers)
.text("tez")
.build()
.unwrap();
assert_eq!(request.headers().get_all("x-mode").iter().count(), 2);
assert_eq!(request.headers()["x-untouched"], "value");
assert_eq!(request.headers()[CONTENT_TYPE], "text/plain; charset=utf-8");
}
#[test]
fn query_appends_parameters_and_retains_the_first_error() {
let client = Client::new().unwrap();
let request = client
.post("/users?existing=true")
.query(&[("tag", "one"), ("tag", "two")])
.json(&FailingValue)
.header("not a valid header name", "value")
.build();
let Err(error) = request else {
panic!("a failing JSON value unexpectedly built a request");
};
assert!(error.is_request());
assert!(error.to_string().contains("JSON"));
}
#[test]
fn zero_timeout_is_retained_without_echoing_the_request() {
let client = Client::new().unwrap();
let result = client
.get("https://example.com/users?token=secret")
.timeout(Duration::ZERO)
.header("not a valid header name", "secret")
.timeout(None)
.build();
let Err(error) = result else {
panic!("a zero timeout unexpectedly built a request");
};
assert!(error.is_request());
assert_eq!(
error.to_string(),
"request timeout must be greater than zero"
);
assert!(!format!("{error:?}").contains("secret"));
}
}