eventsrc_client/lib.rs
1//! Backend-neutral SSE client APIs with two explicit public modes:
2//!
3//! - [`oneshot::EventSource`] consumes a single accepted body stream
4//! - [`replayable::EventSource`] reconnects through a backend-neutral connector
5//!
6//! The default `reqwest` feature provides extension trait impls for
7//! `reqwest::Response` and `reqwest::RequestBuilder`, including validation of
8//! HTTP status and `content-type`.
9//!
10//! # One-Shot Usage
11//!
12//! Inside an async context:
13//!
14//! ```no_run
15//! # async fn demo() -> Result<(), Box<dyn std::error::Error>> {
16//! use futures_util::StreamExt;
17//! let response = reqwest::Client::new()
18//! .get("https://example.com/v1/stream")
19//! .send()
20//! .await?;
21//!
22//! use eventsrc_client::oneshot::EventSourceExt as _;
23//!
24//! let mut stream = response.event_source()?;
25//!
26//! while let Some(event) = stream.next().await {
27//! let event = event?;
28//! println!("{}", event.data());
29//! }
30//! # Ok(())
31//! # }
32//! ```
33//!
34//! # Replayable Usage
35//!
36//! Inside an async context:
37//!
38//! ```no_run
39//! # async fn demo() -> Result<(), Box<dyn std::error::Error>> {
40//! use eventsrc_client::replayable::EventSourceExt as _;
41//! use futures_util::StreamExt;
42//!
43//! let mut stream = reqwest::Client::new()
44//! .get("https://example.com/events")
45//! .event_source()?;
46//!
47//! while let Some(event) = stream.next().await {
48//! let event = event?;
49//! println!("{}", event.data());
50//! }
51//! # Ok(())
52//! # }
53//! ```
54//!
55//! # Retry Policies
56//!
57//! Replayable mode separates retry classification from retry timing:
58//!
59//! - [`replayable::EventSource`] decides which transitions are retryable
60//! - [`replayable::RetryPolicy`] decides how long to wait before retrying
61//!
62//! Built-in policies:
63//!
64//! - [`replayable::ConstantBackoff`] for a fixed delay
65//! - [`replayable::ExponentialBackoff`] for failure-sensitive backoff
66//! - [`replayable::NeverRetry`] to stop reconnecting after the first disconnect or failure
67
68#![deny(unused_imports)]
69#![deny(missing_docs)]
70#![cfg_attr(docsrs, feature(doc_cfg))]
71
72/// Unified client-layer error types and helpers.
73pub mod error;
74/// One-shot SSE consumption over a single accepted body stream.
75pub mod oneshot;
76/// Reconnecting SSE consumption with replay and retry support.
77pub mod replayable;
78#[cfg(feature = "reqwest")]
79mod reqwest;