1use std::borrow::Cow;
15
16pub const FRAME_LIMIT: usize = 64 * 1024 * 1024;
21
22#[derive(Debug, Clone, Copy, PartialEq, Eq, thiserror::Error)]
25#[error("more than {limit} bytes")]
26pub struct TooLarge {
27 pub limit: usize,
29 pub asked: usize,
32}
33
34#[derive(Debug, Clone, Copy, PartialEq, Eq)]
36pub enum Framing {
37 Sse,
39 Ndjson,
41 Whole,
43}
44
45impl Framing {
46 pub fn framer(self) -> Option<Framer> {
49 self.framer_with_limit(FRAME_LIMIT)
50 }
51
52 fn framer_with_limit(self, limit: usize) -> Option<Framer> {
55 let lines = match self {
56 Self::Sse => Lines::Sse(SseFramer::with_limit(limit)),
57 Self::Ndjson => Lines::Ndjson(NdjsonFramer::with_limit(limit)),
58 Self::Whole => return None,
59 };
60 Some(Framer { lines })
61 }
62
63 pub fn split(&self, bytes: &[u8]) -> Vec<WireFrame> {
76 let Some(mut framer) = self.framer_with_limit(usize::MAX) else {
77 return (!bytes.is_empty())
78 .then(|| WireFrame::from_bytes(bytes.to_vec()))
79 .into_iter()
80 .collect();
81 };
82 let mut frames: Vec<WireFrame> = framer.push(bytes).flatten().collect();
83 frames.extend(framer.finish());
84 frames
85 }
86}
87
88#[derive(Debug, Clone, PartialEq, Eq)]
93pub enum WireFrame {
94 Text(String),
96 Bytes(Vec<u8>),
98}
99
100impl WireFrame {
101 pub fn as_str(&self) -> Cow<'_, str> {
103 match self {
104 Self::Text(text) => Cow::Borrowed(text),
105 Self::Bytes(bytes) => String::from_utf8_lossy(bytes),
106 }
107 }
108
109 pub fn as_bytes(&self) -> &[u8] {
111 match self {
112 Self::Text(text) => text.as_bytes(),
113 Self::Bytes(bytes) => bytes,
114 }
115 }
116
117 pub fn into_bytes(self) -> Vec<u8> {
119 match self {
120 Self::Text(text) => text.into_bytes(),
121 Self::Bytes(bytes) => bytes,
122 }
123 }
124
125 pub fn from_bytes(bytes: Vec<u8>) -> Self {
127 match String::from_utf8(bytes) {
128 Ok(text) => Self::Text(text),
129 Err(error) => Self::Bytes(error.into_bytes()),
130 }
131 }
132}
133
134#[derive(Debug)]
136pub struct Framer {
137 lines: Lines,
138}
139
140#[derive(Debug)]
141enum Lines {
142 Sse(SseFramer),
143 Ndjson(NdjsonFramer),
144}
145
146impl Framer {
147 pub fn push(&mut self, chunk: &[u8]) -> impl Iterator<Item = Result<WireFrame, TooLarge>> + '_ {
152 let (sse, ndjson) = match &mut self.lines {
153 Lines::Sse(framer) => (Some(framer.push(chunk)), None),
154 Lines::Ndjson(framer) => (None, Some(framer.push(chunk))),
155 };
156 let events = sse.into_iter().flatten();
157 let events = events.filter(|event| {
158 event
159 .as_ref()
160 .map_or(true, |event| !event.data.trim().is_empty())
161 });
162 let events = events.map(|event| event.map(|event| WireFrame::Text(event.data)));
163 let lines = ndjson.into_iter().flatten();
164 events.chain(lines.map(|line| line.map(WireFrame::from_bytes)))
165 }
166
167 pub fn finish(&mut self) -> Option<WireFrame> {
170 match &mut self.lines {
171 Lines::Sse(_) => None,
172 Lines::Ndjson(framer) => framer.finish().map(WireFrame::from_bytes),
173 }
174 }
175
176 pub fn pending(&self) -> usize {
179 match &self.lines {
180 Lines::Sse(framer) => framer.pending(),
181 Lines::Ndjson(framer) => framer.pending(),
182 }
183 }
184}
185
186#[derive(Debug, Clone, Default, PartialEq, Eq)]
188pub struct SseEvent {
189 pub event: Cow<'static, str>,
191 pub data: String,
193 pub id: String,
195 pub retry: Option<u64>,
199}
200
201#[derive(Debug, Clone, Copy, PartialEq, Eq)]
203pub enum SseField {
204 Data,
206 Event,
208 Id,
210 Blank,
212 Other,
214}
215
216#[derive(Debug, Clone, PartialEq, Eq)]
218pub struct SseLine {
219 pub span: std::ops::Range<usize>,
221 pub content: std::ops::Range<usize>,
223 pub value: Option<std::ops::Range<usize>>,
225 pub field: SseField,
227}
228
229#[derive(Debug, Clone, PartialEq, Eq)]
231pub struct RecordedSseEvent {
232 pub event: SseEvent,
234 pub end: usize,
236}
237
238#[derive(Debug, Default)]
240pub struct SseBatch {
241 pub events: Vec<RecordedSseEvent>,
243 pub lines: Vec<SseLine>,
245}
246
247const BOM: [u8; 3] = [0xef, 0xbb, 0xbf];
249
250#[derive(Debug)]
253pub struct SseFramer {
254 buffer: Vec<u8>,
256 scanned: usize,
258 after_cr: bool,
261 ready: Vec<Result<SseEvent, TooLarge>>,
263 event_type: String,
264 data: String,
265 last_event_id: String,
266 retry: Option<u64>,
267 bom_prefix: usize,
269 bom_done: bool,
270 since_dispatch: usize,
272 offset: usize,
274 limit: usize,
276 copied: usize,
278 refused: bool,
280 recording: bool,
283}
284
285impl Default for SseFramer {
286 fn default() -> Self {
287 Self::with_limit(FRAME_LIMIT)
288 }
289}
290
291impl SseFramer {
292 pub fn new() -> Self {
295 Self::default()
296 }
297
298 pub fn with_limit(limit: usize) -> Self {
301 Self {
302 buffer: Vec::new(),
303 scanned: 0,
304 after_cr: false,
305 ready: Vec::new(),
306 event_type: String::new(),
307 data: String::new(),
308 last_event_id: String::new(),
309 retry: None,
310 bom_prefix: 0,
311 bom_done: false,
312 since_dispatch: 0,
313 offset: 0,
314 limit,
315 copied: 0,
316 refused: false,
317 recording: false,
318 }
319 }
320
321 pub fn push(&mut self, chunk: &[u8]) -> std::vec::Drain<'_, Result<SseEvent, TooLarge>> {
328 let mut rest = chunk;
329 self.copied = 0;
330 while !self.refused && !rest.is_empty() {
331 let room = self.limit.saturating_sub(self.held()).saturating_add(1);
332 let (piece, after) = rest.split_at(room.min(rest.len()));
333 self.push_inner(piece, None);
334 rest = after;
335 if self.held() > self.limit {
336 self.refuse(self.held());
337 }
338 }
339 self.ready.drain(..)
340 }
341
342 fn held(&self) -> usize {
346 self.buffer
347 .len()
348 .saturating_add(self.data.len())
349 .saturating_add(self.event_type.len())
350 .saturating_add(self.last_event_id.len())
351 .saturating_add(self.copied)
352 }
353
354 fn refuse(&mut self, asked: usize) {
356 self.refused = true;
357 self.buffer = Vec::new();
358 self.data = String::new();
359 self.ready.push(Err(TooLarge {
360 limit: self.limit,
361 asked,
362 }));
363 }
364
365 pub fn push_recording(&mut self, chunk: &[u8]) -> SseBatch {
367 self.recording = true;
368 let mut batch = SseBatch::default();
369 self.push_inner(chunk, Some(&mut batch));
370 batch
371 }
372
373 pub fn finish_recording(&mut self) -> SseBatch {
376 self.recording = true;
377 let mut batch = SseBatch::default();
378 if self.bom_prefix > 0 {
379 self.buffer
380 .extend_from_slice(BOM.get(..self.bom_prefix).unwrap_or_default());
381 self.bom_prefix = 0;
382 self.bom_done = true;
383 }
384 if !self.buffer.is_empty() {
385 let buffer = std::mem::take(&mut self.buffer);
386 let start = self.offset;
387 self.offset = self.offset.saturating_add(buffer.len());
388 let (field, value) = self.line(&String::from_utf8_lossy(&buffer));
389 batch.lines.push(SseLine {
390 span: start..self.offset,
391 content: start..self.offset,
392 value: value.map(|at| start.saturating_add(at)..self.offset),
393 field,
394 });
395 }
396 self.dispatch();
397 if let Some(Ok(event)) = self.ready.pop() {
398 batch.events.push(RecordedSseEvent {
399 event,
400 end: self.offset,
401 });
402 }
403 batch
404 }
405
406 fn push_inner(&mut self, chunk: &[u8], mut recording: Option<&mut SseBatch>) {
407 let mut chunk = self.strip_bom(chunk);
408 if self.after_cr
409 && let Some((&first, rest)) = chunk.split_first()
410 {
411 self.after_cr = false;
412 if first == b'\n' {
413 chunk = rest;
414 self.offset = self.offset.saturating_add(1);
415 if self.since_dispatch > 0 {
417 self.since_dispatch = self.since_dispatch.saturating_add(1);
418 }
419 }
420 }
421 self.buffer.extend_from_slice(chunk);
422 let buffer = std::mem::take(&mut self.buffer);
424 let mut rest = buffer.as_slice();
425 while let Some((line, next)) = terminated_line(rest, self.scanned) {
426 self.scanned = 0;
427 let start = self.offset;
428 self.offset = self.offset.saturating_add(rest.len() - next.len());
429 self.since_dispatch = self.since_dispatch.saturating_add(rest.len() - next.len());
430 self.after_cr = next.is_empty() && rest.last() == Some(&b'\r');
431 let decoded = self.held().saturating_add(decoded_len(line));
434 if recording.is_none() && decoded > self.limit {
435 self.refuse(decoded);
436 return;
437 }
438 let (field, value) = self.line(&String::from_utf8_lossy(line));
439 if self.refused {
440 return;
441 }
442 if recording.is_none() && self.held() > self.limit {
444 rest = next;
445 break;
446 }
447 if let Some(batch) = recording.as_deref_mut() {
448 batch.lines.push(SseLine {
449 span: start..self.offset,
450 content: start..start.saturating_add(line.len()),
451 value: value
452 .map(|at| start.saturating_add(at)..start.saturating_add(line.len())),
453 field,
454 });
455 if let Some(Ok(event)) = self.ready.pop() {
456 batch.events.push(RecordedSseEvent {
457 event,
458 end: self.offset,
459 });
460 }
461 }
462 rest = next;
463 }
464 self.scanned = rest.len();
465 let consumed = buffer.len() - rest.len();
466 self.buffer = buffer;
467 self.buffer.drain(..consumed);
468 }
469
470 pub fn pending(&self) -> usize {
473 self.since_dispatch.saturating_add(self.buffer.len())
474 }
475
476 fn strip_bom<'a>(&mut self, chunk: &'a [u8]) -> &'a [u8] {
479 if self.bom_done {
480 return chunk;
481 }
482 let mut rest = chunk;
483 while let Some(&byte) = rest.first() {
484 if BOM.get(self.bom_prefix) != Some(&byte) {
485 let matched = std::mem::take(&mut self.bom_prefix);
487 self.bom_done = true;
488 self.buffer
489 .extend_from_slice(BOM.get(..matched).unwrap_or_default());
490 return rest;
491 }
492 self.bom_prefix += 1;
493 rest = rest.get(1..).unwrap_or_default();
494 if self.bom_prefix == BOM.len() {
495 self.offset = self.offset.saturating_add(BOM.len());
496 self.bom_prefix = 0;
497 self.bom_done = true;
498 return rest;
499 }
500 }
501 rest
502 }
503
504 fn line(&mut self, line: &str) -> (SseField, Option<usize>) {
506 if line.is_empty() {
507 self.dispatch();
508 return (SseField::Blank, None);
509 }
510 if line.starts_with(':') {
512 return (SseField::Other, None);
513 }
514 let (field, value, at) = match line.split_once(':') {
515 Some((field, value)) => {
516 let trimmed = value.strip_prefix(' ').unwrap_or(value);
517 (
518 field,
519 trimmed,
520 Some(field.len() + 1 + value.len() - trimmed.len()),
521 )
522 }
523 None => (line, "", None),
524 };
525 let field = match field {
526 "event" => {
527 self.event_type.clear();
528 self.event_type.push_str(value);
529 SseField::Event
530 }
531 "data" => {
532 self.data.push_str(value);
533 self.data.push('\n');
534 SseField::Data
535 }
536 "id" if !value.contains('\0') => {
538 self.last_event_id.clear();
539 self.last_event_id.push_str(value);
540 SseField::Id
541 }
542 "retry" if !value.is_empty() && value.bytes().all(|b| b.is_ascii_digit()) => {
543 self.retry = Some(value.parse().unwrap_or(u64::MAX));
545 SseField::Other
546 }
547 _ => SseField::Other,
548 };
549 (field, at)
550 }
551
552 fn dispatch(&mut self) {
555 self.since_dispatch = 0;
556 if self.data.is_empty() {
557 self.event_type.clear();
558 return;
559 }
560 self.data.pop();
561 let asked = self.held().saturating_add(self.last_event_id.len());
564 if !self.recording && asked > self.limit {
565 return self.refuse(asked);
566 }
567 let event = if self.event_type.is_empty() {
568 Cow::Borrowed("message")
569 } else {
570 Cow::Owned(std::mem::take(&mut self.event_type))
571 };
572 self.copied = self.copied.saturating_add(self.last_event_id.len());
573 self.ready.push(Ok(SseEvent {
574 event,
575 data: std::mem::take(&mut self.data),
576 id: self.last_event_id.clone(),
577 retry: self.retry.take(),
578 }));
579 self.event_type.clear();
580 }
581}
582
583#[derive(Debug)]
587pub struct NdjsonFramer {
588 buffer: Vec<u8>,
589 scanned: usize,
591 ready: Vec<Result<Vec<u8>, TooLarge>>,
592 limit: usize,
594 skipping: bool,
596}
597
598impl Default for NdjsonFramer {
599 fn default() -> Self {
600 Self::with_limit(FRAME_LIMIT)
601 }
602}
603
604impl NdjsonFramer {
605 pub fn new() -> Self {
608 Self::default()
609 }
610
611 pub fn with_limit(limit: usize) -> Self {
614 Self {
615 buffer: Vec::new(),
616 scanned: 0,
617 ready: Vec::new(),
618 limit,
619 skipping: false,
620 }
621 }
622
623 pub fn push(&mut self, chunk: &[u8]) -> std::vec::Drain<'_, Result<Vec<u8>, TooLarge>> {
629 let mut rest = chunk;
630 while !rest.is_empty() {
631 if self.skipping {
632 let Some(end) = rest.iter().position(|byte| *byte == b'\n') else {
633 break;
634 };
635 self.skipping = false;
636 rest = rest.get(end + 1..).unwrap_or_default();
637 continue;
638 }
639 let room = self.limit.saturating_sub(self.held()).saturating_add(1);
640 let (piece, after) = rest.split_at(room.min(rest.len()));
641 self.lines(piece);
642 rest = after;
643 if self.held() > self.limit {
644 let asked = self.held();
645 self.buffer = Vec::new();
646 self.scanned = 0;
647 self.skipping = true;
648 self.ready.push(Err(TooLarge {
649 limit: self.limit,
650 asked,
651 }));
652 }
653 }
654 self.ready.drain(..)
655 }
656
657 fn held(&self) -> usize {
660 let cr = self.buffer.last() == Some(&b'\r');
661 self.buffer.len() - usize::from(cr)
662 }
663
664 fn lines(&mut self, chunk: &[u8]) {
666 self.buffer.extend_from_slice(chunk);
667 let mut rest = self.buffer.as_slice();
668 while let Some((line, end)) = split_line(rest, self.scanned, |byte| *byte == b'\n') {
669 self.scanned = 0;
670 let line = line.strip_suffix(b"\r").unwrap_or(line);
671 if line.len() > self.limit {
673 self.ready.push(Err(TooLarge {
674 limit: self.limit,
675 asked: line.len(),
676 }));
677 } else if !line.is_empty() {
678 self.ready.push(Ok(line.to_vec()));
679 }
680 rest = end.get(1..).unwrap_or_default();
681 }
682 self.scanned = rest.len();
683 let consumed = self.buffer.len() - rest.len();
684 self.buffer.drain(..consumed);
685 }
686
687 pub fn finish(&mut self) -> Option<Vec<u8>> {
691 let mut line = std::mem::take(&mut self.buffer);
692 if line.last() == Some(&b'\r') {
693 line.pop();
694 }
695 (!line.is_empty()).then_some(line)
696 }
697
698 pub fn pending(&self) -> usize {
700 self.buffer.len()
701 }
702}
703
704fn decoded_len(line: &[u8]) -> usize {
707 let replacement = char::REPLACEMENT_CHARACTER.len_utf8();
708 line.utf8_chunks().fold(0, |len, chunk| {
709 let invalid = if chunk.invalid().is_empty() {
710 0
711 } else {
712 replacement
713 };
714 len.saturating_add(chunk.valid().len())
715 .saturating_add(invalid)
716 })
717}
718
719fn terminated_line(buffer: &[u8], scanned: usize) -> Option<(&[u8], &[u8])> {
725 let (line, end) = split_line(buffer, scanned, |byte| *byte == b'\n' || *byte == b'\r')?;
726 let rest = end.strip_prefix(b"\r\n").or_else(|| end.get(1..));
727 Some((line, rest.unwrap_or_default()))
728}
729
730fn split_line(buffer: &[u8], scanned: usize, ends: impl Fn(&u8) -> bool) -> Option<(&[u8], &[u8])> {
733 buffer.split_at_checked(scanned + buffer.iter().skip(scanned).position(ends)?)
734}
735
736#[cfg(test)]
737mod tests;