Skip to main content

graphrt_llm/
sse.rs

1//! Minimal Server-Sent Events parser.
2//!
3//! A transport utility used by the built-in providers, public so custom
4//! [`crate::ChatModel`] implementations can reuse it.
5//!
6//! Incremental: feed arbitrary byte chunks with [`SseParser::push`], receive
7//! complete events. Handles `\n`, `\r\n` and `\r` line endings (including a
8//! `\r\n` split across chunks), multi-line `data:`, `event:`, `id:`, comments
9//! and UTF-8 sequences split across chunks.
10//!
11//! Memory is bounded: a single line or event larger than the configured limit
12//! (default [`DEFAULT_MAX_EVENT_BYTES`]) is an error instead of growing the
13//! buffer without bound.
14
15/// Default upper bound for one line or one event's accumulated data (16 MiB).
16pub const DEFAULT_MAX_EVENT_BYTES: usize = 16 * 1024 * 1024;
17
18/// The stream exceeded the parser's size limit.
19#[derive(Clone, Debug, PartialEq, Eq, thiserror::Error)]
20#[error("server-sent event exceeds {limit} bytes")]
21pub struct SseTooLarge {
22    pub limit: usize,
23}
24
25/// One dispatched event.
26#[derive(Clone, Debug, Default, PartialEq, Eq)]
27pub struct SseEvent {
28    /// The `event:` field, if any (otherwise the default `message` type).
29    pub event: Option<String>,
30    /// Concatenated `data:` lines, joined with `\n`.
31    pub data: String,
32    pub id: Option<String>,
33}
34
35/// Incremental SSE parser.
36#[derive(Debug)]
37pub struct SseParser {
38    line: Vec<u8>,
39    skip_lf: bool,
40    event: Option<String>,
41    data: String,
42    has_data: bool,
43    id: Option<String>,
44    max_bytes: usize,
45}
46
47impl Default for SseParser {
48    fn default() -> Self {
49        Self::with_limit(DEFAULT_MAX_EVENT_BYTES)
50    }
51}
52
53impl SseParser {
54    pub fn new() -> Self {
55        Self::default()
56    }
57
58    /// Parser rejecting lines or events larger than `max_bytes`.
59    pub fn with_limit(max_bytes: usize) -> Self {
60        Self {
61            line: Vec::new(),
62            skip_lf: false,
63            event: None,
64            data: String::new(),
65            has_data: false,
66            id: None,
67            max_bytes,
68        }
69    }
70
71    /// Feed bytes, returning every event completed by them.
72    pub fn push(&mut self, bytes: &[u8]) -> Result<Vec<SseEvent>, SseTooLarge> {
73        let mut events = Vec::new();
74        for &b in bytes {
75            if self.skip_lf {
76                self.skip_lf = false;
77                if b == b'\n' {
78                    continue;
79                }
80            }
81            match b {
82                b'\n' => self.end_line(&mut events)?,
83                b'\r' => {
84                    self.end_line(&mut events)?;
85                    self.skip_lf = true;
86                }
87                other => {
88                    if self.line.len() >= self.max_bytes {
89                        return Err(SseTooLarge { limit: self.max_bytes });
90                    }
91                    self.line.push(other);
92                }
93            }
94        }
95        Ok(events)
96    }
97
98    /// Flush a final event not terminated by a blank line (end of stream).
99    pub fn finish(&mut self) -> Result<Option<SseEvent>, SseTooLarge> {
100        let mut events = Vec::new();
101        if !self.line.is_empty() {
102            self.end_line(&mut events)?;
103        }
104        self.dispatch(&mut events);
105        Ok(events.pop())
106    }
107
108    fn end_line(&mut self, events: &mut Vec<SseEvent>) -> Result<(), SseTooLarge> {
109        let raw = std::mem::take(&mut self.line);
110        let line = String::from_utf8_lossy(&raw);
111        if line.is_empty() {
112            self.dispatch(events);
113            return Ok(());
114        }
115        if line.starts_with(':') {
116            return Ok(()); // comment / keep-alive
117        }
118        let (field, value) = match line.find(':') {
119            Some(pos) => {
120                let (f, rest) = line.split_at(pos);
121                let v = rest.strip_prefix(':').unwrap_or(rest);
122                (f, v.strip_prefix(' ').unwrap_or(v))
123            }
124            None => (line.as_ref(), ""),
125        };
126        match field {
127            "data" => {
128                if self.data.len().saturating_add(value.len()).saturating_add(1) > self.max_bytes {
129                    return Err(SseTooLarge { limit: self.max_bytes });
130                }
131                if self.has_data {
132                    self.data.push('\n');
133                }
134                self.data.push_str(value);
135                self.has_data = true;
136            }
137            "event" => self.event = Some(value.to_owned()),
138            "id" => self.id = Some(value.to_owned()),
139            _ => {} // `retry` and unknown fields are ignored
140        }
141        Ok(())
142    }
143
144    fn dispatch(&mut self, events: &mut Vec<SseEvent>) {
145        if self.has_data {
146            events.push(SseEvent {
147                event: self.event.take(),
148                data: std::mem::take(&mut self.data),
149                id: self.id.clone(),
150            });
151        } else {
152            self.event = None;
153        }
154        self.has_data = false;
155    }
156}
157
158#[cfg(test)]
159mod tests {
160    use super::*;
161
162    #[test]
163    fn basic_events() {
164        let mut p = SseParser::new();
165        let ev = p.push(b"event: ping\ndata: {}\n\ndata: a\ndata: b\n\n").unwrap();
166        assert_eq!(ev.len(), 2);
167        assert_eq!(ev[0].event.as_deref(), Some("ping"));
168        assert_eq!(ev[0].data, "{}");
169        assert_eq!(ev[1].event, None);
170        assert_eq!(ev[1].data, "a\nb");
171    }
172
173    #[test]
174    fn split_chunks_and_crlf() {
175        let mut p = SseParser::new();
176        let mut all = Vec::new();
177        for chunk in [&b"da"[..], b"ta: hel", b"lo\r", b"\n\r", b"\n: comment\r\ndata:x\r\r"] {
178            all.extend(p.push(chunk).unwrap());
179        }
180        assert_eq!(all.len(), 2);
181        assert_eq!(all[0].data, "hello");
182        assert_eq!(all[1].data, "x");
183    }
184
185    #[test]
186    fn utf8_split_across_chunks() {
187        let text = "data: héllo\n\n".as_bytes();
188        let mut p = SseParser::new();
189        let mut all = p.push(&text[..8]).unwrap();
190        all.extend(p.push(&text[8..]).unwrap());
191        assert_eq!(all[0].data, "héllo");
192    }
193
194    #[test]
195    fn event_without_data_is_not_dispatched_and_finish_flushes() {
196        let mut p = SseParser::new();
197        assert!(p.push(b"event: x\n\n").unwrap().is_empty());
198        assert!(p.push(b"data: tail").unwrap().is_empty());
199        assert_eq!(p.finish().unwrap().map(|e| e.data), Some("tail".to_owned()));
200    }
201
202    #[test]
203    fn oversized_lines_and_events_are_rejected() {
204        let mut p = SseParser::with_limit(16);
205        assert_eq!(p.push(&[b'x'; 17]), Err(SseTooLarge { limit: 16 }));
206        let mut p = SseParser::with_limit(16);
207        assert!(p.push(b"data: 0123456789\n").is_ok());
208        assert_eq!(p.push(b"data: 0123456789\n"), Err(SseTooLarge { limit: 16 }));
209    }
210}