sse-core

A high-performance, no_std compatible state-machine parser for Server-Sent Events (SSE).

sse-core is designed to be the foundational parsing layer for SSE clients. It does not perform any network I/O. Instead, it provides a highly efficient state machine that consumes raw byte buffers and yields parsed SSE events.

Features

• no_std Compatible: Requires only the alloc crate, making it perfect for embedded environments or custom network stacks.
• Zero-I/O State Machine: Operates strictly on byte buffers (bytes::Buf), cleanly decoupling parsing logic from the transport layer.
• Async Stream Wrapper: Includes an optional SseStream wrapper to easily integrate with standard async network streams (futures-core::TryStream).
• Memory Safe: Enforces strict, configurable maximum payload sizes to prevent memory exhaustion from malicious or misconfigured servers.
• Smart Backoff: Includes a customizable utility (SseRetryConfig) for calculating exponential backoffs and reconnect delays with jitter.

Usage

The Low-Level Decoder

If you are managing your own buffers, use the SseDecoder directly:

use bytes::Bytes;
use sse_core::SseDecoder;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut decoder = SseDecoder::new();
    let mut buffer = Bytes::from("data: hello world\n\n");

    while let Some(event) = decoder.next(&mut buffer)? {
        println!("Parsed event: {:?}", event);
    }
    Ok(())
}

The Async Stream Wrapper

If you have an existing async byte stream (like a TCP socket or HTTP body), wrap it in SseStream:

use sse_core::SseStream;
use futures_util::StreamExt;

// Assume `tcp_byte_stream` implements `TryStream<Ok = bytes::Bytes>`
let mut stream = SseStream::new(tcp_byte_stream);

while let Some(result) = stream.next().await {
    match result {
        Ok(event) => println!("Event: {:?}", event),
        Err(e) => eprintln!("Stream error: {}", e),
    }
}

Feature Flags

sse-core is highly configurable, allowing you to strip out async or standard library dependencies for constrained environments. By default, all features are enabled.

• std: Enables standard library support. Disable this for no_std environments. (note: the alloc crate is still required).
• stream: Enables the SseStream wrapper for asynchronous byte streams. Disable this if you only need the raw, synchronous SseDecoder state machine.
• fastrand: Enables randomized jitter calculations in SseRetryConfig to prevent thundering herd scenarios (requires std).
• serde: Implements serde's Serialize and Deserialize traits on common types.

no_std Usage

To use sse-core in a no_std environment (using only the raw state-machine parser), disable the default features in your Cargo.toml:

[dependencies]
sse-core = { version = "0.1", default-features = false }

# Or if you need async
sse-core = { version = "0.1", default-features = false, features = ["stream"] }