Crate sse_core 

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, allocation-minimized state machine that consumes raw bytes 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: The SseDecoder operates strictly on byte buffers (bytes::Buf), decoupling parsing from the transport layer.
• Async Stream Wrapper: Includes a lightweight SseStream wrapper to easily integrate with futures-core::TryStream (e.g., standard async network streams).
• Memory Efficient: Leverages Cow for event names to avoid allocating strings for standard "message" events, and cleanly enforces configurable maximum payload sizes to prevent memory exhaustion from malicious servers.
• Jittered Backoff: Includes a customizable mathematical utility (SseRetryConfig) for calculating exponential backoffs and reconnect delays.

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

• jitter (enabled by default): Includes randomized jitter calculations in SseRetryConfig to prevent thundering herd problems on reconnects. Requires the std library. Disable this for no_std usage.

Structs

MessageEvent

Represents a single Server-Sent Event message.

PayloadTooLargeError

Error indicating that a parsed field exceeded the maximum allowed buffer size.

SseDecoder

The core state-machine parser for SSE.

SseRetryConfig

Configuration for exponential backoff and jitter during stream reconnections.

SseStream

An asynchronous stream wrapper that parses SSE events from an underlying byte stream.

Enums

SseEvent

Commands and payloads yielded by the SSE stream.

SseStreamError

Errors that can occur while reading from an SseStream.

Type Aliases

SseStreamResult

An alias for Result with the error set to SseStreamError<E>.