tez 0.0.2

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

use bytes::Bytes;
use futures_util::Stream;
use http_body::Body as _;
use http_body::{Frame, SizeHint};
use serde::de::DeserializeOwned;

mod decoder;

use decoder::Decoder;

use crate::{Body, Error, Event, Result};

const TERMINAL_DATA: &str = "[DONE]";

/// A one-shot response body consumed incrementally.
///
/// Use [`ResponseStream::events`] to frame JSON, NDJSON, JSON Lines, or
/// server-sent event responses into logical events. This type also implements
/// [`http_body::Body`] for callers that need raw HTTP data frames and trailers.
pub struct ResponseStream {
    body: Body,
    content_type: Option<String>,
}

impl ResponseStream {
    pub(crate) fn new(body: Body, content_type: Option<String>) -> Self {
        Self { body, content_type }
    }

    /// Frames the response into logical events as body data arrives.
    ///
    /// Event framing is inferred from `Content-Type`:
    ///
    /// - JSON responses produce one event when the document is complete.
    /// - NDJSON and JSON Lines responses produce one event per record.
    /// - Server-sent event responses produce one event per SSE dispatch.
    ///
    /// Unsupported or missing content types are reported by the returned
    /// stream. Each event may contain at most 32 MiB.
    #[must_use]
    pub fn events(self) -> EventStream {
        EventStream::new(self.body, self.content_type.as_deref())
    }

    /// Consumes this stream and returns the underlying Tez body.
    #[must_use]
    pub fn into_body(self) -> Body {
        self.body
    }
}

impl http_body::Body for ResponseStream {
    type Data = Bytes;
    type Error = Error;

    fn poll_frame(
        self: Pin<&mut Self>,
        context: &mut Context<'_>,
    ) -> Poll<Option<std::result::Result<Frame<Self::Data>, Self::Error>>> {
        Pin::new(&mut self.get_mut().body).poll_frame(context)
    }

    fn is_end_stream(&self) -> bool {
        self.body.is_end_stream()
    }

    fn size_hint(&self) -> SizeHint {
        self.body.size_hint()
    }
}

impl fmt::Debug for ResponseStream {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        formatter
            .debug_struct("ResponseStream")
            .field("has_content_type", &self.content_type.is_some())
            .finish_non_exhaustive()
    }
}

/// A one-shot stream of logical response events.
///
/// Tez infers JSON, NDJSON, JSON Lines, or server-sent event framing from the
/// response `Content-Type`. Each event may contain at most 32 MiB. Invalid
/// framing and unsupported content types are reported as stream errors.
///
/// The default item is [`Event`]. Calling [`EventStream::json`] returns the
/// same stream typed to the decoded JSON value.
pub struct EventStream<T = Event> {
    body: Body,
    decoder: Option<Decoder>,
    framing_error: Option<Error>,
    pending_data: Option<Bytes>,
    data_offset: usize,
    decode: fn(Event) -> Result<Option<T>>,
    finished: bool,
}

impl EventStream<Event> {
    fn new(body: Body, content_type: Option<&str>) -> Self {
        let (decoder, framing_error) = match Decoder::for_content_type(content_type) {
            Ok(decoder) => (Some(decoder), None),
            Err(error) => (None, Some(error)),
        };

        Self {
            body,
            decoder,
            framing_error,
            pending_data: None,
            data_offset: 0,
            decode: keep_event,
            finished: false,
        }
    }

    /// Deserializes each event's data as JSON.
    ///
    /// The conventional non-JSON terminal event `[DONE]` ends the typed stream.
    /// Use the undecoded [`EventStream`] when terminal events or SSE metadata
    /// must be observed directly.
    #[must_use]
    pub fn json<T>(self) -> EventStream<T>
    where
        T: DeserializeOwned,
    {
        EventStream {
            body: self.body,
            decoder: self.decoder,
            framing_error: self.framing_error,
            pending_data: self.pending_data,
            data_offset: self.data_offset,
            decode: decode_json,
            finished: self.finished,
        }
    }
}

impl<T> EventStream<T> {
    /// Reads the next logical event.
    pub async fn next(&mut self) -> Result<Option<T>> {
        std::future::poll_fn(|context| Pin::new(&mut *self).poll_next(context))
            .await
            .transpose()
    }

    fn poll_event(&mut self, context: &mut Context<'_>) -> Poll<Option<Result<Event>>> {
        if let Some(error) = self.framing_error.take() {
            self.finished = true;
            return Poll::Ready(Some(Err(error)));
        }

        loop {
            if let Some(data) = self.pending_data.take() {
                let mut offset = self.data_offset;
                let decoded = self
                    .decoder
                    .as_mut()
                    .expect("a valid event stream has a decoder")
                    .push_one(&data, &mut offset);

                if offset < data.len() {
                    self.pending_data = Some(data);
                    self.data_offset = offset;
                } else {
                    self.data_offset = 0;
                }

                match decoded {
                    Ok(Some(event)) => return Poll::Ready(Some(Ok(event))),
                    Ok(None) => {}
                    Err(error) => {
                        self.finished = true;
                        self.pending_data = None;
                        return Poll::Ready(Some(Err(error)));
                    }
                }
            }

            if self.finished {
                return Poll::Ready(None);
            }

            match Pin::new(&mut self.body).poll_frame(context) {
                Poll::Ready(Some(Ok(frame))) => {
                    if let Ok(data) = frame.into_data() {
                        self.pending_data = Some(data);
                        self.data_offset = 0;
                    }
                }
                Poll::Ready(Some(Err(error))) => {
                    self.finished = true;
                    return Poll::Ready(Some(Err(error)));
                }
                Poll::Ready(None) => {
                    self.finished = true;
                    return match self
                        .decoder
                        .as_mut()
                        .expect("a valid event stream has a decoder")
                        .finish()
                    {
                        Ok(Some(event)) => Poll::Ready(Some(Ok(event))),
                        Ok(None) => Poll::Ready(None),
                        Err(error) => Poll::Ready(Some(Err(error))),
                    };
                }
                Poll::Pending => return Poll::Pending,
            }
        }
    }
}

impl<T> fmt::Debug for EventStream<T> {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        formatter
            .debug_struct("EventStream")
            .finish_non_exhaustive()
    }
}

impl<T> Stream for EventStream<T> {
    type Item = Result<T>;

    fn poll_next(mut self: Pin<&mut Self>, context: &mut Context<'_>) -> Poll<Option<Self::Item>> {
        if self.finished {
            return Poll::Ready(None);
        }

        match self.poll_event(context) {
            Poll::Ready(Some(Ok(event))) => match (self.decode)(event) {
                Ok(Some(event)) => Poll::Ready(Some(Ok(event))),
                Ok(None) => {
                    self.finished = true;
                    Poll::Ready(None)
                }
                Err(error) => {
                    self.finished = true;
                    Poll::Ready(Some(Err(error)))
                }
            },
            Poll::Ready(Some(Err(error))) => {
                self.finished = true;
                Poll::Ready(Some(Err(error)))
            }
            Poll::Ready(None) => {
                self.finished = true;
                Poll::Ready(None)
            }
            Poll::Pending => Poll::Pending,
        }
    }
}

fn keep_event(event: Event) -> Result<Option<Event>> {
    Ok(Some(event))
}

fn decode_json<T>(event: Event) -> Result<Option<T>>
where
    T: DeserializeOwned,
{
    if event.data() == TERMINAL_DATA {
        return Ok(None);
    }
    event.json().map(Some)
}