tez 0.0.2

A lightweight, ergonomic, and fast high-level HTTP client for Rust
Documentation
use std::{fmt, net::SocketAddr, pin::Pin};

use bytes::Bytes;
use http::{HeaderMap, StatusCode, Uri, Version, header};
use http_body::Body as _;
use serde::de::DeserializeOwned;

use crate::{Body, Error, Result, stream::ResponseStream};

const COLLECTION_LIMIT: usize = 16 * 1024 * 1024;

/// A final HTTP response with a one-shot streaming Tez body.
///
/// An HTTP status is never an error by itself. Inspect [`Response::status`] to
/// decide what success means for the operation. Borrow the one-shot body to
/// stream frames, consume it with a collecting helper, or call
/// [`Response::discard`].
pub struct Response {
    inner: http::Response<Body>,
    url: Uri,
    content_length: Option<u64>,
    remote_addr: Option<SocketAddr>,
}

impl Response {
    pub(crate) fn new(
        status: StatusCode,
        version: Version,
        headers: HeaderMap,
        body: Body,
        url: Uri,
        content_length: Option<u64>,
        remote_addr: Option<SocketAddr>,
    ) -> Self {
        let mut inner = http::Response::builder()
            .status(status)
            .version(version)
            .body(body)
            .expect("a received HTTP response always has valid parts");
        *inner.headers_mut() = headers;
        Self {
            inner,
            url,
            content_length,
            remote_addr,
        }
    }

    /// Returns the final status code after redirects.
    #[must_use]
    pub fn status(&self) -> StatusCode {
        self.inner.status()
    }

    /// Returns the HTTP version used by the final response.
    #[must_use]
    pub fn version(&self) -> Version {
        self.inner.version()
    }

    /// Returns response headers, preserving repeated values.
    #[must_use]
    pub fn headers(&self) -> &HeaderMap {
        self.inner.headers()
    }

    /// Returns the final absolute URL after redirects.
    #[must_use]
    pub fn url(&self) -> &Uri {
        &self.url
    }

    /// Returns the exposed response body length when it is known.
    ///
    /// This is body metadata after the client's decompression policy, not a
    /// parsed `Content-Length` header. Automatically decompressed or streaming
    /// responses commonly have no known length.
    #[must_use]
    pub const fn content_length(&self) -> Option<u64> {
        self.content_length
    }

    /// Returns the final transport peer address when it is known.
    ///
    /// When a proxy is in use, this may be the proxy address rather than the
    /// origin server address.
    #[must_use]
    pub const fn remote_addr(&self) -> Option<SocketAddr> {
        self.remote_addr
    }

    /// Returns the one-shot streaming response body.
    #[must_use]
    pub fn body(&self) -> &Body {
        self.inner.body()
    }

    /// Returns the one-shot streaming response body mutably.
    #[must_use]
    pub fn body_mut(&mut self) -> &mut Body {
        self.inner.body_mut()
    }

    /// Consumes the response and returns its one-shot streaming body.
    #[must_use]
    pub fn into_body(self) -> Body {
        self.inner.into_body()
    }

    /// Consumes the response as an incremental body stream.
    ///
    /// Call [`ResponseStream::events`] to infer the response framing from its
    /// `Content-Type`, or consume this value as a raw [`http_body::Body`].
    #[must_use]
    pub fn stream(self) -> ResponseStream {
        let content_type = content_type(self.headers()).map(ToOwned::to_owned);
        ResponseStream::new(self.into_body(), content_type)
    }

    /// Collects up to 16 MiB of response body data.
    ///
    /// The limit applies after automatic decompression when enabled. This
    /// consumes the response. Use streaming access for larger bodies.
    pub async fn bytes(self) -> Result<Bytes> {
        collect(self.into_body()).await
    }

    /// Collects up to 16 MiB of response body data as UTF-8 text.
    ///
    /// The limit applies after automatic decompression when enabled. This
    /// consumes the response and returns a decode error for invalid UTF-8.
    pub async fn text(self) -> Result<String> {
        String::from_utf8(self.bytes().await?.to_vec())
            .map_err(|_| Error::decode("response text is not valid UTF-8"))
    }

    /// Collects up to 16 MiB of response body data as JSON.
    ///
    /// The limit applies after automatic decompression when enabled. This
    /// consumes the response. JSON is decoded regardless of the response
    /// `Content-Type` value.
    pub async fn json<T>(self) -> Result<T>
    where
        T: DeserializeOwned,
    {
        serde_json::from_slice(&self.bytes().await?)
            .map_err(|_| Error::decode("response JSON could not be decoded"))
    }

