1use std::sync::Arc;
4
5use bytes::Bytes;
6use http::Version;
7
8use crate::body::RequestBody;
9use crate::client::Client;
10use crate::error::Result;
11use crate::headers::Headers;
12use crate::redirect::RedirectPolicy;
13use crate::response::Response;
14use crate::retry::RetryPolicy;
15use crate::timeout::Timeout;
16use crate::trace::TraceObserver;
17
18use crate::auth::AuthScheme;
19#[cfg(feature = "proxy")]
20use crate::proxy::ProxyConfig;
21
22#[derive(Default, Clone)]
31pub struct TransportHints {
32 pub target: Option<Bytes>,
38 pub sni_hostname: Option<String>,
43 pub trace: Option<Arc<dyn TraceObserver>>,
50}
51
52impl std::fmt::Debug for TransportHints {
53 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
54 f.debug_struct("TransportHints")
55 .field("target", &self.target)
56 .field("sni_hostname", &self.sni_hostname)
57 .field("trace", &self.trace.as_ref().map(|_| "..."))
58 .finish()
59 }
60}
61
62#[derive(Debug, Clone, Default)]
67#[allow(
68 clippy::large_enum_variant,
69 reason = "ProxyConfig is transient and cloning it is cheap; boxing adds unnecessary allocation"
70)]
71pub enum ProxyOverride {
72 #[default]
74 Inherit,
75 Direct,
77 #[cfg(feature = "proxy")]
79 Override(ProxyConfig),
80}
81
82pub(crate) struct RequestParts {
89 pub(crate) method: http::Method,
90 pub(crate) url: url::Url,
91 pub(crate) headers: Headers,
92 pub(crate) body: RequestBody,
93 pub(crate) version: Version,
94 pub(crate) timeout: Option<Timeout>,
95 pub(crate) redirect: Option<RedirectPolicy>,
96 pub(crate) auth: Option<AuthScheme>,
97 pub(crate) auth_disabled: bool,
98 pub(crate) decompress: Option<bool>,
99 pub(crate) proxy_override: ProxyOverride,
100 pub(crate) retry: Option<RetryPolicy>,
101 pub(crate) transport_hints: TransportHints,
102}
103
104impl RequestParts {
105 #[allow(
112 dead_code,
113 reason = "exhaustiveness anchor for RequestParts: guarantees new fields fail to compile even though live code uses retry_request"
114 )]
115 pub(crate) fn into_request(self) -> Request {
116 let RequestParts {
117 method,
118 url,
119 headers,
120 body,
121 version,
122 timeout,
123 redirect,
124 auth,
125 auth_disabled,
126 decompress,
127 proxy_override,
128 retry,
129 transport_hints,
130 } = self;
131 let mut request = Request::new(method, url);
132 *request.headers_mut() = headers;
133 request.set_body(body);
134 request.set_version(version);
135 request.set_timeout(timeout);
136 request.set_redirect(redirect);
137 request.set_auth(auth);
138 request.set_auth_disabled(auth_disabled);
139 request.set_decompress(decompress);
140 #[cfg(feature = "proxy")]
141 request.set_proxy_override(proxy_override);
142 #[cfg(not(feature = "proxy"))]
143 let _ = proxy_override;
144 request.set_retry(retry);
145 request.set_transport_hints(transport_hints);
146 request
147 }
148
149 pub(crate) fn retry_request(
163 &self,
164 attempt_timeout: Option<Timeout>,
165 ) -> crate::error::Result<Request> {
166 let replayed = self.body.try_clone_for_retry()?;
167 let mut request = Request::new(self.method.clone(), self.url.clone());
168 *request.headers_mut() = self.headers.clone();
169 request.set_body(replayed);
170 request.set_version(self.version);
171 request.set_timeout(attempt_timeout);
172 request.set_redirect(self.redirect.clone());
173 request.set_auth(self.auth.clone());
174 request.set_auth_disabled(self.auth_disabled);
175 request.set_decompress(self.decompress);
176 #[cfg(feature = "proxy")]
177 request.set_proxy_override(self.proxy_override.clone());
178 request.set_retry(self.retry.clone());
179 request.set_transport_hints(self.transport_hints.clone());
180 Ok(request)
181 }
182
183 pub(crate) fn shrink_total_deadline(
189 timeout: &Timeout,
190 elapsed: std::time::Duration,
191 ) -> Timeout {
192 let mut out = *timeout;
193 if let Some(total) = out.total {
194 out.total = Some(total.saturating_sub(elapsed));
195 }
196 out
197 }
198}
199
200pub struct Request {
209 method: http::Method,
210 url: url::Url,
211 headers: Headers,
212 body: RequestBody,
213 version: Version,
214 timeout: Option<Timeout>,
215 redirect: Option<RedirectPolicy>,
216 auth: Option<AuthScheme>,
217 auth_disabled: bool,
218 decompress: Option<bool>,
219 proxy_override: ProxyOverride,
221 retry: Option<RetryPolicy>,
223 transport_hints: TransportHints,
225}
226
227impl std::fmt::Debug for Request {
228 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
229 f.debug_struct("Request")
230 .field("method", &self.method)
231 .field("url", &crate::redact::redact_url(&self.url))
232 .field("headers", &self.headers)
233 .field("body", &self.body)
234 .field("version", &self.version)
235 .field("timeout", &self.timeout)
236 .field("redirect", &self.redirect)
237 .field("auth", &self.auth)
238 .field("auth_disabled", &self.auth_disabled)
239 .field("decompress", &self.decompress)
240 .field("proxy_override", &self.proxy_override)
241 .field("retry", &self.retry)
242 .field("transport_hints", &self.transport_hints)
243 .finish()
244 }
245}
246
247impl Request {
248 pub(crate) fn new(method: http::Method, url: url::Url) -> Self {
250 Self {
251 method,
252 url,
253 headers: Headers::new(),
254 body: RequestBody::default(),
255 version: Version::HTTP_11,
256 timeout: None,
257 redirect: None,
258 auth: None,
259 auth_disabled: false,
260 decompress: None,
261 proxy_override: ProxyOverride::Inherit,
262 retry: None,
263 transport_hints: TransportHints::default(),
264 }
265 }
266
267 #[must_use]
269 pub fn method(&self) -> &http::Method {
270 &self.method
271 }
272
273 #[must_use]
275 pub fn url(&self) -> &url::Url {
276 &self.url
277 }
278
279 #[must_use]
281 pub fn headers(&self) -> &Headers {
282 &self.headers
283 }
284
285 pub fn headers_mut(&mut self) -> &mut Headers {
287 &mut self.headers
288 }
289
290 #[must_use]
292 pub fn body(&self) -> &RequestBody {
293 &self.body
294 }
295
296 pub fn set_body(&mut self, body: RequestBody) {
298 self.body = body;
299 }
300
301 #[must_use]
303 pub fn version(&self) -> Version {
304 self.version
305 }
306
307 pub fn set_version(&mut self, version: Version) {
309 self.version = version;
310 }
311
312 #[must_use]
314 pub fn timeout(&self) -> Option<&Timeout> {
315 self.timeout.as_ref()
316 }
317
318 pub fn set_timeout(&mut self, timeout: Option<Timeout>) {
320 self.timeout = timeout;
321 }
322
323 #[must_use]
325 pub fn redirect(&self) -> Option<&RedirectPolicy> {
326 self.redirect.as_ref()
327 }
328
329 pub fn set_redirect(&mut self, redirect: Option<RedirectPolicy>) {
331 self.redirect = redirect;
332 }
333
334 #[must_use]
336 pub fn auth(&self) -> Option<&AuthScheme> {
337 self.auth.as_ref()
338 }
339
340 pub fn set_auth(&mut self, auth: Option<AuthScheme>) {
342 self.auth = auth;
343 }
344
345 #[must_use]
347 pub fn is_auth_disabled(&self) -> bool {
348 self.auth_disabled
349 }
350
351 pub fn set_auth_disabled(&mut self, disabled: bool) {
353 self.auth_disabled = disabled;
354 }
355
356 #[must_use]
362 pub fn decompress(&self) -> Option<bool> {
363 self.decompress
364 }
365
366 pub fn set_decompress(&mut self, decompress: Option<bool>) {
368 self.decompress = decompress;
369 }
370
371 #[cfg(feature = "proxy")]
373 #[must_use]
374 pub fn proxy_override(&self) -> &ProxyOverride {
375 &self.proxy_override
376 }
377
378 #[cfg(feature = "proxy")]
380 pub fn set_proxy_override(&mut self, proxy: ProxyOverride) {
381 self.proxy_override = proxy;
382 }
383
384 #[must_use]
386 pub fn retry(&self) -> Option<&RetryPolicy> {
387 self.retry.as_ref()
388 }
389
390 pub fn set_retry(&mut self, retry: Option<RetryPolicy>) {
392 self.retry = retry;
393 }
394
395 #[must_use]
397 pub fn transport_hints(&self) -> &TransportHints {
398 &self.transport_hints
399 }
400
401 pub fn set_transport_hints(&mut self, hints: TransportHints) {
403 self.transport_hints = hints;
404 }
405
406 pub(crate) fn into_parts(self) -> RequestParts {
410 RequestParts {
411 method: self.method,
412 url: self.url,
413 headers: self.headers,
414 body: self.body,
415 version: self.version,
416 timeout: self.timeout,
417 redirect: self.redirect,
418 auth: self.auth,
419 auth_disabled: self.auth_disabled,
420 decompress: self.decompress,
421 proxy_override: self.proxy_override,
422 retry: self.retry,
423 transport_hints: self.transport_hints,
424 }
425 }
426}
427
428pub struct RequestBuilder {
430 client: Option<Client>,
431 method: http::Method,
432 url: url::Url,
433 headers: Headers,
434 body: RequestBody,
435 timeout: Option<Timeout>,
436 redirect: Option<RedirectPolicy>,
437 auth: Option<AuthScheme>,
438 auth_disabled: bool,
439 decompress: Option<bool>,
440 proxy_override: ProxyOverride,
441 retry: Option<RetryPolicy>,
442 transport_hints: TransportHints,
443 error: Option<crate::Error>,
444}
445
446impl RequestBuilder {
447 pub(crate) fn new(client: Client, method: http::Method, url: url::Url) -> Self {
449 Self {
450 client: Some(client),
451 method,
452 url,
453 headers: Headers::new(),
454 body: RequestBody::default(),
455 timeout: None,
456 redirect: None,
457 auth: None,
458 auth_disabled: false,
459 decompress: None,
460 proxy_override: ProxyOverride::Inherit,
461 retry: None,
462 transport_hints: TransportHints::default(),
463 error: None,
464 }
465 }
466
467 #[must_use]
469 pub fn header(mut self, name: &str, value: &str) -> Self {
470 if let Err(e) = self.headers.insert(name, value) {
471 if self.error.is_none() {
472 self.error = Some(e);
473 }
474 }
475 self
476 }
477
478 #[must_use]
480 pub fn headers(mut self, headers: Headers) -> Self {
481 self.headers = headers;
482 self
483 }
484
485 #[must_use]
487 pub fn query(mut self, key: &str, value: &str) -> Self {
488 self.url.query_pairs_mut().append_pair(key, value);
489 self
490 }
491
492 #[must_use]
494 pub fn body(mut self, body: impl Into<RequestBody>) -> Self {
495 self.body = body.into();
496 self
497 }
498
499 #[must_use]
501 pub fn bytes(self, data: impl Into<Bytes>) -> Self {
502 self.body(RequestBody::Bytes(data.into()))
503 }
504
505 #[must_use]
511 pub fn timeout(mut self, timeout: Timeout) -> Self {
512 self.timeout = Some(timeout);
513 self
514 }
515
516 #[must_use]
521 pub fn redirect_policy(mut self, policy: RedirectPolicy) -> Self {
522 self.redirect = Some(policy);
523 self
524 }
525
526 #[must_use]
530 pub fn auth(mut self, auth: impl Into<AuthScheme>) -> Self {
531 self.auth = Some(auth.into());
532 self.auth_disabled = false;
533 self
534 }
535
536 #[must_use]
541 pub fn without_auth(mut self) -> Self {
542 self.auth_disabled = true;
543 self.auth = None;
544 self
545 }
546
547 #[cfg(feature = "proxy")]
551 #[must_use]
552 pub fn proxy(mut self, proxy: &crate::proxy::Proxy) -> Self {
553 self.proxy_override = ProxyOverride::Override(proxy.config());
554 self
555 }
556
557 #[cfg(feature = "proxy")]
562 #[must_use]
563 pub fn without_proxy(mut self) -> Self {
564 self.proxy_override = ProxyOverride::Direct;
565 self
566 }
567
568 #[must_use]
573 pub fn decompress(mut self, decompress: bool) -> Self {
574 self.decompress = Some(decompress);
575 self
576 }
577
578 #[must_use]
583 pub fn retry(mut self, policy: RetryPolicy) -> Self {
584 self.retry = Some(policy);
585 self
586 }
587
588 #[must_use]
591 pub fn without_retry(mut self) -> Self {
592 self.retry = Some(RetryPolicy::default());
593 self
594 }
595
596 #[must_use]
601 pub fn transport_hints(mut self, hints: TransportHints) -> Self {
602 self.transport_hints = hints;
603 self
604 }
605
606 pub fn build(mut self) -> Result<Request> {
613 if let Some(e) = self.error.take() {
614 return Err(e);
615 }
616 let request_target = self
617 .transport_hints
618 .target
619 .as_deref()
620 .unwrap_or_else(|| self.url.as_str().as_bytes());
621 self.headers
622 .validate_request_size(&self.method, request_target)?;
623 let mut req = Request::new(self.method, self.url);
624 req.headers = self.headers;
625 req.body = self.body;
626 req.timeout = self.timeout;
627 req.redirect = self.redirect;
628 req.auth = self.auth;
629 req.auth_disabled = self.auth_disabled;
630 req.decompress = self.decompress;
631 req.proxy_override = self.proxy_override;
632 req.retry = self.retry;
633 req.transport_hints = self.transport_hints;
634 Ok(req)
635 }
636
637 pub async fn send(self) -> Result<Response> {
643 let client = self.client.clone().ok_or_else(|| {
644 crate::Error::RequestBuild("no client associated with request builder".into())
645 })?;
646 let request = self.build()?;
647 Box::pin(client.send(request)).await
648 }
649}
650
651#[cfg(test)]
652mod tests {
653 use proptest::prelude::*;
654
655 use super::Request;
656 use crate::auth::{AuthScheme, BasicAuth};
657 use bytes::Bytes;
658
659 proptest::proptest! {
660 #[test]
661 fn url_parse_round_trip(scheme in "https?", host in "[a-z]{2,10}\\.[a-z]{2,5}", path in "/[a-z]{0,20}") {
662 let url_str = format!("{scheme}://{host}{path}");
663 let parsed = url::Url::parse(&url_str).unwrap();
664 let serialized = parsed.to_string();
665 prop_assert_eq!(url_str, serialized);
666 }
667
668 #[test]
669 fn query_pairs_round_trip(key in "[a-z]{1,10}", value in "[a-z0-9]{1,20}") {
670 let mut url = url::Url::parse("http://example.com/").unwrap();
671 url.query_pairs_mut().append_pair(&key, &value);
672 let found = url.query_pairs().find(|(k, _)| k == &key).map(|(_, v)| v.into_owned());
673 prop_assert_eq!(found, Some(value));
674 }
675
676 #[test]
677 fn url_with_arbitrary_path(path in "/[a-zA-Z0-9._/-]{0,50}") {
678 let url_str = format!("http://example.com{path}");
679 let _ = url::Url::parse(&url_str);
681 }
682 }
683
684 #[test]
685 fn request_debug_redacts_secrets() {
686 let url = url::Url::parse("https://example.com/submit?api_key=top-secret-key").unwrap();
687 let mut req = Request::new(http::Method::POST, url);
688 req.headers_mut()
689 .insert("authorization", "Bearer bearer-secret-token")
690 .unwrap();
691 req.headers_mut()
692 .insert("cookie", "session=cookie-secret")
693 .unwrap();
694 req.set_body(crate::body::RequestBody::Bytes(Bytes::from(
695 "password=form-secret",
696 )));
697 req.set_auth(Some(AuthScheme::Basic(
698 BasicAuth::new("user", "auth-secret").unwrap(),
699 )));
700 let debug = format!("{req:?}");
701 for leaked in [
702 "top-secret-key",
703 "bearer-secret-token",
704 "cookie-secret",
705 "form-secret",
706 "auth-secret",
707 ] {
708 assert!(
709 !debug.contains(leaked),
710 "Request Debug must not leak {leaked:?}: {debug}"
711 );
712 }
713 assert!(debug.contains("example.com"), "keeps the host: {debug}");
715 assert!(debug.contains("POST"), "keeps the method: {debug}");
716 }
717}