tez 0.0.3

A lightweight, ergonomic, and fast high-level HTTP client for Rust
Documentation
//! One logical request from preparation through its final response.

use std::{
    sync::Arc,
    time::{Duration, Instant},
};

use crate::{
    Error, Request, Response, Result,
    auth::Authentication,
    client::{ClientInner, merge_default_headers, resolve_target, validate_framing},
    redirect::{Decision, RequestChain},
    request::resolve_timeout,
    retry::{self, Plan, RepeatableRequest},
    runtime::Deadline,
};
#[cfg(feature = "cookies")]
use http::header::COOKIE;
use http::{
    Method, StatusCode,
    header::{ACCEPT_ENCODING, PROXY_AUTHORIZATION, RANGE, UPGRADE},
};

/// Sends one logical request through client policy and one or more wire attempts.
pub(crate) async fn send(client: &ClientInner, request: Request) -> Result<Response> {
    let timeout = resolve_timeout(&request, client.timeouts.total_timeout());
    Dispatch {
        client,
        started: Instant::now(),
        timeout,
    }
    .send(request)
    .await
}

struct Dispatch<'client> {
    client: &'client ClientInner,
    started: Instant,
    timeout: Option<Duration>,
}

impl Dispatch<'_> {
    async fn send(&self, request: Request) -> Result<Response> {
        let PreparedRequest {
            request,
            explicit_cookie,
        } = self.prepare(request).await?;
        match Plan::new(self.client.retry, request) {
            Plan::Once(request) => {
                let (mut response, redirects) = self.follow(request, explicit_cookie).await?;
                response.record_dispatch(1, redirects, self.started.elapsed());
                Ok(response)
            }
            Plan::Repeat(request) => self.repeat(&request, explicit_cookie).await,
        }
    }

    async fn repeat(&self, request: &RepeatableRequest, explicit_cookie: bool) -> Result<Response> {
        let mut attempts = 0;
        let mut redirects = 0;
        loop {
            attempts += 1;
            match self.follow(request.request(), explicit_cookie).await {
                Ok((mut response, followed)) => {
                    redirects += followed;
                    let Some(delay) = retry::retry_after_response(&response, attempts) else {
                        response.record_dispatch(attempts, redirects, self.started.elapsed());
                        return Ok(response);
                    };
                    response.discard().await?;
                    self.wait(delay).await?;
                }
                Err(error) => {
                    let Some(delay) = retry::retry_after_error(&error, attempts) else {
                        return Err(error);
                    };
                    self.wait(delay).await?;
                }
            }
        }
    }

    async fn prepare(&self, request: Request) -> Result<PreparedRequest> {
        let (mut parts, body) = request.into_parts();
        parts.uri = resolve_target(self.client.base_url.as_ref(), &parts.uri)?;
        if self.client.https_only && parts.uri.scheme_str() != Some("https") {
            return Err(Error::request("request URL must use HTTPS"));
        }
        merge_default_headers(&mut parts.headers, &self.client.default_headers);
        if self.client.decompresses_responses
            && parts.method != Method::CONNECT
            && !parts.headers.contains_key(ACCEPT_ENCODING)
            && !parts.headers.contains_key(RANGE)
            && !parts.headers.contains_key(UPGRADE)
            && let Some(accepted) = crate::compression::accepted()
        {
            parts.headers.insert(ACCEPT_ENCODING, accepted);
        }
        let mut request = http::Request::from_parts(parts, body);
        #[cfg(feature = "cookies")]
        let explicit_cookie = request.headers().contains_key(COOKIE);
        #[cfg(not(feature = "cookies"))]
        let explicit_cookie = false;
        #[cfg(feature = "cookies")]
        if let Some(cookies) = &self.client.cookies
            && !explicit_cookie
        {
            let uri = request.uri().clone();
            cookies.add_request_header(request.headers_mut(), &uri);
        }
        let request_auth = request.extensions_mut().remove::<Arc<dyn Authentication>>();
        let authentication = request_auth.as_deref().or(self.client.auth.as_deref());
        if let Some(authentication) = authentication {
            authentication.authenticate(&mut request).await?;
        }
        Ok(PreparedRequest {
            request,
            explicit_cookie,
        })
    }

    async fn follow(
        &self,
        mut request: Request,
        explicit_cookie: bool,
    ) -> Result<(Response, usize)> {
        #[cfg(not(feature = "cookies"))]
        let _ = explicit_cookie;
        // Proxy credentials belong only to the configured proxy hop. Repeat
        // this at the connection boundary as defense in depth for low-level
        // callers that bypass this policy layer.
        request.headers_mut().remove(PROXY_AUTHORIZATION);
        validate_framing(request.headers(), request.body())?;
        if self.client.redirects == crate::redirect::Policy::NoFollow {
            let response = self.attempt(request).await?;
            #[cfg(feature = "cookies")]
            if let Some(cookies) = &self.client.cookies {
                cookies.store_response_headers(response.headers(), response.url());
            }
            return Ok((response, 0));
        }
        let mut chain = RequestChain::new(request);
        let mut followed = 0;
        #[cfg(feature = "cookies")]
        let mut first = true;
        loop {
            let mut request = chain.request().ok_or_else(Error::redirect)?;
            #[cfg(feature = "cookies")]
            if !first && let Some(cookies) = &self.client.cookies {
                if !explicit_cookie {
                    request.headers_mut().remove(COOKIE);
                }
                let uri = request.uri().clone();
                cookies.add_request_header(request.headers_mut(), &uri);
            }
            #[cfg(feature = "cookies")]
            {
                first = false;
            }
            request.headers_mut().remove(PROXY_AUTHORIZATION);
            validate_framing(request.headers(), request.body())?;
            let response = self.attempt(request).await?;
            #[cfg(feature = "cookies")]
            if let Some(cookies) = &self.client.cookies {
                cookies.store_response_headers(response.headers(), response.url());
            }
            if !response.status().is_redirection() {
                return Ok((response, followed));
            }
            let Some(redirect) = chain.redirect(&response)? else {
                return Ok((response, followed));
            };
            let next_redirect = followed + 1;
            match crate::redirect::decide(
                self.client.redirects,
                self.client.https_only,
                &redirect.previous,
                &redirect.next,
                next_redirect,
            ) {
                Decision::Follow => {
                    chain.follow(&response, redirect);
                    followed = next_redirect;
                    response.discard().await?;
                }
                Decision::Return => return Ok((response, followed)),
                Decision::Error => return Err(Error::redirect()),
            }
        }
    }

    async fn attempt(&self, request: Request) -> Result<Response> {
        let url = request.uri().clone();
        let method = request.method().clone();
        let range = request.headers().contains_key(RANGE);
        let mut received = self
            .client
            .connection
            .send_with_deadline(
                request,
                Deadline::after(self.remaining()?, self.client.connection.timer())?,
            )
            .await?;
        if self.client.decompresses_responses
            && !range
            && response_can_have_body(&method, received.parts.status)
        {
            received.body =
                crate::compression::response(&mut received.parts.headers, received.body);
        }
        Ok(Response::new(
            received.parts,
            received.body,
            url,
            Some(received.remote_addr),
            self.client.limits,
        ))
    }

    fn remaining(&self) -> Result<Option<Duration>> {
        self.timeout
            .map(|timeout| {
                timeout
                    .checked_sub(self.started.elapsed())
                    .filter(|remaining| !remaining.is_zero())
                    .ok_or_else(Error::timeout)
            })
            .transpose()
    }

    async fn wait(&self, delay: Duration) -> Result<()> {
        if let Some(remaining) = self.remaining()?
            && delay >= remaining
        {
            return Err(Error::timeout());
        }
        self.client.connection.timer().after(delay).await;
        self.remaining().map(|_| ())
    }
}

