Struct SseDecoder

Source

pub struct SseDecoder { /* private fields */ }

Expand description

The core state-machine parser for SSE.

This decoder does not perform any I/O. It consumes bytes from a given buffer and yields parsed SseEvents. It is suitable for no_std environments.

Implementations§

Source §

impl SseDecoder

Source

pub fn new() -> Self

Creates a new decoder with the default payload size limit of 512KiB.

§Example

let mut decoder = SseDecoder::new();
let mut buf = Bytes::from("data: standard stream\n\n");

let event = decoder.next(&mut buf).transpose()?;
assert!(event.is_some());

Source

pub fn with_limit(max_payload_size: NonZeroUsize) -> Self

Creates a new decoder with a custom maximum payload size limit.

This is useful in memory-constrained environments or when connecting to untrusted servers to prevent memory exhaustion from unbounded input.

The limit applies independently to each of the three values an event accumulates — its data, its name and its ID — so peak memory is a small multiple of max_payload_size rather than exactly that. See next() for what each of them accumulates.

§Example

// Create a strict decoder that rejects payloads over 1024 bytes
let limit = NonZeroUsize::new(1024).unwrap();
let mut decoder = SseDecoder::with_limit(limit);

let mut buf = Bytes::from("data: small payload\n\n");
let Some(event) = decoder.next(&mut buf) else {
    panic!();
};
assert!(event.is_ok());

Source

pub fn last_event_id(&self) -> Option<&Arc<str>>

Returns the current Last-Event-ID known to the decoder, if any.

Source

pub fn reconnect_with_id(&mut self, id: Option<Arc<str>>)

Resets the decoder state for a new connection, explicitly overriding the currently tracked Last-Event-ID.

This method clears all internal byte buffers and resets the parser, but instead of keeping the previous ID (like reconnect()) or dropping it (like clear()), it injects the provided ID.

It is typically used to prime the state machine with a known ID (e.g., from a local database) right before feeding the decoder bytes from a newly established connection.

Source

pub fn clear(&mut self)

Resets the decoder state completely, dropping the current Last-Event-ID.

This clears all internal byte buffers and purges the parser’s state, effectively starting fresh. Because it drops the Last-Event-ID, the next connection will start from the present moment rather than resuming.

To reset the state but keep the current ID, use reconnect().
To reset the state and inject a specific ID, use reconnect_with_id().

Source

pub fn reconnect(&mut self)

Resets the buffer state for a new connection while retaining the Last-Event-ID.

This clears the internal byte buffers to prepare for a fresh stream of data, but safely preserves the most recently parsed Last-Event-ID. This ensures that when you reconnect to the server, you can resume exactly where you left off.

To reset the state and drop the ID, use clear().
To reset the state and override the ID, use reconnect_with_id().

Source

pub fn next( &mut self, buf: &mut impl Buf, ) -> Option<Result<SseEvent, PayloadTooLargeError>>

Consumes bytes from the provided buffer and attempts to yield an event.

The decoder does not store unparsed bytes internally. It reads directly from the provided buffer, advancing the buffer’s cursor only for the bytes it successfully parses.

If Ok(None) is returned, the provided buffer has been exhausted and more bytes are needed to complete the current event. You should fetch more data, append it to your buffer, and call next() again.

§Example

use bytes::{Buf, Bytes};

let mut decoder = SseDecoder::new();
let mut buffer = Bytes::from("data: hello\n\n");

// Call next() in a loop to drain all available events
while let Some(event) = decoder.next(&mut buffer) {
    println!("Received: {event:?}");
}

// When next() returns None, the decoder is waiting for more data.
assert!(buffer.is_empty());

§Errors

Returns a PayloadTooLargeError when an event’s accumulated data, name or ID would exceed the maximum payload size configured for this decoder. The limit is not per line:

data accumulates every data: line of the current event, joined by newlines, so the limit bounds the whole event payload and is only reset once the event is dispatched.
event and id are reset by each event: / id: field, so for those the limit does bound a single line.

The offending event is discarded rather than silently truncated: the decoder skips the rest of the current event and resynchronizes at the next event boundary, so it stays usable after the error. retry: fields are still honoured while the discarded event is being skipped.