tez 0.0.3

A lightweight, ergonomic, and fast high-level HTTP client for Rust
Documentation
use std::{fmt, time::Duration};

use serde::de::DeserializeOwned;

use crate::Result;

/// One server-sent event received from or sent in an HTTP body.
///
/// Events carry data and may include an event name, identifier, and suggested
/// reconnection delay.
#[derive(Clone, Eq, PartialEq)]
pub struct Event {
    name: Option<String>,
    data: String,
    id: Option<String>,
    retry: Option<Duration>,
}

impl Event {
    /// Creates a server-sent event with one data value.
    ///
    /// Embedded line endings are encoded as multiple `data` fields when this
    /// event is used in a streaming request body.
    #[must_use]
    pub fn new(data: impl Into<String>) -> Self {
        Self {
            name: None,
            data: data.into(),
            id: None,
            retry: None,
        }
    }

    /// Sets the event name used by an outbound server-sent event.
    #[must_use]
    pub fn with_event(mut self, name: impl Into<String>) -> Self {
        self.name = Some(name.into());
        self
    }

    /// Sets the identifier used by an outbound server-sent event.
    #[must_use]
    pub fn with_id(mut self, id: impl Into<String>) -> Self {
        self.id = Some(id.into());
        self
    }

    /// Sets the reconnection delay used by an outbound server-sent event.
    #[must_use]
    pub const fn with_retry(mut self, retry: Duration) -> Self {
        self.retry = Some(retry);
        self
    }

    pub(crate) fn with_metadata(
        data: String,
        name: Option<String>,
        id: Option<String>,
        retry: Option<Duration>,
    ) -> Self {
        Self {
            name,
            data,
            id,
            retry,
        }
    }

    /// Returns the optional SSE event name.
    #[must_use]
    pub fn event(&self) -> Option<&str> {
        self.name.as_deref()
    }

    /// Returns the complete, newline-joined data field.
    #[must_use]
    pub fn data(&self) -> &str {
        &self.data
    }

    /// Returns the current event identifier, when one has been set.
    #[must_use]
    pub fn id(&self) -> Option<&str> {
        self.id.as_deref()
    }

    /// Returns the current reconnection delay requested by the server.
    #[must_use]
    pub fn retry(&self) -> Option<Duration> {
        self.retry
    }

    /// Decodes the event data as JSON.
    ///
    /// # Errors
    ///
    /// Returns a decode error when the event data is not valid JSON for `T`.
    pub fn json<T>(&self) -> Result<T>
    where
        T: DeserializeOwned,
    {
        crate::content::decode_json(self.data.as_bytes(), "event JSON could not be decoded")
    }
}

impl fmt::Debug for Event {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        formatter
            .debug_struct("Event")
            .field("has_event", &self.name.is_some())
            .field("data_len", &self.data.len())
            .field("has_id", &self.id.is_some())
            .field("retry", &self.retry)
            .finish()
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn debug_never_exposes_event_contents() {
        let event = Event::with_metadata(
            "body secret".to_owned(),
            Some("event secret".to_owned()),
            Some("id secret".to_owned()),
            None,
        );

        let debug = format!("{event:?}");
        assert!(!debug.contains("event secret"));
        assert!(!debug.contains("body secret"));
        assert!(!debug.contains("id secret"));
        assert!(debug.contains("has_event"));
        assert!(debug.contains("data_len"));
    }
}