Skip to main content

eggfetch_core/
request.rs

1//! Request types and builder.
2
3use 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/// Typed transport-level hints carried on a request.
23///
24/// These are *not* HTTP headers and do not affect logical URL semantics
25/// (routing, cookies, auth-origin comparisons, redirects, proxy selection).
26/// They control only the wire-level behavior of the transport layer.
27///
28/// Timeout is kept in the existing [`Timeout`] model and must not be
29/// duplicated here.
30#[derive(Default, Clone)]
31pub struct TransportHints {
32    /// Override the wire request target (e.g. `OPTIONS *`, absolute-form).
33    ///
34    /// When present this replaces only the URI sent on the wire; the
35    /// logical URL used for connection routing, Host header defaults,
36    /// cookies, auth, redirects, and proxy selection remains unchanged.
37    pub target: Option<Bytes>,
38    /// Override the TLS Server Name Indication hostname.
39    ///
40    /// TCP connects to the URL host/IP; TLS uses this name for SNI and
41    /// certificate verification.
42    pub sni_hostname: Option<String>,
43    /// Optional trace observer for transport lifecycle events.
44    ///
45    /// When present, the transport layer emits typed events at each
46    /// lifecycle boundary (TCP connect, TLS handshake, request/response
47    /// headers, body chunks, connection close). The observer is invoked
48    /// synchronously within the async context and must not block.
49    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/// Proxy override for a specific request.
63///
64/// Controls whether a request inherits the client-level proxy,
65/// bypasses the proxy entirely, or uses a specific proxy configuration.
66#[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    /// Inherit the client-level proxy configuration (default).
73    #[default]
74    Inherit,
75    /// Send the request directly, bypassing any client proxy.
76    Direct,
77    /// Use a specific proxy configuration for this request.
78    #[cfg(feature = "proxy")]
79    Override(ProxyConfig),
80}
81
82/// Parts returned by [`Request::into_parts`].
83///
84/// This is the complete logical-request state carried across retry and
85/// redirect policy transformations. All reconstruction goes through the
86/// typed helpers below so a newly added field fails to compile (via
87/// exhaustive construction) rather than being silently dropped.
88pub(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    /// Reassemble the parts into a [`Request`] without body replay.
106    ///
107    /// Exhaustively constructs the request so adding a field to
108    /// [`RequestParts`] without updating this path is a compile error.
109    /// Used by regression tests as the canonical round-trip anchor; the
110    /// live retry path uses [`Self::retry_request`] with a shrunk deadline.
111    #[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    /// Build the retry attempt for the same logical request.
150    ///
151    /// Preserves every request-local override that remains valid for
152    /// another attempt (including transport hints, proxy/decompression
153    /// overrides, auth-disable state, redirect and retry policy) while
154    /// applying the shrunk `attempt_timeout` for the remaining total
155    /// deadline. Non-replayable stream bodies return the existing
156    /// [`crate::error::Error::BodyNotReplayableForRetry`] classification.
157    ///
158    /// # Errors
159    ///
160    /// Returns [`crate::error::Error::BodyNotReplayableForRetry`] when the
161    /// saved body is a one-shot stream.
162    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    /// Apply a shrunk total deadline to a timeout value.
184    ///
185    /// Returns the timeout with `total` replaced by `total - elapsed`
186    /// (saturating). Used by both retry and redirect loops so the original
187    /// total deadline shrinks rather than restarting on each attempt/hop.
188    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
200/// An outgoing HTTP request.
201///
202/// # Security
203///
204/// The `Debug` implementation redacts secrets: the URL is rendered without
205/// userinfo, query parameters, or fragments (query strings routinely carry
206/// API keys), sensitive headers use the redacted form, and the body is
207/// summarized by length only. See [`crate::redact`].
208pub 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: `None` = inherit, `Some(None)` = direct, `Some(Some(c))` = explicit.
220    proxy_override: ProxyOverride,
221    /// Per-request retry policy override.
222    retry: Option<RetryPolicy>,
223    /// Typed transport-level hints (target override, SNI hostname, etc.).
224    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    /// Create a new request (crate-internal).
249    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    /// Returns the HTTP method.
268    #[must_use]
269    pub fn method(&self) -> &http::Method {
270        &self.method
271    }
272
273    /// Returns the request URL.
274    #[must_use]
275    pub fn url(&self) -> &url::Url {
276        &self.url
277    }
278
279    /// Returns a reference to the request headers.
280    #[must_use]
281    pub fn headers(&self) -> &Headers {
282        &self.headers
283    }
284
285    /// Returns a mutable reference to the request headers.
286    pub fn headers_mut(&mut self) -> &mut Headers {
287        &mut self.headers
288    }
289
290    /// Returns the request body.
291    #[must_use]
292    pub fn body(&self) -> &RequestBody {
293        &self.body
294    }
295
296    /// Set the request body.
297    pub fn set_body(&mut self, body: RequestBody) {
298        self.body = body;
299    }
300
301    /// Returns the HTTP version.
302    #[must_use]
303    pub fn version(&self) -> Version {
304        self.version
305    }
306
307    /// Set the HTTP version.
308    pub fn set_version(&mut self, version: Version) {
309        self.version = version;
310    }
311
312    /// Returns the request timeout configuration, if set.
313    #[must_use]
314    pub fn timeout(&self) -> Option<&Timeout> {
315        self.timeout.as_ref()
316    }
317
318    /// Set the request-level timeout.
319    pub fn set_timeout(&mut self, timeout: Option<Timeout>) {
320        self.timeout = timeout;
321    }
322
323    /// Returns the request-level redirect policy override, if set.
324    #[must_use]
325    pub fn redirect(&self) -> Option<&RedirectPolicy> {
326        self.redirect.as_ref()
327    }
328
329    /// Set the request-level redirect policy override.
330    pub fn set_redirect(&mut self, redirect: Option<RedirectPolicy>) {
331        self.redirect = redirect;
332    }
333
334    /// Returns a reference to the request-level auth override, if set.
335    #[must_use]
336    pub fn auth(&self) -> Option<&AuthScheme> {
337        self.auth.as_ref()
338    }
339
340    /// Set the request-level auth override.
341    pub fn set_auth(&mut self, auth: Option<AuthScheme>) {
342        self.auth = auth;
343    }
344
345    /// Returns whether auth has been explicitly disabled for this request.
346    #[must_use]
347    pub fn is_auth_disabled(&self) -> bool {
348        self.auth_disabled
349    }
350
351    /// Mark this request as having auth explicitly disabled.
352    pub fn set_auth_disabled(&mut self, disabled: bool) {
353        self.auth_disabled = disabled;
354    }
355
356    /// Returns the per-request decompression override, if set.
357    ///
358    /// - `Some(true)`: force decompression on
359    /// - `Some(false)`: force decompression off
360    /// - `None`: use client-level setting
361    #[must_use]
362    pub fn decompress(&self) -> Option<bool> {
363        self.decompress
364    }
365
366    /// Set the per-request decompression override.
367    pub fn set_decompress(&mut self, decompress: Option<bool>) {
368        self.decompress = decompress;
369    }
370
371    /// Returns the proxy override for this request.
372    #[cfg(feature = "proxy")]
373    #[must_use]
374    pub fn proxy_override(&self) -> &ProxyOverride {
375        &self.proxy_override
376    }
377
378    /// Set the per-request proxy override.
379    #[cfg(feature = "proxy")]
380    pub fn set_proxy_override(&mut self, proxy: ProxyOverride) {
381        self.proxy_override = proxy;
382    }
383
384    /// Returns the per-request retry policy override, if set.
385    #[must_use]
386    pub fn retry(&self) -> Option<&RetryPolicy> {
387        self.retry.as_ref()
388    }
389
390    /// Set the per-request retry policy override.
391    pub fn set_retry(&mut self, retry: Option<RetryPolicy>) {
392        self.retry = retry;
393    }
394
395    /// Returns a reference to the transport hints for this request.
396    #[must_use]
397    pub fn transport_hints(&self) -> &TransportHints {
398        &self.transport_hints
399    }
400
401    /// Set the transport hints for this request.
402    pub fn set_transport_hints(&mut self, hints: TransportHints) {
403        self.transport_hints = hints;
404    }
405
406    /// Decompose a request into its parts.
407    ///
408    /// Returns the request fields as named parts.
409    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
428/// Fluent builder for constructing requests.
429pub 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    /// Create a new request builder associated with a client.
448    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    /// Add a single header to the request.
468    #[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    /// Replace all headers with the provided set.
479    #[must_use]
480    pub fn headers(mut self, headers: Headers) -> Self {
481        self.headers = headers;
482        self
483    }
484
485    /// Append a query parameter to the URL.
486    #[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    /// Set the request body from any type that converts into `RequestBody`.
493    #[must_use]
494    pub fn body(mut self, body: impl Into<RequestBody>) -> Self {
495        self.body = body.into();
496        self
497    }
498
499    /// Set the request body from bytes.
500    #[must_use]
501    pub fn bytes(self, data: impl Into<Bytes>) -> Self {
502        self.body(RequestBody::Bytes(data.into()))
503    }
504
505    /// Set the timeout for this specific request.
506    ///
507    /// When set, this overrides the client-level timeout on a per-field
508    /// basis: only fields present here replace the corresponding
509    /// client-level fields.
510    #[must_use]
511    pub fn timeout(mut self, timeout: Timeout) -> Self {
512        self.timeout = Some(timeout);
513        self
514    }
515
516    /// Override the redirect policy for this specific request.
517    ///
518    /// When set, this overrides the client-level redirect policy for
519    /// this request only.
520    #[must_use]
521    pub fn redirect_policy(mut self, policy: RedirectPolicy) -> Self {
522        self.redirect = Some(policy);
523        self
524    }
525
526    /// Set authentication for this specific request.
527    ///
528    /// Overrides client-level auth.
529    #[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    /// Disable authentication for this specific request.
537    ///
538    /// When set, no auth is applied to this request even if the client
539    /// has a default auth configured.
540    #[must_use]
541    pub fn without_auth(mut self) -> Self {
542        self.auth_disabled = true;
543        self.auth = None;
544        self
545    }
546
547    /// Override the proxy for this specific request.
548    ///
549    /// When set, this proxy is used instead of the client-level proxy.
550    #[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    /// Disable proxy for this specific request.
558    ///
559    /// When set, the request is sent directly without going through
560    /// any proxy, even if the client has a default proxy configured.
561    #[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    /// Override decompression for this specific request.
569    ///
570    /// - `true`: enable decompression regardless of client setting
571    /// - `false`: disable decompression regardless of client setting
572    #[must_use]
573    pub fn decompress(mut self, decompress: bool) -> Self {
574        self.decompress = Some(decompress);
575        self
576    }
577
578    /// Override the retry policy for this specific request.
579    ///
580    /// When set, this overrides the client-level retry policy for
581    /// this request only.
582    #[must_use]
583    pub fn retry(mut self, policy: RetryPolicy) -> Self {
584        self.retry = Some(policy);
585        self
586    }
587
588    /// Disable retries for this specific request, even if the client
589    /// has a retry policy configured.
590    #[must_use]
591    pub fn without_retry(mut self) -> Self {
592        self.retry = Some(RetryPolicy::default());
593        self
594    }
595
596    /// Set the transport hints for this request.
597    ///
598    /// Transport hints control wire-level behavior (target override,
599    /// SNI hostname) without affecting logical URL semantics.
600    #[must_use]
601    pub fn transport_hints(mut self, hints: TransportHints) -> Self {
602        self.transport_hints = hints;
603        self
604    }
605
606    /// Build the request without sending it.
607    ///
608    /// # Errors
609    ///
610    /// Returns an error if a previous builder step failed (e.g., invalid
611    /// header).
612    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    /// Build and send the request.
638    ///
639    /// # Errors
640    ///
641    /// Returns an error if the request could not be built or sent.
642    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            // Must not panic
680            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        // Non-secret structure is still visible for diagnostics.
714        assert!(debug.contains("example.com"), "keeps the host: {debug}");
715        assert!(debug.contains("POST"), "keeps the method: {debug}");
716    }
717}