spikard 0.5.0 → 0.6.1

data/vendor/crates/spikard-http/src/sse.rs

@@ -1,1409 +1,1409 @@
-//! Server-Sent Events (SSE) support for Spikard
-//!
-//! Provides SSE streaming with event generation and lifecycle management.
-
-use axum::{
-    extract::State,
-    response::{
-        IntoResponse,
-        sse::{Event, KeepAlive, Sse},
-    },
-};
-use futures_util::stream;
-use serde_json::Value;
-use std::{convert::Infallible, sync::Arc, time::Duration};
-use tracing::{debug, error, info};
-
-/// SSE event producer trait
-///
-/// Implement this trait to create custom Server-Sent Event (SSE) producers for your application.
-/// The producer generates events that are streamed to connected clients.
-///
-/// # Understanding SSE
-///
-/// Server-Sent Events (SSE) provide one-way communication from server to client over HTTP.
-/// Unlike WebSocket, SSE uses standard HTTP and automatically handles reconnection.
-/// Use SSE when you need to push data to clients without bidirectional communication.
-///
-/// # Implementing the Trait
-///
-/// You must implement the `next_event` method to generate events. The `on_connect` and
-/// `on_disconnect` methods are optional lifecycle hooks.
-///
-/// # Example
-///
-/// ```ignore
-/// use spikard_http::sse::{SseEventProducer, SseEvent};
-/// use serde_json::json;
-/// use std::time::Duration;
-/// use tokio::time::sleep;
-///
-/// struct CounterProducer {
-///     limit: usize,
-/// }
-///
-/// #[async_trait]
-/// impl SseEventProducer for CounterProducer {
-///     async fn next_event(&self) -> Option<SseEvent> {
-///         static COUNTER: std::sync::atomic::AtomicUsize = std::sync::atomic::AtomicUsize::new(0);
-///
-///         let count = COUNTER.fetch_add(1, std::sync::atomic::Ordering::Relaxed);
-///         if count < self.limit {
-///             Some(SseEvent::new(json!({"count": count})))
-///         } else {
-///             None
-///         }
-///     }
-///
-///     async fn on_connect(&self) {
-///         println!("Client connected");
-///     }
-///
-///     async fn on_disconnect(&self) {
-///         println!("Client disconnected");
-///     }
-/// }
-/// ```
-pub trait SseEventProducer: Send + Sync {
-    /// Generate the next event
-    ///
-    /// Called repeatedly to produce the event stream. Should return `Some(event)` when
-    /// an event is ready to send, or `None` when the stream should end.
-    ///
-    /// # Returns
-    /// * `Some(event)` - Event to send to the client
-    /// * `None` - Stream complete, connection will close
-    fn next_event(&self) -> impl std::future::Future<Output = Option<SseEvent>> + Send;
-
-    /// Called when a client connects to the SSE endpoint
-    ///
-    /// Optional lifecycle hook invoked when a new SSE connection is established.
-    /// Default implementation does nothing.
-    fn on_connect(&self) -> impl std::future::Future<Output = ()> + Send {
-        async {}
-    }
-
-    /// Called when a client disconnects from the SSE endpoint
-    ///
-    /// Optional lifecycle hook invoked when an SSE connection is closed (either by the
-    /// client or the stream ending). Default implementation does nothing.
-    fn on_disconnect(&self) -> impl std::future::Future<Output = ()> + Send {
-        async {}
-    }
-}
-
-/// An individual SSE event
-///
-/// Represents a single Server-Sent Event to be sent to a connected client.
-/// Events can have an optional type, ID, and retry timeout for advanced scenarios.
-///
-/// # Fields
-///
-/// * `event_type` - Optional event type string (used for client-side event filtering)
-/// * `data` - JSON data payload to send to the client
-/// * `id` - Optional event ID (clients can use this to resume after disconnect)
-/// * `retry` - Optional retry timeout in milliseconds (tells client when to reconnect)
-///
-/// # SSE Format
-///
-/// Events are serialized to the following text format:
-/// ```text
-/// event: event_type
-/// data: {"json":"value"}
-/// id: event-123
-/// retry: 3000
-/// ```
-#[derive(Debug, Clone)]
-pub struct SseEvent {
-    /// Event type (optional)
-    pub event_type: Option<String>,
-    /// Event data (JSON value)
-    pub data: Value,
-    /// Event ID (optional, for client-side reconnection)
-    pub id: Option<String>,
-    /// Retry timeout in milliseconds (optional)
-    pub retry: Option<u64>,
-}
-
-impl SseEvent {
-    /// Create a new SSE event with data only
-    ///
-    /// Creates a minimal event with just the data payload. Use builder methods
-    /// to add optional fields.
-    ///
-    /// # Arguments
-    /// * `data` - JSON value to send to the client
-    ///
-    /// # Example
-    ///
-    /// ```ignore
-    /// use serde_json::json;
-    /// use spikard_http::sse::SseEvent;
-    ///
-    /// let event = SseEvent::new(json!({"status": "connected"}));
-    /// ```
-    pub fn new(data: Value) -> Self {
-        Self {
-            event_type: None,
-            data,
-            id: None,
-            retry: None,
-        }
-    }
-
-    /// Create a new SSE event with an event type and data
-    ///
-    /// Creates an event with a type field. Clients can filter events by type
-    /// in their event listener.
-    ///
-    /// # Arguments
-    /// * `event_type` - String identifying the event type (e.g., "update", "error")
-    /// * `data` - JSON value to send to the client
-    ///
-    /// # Example
-    ///
-    /// ```ignore
-    /// use serde_json::json;
-    /// use spikard_http::sse::SseEvent;
-    ///
-    /// let event = SseEvent::with_type("update", json!({"count": 42}));
-    /// // Client can listen with: eventSource.addEventListener("update", ...)
-    /// ```
-    pub fn with_type(event_type: impl Into<String>, data: Value) -> Self {
-        Self {
-            event_type: Some(event_type.into()),
-            data,
-            id: None,
-            retry: None,
-        }
-    }
-
-    /// Set the event ID for client-side reconnection support
-    ///
-    /// Sets an ID that clients can use to resume from this point if they disconnect.
-    /// The client sends this ID back in the `Last-Event-ID` header when reconnecting.
-    ///
-    /// # Arguments
-    /// * `id` - Unique identifier for this event
-    ///
-    /// # Example
-    ///
-    /// ```ignore
-    /// use serde_json::json;
-    /// use spikard_http::sse::SseEvent;
-    ///
-    /// let event = SseEvent::new(json!({"count": 1}))
-    ///     .with_id("event-1");
-    /// ```
-    pub fn with_id(mut self, id: impl Into<String>) -> Self {
-        self.id = Some(id.into());
-        self
-    }
-
-    /// Set the retry timeout for client reconnection
-    ///
-    /// Sets the time in milliseconds clients should wait before attempting to reconnect
-    /// if the connection is lost. The client browser will automatically handle reconnection.
-    ///
-    /// # Arguments
-    /// * `retry_ms` - Retry timeout in milliseconds
-    ///
-    /// # Example
-    ///
-    /// ```ignore
-    /// use serde_json::json;
-    /// use spikard_http::sse::SseEvent;
-    ///
-    /// let event = SseEvent::new(json!({"data": "value"}))
-    ///     .with_retry(5000); // Reconnect after 5 seconds
-    /// ```
-    pub fn with_retry(mut self, retry_ms: u64) -> Self {
-        self.retry = Some(retry_ms);
-        self
-    }
-
-    /// Convert to Axum's SSE Event
-    fn into_axum_event(self) -> Event {
-        let json_data = match serde_json::to_string(&self.data) {
-            Ok(json) => json,
-            Err(e) => {
-                error!("Failed to serialize SSE event data: {}", e);
-                "null".to_string()
-            }
-        };
-
-        let mut event = Event::default().data(json_data);
-
-        if let Some(event_type) = self.event_type {
-            event = event.event(event_type);
-        }
-
-        if let Some(id) = self.id {
-            event = event.id(id);
-        }
-
-        if let Some(retry) = self.retry {
-            event = event.retry(Duration::from_millis(retry));
-        }
-
-        event
-    }
-}
-
-/// SSE state shared across connections
-///
-/// Contains the event producer and optional JSON schema for validating
-/// events. This state is shared among all connections to the same SSE endpoint.
-pub struct SseState<P: SseEventProducer> {
-    /// The event producer implementation
-    producer: Arc<P>,
-    /// Optional JSON Schema for validating outgoing events
-    event_schema: Option<Arc<jsonschema::Validator>>,
-}
-
-impl<P: SseEventProducer> Clone for SseState<P> {
-    fn clone(&self) -> Self {
-        Self {
-            producer: Arc::clone(&self.producer),
-            event_schema: self.event_schema.clone(),
-        }
-    }
-}
-
-impl<P: SseEventProducer + 'static> SseState<P> {
-    /// Create new SSE state with an event producer
-    ///
-    /// Creates a new state without event validation schema.
-    /// Events are not validated.
-    ///
-    /// # Arguments
-    /// * `producer` - The event producer implementation
-    ///
-    /// # Example
-    ///
-    /// ```ignore
-    /// let state = SseState::new(MyProducer);
-    /// ```
-    pub fn new(producer: P) -> Self {
-        Self {
-            producer: Arc::new(producer),
-            event_schema: None,
-        }
-    }
-
-    /// Create new SSE state with an event producer and optional event schema
-    ///
-    /// Creates a new state with optional JSON schema for validating outgoing events.
-    /// If a schema is provided and an event fails validation, it is silently dropped.
-    ///
-    /// # Arguments
-    /// * `producer` - The event producer implementation
-    /// * `event_schema` - Optional JSON schema for validating events
-    ///
-    /// # Returns
-    /// * `Ok(state)` - Successfully created state
-    /// * `Err(msg)` - Invalid schema provided
-    ///
-    /// # Example
-    ///
-    /// ```ignore
-    /// use serde_json::json;
-    ///
-    /// let event_schema = json!({
-    ///     "type": "object",
-    ///     "properties": {
-    ///         "count": {"type": "integer"}
-    ///     }
-    /// });
-    ///
-    /// let state = SseState::with_schema(MyProducer, Some(event_schema))?;
-    /// ```
-    pub fn with_schema(producer: P, event_schema: Option<serde_json::Value>) -> Result<Self, String> {
-        let event_validator = if let Some(schema) = event_schema {
-            Some(Arc::new(
-                jsonschema::validator_for(&schema).map_err(|e| format!("Invalid event schema: {}", e))?,
-            ))
-        } else {
-            None
-        };
-
-        Ok(Self {
-            producer: Arc::new(producer),
-            event_schema: event_validator,
-        })
-    }
-}
-
-/// SSE endpoint handler
-///
-/// This is the main entry point for SSE connections. Use this as an Axum route
-/// handler by passing it to an Axum router's `.route()` method with `get()`.
-///
-/// The handler establishes a connection and streams events from the producer to
-/// the client using the Server-Sent Events protocol (text/event-stream).
-///
-/// # Arguments
-/// * `State(state)` - Application state containing the event producer and optional schema
-///
-/// # Returns
-/// A streaming response with the `text/event-stream` content type
-///
-/// # Example
-///
-/// ```ignore
-/// use axum::{Router, routing::get, extract::State};
-///
-/// let state = SseState::new(MyProducer);
-/// let router = Router::new()
-///     .route("/events", get(sse_handler::<MyProducer>))
-///     .with_state(state);
-///
-/// // Client usage:
-/// // const eventSource = new EventSource('/events');
-/// // eventSource.onmessage = (e) => console.log(e.data);
-/// ```
-pub async fn sse_handler<P: SseEventProducer + 'static>(State(state): State<SseState<P>>) -> impl IntoResponse {
-    info!("SSE client connected");
-
-    state.producer.on_connect().await;
-
-    let producer = Arc::clone(&state.producer);
-    let event_schema = state.event_schema.clone();
-    let stream = stream::unfold((producer, event_schema), |(producer, event_schema)| async move {
-        match producer.next_event().await {
-            Some(sse_event) => {
-                debug!("Sending SSE event: {:?}", sse_event.event_type);
-
-                if let Some(validator) = &event_schema
-                    && !validator.is_valid(&sse_event.data)
-                {
-                    error!("SSE event validation failed");
-                    return Some((
-                        Ok::<_, Infallible>(Event::default().data("validation_error")),
-                        (producer, event_schema),
-                    ));
-                }
-
-                let event = sse_event.into_axum_event();
-                Some((Ok::<_, Infallible>(event), (producer, event_schema)))
-            }
-            None => {
-                info!("SSE stream ended");
-                producer.on_disconnect().await;
-                None
-            }
-        }
-    });
-
-    let sse_response =
-        Sse::new(stream).keep_alive(KeepAlive::new().interval(Duration::from_secs(15)).text("keep-alive"));
-
-    sse_response.into_response()
-}
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-    use std::sync::Arc;
-    use std::sync::atomic::{AtomicBool, AtomicUsize, Ordering};
-
-    struct TestProducer {
-        count: AtomicUsize,
-    }
-
-    impl SseEventProducer for TestProducer {
-        async fn next_event(&self) -> Option<SseEvent> {
-            let count = self.count.fetch_add(1, Ordering::Relaxed);
-            if count < 3 {
-                Some(SseEvent::new(serde_json::json!({
-                    "message": format!("Event {}", count)
-                })))
-            } else {
-                None
-            }
-        }
-    }
-
-    /// Producer that tracks connect/disconnect lifecycle
-    struct LifecycleProducer {
-        connect_count: Arc<AtomicUsize>,
-        disconnect_count: Arc<AtomicUsize>,
-        event_count: AtomicUsize,
-    }
-
-    impl LifecycleProducer {
-        fn new(connect: Arc<AtomicUsize>, disconnect: Arc<AtomicUsize>) -> Self {
-            Self {
-                connect_count: connect,
-                disconnect_count: disconnect,
-                event_count: AtomicUsize::new(0),
-            }
-        }
-    }
-
-    impl SseEventProducer for LifecycleProducer {
-        async fn next_event(&self) -> Option<SseEvent> {
-            let idx: usize = self.event_count.fetch_add(1, Ordering::Relaxed);
-            if idx < 2 {
-                Some(SseEvent::new(serde_json::json!({"event": idx})))
-            } else {
-                None
-            }
-        }
-
-        async fn on_connect(&self) {
-            self.connect_count.fetch_add(1, Ordering::Relaxed);
-        }
-
-        async fn on_disconnect(&self) {
-            self.disconnect_count.fetch_add(1, Ordering::Relaxed);
-        }
-    }
-
-    /// Producer for multiline event testing
-    struct MultilineProducer {
-        sent: AtomicBool,
-    }
-
-    impl SseEventProducer for MultilineProducer {
-        async fn next_event(&self) -> Option<SseEvent> {
-            let was_sent: bool = self.sent.swap(true, Ordering::Relaxed);
-            if !was_sent {
-                Some(SseEvent::new(serde_json::json!({
-                    "text": "line1\nline2\nline3"
-                })))
-            } else {
-                None
-            }
-        }
-    }
-
-    /// Producer for special characters testing
-    struct SpecialCharsProducer {
-        sent: AtomicBool,
-    }
-
-    impl SseEventProducer for SpecialCharsProducer {
-        async fn next_event(&self) -> Option<SseEvent> {
-            let was_sent: bool = self.sent.swap(true, Ordering::Relaxed);
-            if !was_sent {
-                Some(SseEvent::new(serde_json::json!({
-                    "data": "special: \"quotes\", \\ backslash, \t tab, \r\n crlf"
-                })))
-            } else {
-                None
-            }
-        }
-    }
-
-    /// Producer for large payload testing
-    struct LargePayloadProducer {
-        sent: AtomicBool,
-    }
-
-    impl SseEventProducer for LargePayloadProducer {
-        async fn next_event(&self) -> Option<SseEvent> {
-            let was_sent: bool = self.sent.swap(true, Ordering::Relaxed);
-            if !was_sent {
-                let large_string: String = "x".repeat(100_000);
-                Some(SseEvent::new(serde_json::json!({
-                    "payload": large_string
-                })))
-            } else {
-                None
-            }
-        }
-    }
-
-    /// Producer that sends many events rapidly
-    struct RapidEventProducer {
-        event_count: usize,
-        current: AtomicUsize,
-    }
-
-    impl RapidEventProducer {
-        fn new(count: usize) -> Self {
-            Self {
-                event_count: count,
-                current: AtomicUsize::new(0),
-            }
-        }
-    }
-
-    impl SseEventProducer for RapidEventProducer {
-        async fn next_event(&self) -> Option<SseEvent> {
-            let idx: usize = self.current.fetch_add(1, Ordering::Relaxed);
-            if idx < self.event_count {
-                Some(SseEvent::new(serde_json::json!({
-                    "id": idx,
-                    "data": format!("event_{}", idx)
-                })))
-            } else {
-                None
-            }
-        }
-    }
-
-    /// Producer with all event fields populated
-    struct FullFieldProducer {
-        sent: AtomicBool,
-    }
-
-    impl SseEventProducer for FullFieldProducer {
-        async fn next_event(&self) -> Option<SseEvent> {
-            let was_sent: bool = self.sent.swap(true, Ordering::Relaxed);
-            if !was_sent {
-                Some(
-                    SseEvent::with_type(
-                        "counter_update",
-                        serde_json::json!({
-                            "count": 42,
-                            "status": "active"
-                        }),
-                    )
-                    .with_id("event-123")
-                    .with_retry(5000),
-                )
-            } else {
-                None
-            }
-        }
-    }
-
-    /// Producer that ends immediately (keep-alive test)
-    struct NoEventProducer;
-
-    impl SseEventProducer for NoEventProducer {
-        async fn next_event(&self) -> Option<SseEvent> {
-            None
-        }
-    }
-
-    #[test]
-    fn test_sse_event_creation_minimal() {
-        let event: SseEvent = SseEvent::new(serde_json::json!({"test": "data"}));
-        assert!(event.event_type.is_none());
-        assert!(event.id.is_none());
-        assert!(event.retry.is_none());
-    }
-
-    #[test]
-    fn test_sse_event_with_all_fields() {
-        let event: SseEvent = SseEvent::with_type("update", serde_json::json!({"count": 42}))
-            .with_id("event-001")
-            .with_retry(3000);
-
-        assert_eq!(event.event_type, Some("update".to_string()));
-        assert_eq!(event.id, Some("event-001".to_string()));
-        assert_eq!(event.retry, Some(3000));
-    }
-
-    #[test]
-    fn test_sse_event_builder_pattern() {
-        let event: SseEvent = SseEvent::with_type("notification", serde_json::json!({"text": "hello"}))
-            .with_id("notif-456")
-            .with_retry(5000);
-
-        assert_eq!(event.event_type, Some("notification".to_string()));
-        assert_eq!(event.id, Some("notif-456".to_string()));
-        assert_eq!(event.retry, Some(5000));
-    }
-
-    #[test]
-    fn test_sse_event_multiline_data() {
-        let event: SseEvent = SseEvent::new(serde_json::json!({
-            "text": "line1\nline2\nline3"
-        }));
-
-        assert!(event.data.is_object());
-        let text: Option<&str> = event.data.get("text").and_then(|v| v.as_str());
-        assert_eq!(text, Some("line1\nline2\nline3"));
-    }
-
-    #[test]
-    fn test_sse_event_special_characters() {
-        let event: SseEvent = SseEvent::new(serde_json::json!({
-            "data": "special: \"quotes\", \\ backslash"
-        }));
-
-        assert!(event.data.is_object());
-    }
-
-    #[test]
-    fn test_sse_event_large_payload() {
-        let large_string: String = "x".repeat(100_000);
-        let event: SseEvent = SseEvent::new(serde_json::json!({
-            "payload": large_string.clone()
-        }));
-
-        let payload_field: Option<&str> = event.data.get("payload").and_then(|v| v.as_str());
-        assert_eq!(payload_field.map(|s| s.len()), Some(100_000));
-    }
-
-    #[test]
-    fn test_sse_event_into_axum_event_conversion() {
-        let event: SseEvent = SseEvent::new(serde_json::json!({"msg": "test"}));
-        let _axum_event: axum::response::sse::Event = event.into_axum_event();
-    }
-
-    #[test]
-    fn test_sse_event_into_axum_with_all_fields() {
-        let event: SseEvent = SseEvent::with_type("event", serde_json::json!({"id": 1}))
-            .with_id("123")
-            .with_retry(5000);
-
-        let _axum_event: axum::response::sse::Event = event.into_axum_event();
-    }
-
-    #[test]
-    fn test_sse_state_creation() {
-        let producer: TestProducer = TestProducer {
-            count: AtomicUsize::new(0),
-        };
-        let state: SseState<TestProducer> = SseState::new(producer);
-        let cloned: SseState<TestProducer> = state.clone();
-        assert!(Arc::ptr_eq(&state.producer, &cloned.producer));
-    }
-
-    #[test]
-    fn test_sse_state_with_schema_valid() {
-        let producer: TestProducer = TestProducer {
-            count: AtomicUsize::new(0),
-        };
-        let schema: serde_json::Value = serde_json::json!({
-            "type": "object",
-            "properties": {
-                "message": {"type": "string"}
-            }
-        });
-
-        let result: Result<SseState<TestProducer>, String> = SseState::with_schema(producer, Some(schema));
-        assert!(result.is_ok());
-    }
-
-    #[test]
-    fn test_sse_state_with_invalid_schema() {
-        let producer: TestProducer = TestProducer {
-            count: AtomicUsize::new(0),
-        };
-        let invalid_schema: serde_json::Value = serde_json::json!({
-            "type": "not-a-valid-type"
-        });
-
-        let result: Result<SseState<TestProducer>, String> = SseState::with_schema(producer, Some(invalid_schema));
-        assert!(result.is_err());
-    }
-
-    #[test]
-    fn test_sse_state_with_schema_none() {
-        let producer: TestProducer = TestProducer {
-            count: AtomicUsize::new(0),
-        };
-        let result: Result<SseState<TestProducer>, String> = SseState::with_schema(producer, None);
-        assert!(result.is_ok());
-    }
-
-    #[tokio::test]
-    async fn test_sse_lifecycle_on_connect_called() {
-        let connect_count: Arc<AtomicUsize> = Arc::new(AtomicUsize::new(0));
-        let disconnect_count: Arc<AtomicUsize> = Arc::new(AtomicUsize::new(0));
-
-        let producer: LifecycleProducer =
-            LifecycleProducer::new(Arc::clone(&connect_count), Arc::clone(&disconnect_count));
-
-        producer.on_connect().await;
-        assert_eq!(connect_count.load(Ordering::Relaxed), 1);
-    }
-
-    #[tokio::test]
-    async fn test_sse_lifecycle_on_disconnect_called() {
-        let connect_count: Arc<AtomicUsize> = Arc::new(AtomicUsize::new(0));
-        let disconnect_count: Arc<AtomicUsize> = Arc::new(AtomicUsize::new(0));
-
-        let producer: LifecycleProducer =
-            LifecycleProducer::new(Arc::clone(&connect_count), Arc::clone(&disconnect_count));
-
-        producer.on_disconnect().await;
-        assert_eq!(disconnect_count.load(Ordering::Relaxed), 1);
-    }
-
-    #[tokio::test]
-    async fn test_sse_event_ordering_preserved() {
-        let producer: RapidEventProducer = RapidEventProducer::new(10);
-
-        let mut last_idx: i32 = -1;
-        for _ in 0..10 {
-            if let Some(event) = producer.next_event().await {
-                if let Some(id) = event.data.get("id").and_then(|v| v.as_i64()) {
-                    assert!(id as i32 > last_idx, "Event ordering violated");
-                    last_idx = id as i32;
-                }
-            }
-        }
-    }
-
-    #[tokio::test]
-    async fn test_sse_rapid_event_sending() {
-        let producer: RapidEventProducer = RapidEventProducer::new(100);
-
-        let mut count: usize = 0;
-        loop {
-            match producer.next_event().await {
-                Some(_event) => count += 1,
-                None => break,
-            }
-        }
-
-        assert_eq!(count, 100);
-    }
-
-    #[test]
-    fn test_sse_event_with_empty_data_object() {
-        let event: SseEvent = SseEvent::new(serde_json::json!({}));
-        assert!(event.data.is_object());
-    }
-
-    #[test]
-    fn test_sse_event_with_nested_data() {
-        let event: SseEvent = SseEvent::new(serde_json::json!({
-            "nested": {
-                "deep": {
-                    "value": "found"
-                }
-            }
-        }));
-
-        let deep_value: Option<&str> = event
-            .data
-            .get("nested")
-            .and_then(|v| v.get("deep"))
-            .and_then(|v| v.get("value"))
-            .and_then(|v| v.as_str());
-
-        assert_eq!(deep_value, Some("found"));
-    }
-
-    #[tokio::test]
-    async fn test_sse_producer_stream_ends_cleanly() {
-        let producer: NoEventProducer = NoEventProducer;
-
-        let event1: Option<SseEvent> = producer.next_event().await;
-        assert!(event1.is_none());
-
-        let event2: Option<SseEvent> = producer.next_event().await;
-        assert!(event2.is_none());
-    }
-
-    #[test]
-    fn test_sse_event_clone() {
-        let original: SseEvent = SseEvent::with_type("test", serde_json::json!({"data": "test"}))
-            .with_id("id-1")
-            .with_retry(2000);
-
-        let cloned: SseEvent = original.clone();
-
-        assert_eq!(cloned.event_type, original.event_type);
-        assert_eq!(cloned.id, original.id);
-        assert_eq!(cloned.retry, original.retry);
-        assert_eq!(cloned.data, original.data);
-    }
-
-    #[test]
-    fn test_sse_event_debug_impl() {
-        let event: SseEvent = SseEvent::new(serde_json::json!({"msg": "debug"}));
-        let debug_str: String = format!("{:?}", event);
-        assert!(debug_str.contains("SseEvent"));
-    }
-
-    #[tokio::test]
-    async fn test_sse_multiple_producers_independent() {
-        let producer1: TestProducer = TestProducer {
-            count: AtomicUsize::new(0),
-        };
-        let producer2: TestProducer = TestProducer {
-            count: AtomicUsize::new(0),
-        };
-
-        let _event1: Option<SseEvent> = producer1.next_event().await;
-        let _event2: Option<SseEvent> = producer2.next_event().await;
-
-        let count1: usize = producer1.count.load(Ordering::Relaxed);
-        let count2: usize = producer2.count.load(Ordering::Relaxed);
-
-        assert_eq!(count1, 1);
-        assert_eq!(count2, 1);
-    }
-
-    #[test]
-    fn test_sse_state_cloning_preserves_schema() {
-        let producer: TestProducer = TestProducer {
-            count: AtomicUsize::new(0),
-        };
-        let schema: serde_json::Value = serde_json::json!({
-            "type": "object",
-            "properties": {
-                "message": {"type": "string"}
-            }
-        });
-
-        let state: SseState<TestProducer> =
-            SseState::with_schema(producer, Some(schema)).expect("schema should be valid");
-        let cloned: SseState<TestProducer> = state.clone();
-
-        assert!(Arc::ptr_eq(&state.producer, &cloned.producer));
-        match (&state.event_schema, &cloned.event_schema) {
-            (Some(s1), Some(s2)) => {
-                assert!(Arc::ptr_eq(s1, s2));
-            }
-            _ => panic!("Schema should be preserved in clone"),
-        }
-    }
-
-    #[tokio::test]
-    async fn test_sse_large_payload_integrity() {
-        let producer: LargePayloadProducer = LargePayloadProducer {
-            sent: AtomicBool::new(false),
-        };
-
-        let event: Option<SseEvent> = producer.next_event().await;
-        assert!(event.is_some());
-
-        if let Some(evt) = event {
-            let payload: Option<&str> = evt.data.get("payload").and_then(|v| v.as_str());
-            assert_eq!(payload.map(|s| s.len()), Some(100_000));
-        }
-    }
-
-    #[tokio::test]
-    async fn test_sse_multiline_data_preservation() {
-        let producer: MultilineProducer = MultilineProducer {
-            sent: AtomicBool::new(false),
-        };
-
-        let event: Option<SseEvent> = producer.next_event().await;
-        assert!(event.is_some());
-
-        if let Some(evt) = event {
-            let text: Option<&str> = evt.data.get("text").and_then(|v| v.as_str());
-            assert_eq!(text, Some("line1\nline2\nline3"));
-        }
-    }
-
-    #[tokio::test]
-    async fn test_sse_special_chars_in_payload() {
-        let producer: SpecialCharsProducer = SpecialCharsProducer {
-            sent: AtomicBool::new(false),
-        };
-
-        let event: Option<SseEvent> = producer.next_event().await;
-        assert!(event.is_some());
-
-        if let Some(evt) = event {
-            let data: Option<&str> = evt.data.get("data").and_then(|v| v.as_str());
-            assert!(data.is_some());
-            assert!(data.unwrap().contains("quotes"));
-        }
-    }
-
-    #[tokio::test]
-    async fn test_sse_full_event_fields_together() {
-        let producer: FullFieldProducer = FullFieldProducer {
-            sent: AtomicBool::new(false),
-        };
-
-        let event: Option<SseEvent> = producer.next_event().await;
-        assert!(event.is_some());
-
-        if let Some(evt) = event {
-            assert_eq!(evt.event_type, Some("counter_update".to_string()));
-            assert_eq!(evt.id, Some("event-123".to_string()));
-            assert_eq!(evt.retry, Some(5000));
-            assert_eq!(evt.data.get("count").and_then(|v| v.as_i64()), Some(42));
-        }
-    }
-
-    #[test]
-    fn test_sse_event_to_axum_preserves_data() {
-        let event = SseEvent::new(serde_json::json!({"key": "value"}));
-        let _axum_event: axum::response::sse::Event = event.into_axum_event();
-    }
-
-    #[test]
-    fn test_sse_event_data_only_no_metadata() {
-        let event = SseEvent::new(serde_json::json!({"message": "hello"}));
-        assert!(event.event_type.is_none(), "event_type should be None");
-        assert!(event.id.is_none(), "id should be None");
-        assert!(event.retry.is_none(), "retry should be None");
-
-        let _axum_event: axum::response::sse::Event = event.into_axum_event();
-    }
-
-    #[test]
-    fn test_sse_event_with_all_fields_filled() {
-        let event = SseEvent::with_type("update", serde_json::json!({"status": "ok"}))
-            .with_id("evt-999")
-            .with_retry(10000);
-
-        assert_eq!(event.event_type.as_ref(), Some(&"update".to_string()));
-        assert_eq!(event.id.as_ref(), Some(&"evt-999".to_string()));
-        assert_eq!(event.retry, Some(10000));
-
-        let _axum_event: axum::response::sse::Event = event.into_axum_event();
-    }
-
-    #[test]
-    fn test_sse_event_empty_data_field() {
-        let event = SseEvent::new(serde_json::json!({}));
-        assert!(event.data.is_object());
-        assert_eq!(event.data.as_object().unwrap().len(), 0);
-
-        let _axum_event: axum::response::sse::Event = event.into_axum_event();
-    }
-
-    #[test]
-    fn test_sse_event_data_with_newlines_in_string() {
-        let multiline_data = "first line\nsecond line\nthird line";
-        let event = SseEvent::new(serde_json::json!({"text": multiline_data}));
-
-        let stored_text = event.data.get("text").and_then(|v| v.as_str());
-        assert_eq!(stored_text, Some(multiline_data));
-
-        let _axum_event: axum::response::sse::Event = event.into_axum_event();
-    }
-
-    #[test]
-    fn test_sse_event_data_with_colons() {
-        let data_with_colons = "key1: value1, key2: value2";
-        let event = SseEvent::new(serde_json::json!({"data": data_with_colons}));
-
-        let stored_data = event.data.get("data").and_then(|v| v.as_str());
-        assert_eq!(stored_data, Some(data_with_colons));
-
-        let _axum_event: axum::response::sse::Event = event.into_axum_event();
-    }
-
-    #[test]
-    fn test_sse_event_comment_only_structure() {
-        let event = SseEvent::new(serde_json::json!({"comment": "this is a comment"}));
-        let _axum_event: axum::response::sse::Event = event.into_axum_event();
-    }
-
-    #[test]
-    fn test_sse_event_type_with_spaces() {
-        let event = SseEvent::with_type("event type with spaces", serde_json::json!({"data": "test"}));
-        assert_eq!(event.event_type, Some("event type with spaces".to_string()));
-
-        let _axum_event: axum::response::sse::Event = event.into_axum_event();
-    }
-
-    #[test]
-    fn test_sse_event_type_with_special_chars() {
-        let event_types = vec!["update-v2", "event_123", "message.sent", "type-with-dash"];
-
-        for event_type in event_types {
-            let event = SseEvent::with_type(event_type, serde_json::json!({"data": "test"}));
-            assert_eq!(event.event_type.as_ref(), Some(&event_type.to_string()));
-
-            let _axum_event: axum::response::sse::Event = event.into_axum_event();
-        }
-    }
-
-    #[test]
-    fn test_sse_event_id_alphanumeric() {
-        let ids = vec!["123", "abc-def", "event_001", "id-with-dashes-123"];
-
-        for id in ids {
-            let event = SseEvent::new(serde_json::json!({"data": "test"})).with_id(id);
-            assert_eq!(event.id.as_ref(), Some(&id.to_string()));
-
-            let _axum_event: axum::response::sse::Event = event.into_axum_event();
-        }
-    }
-
-    #[test]
-    fn test_sse_event_retry_zero() {
-        let event = SseEvent::new(serde_json::json!({"data": "test"})).with_retry(0);
-        assert_eq!(event.retry, Some(0));
-
-        let _axum_event: axum::response::sse::Event = event.into_axum_event();
-    }
-
-    #[test]
-    fn test_sse_event_retry_small_value() {
-        let event = SseEvent::new(serde_json::json!({"data": "test"})).with_retry(100);
-        assert_eq!(event.retry, Some(100));
-
-        let _axum_event: axum::response::sse::Event = event.into_axum_event();
-    }
-
-    #[test]
-    fn test_sse_event_retry_large_value() {
-        let large_retry = u64::MAX / 2;
-        let event = SseEvent::new(serde_json::json!({"data": "test"})).with_retry(large_retry);
-        assert_eq!(event.retry, Some(large_retry));
-
-        let _axum_event: axum::response::sse::Event = event.into_axum_event();
-    }
-
-    #[test]
-    fn test_sse_event_retry_typical_values() {
-        let typical_retries = vec![1000, 3000, 5000, 10000, 30000];
-
-        for retry_ms in typical_retries {
-            let event = SseEvent::new(serde_json::json!({"data": "test"})).with_retry(retry_ms);
-            assert_eq!(event.retry, Some(retry_ms));
-
-            let _axum_event: axum::response::sse::Event = event.into_axum_event();
-        }
-    }
-
-    #[test]
-    fn test_sse_event_utf8_emoji_in_data() {
-        let emoji_data = "Hello 👋 World 🌍";
-        let event = SseEvent::new(serde_json::json!({"text": emoji_data}));
-
-        let stored = event.data.get("text").and_then(|v| v.as_str());
-        assert_eq!(stored, Some(emoji_data));
-
-        let _axum_event: axum::response::sse::Event = event.into_axum_event();
-    }
-
-    #[test]
-    fn test_sse_event_utf8_chinese_characters() {
-        let chinese_text = "你好世界";
-        let event = SseEvent::new(serde_json::json!({"text": chinese_text}));
-
-        let stored = event.data.get("text").and_then(|v| v.as_str());
-        assert_eq!(stored, Some(chinese_text));
-
-        let _axum_event: axum::response::sse::Event = event.into_axum_event();
-    }
-
-    #[test]
-    fn test_sse_event_utf8_arabic_characters() {
-        let arabic_text = "مرحبا بالعالم";
-        let event = SseEvent::new(serde_json::json!({"text": arabic_text}));
-
-        let stored = event.data.get("text").and_then(|v| v.as_str());
-        assert_eq!(stored, Some(arabic_text));
-
-        let _axum_event: axum::response::sse::Event = event.into_axum_event();
-    }
-
-    #[test]
-    fn test_sse_event_utf8_mixed_scripts() {
-        let mixed = "Hello 你好 مرحبا 👋";
-        let event = SseEvent::new(serde_json::json!({"text": mixed}));
-
-        let stored = event.data.get("text").and_then(|v| v.as_str());
-        assert_eq!(stored, Some(mixed));
-
-        let _axum_event: axum::response::sse::Event = event.into_axum_event();
-    }
-
-    #[test]
-    fn test_sse_event_json_serialization_produces_valid_utf8() {
-        let event = SseEvent::new(serde_json::json!({"text": "test"}));
-        let _axum_event: axum::response::sse::Event = event.into_axum_event();
-    }
-
-    #[test]
-    fn test_sse_event_64kb_payload() {
-        let large_data = "x".repeat(65536);
-        let event = SseEvent::new(serde_json::json!({"payload": large_data.clone()}));
-
-        let stored = event.data.get("payload").and_then(|v| v.as_str());
-        assert_eq!(stored.map(|s| s.len()), Some(65536));
-
-        let _axum_event: axum::response::sse::Event = event.into_axum_event();
-    }
-
-    #[test]
-    fn test_sse_event_1mb_payload() {
-        let large_data = "y".repeat(1_000_000);
-        let event = SseEvent::new(serde_json::json!({"payload": large_data.clone()}));
-
-        let stored = event.data.get("payload").and_then(|v| v.as_str());
-        assert_eq!(stored.map(|s| s.len()), Some(1_000_000));
-
-        let _axum_event: axum::response::sse::Event = event.into_axum_event();
-    }
-
-    #[test]
-    fn test_sse_event_deeply_nested_json() {
-        let deeply_nested = serde_json::json!({
-            "level1": {
-                "level2": {
-                    "level3": {
-                        "level4": {
-                            "level5": {
-                                "level6": {
-                                    "level7": {
-                                        "value": "deep"
-                                    }
-                                }
-                            }
-                        }
-                    }
-                }
-            }
-        });
-
-        let event = SseEvent::new(deeply_nested);
-        let _axum_event: axum::response::sse::Event = event.into_axum_event();
-    }
-
-    #[test]
-    fn test_sse_event_array_in_data() {
-        let event = SseEvent::new(serde_json::json!({
-            "items": [1, 2, 3, 4, 5]
-        }));
-
-        let items = event.data.get("items").and_then(|v| v.as_array());
-        assert!(items.is_some());
-        assert_eq!(items.unwrap().len(), 5);
-
-        let _axum_event: axum::response::sse::Event = event.into_axum_event();
-    }
-
-    #[test]
-    fn test_sse_event_null_value_in_data() {
-        let event = SseEvent::new(serde_json::json!({
-            "nullable": null
-        }));
-
-        assert!(event.data.get("nullable").unwrap().is_null());
-
-        let _axum_event: axum::response::sse::Event = event.into_axum_event();
-    }
-
-    #[test]
-    fn test_sse_event_boolean_values() {
-        let event = SseEvent::new(serde_json::json!({
-            "active": true,
-            "deleted": false
-        }));
-
-        assert_eq!(event.data.get("active").and_then(|v| v.as_bool()), Some(true));
-        assert_eq!(event.data.get("deleted").and_then(|v| v.as_bool()), Some(false));
-
-        let _axum_event: axum::response::sse::Event = event.into_axum_event();
-    }
-
-    #[tokio::test]
-    async fn test_sse_last_event_id_header_simulation() {
-        let producer = RapidEventProducer::new(5);
-
-        let mut events = Vec::new();
-        for _ in 0..5 {
-            if let Some(evt) = producer.next_event().await {
-                events.push(evt);
-            }
-        }
-
-        assert_eq!(events.len(), 5);
-    }
-
-    #[tokio::test]
-    async fn test_sse_retry_timeout_specification() {
-        let producer = FullFieldProducer {
-            sent: AtomicBool::new(false),
-        };
-
-        let event = producer.next_event().await;
-        assert!(event.is_some());
-
-        if let Some(evt) = event {
-            assert_eq!(evt.retry, Some(5000), "Retry should be 5000ms");
-        }
-    }
-
-    #[test]
-    fn test_sse_event_builder_method_chaining() {
-        let event = SseEvent::new(serde_json::json!({"data": "test"}))
-            .with_id("id-1")
-            .with_retry(3000);
-
-        assert_eq!(event.id, Some("id-1".to_string()));
-        assert_eq!(event.retry, Some(3000));
-
-        let event2 = SseEvent::with_type("msg", serde_json::json!({"x": 1}))
-            .with_id("id-2")
-            .with_retry(5000);
-
-        assert_eq!(event2.event_type, Some("msg".to_string()));
-        assert_eq!(event2.id, Some("id-2".to_string()));
-        assert_eq!(event2.retry, Some(5000));
-    }
-
-    #[test]
-    fn test_sse_event_overwriting_fields() {
-        let event = SseEvent::new(serde_json::json!({"v": 1}))
-            .with_id("id-original")
-            .with_retry(1000);
-
-        assert_eq!(event.id, Some("id-original".to_string()));
-        assert_eq!(event.retry, Some(1000));
-    }
-
-    #[test]
-    fn test_sse_event_type_empty_string() {
-        let event = SseEvent::with_type("", serde_json::json!({"data": "test"}));
-        assert_eq!(event.event_type, Some("".to_string()));
-
-        let _axum_event: axum::response::sse::Event = event.into_axum_event();
-    }
-
-    #[test]
-    fn test_sse_event_id_empty_string() {
-        let event = SseEvent::new(serde_json::json!({"data": "test"})).with_id("");
-        assert_eq!(event.id, Some("".to_string()));
-
-        let _axum_event: axum::response::sse::Event = event.into_axum_event();
-    }
-
-    #[tokio::test]
-    async fn test_sse_event_sequence_maintains_order() {
-        let producer = RapidEventProducer::new(10);
-
-        let mut event_ids = Vec::new();
-        for _ in 0..10 {
-            if let Some(evt) = producer.next_event().await {
-                if let Some(id) = evt.data.get("id").and_then(|v| v.as_i64()) {
-                    event_ids.push(id);
-                }
-            }
-        }
-
-        for i in 0..event_ids.len() {
-            assert_eq!(event_ids[i], i as i64, "Event order should match insertion order");
-        }
-    }
-
-    #[tokio::test]
-    async fn test_sse_rapid_events_no_loss() {
-        let producer = RapidEventProducer::new(50);
-
-        let mut count = 0;
-        loop {
-            match producer.next_event().await {
-                Some(_) => count += 1,
-                None => break,
-            }
-        }
-
-        assert_eq!(count, 50, "All events should be produced without loss");
-    }
-
-    #[tokio::test]
-    async fn test_sse_event_batching_simulation() {
-        let producer = RapidEventProducer::new(20);
-
-        let mut batch_size = 0;
-        let mut batch_count = 0;
-
-        loop {
-            match producer.next_event().await {
-                Some(_evt) => {
-                    batch_size += 1;
-                    if batch_size >= 5 {
-                        batch_count += 1;
-                        batch_size = 0;
-                    }
-                }
-                None => {
-                    if batch_size > 0 {
-                        batch_count += 1;
-                    }
-                    break;
-                }
-            }
-        }
-
-        assert!(batch_count >= 4, "Should have processed at least 4 batches");
-    }
-
-    #[test]
-    fn test_sse_state_arc_sharing() {
-        let producer = TestProducer {
-            count: AtomicUsize::new(0),
-        };
-        let state1 = SseState::new(producer);
-        let state2 = state1.clone();
-        let state3 = state2.clone();
-
-        assert!(Arc::ptr_eq(&state1.producer, &state2.producer));
-        assert!(Arc::ptr_eq(&state2.producer, &state3.producer));
-    }
-
-    #[test]
-    fn test_sse_state_schema_arc_sharing() {
-        let producer = TestProducer {
-            count: AtomicUsize::new(0),
-        };
-        let schema = serde_json::json!({
-            "type": "object"
-        });
-
-        let state1 = SseState::with_schema(producer, Some(schema)).expect("schema should be valid");
-        let state2 = state1.clone();
-
-        match (&state1.event_schema, &state2.event_schema) {
-            (Some(s1), Some(s2)) => {
-                assert!(Arc::ptr_eq(s1, s2));
-            }
-            _ => panic!("Both states should have schema"),
-        }
-    }
-
-    #[test]
-    fn test_sse_event_into_axum_event_numeric_data() {
-        let event = SseEvent::new(serde_json::json!({
-            "count": 42,
-            "temperature": 98.6,
-            "negative": -273
-        }));
-
-        let _axum_event: axum::response::sse::Event = event.into_axum_event();
-    }
-
-    #[test]
-    fn test_sse_event_json_number_precision() {
-        let event = SseEvent::new(serde_json::json!({
-            "float": 3.14159265359,
-            "large_int": 9007199254740991i64
-        }));
-
-        assert_eq!(event.data.get("float").and_then(|v| v.as_f64()), Some(3.14159265359));
-
-        let _axum_event: axum::response::sse::Event = event.into_axum_event();
-    }
-
-    #[test]
-    fn test_sse_event_string_escaping() {
-        let event = SseEvent::new(serde_json::json!({
-            "escaped": "line1\nline2\ttab",
-            "quotes": "He said \"hello\"",
-            "backslash": "path\\to\\file"
-        }));
-
-        let _axum_event: axum::response::sse::Event = event.into_axum_event();
-    }
-
-    #[test]
-    fn test_sse_event_all_json_types_combined() {
-        let event = SseEvent::new(serde_json::json!({
-            "string": "text",
-            "number": 123,
-            "float": 1.5,
-            "boolean": true,
-            "null_value": null,
-            "array": [1, 2, 3],
-            "object": {
-                "nested": "value"
-            }
-        }));
-
-        let _axum_event: axum::response::sse::Event = event.into_axum_event();
-    }
-}
+//! Server-Sent Events (SSE) support for Spikard
+//!
+//! Provides SSE streaming with event generation and lifecycle management.
+
+use axum::{
+    extract::State,
+    response::{
+        IntoResponse,
+        sse::{Event, KeepAlive, Sse},
+    },
+};
+use futures_util::stream;
+use serde_json::Value;
+use std::{convert::Infallible, sync::Arc, time::Duration};
+use tracing::{debug, error, info};
+
+/// SSE event producer trait
+///
+/// Implement this trait to create custom Server-Sent Event (SSE) producers for your application.
+/// The producer generates events that are streamed to connected clients.
+///
+/// # Understanding SSE
+///
+/// Server-Sent Events (SSE) provide one-way communication from server to client over HTTP.
+/// Unlike WebSocket, SSE uses standard HTTP and automatically handles reconnection.
+/// Use SSE when you need to push data to clients without bidirectional communication.
+///
+/// # Implementing the Trait
+///
+/// You must implement the `next_event` method to generate events. The `on_connect` and
+/// `on_disconnect` methods are optional lifecycle hooks.
+///
+/// # Example
+///
+/// ```ignore
+/// use spikard_http::sse::{SseEventProducer, SseEvent};
+/// use serde_json::json;
+/// use std::time::Duration;
+/// use tokio::time::sleep;
+///
+/// struct CounterProducer {
+///     limit: usize,
+/// }
+///
+/// #[async_trait]
+/// impl SseEventProducer for CounterProducer {
+///     async fn next_event(&self) -> Option<SseEvent> {
+///         static COUNTER: std::sync::atomic::AtomicUsize = std::sync::atomic::AtomicUsize::new(0);
+///
+///         let count = COUNTER.fetch_add(1, std::sync::atomic::Ordering::Relaxed);
+///         if count < self.limit {
+///             Some(SseEvent::new(json!({"count": count})))
+///         } else {
+///             None
+///         }
+///     }
+///
+///     async fn on_connect(&self) {
+///         println!("Client connected");
+///     }
+///
+///     async fn on_disconnect(&self) {
+///         println!("Client disconnected");
+///     }
+/// }
+/// ```
+pub trait SseEventProducer: Send + Sync {
+    /// Generate the next event
+    ///
+    /// Called repeatedly to produce the event stream. Should return `Some(event)` when
+    /// an event is ready to send, or `None` when the stream should end.
+    ///
+    /// # Returns
+    /// * `Some(event)` - Event to send to the client
+    /// * `None` - Stream complete, connection will close
+    fn next_event(&self) -> impl std::future::Future<Output = Option<SseEvent>> + Send;
+
+    /// Called when a client connects to the SSE endpoint
+    ///
+    /// Optional lifecycle hook invoked when a new SSE connection is established.
+    /// Default implementation does nothing.
+    fn on_connect(&self) -> impl std::future::Future<Output = ()> + Send {
+        async {}
+    }
+
+    /// Called when a client disconnects from the SSE endpoint
+    ///
+    /// Optional lifecycle hook invoked when an SSE connection is closed (either by the
+    /// client or the stream ending). Default implementation does nothing.
+    fn on_disconnect(&self) -> impl std::future::Future<Output = ()> + Send {
+        async {}
+    }
+}
+
+/// An individual SSE event
+///
+/// Represents a single Server-Sent Event to be sent to a connected client.
+/// Events can have an optional type, ID, and retry timeout for advanced scenarios.
+///
+/// # Fields
+///
+/// * `event_type` - Optional event type string (used for client-side event filtering)
+/// * `data` - JSON data payload to send to the client
+/// * `id` - Optional event ID (clients can use this to resume after disconnect)
+/// * `retry` - Optional retry timeout in milliseconds (tells client when to reconnect)
+///
+/// # SSE Format
+///
+/// Events are serialized to the following text format:
+/// ```text
+/// event: event_type
+/// data: {"json":"value"}
+/// id: event-123
+/// retry: 3000
+/// ```
+#[derive(Debug, Clone)]
+pub struct SseEvent {
+    /// Event type (optional)
+    pub event_type: Option<String>,
+    /// Event data (JSON value)
+    pub data: Value,
+    /// Event ID (optional, for client-side reconnection)
+    pub id: Option<String>,
+    /// Retry timeout in milliseconds (optional)
+    pub retry: Option<u64>,
+}
+
+impl SseEvent {
+    /// Create a new SSE event with data only
+    ///
+    /// Creates a minimal event with just the data payload. Use builder methods
+    /// to add optional fields.
+    ///
+    /// # Arguments
+    /// * `data` - JSON value to send to the client
+    ///
+    /// # Example
+    ///
+    /// ```ignore
+    /// use serde_json::json;
+    /// use spikard_http::sse::SseEvent;
+    ///
+    /// let event = SseEvent::new(json!({"status": "connected"}));
+    /// ```
+    pub fn new(data: Value) -> Self {
+        Self {
+            event_type: None,
+            data,
+            id: None,
+            retry: None,
+        }
+    }
+
+    /// Create a new SSE event with an event type and data
+    ///
+    /// Creates an event with a type field. Clients can filter events by type
+    /// in their event listener.
+    ///
+    /// # Arguments
+    /// * `event_type` - String identifying the event type (e.g., "update", "error")
+    /// * `data` - JSON value to send to the client
+    ///
+    /// # Example
+    ///
+    /// ```ignore
+    /// use serde_json::json;
+    /// use spikard_http::sse::SseEvent;
+    ///
+    /// let event = SseEvent::with_type("update", json!({"count": 42}));
+    /// // Client can listen with: eventSource.addEventListener("update", ...)
+    /// ```
+    pub fn with_type(event_type: impl Into<String>, data: Value) -> Self {
+        Self {
+            event_type: Some(event_type.into()),
+            data,
+            id: None,
+            retry: None,
+        }
+    }
+
+    /// Set the event ID for client-side reconnection support
+    ///
+    /// Sets an ID that clients can use to resume from this point if they disconnect.
+    /// The client sends this ID back in the `Last-Event-ID` header when reconnecting.
+    ///
+    /// # Arguments
+    /// * `id` - Unique identifier for this event
+    ///
+    /// # Example
+    ///
+    /// ```ignore
+    /// use serde_json::json;
+    /// use spikard_http::sse::SseEvent;
+    ///
+    /// let event = SseEvent::new(json!({"count": 1}))
+    ///     .with_id("event-1");
+    /// ```
+    pub fn with_id(mut self, id: impl Into<String>) -> Self {
+        self.id = Some(id.into());
+        self
+    }
+
+    /// Set the retry timeout for client reconnection
+    ///
+    /// Sets the time in milliseconds clients should wait before attempting to reconnect
+    /// if the connection is lost. The client browser will automatically handle reconnection.
+    ///
+    /// # Arguments
+    /// * `retry_ms` - Retry timeout in milliseconds
+    ///
+    /// # Example
+    ///
+    /// ```ignore
+    /// use serde_json::json;
+    /// use spikard_http::sse::SseEvent;
+    ///
+    /// let event = SseEvent::new(json!({"data": "value"}))
+    ///     .with_retry(5000); // Reconnect after 5 seconds
+    /// ```
+    pub fn with_retry(mut self, retry_ms: u64) -> Self {
+        self.retry = Some(retry_ms);
+        self
+    }
+
+    /// Convert to Axum's SSE Event
+    fn into_axum_event(self) -> Event {
+        let json_data = match serde_json::to_string(&self.data) {
+            Ok(json) => json,
+            Err(e) => {
+                error!("Failed to serialize SSE event data: {}", e);
+                "null".to_string()
+            }
+        };
+
+        let mut event = Event::default().data(json_data);
+
+        if let Some(event_type) = self.event_type {
+            event = event.event(event_type);
+        }
+
+        if let Some(id) = self.id {
+            event = event.id(id);
+        }
+
+        if let Some(retry) = self.retry {
+            event = event.retry(Duration::from_millis(retry));
+        }
+
+        event
+    }
+}
+
+/// SSE state shared across connections
+///
+/// Contains the event producer and optional JSON schema for validating
+/// events. This state is shared among all connections to the same SSE endpoint.
+pub struct SseState<P: SseEventProducer> {
+    /// The event producer implementation
+    producer: Arc<P>,
+    /// Optional JSON Schema for validating outgoing events
+    event_schema: Option<Arc<jsonschema::Validator>>,
+}
+
+impl<P: SseEventProducer> Clone for SseState<P> {
+    fn clone(&self) -> Self {
+        Self {
+            producer: Arc::clone(&self.producer),
+            event_schema: self.event_schema.clone(),
+        }
+    }
+}
+
+impl<P: SseEventProducer + 'static> SseState<P> {
+    /// Create new SSE state with an event producer
+    ///
+    /// Creates a new state without event validation schema.
+    /// Events are not validated.
+    ///
+    /// # Arguments
+    /// * `producer` - The event producer implementation
+    ///
+    /// # Example
+    ///
+    /// ```ignore
+    /// let state = SseState::new(MyProducer);
+    /// ```
+    pub fn new(producer: P) -> Self {
+        Self {
+            producer: Arc::new(producer),
+            event_schema: None,
+        }
+    }
+
+    /// Create new SSE state with an event producer and optional event schema
+    ///
+    /// Creates a new state with optional JSON schema for validating outgoing events.
+    /// If a schema is provided and an event fails validation, it is silently dropped.
+    ///
+    /// # Arguments
+    /// * `producer` - The event producer implementation
+    /// * `event_schema` - Optional JSON schema for validating events
+    ///
+    /// # Returns
+    /// * `Ok(state)` - Successfully created state
+    /// * `Err(msg)` - Invalid schema provided
+    ///
+    /// # Example
+    ///
+    /// ```ignore
+    /// use serde_json::json;
+    ///
+    /// let event_schema = json!({
+    ///     "type": "object",
+    ///     "properties": {
+    ///         "count": {"type": "integer"}
+    ///     }
+    /// });
+    ///
+    /// let state = SseState::with_schema(MyProducer, Some(event_schema))?;
+    /// ```
+    pub fn with_schema(producer: P, event_schema: Option<serde_json::Value>) -> Result<Self, String> {
+        let event_validator = if let Some(schema) = event_schema {
+            Some(Arc::new(
+                jsonschema::validator_for(&schema).map_err(|e| format!("Invalid event schema: {}", e))?,
+            ))
+        } else {
+            None
+        };
+
+        Ok(Self {
+            producer: Arc::new(producer),
+            event_schema: event_validator,
+        })
+    }
+}
+
+/// SSE endpoint handler
+///
+/// This is the main entry point for SSE connections. Use this as an Axum route
+/// handler by passing it to an Axum router's `.route()` method with `get()`.
+///
+/// The handler establishes a connection and streams events from the producer to
+/// the client using the Server-Sent Events protocol (text/event-stream).
+///
+/// # Arguments
+/// * `State(state)` - Application state containing the event producer and optional schema
+///
+/// # Returns
+/// A streaming response with the `text/event-stream` content type
+///
+/// # Example
+///
+/// ```ignore
+/// use axum::{Router, routing::get, extract::State};
+///
+/// let state = SseState::new(MyProducer);
+/// let router = Router::new()
+///     .route("/events", get(sse_handler::<MyProducer>))
+///     .with_state(state);
+///
+/// // Client usage:
+/// // const eventSource = new EventSource('/events');
+/// // eventSource.onmessage = (e) => console.log(e.data);
+/// ```
+pub async fn sse_handler<P: SseEventProducer + 'static>(State(state): State<SseState<P>>) -> impl IntoResponse {
+    info!("SSE client connected");
+
+    state.producer.on_connect().await;
+
+    let producer = Arc::clone(&state.producer);
+    let event_schema = state.event_schema.clone();
+    let stream = stream::unfold((producer, event_schema), |(producer, event_schema)| async move {
+        match producer.next_event().await {
+            Some(sse_event) => {
+                debug!("Sending SSE event: {:?}", sse_event.event_type);
+
+                if let Some(validator) = &event_schema
+                    && !validator.is_valid(&sse_event.data)
+                {
+                    error!("SSE event validation failed");
+                    return Some((
+                        Ok::<_, Infallible>(Event::default().data("validation_error")),
+                        (producer, event_schema),
+                    ));
+                }
+
+                let event = sse_event.into_axum_event();
+                Some((Ok::<_, Infallible>(event), (producer, event_schema)))
+            }
+            None => {
+                info!("SSE stream ended");
+                producer.on_disconnect().await;
+                None
+            }
+        }
+    });
+
+    let sse_response =
+        Sse::new(stream).keep_alive(KeepAlive::new().interval(Duration::from_secs(15)).text("keep-alive"));
+
+    sse_response.into_response()
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::sync::Arc;
+    use std::sync::atomic::{AtomicBool, AtomicUsize, Ordering};
+
+    struct TestProducer {
+        count: AtomicUsize,
+    }
+
+    impl SseEventProducer for TestProducer {
+        async fn next_event(&self) -> Option<SseEvent> {
+            let count = self.count.fetch_add(1, Ordering::Relaxed);
+            if count < 3 {
+                Some(SseEvent::new(serde_json::json!({
+                    "message": format!("Event {}", count)
+                })))
+            } else {
+                None
+            }
+        }
+    }
+
+    /// Producer that tracks connect/disconnect lifecycle
+    struct LifecycleProducer {
+        connect_count: Arc<AtomicUsize>,
+        disconnect_count: Arc<AtomicUsize>,
+        event_count: AtomicUsize,
+    }
+
+    impl LifecycleProducer {
+        fn new(connect: Arc<AtomicUsize>, disconnect: Arc<AtomicUsize>) -> Self {
+            Self {
+                connect_count: connect,
+                disconnect_count: disconnect,
+                event_count: AtomicUsize::new(0),
+            }
+        }
+    }
+
+    impl SseEventProducer for LifecycleProducer {
+        async fn next_event(&self) -> Option<SseEvent> {
+            let idx: usize = self.event_count.fetch_add(1, Ordering::Relaxed);
+            if idx < 2 {
+                Some(SseEvent::new(serde_json::json!({"event": idx})))
+            } else {
+                None
+            }
+        }
+
+        async fn on_connect(&self) {
+            self.connect_count.fetch_add(1, Ordering::Relaxed);
+        }
+
+        async fn on_disconnect(&self) {
+            self.disconnect_count.fetch_add(1, Ordering::Relaxed);
+        }
+    }
+
+    /// Producer for multiline event testing
+    struct MultilineProducer {
+        sent: AtomicBool,
+    }
+
+    impl SseEventProducer for MultilineProducer {
+        async fn next_event(&self) -> Option<SseEvent> {
+            let was_sent: bool = self.sent.swap(true, Ordering::Relaxed);
+            if !was_sent {
+                Some(SseEvent::new(serde_json::json!({
+                    "text": "line1\nline2\nline3"
+                })))
+            } else {
+                None
+            }
+        }
+    }
+
+    /// Producer for special characters testing
+    struct SpecialCharsProducer {
+        sent: AtomicBool,
+    }
+
+    impl SseEventProducer for SpecialCharsProducer {
+        async fn next_event(&self) -> Option<SseEvent> {
+            let was_sent: bool = self.sent.swap(true, Ordering::Relaxed);
+            if !was_sent {
+                Some(SseEvent::new(serde_json::json!({
+                    "data": "special: \"quotes\", \\ backslash, \t tab, \r\n crlf"
+                })))
+            } else {
+                None
+            }
+        }
+    }
+
+    /// Producer for large payload testing
+    struct LargePayloadProducer {
+        sent: AtomicBool,
+    }
+
+    impl SseEventProducer for LargePayloadProducer {
+        async fn next_event(&self) -> Option<SseEvent> {
+            let was_sent: bool = self.sent.swap(true, Ordering::Relaxed);
+            if !was_sent {
+                let large_string: String = "x".repeat(100_000);
+                Some(SseEvent::new(serde_json::json!({
+                    "payload": large_string
+                })))
+            } else {
+                None
+            }
+        }
+    }
+
+    /// Producer that sends many events rapidly
+    struct RapidEventProducer {
+        event_count: usize,
+        current: AtomicUsize,
+    }
+
+    impl RapidEventProducer {
+        fn new(count: usize) -> Self {
+            Self {
+                event_count: count,
+                current: AtomicUsize::new(0),
+            }
+        }
+    }
+
+    impl SseEventProducer for RapidEventProducer {
+        async fn next_event(&self) -> Option<SseEvent> {
+            let idx: usize = self.current.fetch_add(1, Ordering::Relaxed);
+            if idx < self.event_count {
+                Some(SseEvent::new(serde_json::json!({
+                    "id": idx,
+                    "data": format!("event_{}", idx)
+                })))
+            } else {
+                None
+            }
+        }
+    }
+
+    /// Producer with all event fields populated
+    struct FullFieldProducer {
+        sent: AtomicBool,
+    }
+
+    impl SseEventProducer for FullFieldProducer {
+        async fn next_event(&self) -> Option<SseEvent> {
+            let was_sent: bool = self.sent.swap(true, Ordering::Relaxed);
+            if !was_sent {
+                Some(
+                    SseEvent::with_type(
+                        "counter_update",
+                        serde_json::json!({
+                            "count": 42,
+                            "status": "active"
+                        }),
+                    )
+                    .with_id("event-123")
+                    .with_retry(5000),
+                )
+            } else {
+                None
+            }
+        }
+    }
+
+    /// Producer that ends immediately (keep-alive test)
+    struct NoEventProducer;
+
+    impl SseEventProducer for NoEventProducer {
+        async fn next_event(&self) -> Option<SseEvent> {
+            None
+        }
+    }
+
+    #[test]
+    fn test_sse_event_creation_minimal() {
+        let event: SseEvent = SseEvent::new(serde_json::json!({"test": "data"}));
+        assert!(event.event_type.is_none());
+        assert!(event.id.is_none());
+        assert!(event.retry.is_none());
+    }
+
+    #[test]
+    fn test_sse_event_with_all_fields() {
+        let event: SseEvent = SseEvent::with_type("update", serde_json::json!({"count": 42}))
+            .with_id("event-001")
+            .with_retry(3000);
+
+        assert_eq!(event.event_type, Some("update".to_string()));
+        assert_eq!(event.id, Some("event-001".to_string()));
+        assert_eq!(event.retry, Some(3000));
+    }
+
+    #[test]
+    fn test_sse_event_builder_pattern() {
+        let event: SseEvent = SseEvent::with_type("notification", serde_json::json!({"text": "hello"}))
+            .with_id("notif-456")
+            .with_retry(5000);
+
+        assert_eq!(event.event_type, Some("notification".to_string()));
+        assert_eq!(event.id, Some("notif-456".to_string()));
+        assert_eq!(event.retry, Some(5000));
+    }
+
+    #[test]
+    fn test_sse_event_multiline_data() {
+        let event: SseEvent = SseEvent::new(serde_json::json!({
+            "text": "line1\nline2\nline3"
+        }));
+
+        assert!(event.data.is_object());
+        let text: Option<&str> = event.data.get("text").and_then(|v| v.as_str());
+        assert_eq!(text, Some("line1\nline2\nline3"));
+    }
+
+    #[test]
+    fn test_sse_event_special_characters() {
+        let event: SseEvent = SseEvent::new(serde_json::json!({
+            "data": "special: \"quotes\", \\ backslash"
+        }));
+
+        assert!(event.data.is_object());
+    }
+
+    #[test]
+    fn test_sse_event_large_payload() {
+        let large_string: String = "x".repeat(100_000);
+        let event: SseEvent = SseEvent::new(serde_json::json!({
+            "payload": large_string.clone()
+        }));
+
+        let payload_field: Option<&str> = event.data.get("payload").and_then(|v| v.as_str());
+        assert_eq!(payload_field.map(|s| s.len()), Some(100_000));
+    }
+
+    #[test]
+    fn test_sse_event_into_axum_event_conversion() {
+        let event: SseEvent = SseEvent::new(serde_json::json!({"msg": "test"}));
+        let _axum_event: axum::response::sse::Event = event.into_axum_event();
+    }
+
+    #[test]
+    fn test_sse_event_into_axum_with_all_fields() {
+        let event: SseEvent = SseEvent::with_type("event", serde_json::json!({"id": 1}))
+            .with_id("123")
+            .with_retry(5000);
+
+        let _axum_event: axum::response::sse::Event = event.into_axum_event();
+    }
+
+    #[test]
+    fn test_sse_state_creation() {
+        let producer: TestProducer = TestProducer {
+            count: AtomicUsize::new(0),
+        };
+        let state: SseState<TestProducer> = SseState::new(producer);
+        let cloned: SseState<TestProducer> = state.clone();
+        assert!(Arc::ptr_eq(&state.producer, &cloned.producer));
+    }
+
+    #[test]
+    fn test_sse_state_with_schema_valid() {
+        let producer: TestProducer = TestProducer {
+            count: AtomicUsize::new(0),
+        };
+        let schema: serde_json::Value = serde_json::json!({
+            "type": "object",
+            "properties": {
+                "message": {"type": "string"}
+            }
+        });
+
+        let result: Result<SseState<TestProducer>, String> = SseState::with_schema(producer, Some(schema));
+        assert!(result.is_ok());
+    }
+
+    #[test]
+    fn test_sse_state_with_invalid_schema() {
+        let producer: TestProducer = TestProducer {
+            count: AtomicUsize::new(0),
+        };
+        let invalid_schema: serde_json::Value = serde_json::json!({
+            "type": "not-a-valid-type"
+        });
+
+        let result: Result<SseState<TestProducer>, String> = SseState::with_schema(producer, Some(invalid_schema));
+        assert!(result.is_err());
+    }
+
+    #[test]
+    fn test_sse_state_with_schema_none() {
+        let producer: TestProducer = TestProducer {
+            count: AtomicUsize::new(0),
+        };
+        let result: Result<SseState<TestProducer>, String> = SseState::with_schema(producer, None);
+        assert!(result.is_ok());
+    }
+
+    #[tokio::test]
+    async fn test_sse_lifecycle_on_connect_called() {
+        let connect_count: Arc<AtomicUsize> = Arc::new(AtomicUsize::new(0));
+        let disconnect_count: Arc<AtomicUsize> = Arc::new(AtomicUsize::new(0));
+
+        let producer: LifecycleProducer =
+            LifecycleProducer::new(Arc::clone(&connect_count), Arc::clone(&disconnect_count));
+
+        producer.on_connect().await;
+        assert_eq!(connect_count.load(Ordering::Relaxed), 1);
+    }
+
+    #[tokio::test]
+    async fn test_sse_lifecycle_on_disconnect_called() {
+        let connect_count: Arc<AtomicUsize> = Arc::new(AtomicUsize::new(0));
+        let disconnect_count: Arc<AtomicUsize> = Arc::new(AtomicUsize::new(0));
+
+        let producer: LifecycleProducer =
+            LifecycleProducer::new(Arc::clone(&connect_count), Arc::clone(&disconnect_count));
+
+        producer.on_disconnect().await;
+        assert_eq!(disconnect_count.load(Ordering::Relaxed), 1);
+    }
+
+    #[tokio::test]
+    async fn test_sse_event_ordering_preserved() {
+        let producer: RapidEventProducer = RapidEventProducer::new(10);
+
+        let mut last_idx: i32 = -1;
+        for _ in 0..10 {
+            if let Some(event) = producer.next_event().await {
+                if let Some(id) = event.data.get("id").and_then(|v| v.as_i64()) {
+                    assert!(id as i32 > last_idx, "Event ordering violated");
+                    last_idx = id as i32;
+                }
+            }
+        }
+    }
+
+    #[tokio::test]
+    async fn test_sse_rapid_event_sending() {
+        let producer: RapidEventProducer = RapidEventProducer::new(100);
+
+        let mut count: usize = 0;
+        loop {
+            match producer.next_event().await {
+                Some(_event) => count += 1,
+                None => break,
+            }
+        }
+
+        assert_eq!(count, 100);
+    }
+
+    #[test]
+    fn test_sse_event_with_empty_data_object() {
+        let event: SseEvent = SseEvent::new(serde_json::json!({}));
+        assert!(event.data.is_object());
+    }
+
+    #[test]
+    fn test_sse_event_with_nested_data() {
+        let event: SseEvent = SseEvent::new(serde_json::json!({
+            "nested": {
+                "deep": {
+                    "value": "found"
+                }
+            }
+        }));
+
+        let deep_value: Option<&str> = event
+            .data
+            .get("nested")
+            .and_then(|v| v.get("deep"))
+            .and_then(|v| v.get("value"))
+            .and_then(|v| v.as_str());
+
+        assert_eq!(deep_value, Some("found"));
+    }
+
+    #[tokio::test]
+    async fn test_sse_producer_stream_ends_cleanly() {
+        let producer: NoEventProducer = NoEventProducer;
+
+        let event1: Option<SseEvent> = producer.next_event().await;
+        assert!(event1.is_none());
+
+        let event2: Option<SseEvent> = producer.next_event().await;
+        assert!(event2.is_none());
+    }
+
+    #[test]
+    fn test_sse_event_clone() {
+        let original: SseEvent = SseEvent::with_type("test", serde_json::json!({"data": "test"}))
+            .with_id("id-1")
+            .with_retry(2000);
+
+        let cloned: SseEvent = original.clone();
+
+        assert_eq!(cloned.event_type, original.event_type);
+        assert_eq!(cloned.id, original.id);
+        assert_eq!(cloned.retry, original.retry);
+        assert_eq!(cloned.data, original.data);
+    }
+
+    #[test]
+    fn test_sse_event_debug_impl() {
+        let event: SseEvent = SseEvent::new(serde_json::json!({"msg": "debug"}));
+        let debug_str: String = format!("{:?}", event);
+        assert!(debug_str.contains("SseEvent"));
+    }
+
+    #[tokio::test]
+    async fn test_sse_multiple_producers_independent() {
+        let producer1: TestProducer = TestProducer {
+            count: AtomicUsize::new(0),
+        };
+        let producer2: TestProducer = TestProducer {
+            count: AtomicUsize::new(0),
+        };
+
+        let _event1: Option<SseEvent> = producer1.next_event().await;
+        let _event2: Option<SseEvent> = producer2.next_event().await;
+
+        let count1: usize = producer1.count.load(Ordering::Relaxed);
+        let count2: usize = producer2.count.load(Ordering::Relaxed);
+
+        assert_eq!(count1, 1);
+        assert_eq!(count2, 1);
+    }
+
+    #[test]
+    fn test_sse_state_cloning_preserves_schema() {
+        let producer: TestProducer = TestProducer {
+            count: AtomicUsize::new(0),
+        };
+        let schema: serde_json::Value = serde_json::json!({
+            "type": "object",
+            "properties": {
+                "message": {"type": "string"}
+            }
+        });
+
+        let state: SseState<TestProducer> =
+            SseState::with_schema(producer, Some(schema)).expect("schema should be valid");
+        let cloned: SseState<TestProducer> = state.clone();
+
+        assert!(Arc::ptr_eq(&state.producer, &cloned.producer));
+        match (&state.event_schema, &cloned.event_schema) {
+            (Some(s1), Some(s2)) => {
+                assert!(Arc::ptr_eq(s1, s2));
+            }
+            _ => panic!("Schema should be preserved in clone"),
+        }
+    }
+
+    #[tokio::test]
+    async fn test_sse_large_payload_integrity() {
+        let producer: LargePayloadProducer = LargePayloadProducer {
+            sent: AtomicBool::new(false),
+        };
+
+        let event: Option<SseEvent> = producer.next_event().await;
+        assert!(event.is_some());
+
+        if let Some(evt) = event {
+            let payload: Option<&str> = evt.data.get("payload").and_then(|v| v.as_str());
+            assert_eq!(payload.map(|s| s.len()), Some(100_000));
+        }
+    }
+
+    #[tokio::test]
+    async fn test_sse_multiline_data_preservation() {
+        let producer: MultilineProducer = MultilineProducer {
+            sent: AtomicBool::new(false),
+        };
+
+        let event: Option<SseEvent> = producer.next_event().await;
+        assert!(event.is_some());
+
+        if let Some(evt) = event {
+            let text: Option<&str> = evt.data.get("text").and_then(|v| v.as_str());
+            assert_eq!(text, Some("line1\nline2\nline3"));
+        }
+    }
+
+    #[tokio::test]
+    async fn test_sse_special_chars_in_payload() {
+        let producer: SpecialCharsProducer = SpecialCharsProducer {
+            sent: AtomicBool::new(false),
+        };
+
+        let event: Option<SseEvent> = producer.next_event().await;
+        assert!(event.is_some());
+
+        if let Some(evt) = event {
+            let data: Option<&str> = evt.data.get("data").and_then(|v| v.as_str());
+            assert!(data.is_some());
+            assert!(data.unwrap().contains("quotes"));
+        }
+    }
+
+    #[tokio::test]
+    async fn test_sse_full_event_fields_together() {
+        let producer: FullFieldProducer = FullFieldProducer {
+            sent: AtomicBool::new(false),
+        };
+
+        let event: Option<SseEvent> = producer.next_event().await;
+        assert!(event.is_some());
+
+        if let Some(evt) = event {
+            assert_eq!(evt.event_type, Some("counter_update".to_string()));
+            assert_eq!(evt.id, Some("event-123".to_string()));
+            assert_eq!(evt.retry, Some(5000));
+            assert_eq!(evt.data.get("count").and_then(|v| v.as_i64()), Some(42));
+        }
+    }
+
+    #[test]
+    fn test_sse_event_to_axum_preserves_data() {
+        let event = SseEvent::new(serde_json::json!({"key": "value"}));
+        let _axum_event: axum::response::sse::Event = event.into_axum_event();
+    }
+
+    #[test]
+    fn test_sse_event_data_only_no_metadata() {
+        let event = SseEvent::new(serde_json::json!({"message": "hello"}));
+        assert!(event.event_type.is_none(), "event_type should be None");
+        assert!(event.id.is_none(), "id should be None");
+        assert!(event.retry.is_none(), "retry should be None");
+
+        let _axum_event: axum::response::sse::Event = event.into_axum_event();
+    }
+
+    #[test]
+    fn test_sse_event_with_all_fields_filled() {
+        let event = SseEvent::with_type("update", serde_json::json!({"status": "ok"}))
+            .with_id("evt-999")
+            .with_retry(10000);
+
+        assert_eq!(event.event_type.as_ref(), Some(&"update".to_string()));
+        assert_eq!(event.id.as_ref(), Some(&"evt-999".to_string()));
+        assert_eq!(event.retry, Some(10000));
+
+        let _axum_event: axum::response::sse::Event = event.into_axum_event();
+    }
+
+    #[test]
+    fn test_sse_event_empty_data_field() {
+        let event = SseEvent::new(serde_json::json!({}));
+        assert!(event.data.is_object());
+        assert_eq!(event.data.as_object().unwrap().len(), 0);
+
+        let _axum_event: axum::response::sse::Event = event.into_axum_event();
+    }
+
+    #[test]
+    fn test_sse_event_data_with_newlines_in_string() {
+        let multiline_data = "first line\nsecond line\nthird line";
+        let event = SseEvent::new(serde_json::json!({"text": multiline_data}));
+
+        let stored_text = event.data.get("text").and_then(|v| v.as_str());
+        assert_eq!(stored_text, Some(multiline_data));
+
+        let _axum_event: axum::response::sse::Event = event.into_axum_event();
+    }
+
+    #[test]
+    fn test_sse_event_data_with_colons() {
+        let data_with_colons = "key1: value1, key2: value2";
+        let event = SseEvent::new(serde_json::json!({"data": data_with_colons}));
+
+        let stored_data = event.data.get("data").and_then(|v| v.as_str());
+        assert_eq!(stored_data, Some(data_with_colons));
+
+        let _axum_event: axum::response::sse::Event = event.into_axum_event();
+    }
+
+    #[test]
+    fn test_sse_event_comment_only_structure() {
+        let event = SseEvent::new(serde_json::json!({"comment": "this is a comment"}));
+        let _axum_event: axum::response::sse::Event = event.into_axum_event();
+    }
+
+    #[test]
+    fn test_sse_event_type_with_spaces() {
+        let event = SseEvent::with_type("event type with spaces", serde_json::json!({"data": "test"}));
+        assert_eq!(event.event_type, Some("event type with spaces".to_string()));
+
+        let _axum_event: axum::response::sse::Event = event.into_axum_event();
+    }
+
+    #[test]
+    fn test_sse_event_type_with_special_chars() {
+        let event_types = vec!["update-v2", "event_123", "message.sent", "type-with-dash"];
+
+        for event_type in event_types {
+            let event = SseEvent::with_type(event_type, serde_json::json!({"data": "test"}));
+            assert_eq!(event.event_type.as_ref(), Some(&event_type.to_string()));
+
+            let _axum_event: axum::response::sse::Event = event.into_axum_event();
+        }
+    }
+
+    #[test]
+    fn test_sse_event_id_alphanumeric() {
+        let ids = vec!["123", "abc-def", "event_001", "id-with-dashes-123"];
+
+        for id in ids {
+            let event = SseEvent::new(serde_json::json!({"data": "test"})).with_id(id);
+            assert_eq!(event.id.as_ref(), Some(&id.to_string()));
+
+            let _axum_event: axum::response::sse::Event = event.into_axum_event();
+        }
+    }
+
+    #[test]
+    fn test_sse_event_retry_zero() {
+        let event = SseEvent::new(serde_json::json!({"data": "test"})).with_retry(0);
+        assert_eq!(event.retry, Some(0));
+
+        let _axum_event: axum::response::sse::Event = event.into_axum_event();
+    }
+
+    #[test]
+    fn test_sse_event_retry_small_value() {
+        let event = SseEvent::new(serde_json::json!({"data": "test"})).with_retry(100);
+        assert_eq!(event.retry, Some(100));
+
+        let _axum_event: axum::response::sse::Event = event.into_axum_event();
+    }
+
+    #[test]
+    fn test_sse_event_retry_large_value() {
+        let large_retry = u64::MAX / 2;
+        let event = SseEvent::new(serde_json::json!({"data": "test"})).with_retry(large_retry);
+        assert_eq!(event.retry, Some(large_retry));
+
+        let _axum_event: axum::response::sse::Event = event.into_axum_event();
+    }
+
+    #[test]
+    fn test_sse_event_retry_typical_values() {
+        let typical_retries = vec![1000, 3000, 5000, 10000, 30000];
+
+        for retry_ms in typical_retries {
+            let event = SseEvent::new(serde_json::json!({"data": "test"})).with_retry(retry_ms);
+            assert_eq!(event.retry, Some(retry_ms));
+
+            let _axum_event: axum::response::sse::Event = event.into_axum_event();
+        }
+    }
+
+    #[test]
+    fn test_sse_event_utf8_emoji_in_data() {
+        let emoji_data = "Hello 👋 World 🌍";
+        let event = SseEvent::new(serde_json::json!({"text": emoji_data}));
+
+        let stored = event.data.get("text").and_then(|v| v.as_str());
+        assert_eq!(stored, Some(emoji_data));
+
+        let _axum_event: axum::response::sse::Event = event.into_axum_event();
+    }
+
+    #[test]
+    fn test_sse_event_utf8_chinese_characters() {
+        let chinese_text = "你好世界";
+        let event = SseEvent::new(serde_json::json!({"text": chinese_text}));
+
+        let stored = event.data.get("text").and_then(|v| v.as_str());
+        assert_eq!(stored, Some(chinese_text));
+
+        let _axum_event: axum::response::sse::Event = event.into_axum_event();
+    }
+
+    #[test]
+    fn test_sse_event_utf8_arabic_characters() {
+        let arabic_text = "مرحبا بالعالم";
+        let event = SseEvent::new(serde_json::json!({"text": arabic_text}));
+
+        let stored = event.data.get("text").and_then(|v| v.as_str());
+        assert_eq!(stored, Some(arabic_text));
+
+        let _axum_event: axum::response::sse::Event = event.into_axum_event();
+    }
+
+    #[test]
+    fn test_sse_event_utf8_mixed_scripts() {
+        let mixed = "Hello 你好 مرحبا 👋";
+        let event = SseEvent::new(serde_json::json!({"text": mixed}));
+
+        let stored = event.data.get("text").and_then(|v| v.as_str());
+        assert_eq!(stored, Some(mixed));
+
+        let _axum_event: axum::response::sse::Event = event.into_axum_event();
+    }
+
+    #[test]
+    fn test_sse_event_json_serialization_produces_valid_utf8() {
+        let event = SseEvent::new(serde_json::json!({"text": "test"}));
+        let _axum_event: axum::response::sse::Event = event.into_axum_event();
+    }
+
+    #[test]
+    fn test_sse_event_64kb_payload() {
+        let large_data = "x".repeat(65536);
+        let event = SseEvent::new(serde_json::json!({"payload": large_data.clone()}));
+
+        let stored = event.data.get("payload").and_then(|v| v.as_str());
+        assert_eq!(stored.map(|s| s.len()), Some(65536));
+
+        let _axum_event: axum::response::sse::Event = event.into_axum_event();
+    }
+
+    #[test]
+    fn test_sse_event_1mb_payload() {
+        let large_data = "y".repeat(1_000_000);
+        let event = SseEvent::new(serde_json::json!({"payload": large_data.clone()}));
+
+        let stored = event.data.get("payload").and_then(|v| v.as_str());
+        assert_eq!(stored.map(|s| s.len()), Some(1_000_000));
+
+        let _axum_event: axum::response::sse::Event = event.into_axum_event();
+    }
+
+    #[test]
+    fn test_sse_event_deeply_nested_json() {
+        let deeply_nested = serde_json::json!({
+            "level1": {
+                "level2": {
+                    "level3": {
+                        "level4": {
+                            "level5": {
+                                "level6": {
+                                    "level7": {
+                                        "value": "deep"
+                                    }
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+        });
+
+        let event = SseEvent::new(deeply_nested);
+        let _axum_event: axum::response::sse::Event = event.into_axum_event();
+    }
+
+    #[test]
+    fn test_sse_event_array_in_data() {
+        let event = SseEvent::new(serde_json::json!({
+            "items": [1, 2, 3, 4, 5]
+        }));
+
+        let items = event.data.get("items").and_then(|v| v.as_array());
+        assert!(items.is_some());
+        assert_eq!(items.unwrap().len(), 5);
+
+        let _axum_event: axum::response::sse::Event = event.into_axum_event();
+    }
+
+    #[test]
+    fn test_sse_event_null_value_in_data() {
+        let event = SseEvent::new(serde_json::json!({
+            "nullable": null
+        }));
+
+        assert!(event.data.get("nullable").unwrap().is_null());
+
+        let _axum_event: axum::response::sse::Event = event.into_axum_event();
+    }
+
+    #[test]
+    fn test_sse_event_boolean_values() {
+        let event = SseEvent::new(serde_json::json!({
+            "active": true,
+            "deleted": false
+        }));
+
+        assert_eq!(event.data.get("active").and_then(|v| v.as_bool()), Some(true));
+        assert_eq!(event.data.get("deleted").and_then(|v| v.as_bool()), Some(false));
+
+        let _axum_event: axum::response::sse::Event = event.into_axum_event();
+    }
+
+    #[tokio::test]
+    async fn test_sse_last_event_id_header_simulation() {
+        let producer = RapidEventProducer::new(5);
+
+        let mut events = Vec::new();
+        for _ in 0..5 {
+            if let Some(evt) = producer.next_event().await {
+                events.push(evt);
+            }
+        }
+
+        assert_eq!(events.len(), 5);
+    }
+
+    #[tokio::test]
+    async fn test_sse_retry_timeout_specification() {
+        let producer = FullFieldProducer {
+            sent: AtomicBool::new(false),
+        };
+
+        let event = producer.next_event().await;
+        assert!(event.is_some());
+
+        if let Some(evt) = event {
+            assert_eq!(evt.retry, Some(5000), "Retry should be 5000ms");
+        }
+    }
+
+    #[test]
+    fn test_sse_event_builder_method_chaining() {
+        let event = SseEvent::new(serde_json::json!({"data": "test"}))
+            .with_id("id-1")
+            .with_retry(3000);
+
+        assert_eq!(event.id, Some("id-1".to_string()));
+        assert_eq!(event.retry, Some(3000));
+
+        let event2 = SseEvent::with_type("msg", serde_json::json!({"x": 1}))
+            .with_id("id-2")
+            .with_retry(5000);
+
+        assert_eq!(event2.event_type, Some("msg".to_string()));
+        assert_eq!(event2.id, Some("id-2".to_string()));
+        assert_eq!(event2.retry, Some(5000));
+    }
+
+    #[test]
+    fn test_sse_event_overwriting_fields() {
+        let event = SseEvent::new(serde_json::json!({"v": 1}))
+            .with_id("id-original")
+            .with_retry(1000);
+
+        assert_eq!(event.id, Some("id-original".to_string()));
+        assert_eq!(event.retry, Some(1000));
+    }
+
+    #[test]
+    fn test_sse_event_type_empty_string() {
+        let event = SseEvent::with_type("", serde_json::json!({"data": "test"}));
+        assert_eq!(event.event_type, Some("".to_string()));
+
+        let _axum_event: axum::response::sse::Event = event.into_axum_event();
+    }
+
+    #[test]
+    fn test_sse_event_id_empty_string() {
+        let event = SseEvent::new(serde_json::json!({"data": "test"})).with_id("");
+        assert_eq!(event.id, Some("".to_string()));
+
+        let _axum_event: axum::response::sse::Event = event.into_axum_event();
+    }
+
+    #[tokio::test]
+    async fn test_sse_event_sequence_maintains_order() {
+        let producer = RapidEventProducer::new(10);
+
+        let mut event_ids = Vec::new();
+        for _ in 0..10 {
+            if let Some(evt) = producer.next_event().await {
+                if let Some(id) = evt.data.get("id").and_then(|v| v.as_i64()) {
+                    event_ids.push(id);
+                }
+            }
+        }
+
+        for i in 0..event_ids.len() {
+            assert_eq!(event_ids[i], i as i64, "Event order should match insertion order");
+        }
+    }
+
+    #[tokio::test]
+    async fn test_sse_rapid_events_no_loss() {
+        let producer = RapidEventProducer::new(50);
+
+        let mut count = 0;
+        loop {
+            match producer.next_event().await {
+                Some(_) => count += 1,
+                None => break,
+            }
+        }
+
+        assert_eq!(count, 50, "All events should be produced without loss");
+    }
+
+    #[tokio::test]
+    async fn test_sse_event_batching_simulation() {
+        let producer = RapidEventProducer::new(20);
+
+        let mut batch_size = 0;
+        let mut batch_count = 0;
+
+        loop {
+            match producer.next_event().await {
+                Some(_evt) => {
+                    batch_size += 1;
+                    if batch_size >= 5 {
+                        batch_count += 1;
+                        batch_size = 0;
+                    }
+                }
+                None => {
+                    if batch_size > 0 {
+                        batch_count += 1;
+                    }
+                    break;
+                }
+            }
+        }
+
+        assert!(batch_count >= 4, "Should have processed at least 4 batches");
+    }
+
+    #[test]
+    fn test_sse_state_arc_sharing() {
+        let producer = TestProducer {
+            count: AtomicUsize::new(0),
+        };
+        let state1 = SseState::new(producer);
+        let state2 = state1.clone();
+        let state3 = state2.clone();
+
+        assert!(Arc::ptr_eq(&state1.producer, &state2.producer));
+        assert!(Arc::ptr_eq(&state2.producer, &state3.producer));
+    }
+
+    #[test]
+    fn test_sse_state_schema_arc_sharing() {
+        let producer = TestProducer {
+            count: AtomicUsize::new(0),
+        };
+        let schema = serde_json::json!({
+            "type": "object"
+        });
+
+        let state1 = SseState::with_schema(producer, Some(schema)).expect("schema should be valid");
+        let state2 = state1.clone();
+
+        match (&state1.event_schema, &state2.event_schema) {
+            (Some(s1), Some(s2)) => {
+                assert!(Arc::ptr_eq(s1, s2));
+            }
+            _ => panic!("Both states should have schema"),
+        }
+    }
+
+    #[test]
+    fn test_sse_event_into_axum_event_numeric_data() {
+        let event = SseEvent::new(serde_json::json!({
+            "count": 42,
+            "temperature": 98.6,
+            "negative": -273
+        }));
+
+        let _axum_event: axum::response::sse::Event = event.into_axum_event();
+    }
+
+    #[test]
+    fn test_sse_event_json_number_precision() {
+        let event = SseEvent::new(serde_json::json!({
+            "float": 3.14159265359,
+            "large_int": 9007199254740991i64
+        }));
+
+        assert_eq!(event.data.get("float").and_then(|v| v.as_f64()), Some(3.14159265359));
+
+        let _axum_event: axum::response::sse::Event = event.into_axum_event();
+    }
+
+    #[test]
+    fn test_sse_event_string_escaping() {
+        let event = SseEvent::new(serde_json::json!({
+            "escaped": "line1\nline2\ttab",
+            "quotes": "He said \"hello\"",
+            "backslash": "path\\to\\file"
+        }));
+
+        let _axum_event: axum::response::sse::Event = event.into_axum_event();
+    }
+
+    #[test]
+    fn test_sse_event_all_json_types_combined() {
+        let event = SseEvent::new(serde_json::json!({
+            "string": "text",
+            "number": 123,
+            "float": 1.5,
+            "boolean": true,
+            "null_value": null,
+            "array": [1, 2, 3],
+            "object": {
+                "nested": "value"
+            }
+        }));
+
+        let _axum_event: axum::response::sse::Event = event.into_axum_event();
+    }
+}