struct PreparedRequest {
    request: Request,
    explicit_cookie: bool,
}

fn response_can_have_body(method: &Method, status: StatusCode) -> bool {
    method != Method::HEAD
        && !status.is_informational()
        && status != StatusCode::NO_CONTENT
        && status != StatusCode::RESET_CONTENT
        && status != StatusCode::NOT_MODIFIED
        && !(method == Method::CONNECT && status.is_success())
}

#[cfg(test)]
mod tests {
    use std::{
        future::Future as _,
        task::{Context, Poll, Waker},
    };

    use super::*;

    #[tokio::test]
    async fn retry_delay_that_reaches_the_deadline_fails_immediately() {
        let dispatch = Dispatch {
            client: &crate::Client::new().unwrap().inner,
            started: Instant::now(),
            timeout: Some(Duration::from_secs(1)),
        };
        let mut wait = Box::pin(dispatch.wait(Duration::from_secs(2)));
        let mut context = Context::from_waker(Waker::noop());

        let Poll::Ready(Err(error)) = wait.as_mut().poll(&mut context) else {
            panic!("a retry delay that cannot fit must fail immediately");
        };
        assert!(error.is_timeout());
    }

    #[test]
    fn bodyless_responses_are_not_candidates_for_decompression() {
        assert!(!response_can_have_body(&Method::HEAD, StatusCode::OK));
        assert!(!response_can_have_body(
            &Method::GET,
            StatusCode::NO_CONTENT
        ));
        assert!(!response_can_have_body(
            &Method::GET,
            StatusCode::RESET_CONTENT
        ));
        assert!(!response_can_have_body(
            &Method::GET,
            StatusCode::NOT_MODIFIED
        ));
        assert!(!response_can_have_body(&Method::CONNECT, StatusCode::OK));
        assert!(response_can_have_body(&Method::GET, StatusCode::OK));
    }
}