Server-Sent Events (SSE)

Stream real-time events to clients using the Server-Sent Events protocol

The Sse response type enables streaming events to clients using the Server-Sent Events (SSE) protocol. SSE is a simple HTTP-based protocol for pushing updates from the server to the client.

Basic usage

Return a stream of events wrapped in Sse:

use axum::{
    response::sse::{Event, Sse},
    routing::get,
    Router,
};
use futures_util::stream::{self, Stream};
use std::{convert::Infallible, time::Duration};
use tokio_stream::StreamExt as _;

async fn sse_handler() -> Sse<impl Stream<Item = Result<Event, Infallible>>> {
    // A stream that repeats an event every second
    let stream = stream::repeat_with(|| Event::default().data("hi!"))
        .map(Ok)
        .throttle(Duration::from_secs(1));

    Sse::new(stream).keep_alive(KeepAlive::default())
}

let app = Router::new().route("/sse", get(sse_handler));

Example from axum/src/response/sse.rs:6-26 and examples/sse/src/main.rs.

How it works

IntoResponse implementation

The Sse type sets proper headers and wraps the stream in a body:

impl<S, E> IntoResponse for Sse<S>
where
    S: Stream<Item = Result<Event, E>> + Send + 'static,
    E: Into<BoxError>,
{
    fn into_response(self) -> Response {
        (
            [
                (http::header::CONTENT_TYPE, "text/event-stream"),
                (http::header::CACHE_CONTROL, "no-cache"),
            ],
            Body::new(SseBody { /* ... */ }),
        )
            .into_response()
    }
}

See implementation in axum/src/response/sse.rs:90-107.

Response fields

Content-Type · header

Automatically set to text/event-stream

Cache-Control · header

Automatically set to no-cache

body · stream

A stream of SSE events formatted according to the SSE protocol

Event API

Creating events

use axum::response::sse::Event;

// Simple data event
let event = Event::default().data("message");

// Event with all fields
let event = Event::default()
    .event("update")           // Event type
    .data("payload")           // Event data
    .id("unique-id")           // Event ID
    .retry(Duration::from_secs(30)); // Retry timeout

Event fields

data · string

The event payload. Corresponds to MessageEvent.data in the browser. Newlines are automatically handled with multiple data: fields.

event · string

The event type. Used with addEventListener(type, ...) in the browser. Defaults to "message" if not set.

id · string

Event identifier. Sets MessageEvent.lastEventId in the browser. Cannot contain newlines or null characters.

retry · Duration

Reconnection timeout hint for the client in milliseconds.

comment · string

Comment field (ignored by most clients). Can be called multiple times. Cannot contain newlines.

JSON data

use serde::Serialize;

#[derive(Serialize)]
struct Update {
    count: i32,
}

let event = Event::default()
    .json_data(Update { count: 42 })
    .unwrap();

See axum/src/response/sse.rs:246-277.

Custom data writer

For advanced use cases, write data incrementally:

use std::fmt::Write;

let mut writer = Event::default().into_data_writer();
write!(&mut writer, "custom {}", "data").unwrap();
let event = writer.into_event();

See axum/src/response/sse.rs:179-222.

Keep-alive

Keep connections alive by sending periodic messages:

use axum::response::sse::KeepAlive;
use std::time::Duration;

let stream = /* your event stream */;

Sse::new(stream).keep_alive(
    KeepAlive::new()
        .interval(Duration::from_secs(15))
        .text("keep-alive-text")
)

KeepAlive configuration

interval · Duration

Time between keep-alive messages. Default is 15 seconds.

text · string

Custom keep-alive message text. Default is an empty comment.

event · Event

Custom keep-alive event. Allows full control over the keep-alive message.

See implementation in axum/src/response/sse.rs:514-573.

Complete example

use axum::{
    response::sse::{Event, KeepAlive, Sse},
    routing::get,
    Router,
};
use futures_util::stream::{self, Stream};
use std::{convert::Infallible, time::Duration};
use tokio_stream::StreamExt as _;

#[tokio::main]
async fn main() {
    let app = Router::new().route("/events", get(event_stream));
    
    let listener = tokio::net::TcpListener::bind("127.0.0.1:3000")
        .await
        .unwrap();
    axum::serve(listener, app).await;
}

async fn event_stream() -> Sse<impl Stream<Item = Result<Event, Infallible>>> {
    let stream = stream::repeat_with(|| {
        Event::default()
            .event("update")
            .data(format!("timestamp: {}", std::time::SystemTime::now()))
    })
    .map(Ok)
    .throttle(Duration::from_secs(1));

    Sse::new(stream).keep_alive(
        KeepAlive::new()
            .interval(Duration::from_secs(5))
            .text("keep-alive")
    )
}

Browser usage

const eventSource = new EventSource('/events');

// Listen for default "message" events
eventSource.onmessage = (event) => {
    console.log('Received:', event.data);
};

// Listen for custom event types
eventSource.addEventListener('update', (event) => {
    console.log('Update:', event.data);
});

eventSource.onerror = (error) => {
    console.error('SSE error:', error);
};

See also

• Streaming responses for binary streaming
• IntoResponse trait for custom response types
• MDN: Server-Sent Events