use crate::api::error::NetError;
#[cfg(feature = "http-client-cookies")]
use crate::api::http::cookies::CookieRequestContext;
#[cfg(feature = "http-client-codecs")]
use crate::api::http::multipart::Multipart;
#[cfg(feature = "http-client-codecs")]
use crate::api::http::request_codecs::{
append_query, encode_form, encode_json, encode_query, ensure_body_slot,
set_default_content_type, validate_multipart_header, BodyEncoding,
};
use crate::api::http::retry::HttpRetryPolicy;
use crate::api::http::{HttpAdmissionPolicy, HttpTimeouts};
use crate::api::retry::RetrySetting;
use bytes::Bytes;
use http::{HeaderMap, HeaderName, HeaderValue, Method};
#[derive(Clone)]
pub struct HttpRequest {
pub method: Method,
pub path: String,
pub headers: HeaderMap,
pub body: Bytes,
#[cfg(feature = "http-client-cookies")]
pub(crate) cookie_context: CookieRequestContext,
pub(crate) retry_setting: RetrySetting<HttpRetryPolicy>,
pub(crate) timeouts: HttpTimeouts,
admission_policy: Option<HttpAdmissionPolicy>,
}
impl std::fmt::Debug for HttpRequest {
fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
formatter
.debug_struct("HttpRequest")
.field("method", &self.method)
.field("path_bytes", &self.path.len())
.field("header_count", &self.headers.len())
.field("body_bytes", &self.body.len())
.field("retry_setting", &self.retry_setting)
.field("timeouts", &self.timeouts)
.field("admission_policy", &self.admission_policy)
.finish_non_exhaustive()
}
}
pub struct HttpRequestBuilder {
method: Result<Method, NetError>,
path: String,
headers: HeaderMap,
body: Bytes,
retry_setting: RetrySetting<HttpRetryPolicy>,
timeouts: HttpTimeouts,
admission_policy: Option<HttpAdmissionPolicy>,
#[cfg(feature = "http-client-cookies")]
cookie_context: CookieRequestContext,
#[cfg(feature = "http-client-codecs")]
body_configured: bool,
#[cfg(feature = "http-client-codecs")]
body_encoding: Option<BodyEncoding>,
#[cfg(feature = "http-client-codecs")]
body_conflict: bool,
#[cfg(feature = "http-client-codecs")]
multipart_content_type: Option<HeaderValue>,
#[cfg(feature = "http-client-codecs")]
query_parts: Vec<String>,
}
impl HttpRequest {
pub fn builder() -> HttpRequestBuilder {
HttpRequestBuilder {
method: Ok(Method::GET),
path: String::new(),
headers: HeaderMap::new(),
body: Bytes::new(),
retry_setting: RetrySetting::Inherit,
timeouts: HttpTimeouts::new(),
admission_policy: None,
#[cfg(feature = "http-client-cookies")]
cookie_context: CookieRequestContext::default(),
#[cfg(feature = "http-client-codecs")]
body_configured: false,
#[cfg(feature = "http-client-codecs")]
body_encoding: None,
#[cfg(feature = "http-client-codecs")]
body_conflict: false,
#[cfg(feature = "http-client-codecs")]
multipart_content_type: None,
#[cfg(feature = "http-client-codecs")]
query_parts: Vec::new(),
}
}
pub fn timeouts(&self) -> &HttpTimeouts {
&self.timeouts
}
pub fn admission_policy_override(&self) -> Option<HttpAdmissionPolicy> {
self.admission_policy
}
pub fn retry_setting(&self) -> RetrySetting<HttpRetryPolicy> {
self.retry_setting.clone()
}
}
impl HttpRequestBuilder {
pub fn admission_policy(mut self, policy: HttpAdmissionPolicy) -> Self {
self.admission_policy = Some(policy);
self
}
pub fn timeouts(mut self, timeouts: HttpTimeouts) -> Self {
self.timeouts = timeouts;
self
}
pub fn method(mut self, method: impl TryInto<Method>) -> Self {
self.method = method
.try_into()
.map_err(|_| NetError::input("method", "invalid HTTP method token"));
self
}
pub fn path(mut self, path: impl Into<String>) -> Self {
self.path = path.into();
#[cfg(feature = "http-client-codecs")]
for query in &self.query_parts {
append_query(&mut self.path, query);
}
self
}
pub fn headers(mut self, headers: HeaderMap) -> Self {
self.headers = headers;
self
}
pub fn body(mut self, body: Bytes) -> Self {
#[cfg(feature = "http-client-codecs")]
{
if self
.body_encoding
.is_some_and(|encoding| encoding != BodyEncoding::Raw)
{
self.body_conflict = true;
}
self.body_encoding = Some(BodyEncoding::Raw);
self.body_configured = true;
self.multipart_content_type = None;
}
self.body = body;
self
}
#[cfg(feature = "http-client-codecs")]
pub fn query<T: serde::Serialize>(mut self, value: &T) -> Result<Self, NetError> {
let encoded = encode_query(value)?;
append_query(&mut self.path, &encoded);
if !encoded.is_empty() {
self.query_parts.push(encoded);
}
Ok(self)
}
#[cfg(feature = "http-client-codecs")]
pub fn json<T: serde::Serialize>(mut self, value: &T) -> Result<Self, NetError> {
ensure_body_slot(self.body_encoding, BodyEncoding::Json)?;
if self.body_configured {
return Err(crate::api::error::NetError::input(
"body",
"a request body is already configured",
));
}
self.body = Bytes::from(encode_json(value)?);
set_default_content_type(&mut self.headers, "application/json")?;
self.body_configured = true;
self.body_encoding = Some(BodyEncoding::Json);
Ok(self)
}
#[cfg(feature = "http-client-codecs")]
pub fn form<T: serde::Serialize>(mut self, value: &T) -> Result<Self, NetError> {
ensure_body_slot(self.body_encoding, BodyEncoding::Form)?;
if self.body_configured {
return Err(crate::api::error::NetError::input(
"body",
"a request body is already configured",
));
}
self.body = Bytes::from(encode_form(value)?);
set_default_content_type(&mut self.headers, "application/x-www-form-urlencoded")?;
self.body_configured = true;
self.body_encoding = Some(BodyEncoding::Form);
Ok(self)
}
#[cfg(feature = "http-client-codecs")]
pub fn multipart(mut self, value: Multipart) -> Result<Self, NetError> {
ensure_body_slot(self.body_encoding, BodyEncoding::Multipart)?;
if self.body_configured || self.headers.contains_key(http::header::CONTENT_TYPE) {
return Err(crate::api::error::NetError::input(
"body",
"multipart requires an unused body and SDK-owned content-type",
));
}
let (body, content_type) = value.encode()?;
validate_multipart_header(&self.headers, &content_type)?;
self.body = body;
self.headers
.insert(http::header::CONTENT_TYPE, content_type.clone());
self.body_configured = true;
self.body_encoding = Some(BodyEncoding::Multipart);
self.multipart_content_type = Some(content_type);
Ok(self)
}
pub fn retry_setting(mut self, setting: RetrySetting<HttpRetryPolicy>) -> Self {
self.retry_setting = setting;
self
}
#[cfg(feature = "http-client-cookies")]
pub fn cookie_context(mut self, context: CookieRequestContext) -> Self {
self.cookie_context = context;
self
}
pub fn header(
mut self,
name: impl TryInto<HeaderName>,
value: impl TryInto<HeaderValue>,
) -> Result<Self, NetError> {
let name = name
.try_into()
.map_err(|_| NetError::input("header", "invalid name"))?;
let value = value
.try_into()
.map_err(|_| NetError::input("header", "invalid value"))?;
#[cfg(feature = "http-client-codecs")]
if name == http::header::CONTENT_TYPE {
if let Some(expected) = &self.multipart_content_type {
if value != expected {
return Err(NetError::input(
"content-type",
"multipart content-type is managed by the SDK",
));
}
}
}
self.headers.insert(name, value);
Ok(self)
}
pub fn build(self) -> Result<HttpRequest, NetError> {
let method = self.method?;
self.timeouts.validate_request()?;
if self.path.is_empty() {
return Err(NetError::input("path", "path must not be empty"));
}
#[cfg(feature = "http-client-codecs")]
{
if self.body_conflict {
return Err(NetError::input(
"body",
"raw body and a typed body codec cannot be combined",
));
}
if let Some(expected) = &self.multipart_content_type {
if self.headers.get(http::header::CONTENT_TYPE) != Some(expected) {
return Err(NetError::input(
"content-type",
"multipart content-type is managed by the SDK",
));
}
}
}
Ok(HttpRequest {
method,
path: self.path,
headers: self.headers,
body: self.body,
retry_setting: self.retry_setting,
timeouts: self.timeouts,
admission_policy: self.admission_policy,
#[cfg(feature = "http-client-cookies")]
cookie_context: self.cookie_context,
})
}
}
#[cfg(test)]
mod method_builder_tests {
use super::*;
use crate::api::error::{ErrorKind, ErrorStage};
use crate::api::http::HttpRequestMethod;
#[test]
fn builder_rejects_invalid_methods_without_panicking_or_exposing_input() {
for token in ["", "BAD METHOD", "GET\r\nsecret", "GÉT", "GET/", "GET\0"] {
let method = HttpRequestMethod::Extension(token.to_owned());
for result in [
HttpRequest::builder().method(&method).path("/").build(),
HttpRequest::builder().method(method).path("/").build(),
HttpRequest::builder().method(token).path("/").build(),
] {
let error = result.expect_err("invalid methods cannot build a request");
assert_eq!(error.kind(), ErrorKind::InvalidInput);
assert_eq!(error.context().stage, Some(ErrorStage::RequestBuild));
let detail = error.config_error().expect("method error details");
assert_eq!(detail.field(), "method");
assert_eq!(detail.reason(), "invalid HTTP method token");
assert!(!format!("{error} {error:?}").contains("secret"));
}
}
}
#[test]
fn builder_preserves_valid_method_and_allows_replacing_invalid_method() -> Result<(), NetError>
{
for token in [
"GET",
"POST",
"QUERY",
"CUSTOM",
"custom",
"CuStOm",
"X!#$%&'*+-.^_`|~",
] {
let method = HttpRequestMethod::Extension(token.to_owned());
let request = HttpRequest::builder().method(method).path("/").build()?;
assert_eq!(request.method.as_str(), token);
}
let request = HttpRequest::builder()
.method(HttpRequestMethod::Extension("BAD METHOD".to_owned()))
.method(HttpRequestMethod::PATCH)
.path("/")
.build()?;
assert_eq!(request.method, Method::PATCH);
Ok(())
}
}
#[cfg(test)]
mod admission_tests {
use super::*;
use crate::api::http::HttpAdmissionPolicy;
type TestResult = Result<(), Box<dyn std::error::Error + Send + Sync>>;
fn check(condition: bool, message: &str) -> TestResult {
if condition {
Ok(())
} else {
Err(std::io::Error::other(message).into())
}
}
#[test]
fn request_admission_defaults_to_client_inheritance() -> TestResult {
let request = HttpRequest::builder().path("/").build()?;
check(
request.admission_policy_override().is_none(),
"new requests must inherit their client's admission policy",
)
}
#[test]
fn request_admission_override_survives_build_clone_and_debug() -> TestResult {
for policy in [HttpAdmissionPolicy::Wait, HttpAdmissionPolicy::FailFast] {
let request = HttpRequest::builder()
.path("/")
.admission_policy(policy)
.build()?;
let cloned = request.clone();
check(
request.admission_policy_override() == Some(policy)
&& cloned.admission_policy_override() == Some(policy),
"build and clone must retain explicit admission policy overrides",
)?;
let debug = format!("{cloned:?}");
check(
debug.contains("admission_policy") && debug.contains(&format!("{policy:?}")),
"request debug must include its non-sensitive admission configuration",
)?;
}
Ok(())
}
#[test]
fn last_request_admission_override_wins() -> TestResult {
let request = HttpRequest::builder()
.path("/")
.admission_policy(HttpAdmissionPolicy::FailFast)
.admission_policy(HttpAdmissionPolicy::Wait)
.build()?;
check(
request.admission_policy_override() == Some(HttpAdmissionPolicy::Wait),
"the last explicit request admission policy must win",
)
}
}
#[cfg(test)]
#[cfg(feature = "http-client-codecs")]
mod codec_builder_tests {
use super::*;
use bytes::Bytes;
use serde::Serialize;
#[derive(Serialize)]
struct QueryPart {
key: &'static str,
}
#[derive(Serialize)]
struct FormValue {
value: &'static str,
}
#[test]
fn repeated_query_values_survive_path_reset() {
let request = HttpRequest::builder()
.path("/first?fixed=1")
.query(&QueryPart { key: "one" })
.unwrap()
.query(&QueryPart { key: "two" })
.unwrap()
.path("/second?reset=1")
.build()
.unwrap();
assert_eq!(
request.path, "/second?reset=1&key=one&key=two",
"path() must preserve previously appended query parts"
);
}
#[test]
fn form_keeps_a_caller_supplied_content_type() {
let request = HttpRequest::builder()
.path("/form")
.header("content-type", "application/vnd.example.form")
.unwrap()
.form(&FormValue { value: "demo" })
.unwrap()
.build()
.unwrap();
assert_eq!(
request.headers.get(http::header::CONTENT_TYPE).unwrap(),
"application/vnd.example.form"
);
}
#[test]
fn reverse_raw_and_typed_body_combinations_are_rejected_at_build() {
let json_then_raw = HttpRequest::builder()
.path("/body")
.json(&serde_json::json!({"ok": true}))
.unwrap()
.body(Bytes::from_static(b"raw"))
.build();
assert!(json_then_raw.is_err());
let raw_then_json = HttpRequest::builder()
.path("/body")
.body(Bytes::from_static(b"raw"))
.json(&serde_json::json!({"ok": true}));
assert!(raw_then_json.is_err());
let multipart_then_header = HttpRequest::builder()
.path("/multipart")
.multipart(
crate::api::http::Multipart::new()
.text("field", "value")
.unwrap(),
)
.unwrap()
.header("content-type", "multipart/form-data; boundary=user")
.and_then(|builder| builder.build());
assert!(multipart_then_header.is_err());
}
}