    /// Drains the body without retaining it, allowing connection reuse.
    ///
    /// This consumes the response and observes the client's total deadline.
    pub async fn discard(self) -> Result<()> {
        let mut body = self.into_body();
        while let Some(frame) =
            std::future::poll_fn(|context| Pin::new(&mut body).poll_frame(context)).await
        {
            frame?;
        }
        Ok(())
    }
}

fn content_type(headers: &HeaderMap) -> Option<&str> {
    headers.get(header::CONTENT_TYPE)?.to_str().ok()
}

impl fmt::Debug for Response {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        formatter
            .debug_struct("Response")
            .field("status", &self.status())
            .field("version", &self.version())
            .field("header_count", &self.headers().len())
            .field("content_length", &self.content_length())
            .field("remote_addr", &self.remote_addr())
            .finish()
    }
}

async fn collect(mut body: Body) -> Result<Bytes> {
    if body.size_hint().lower() > COLLECTION_LIMIT as u64 {
        return Err(Error::body_too_large());
    }

    let mut bytes = Vec::new();
    while let Some(frame) =
        std::future::poll_fn(|context| Pin::new(&mut body).poll_frame(context)).await
    {
        let frame = frame?;
        if let Ok(data) = frame.into_data() {
            let length = bytes
                .len()
                .checked_add(data.len())
                .ok_or_else(Error::body_too_large)?;
            if length > COLLECTION_LIMIT {
                return Err(Error::body_too_large());
            }
            bytes.extend_from_slice(&data);
        }
    }
    Ok(Bytes::from(bytes))
}

#[cfg(test)]
mod tests {
    use super::*;
    use http_body::{Body as HttpBody, Frame, SizeHint};
    use std::{
        convert::Infallible,
        pin::Pin,
        task::{Context, Poll},
    };

    fn response(body: impl Into<Body>) -> Response {
        Response::new(
            StatusCode::OK,
            Version::HTTP_11,
            HeaderMap::new(),
            body.into(),
            "https://example.com/resource".parse().unwrap(),
            None,
            None,
        )
    }

    #[tokio::test]
    async fn decoders_consume_the_body_and_classify_invalid_data() {
        assert_eq!(response("tez").text().await.unwrap(), "tez");
        assert_eq!(
            response(br#"{"name":"Ada"}"#.as_slice())
                .json::<serde_json::Value>()
                .await
                .unwrap(),
            serde_json::json!({ "name": "Ada" })
        );

        let error = response(vec![0xff]).text().await.unwrap_err();
        assert!(error.is_decode());
    }

    #[tokio::test]
    async fn collection_limit_accepts_the_boundary_and_rejects_the_next_byte() {
        let exact = vec![b'x'; COLLECTION_LIMIT];
        assert_eq!(
            collect(Body::from(exact)).await.unwrap().len(),
            COLLECTION_LIMIT
        );

        let too_large = vec![b'y'; COLLECTION_LIMIT + 1];
        let error = collect(Body::from(too_large)).await.unwrap_err();
        assert!(error.is_body_too_large());
        assert!(error.is_body());
    }

    #[tokio::test]
    async fn collection_does_not_treat_an_upper_hint_as_actual_length() {
        struct LooseUpperBound(Option<Bytes>);

        impl HttpBody for LooseUpperBound {
            type Data = Bytes;
            type Error = Infallible;

            fn poll_frame(
                self: Pin<&mut Self>,
                _context: &mut Context<'_>,
            ) -> Poll<Option<std::result::Result<Frame<Self::Data>, Self::Error>>> {
                Poll::Ready(self.get_mut().0.take().map(Frame::data).map(Ok))
            }

            fn size_hint(&self) -> SizeHint {
                let mut hint = SizeHint::new();
                hint.set_upper(COLLECTION_LIMIT as u64 + 1);
                hint
            }
        }

        let bytes = collect(Body::wrap(LooseUpperBound(Some(Bytes::from_static(
            b"small",
        )))))
        .await
        .unwrap();

        assert_eq!(bytes, "small");
    }

    #[test]
    fn debug_never_includes_header_values_or_body_data() {
        let mut headers = HeaderMap::new();
        headers.insert("authorization", "Bearer secret".parse().unwrap());
        let response = Response::new(
            StatusCode::OK,
            Version::HTTP_11,
            headers,
            Body::from("body secret"),
            "https://example.com/resource?token=secret".parse().unwrap(),
            Some(11),
            Some("127.0.0.1:8080".parse().unwrap()),
        );

        let debug = format!("{response:?}");
        assert!(debug.contains("content_length: Some(11)"));
        assert!(debug.contains("remote_addr: Some(127.0.0.1:8080)"));
        assert!(!debug.contains("secret"));
        assert!(!debug.contains("authorization"));
    }
}