sse-parse 0.1.0

//! Incremental parser for Server-Sent Events (SSE) byte streams.
//!
//! The crate turns an ordered sequence of byte chunks into an ordered
//! sequence of [`Event`]s, following the WHATWG HTML "interpreting an event
//! stream" algorithm. It does no HTTP, no reconnection, and no MIME checking:
//! those belong to the client built on top of it.
//!
//! Two layers:
//!
//! - [`SseParser`] is the sans-IO core. Feed it bytes, drain events. Every
//!   byte sequence is a valid stream, so `feed` has no error to return, and
//!   the time spent is linear in the bytes fed whatever the chunking.
//!   `tests/no_panic.rs` and the fuzz target cover arbitrary bytes and
//!   chunkings, and `tests/perf_gate.rs` bounds the scan count.
//! - [`EventStream`] wraps any [`futures_core::Stream`] of byte chunks and
//!   yields events. It depends on `futures-core` alone, so it runs on any
//!   executor.
//!
//! ```
//! use sse_parse::SseParser;
//!
//! let mut parser = SseParser::new();
//! parser.feed(b"event: add\ndata: first\ndata: second\n\n");
//!
//! let event = parser.next_event().unwrap();
//! assert_eq!(event.event, "add");
//! assert_eq!(event.data, "first\nsecond");
//! assert!(parser.next_event().is_none());
//! ```
//!
//! # Conformance notes
//!
//! - Invalid UTF-8 is replaced with U+FFFD, as the Encoding Standard's UTF-8
//!   decoder does. Parsing never reports an encoding error.
//! - A leading `EF BB BF` byte order mark is stripped exactly once, at stream
//!   offset 0, even when it arrives one byte per chunk. Later BOM bytes are
//!   content.
//! - The last event ID string is committed at every blank line, including
//!   blocks that dispatch no event, so `id:`-only blocks still update
//!   reconnection state.
//! - The reconnection time (`retry`) takes effect when the field is
//!   processed, independent of any later dispatch.
//! - A carriage return at end of stream terminates its line.
//!
//! # `no_std`
//!
//! Disable the default `std` feature to build on `core + alloc`.

#![cfg_attr(not(feature = "std"), no_std)]
#![forbid(unsafe_code)]
#![warn(missing_docs, rust_2018_idioms)]

extern crate alloc;

mod event;
mod parser;
mod stream;

pub use event::Event;
pub use parser::{SseParser, Stats};
pub use stream::{Error, EventStream};