Skip to main content

mutil_ai/
stream.rs

1use std::collections::VecDeque;
2use std::future::Future;
3use std::pin::Pin;
4use std::sync::Arc;
5use std::task::{Context, Poll};
6use std::time::Duration;
7
8use bytes::Bytes;
9use futures_core::Stream;
10
11use crate::audit::{AuditContext, AuditOutcome, FirstTokenKind};
12use crate::cancel::CancellationToken;
13use crate::error::{Error, ErrorKind, Result};
14use crate::security::{RequestBudget, ResponseLimits};
15use crate::sse::{SseError, SseEvent, SseMessage, SseParser};
16use crate::types::{
17    ChatResponse, NativeToolCall, ReasoningKind, ResponseMetadata, ServerToolState, Usage,
18};
19
20/// A boxed provider-neutral stream of model events.
21pub type ModelStream = Pin<Box<dyn Stream<Item = Result<StreamEvent>> + Send + 'static>>;
22
23/// Opt-in transport reconnect policy for an already-started SSE stream.
24#[derive(Debug, Clone, Copy, PartialEq, Eq)]
25pub struct StreamReconnectPolicy {
26    /// Maximum number of reconnect attempts before the stream fails.
27    pub max_attempts: u32,
28    /// Delay between attempts, used when neither the server nor the parser
29    /// supplied a `retry` hint.
30    pub delay: Duration,
31    /// Refuse reconnect when no SSE event id has been observed.
32    pub require_event_id: bool,
33    /// Refuse reconnect delays above this cap (including server retry hints).
34    pub max_delay: Duration,
35    /// Suppress a replayed suffix only when the server guarantees replay semantics.
36    /// Off by default: inherited SSE IDs are not unique event identifiers.
37    pub deduplicate_replay: bool,
38}
39
40impl Default for StreamReconnectPolicy {
41    fn default() -> Self {
42        Self {
43            max_attempts: 2,
44            delay: Duration::from_millis(250),
45            require_event_id: true,
46            max_delay: Duration::from_secs(60),
47            deduplicate_replay: false,
48        }
49    }
50}
51
52impl StreamReconnectPolicy {
53    /// Creates the default policy: 2 attempts, 250 ms delay, requiring an
54    /// event id.
55    pub fn new() -> Self {
56        Self::default()
57    }
58
59    /// Sets the maximum number of reconnect attempts.
60    pub fn max_attempts(mut self, max_attempts: u32) -> Self {
61        self.max_attempts = max_attempts;
62        self
63    }
64
65    /// Sets the delay between reconnect attempts.
66    pub fn delay(mut self, delay: Duration) -> Self {
67        self.delay = delay;
68        self
69    }
70
71    /// Sets whether reconnecting requires an observed SSE event id.
72    pub fn require_event_id(mut self, require_event_id: bool) -> Self {
73        self.require_event_id = require_event_id;
74        self
75    }
76
77    /// Sets the maximum permitted reconnect delay.
78    pub fn max_delay(mut self, max_delay: Duration) -> Self {
79        self.max_delay = max_delay;
80        self
81    }
82
83    /// Enables suffix replay suppression for servers with documented resume semantics.
84    pub fn deduplicate_replay(mut self, enabled: bool) -> Self {
85        self.deduplicate_replay = enabled;
86        self
87    }
88}
89
90/// A provider-neutral streaming event.
91#[derive(Debug, Clone, PartialEq)]
92pub enum StreamEvent {
93    /// The HTTP response was accepted and the stream is starting.
94    Start {
95        provider: &'static str,
96        model: String,
97        metadata: ResponseMetadata,
98    },
99    /// Incremental assistant-visible text.
100    TextDelta { text: String },
101    /// Incremental reasoning summary or readable reasoning text.
102    ReasoningDelta { kind: ReasoningKind, text: String },
103    /// Incremental tool-call data.
104    ///
105    /// `index` identifies the tool call within the assistant message.
106    ToolCallDelta {
107        index: usize,
108        id: Option<String>,
109        name: Option<String>,
110        arguments_delta: String,
111    },
112    /// The complete tool arguments accumulated so far for a call.
113    ToolCallProgress {
114        index: usize,
115        id: Option<String>,
116        name: Option<String>,
117        arguments_so_far: String,
118    },
119    /// Raw custom input progress. This event is not proof of completion.
120    NativeToolProgress {
121        index: usize,
122        item_id: Option<String>,
123        input_so_far: String,
124    },
125    /// A completed native item. Applications must still apply cancellation and
126    /// response-level scheduling policy before executing a write.
127    NativeToolCompleted { index: usize, call: NativeToolCall },
128    /// A provider-hosted or built-in tool changed state.
129    ServerToolStatus {
130        tool: String,
131        call_id: Option<String>,
132        state: ServerToolState,
133    },
134    /// Usage reported during the stream. Providers may send this only at the end.
135    Usage { usage: Usage },
136    /// A server-directed SSE retry delay.
137    Retry { delay: Duration },
138    /// The SDK scheduled a retry or reconnect with stable metadata.
139    Retrying {
140        attempt: u32,
141        max_attempts: u32,
142        delay: Duration,
143        reason: String,
144    },
145    /// A recoverable stream error. Terminal errors are returned as `Err`.
146    Error { error: StreamError },
147    /// The stream completed and the SDK assembled a normal response.
148    ///
149    /// Consumers that persist conversation history should append
150    /// `response.message`, not reconstruct it from deltas.
151    Done {
152        response: Box<ChatResponse>,
153        finish_reason: Option<String>,
154    },
155}
156
157/// Stable, content-free metadata for a recoverable stream error.
158#[derive(Debug, Clone, PartialEq, Eq)]
159pub struct StreamError {
160    /// The error classification, safe to match on.
161    pub kind: ErrorKind,
162    /// A human-readable description without request content.
163    pub message: String,
164    /// Whether the SDK or caller may retry the request.
165    pub recoverable: bool,
166}
167
168/// Provider-specific mapper from one SSE message to zero or more events.
169pub(crate) trait SseMapper: Send + Unpin + 'static {
170    fn configure_limits(&mut self, _limits: ResponseLimits) {}
171    fn map(&mut self, message: SseMessage) -> Result<Vec<StreamEvent>>;
172
173    /// Whether a clean EOF is a valid terminal condition for this protocol.
174    fn eof_is_terminal(&self) -> bool {
175        true
176    }
177
178    /// The SSE parser used by [`SseStream`] for this protocol. Adapters may
179    /// override it to opt into e.g. [`crate::sse::TailPolicy::Flush`].
180    fn sse_parser(&self) -> SseParser {
181        SseParser::new()
182    }
183
184    fn finish(&mut self) -> Result<Vec<StreamEvent>> {
185        Ok(Vec::new())
186    }
187}
188
189pub(crate) fn sse_stream_with_audit<M>(
190    response: reqwest::Response,
191    mapper: M,
192    cancellation: Option<CancellationToken>,
193    idle_timeout: Option<Duration>,
194    audit: Option<AuditContext>,
195    budget: RequestBudget,
196) -> ModelStream
197where
198    M: SseMapper,
199{
200    let metadata = ResponseMetadata::from_response(&response);
201    let cancellation_future = cancellation_future(cancellation.clone());
202    Box::pin(SseStream {
203        inner: Box::pin(response.bytes_stream()),
204        parser: mapper.sse_parser().with_byte_limits(
205            budget.limits.max_sse_line_bytes,
206            budget.limits.max_sse_event_bytes,
207        ),
208        mapper,
209        queue: VecDeque::new(),
210        finished: false,
211        terminal: false,
212        last_event_id: None,
213        recent_events: VecDeque::new(),
214        recent_bytes: 0,
215        replay_events: None,
216        replay_started: false,
217        reconnect: None,
218        reconnect_future: None,
219        cancellation,
220        cancellation_future,
221        idle_timeout,
222        idle_deadline: idle_deadline(idle_timeout),
223        audit,
224        audit_finished: false,
225        audit_status: Some(metadata.status),
226        audit_provider_request_id: metadata.request_id,
227        total_deadline: budget
228            .deadline
229            .map(|deadline| Box::pin(tokio::time::sleep_until(deadline))),
230        budget,
231        event_count: 0,
232    })
233}
234
235type CancellationFuture = Pin<Box<dyn Future<Output = ()> + Send>>;
236
237fn cancellation_future(cancellation: Option<CancellationToken>) -> Option<CancellationFuture> {
238    cancellation.map(|cancellation| {
239        Box::pin(async move {
240            cancellation.cancelled().await;
241        }) as CancellationFuture
242    })
243}
244
245type IdleDeadline = Pin<Box<tokio::time::Sleep>>;
246
247fn idle_deadline(timeout: Option<Duration>) -> Option<IdleDeadline> {
248    timeout.map(|timeout| Box::pin(tokio::time::sleep(timeout)))
249}
250
251type ReconnectFuture = Pin<Box<dyn Future<Output = Result<reqwest::Response>> + Send>>;
252
253trait ReconnectFactory: Send {
254    fn connect(&mut self, last_event_id: Option<String>) -> ReconnectFuture;
255}
256
257impl<F> ReconnectFactory for F
258where
259    F: FnMut(Option<String>) -> ReconnectFuture + Send + 'static,
260{
261    fn connect(&mut self, last_event_id: Option<String>) -> ReconnectFuture {
262        self(last_event_id)
263    }
264}
265
266struct ReconnectState {
267    factory: Box<dyn ReconnectFactory>,
268    policy: StreamReconnectPolicy,
269    attempts: u32,
270}
271
272#[allow(clippy::too_many_arguments)]
273pub(crate) fn sse_stream_with_reconnect<M, F>(
274    response: reqwest::Response,
275    mapper: M,
276    policy: StreamReconnectPolicy,
277    factory: F,
278    cancellation: Option<CancellationToken>,
279    idle_timeout: Option<Duration>,
280    audit: Option<AuditContext>,
281    budget: RequestBudget,
282) -> ModelStream
283where
284    M: SseMapper,
285    F: FnMut(Option<String>) -> ReconnectFuture + Send + 'static,
286{
287    let metadata = ResponseMetadata::from_response(&response);
288    let cancellation_future = cancellation_future(cancellation.clone());
289    Box::pin(SseStream {
290        inner: Box::pin(response.bytes_stream()),
291        parser: mapper.sse_parser().with_byte_limits(
292            budget.limits.max_sse_line_bytes,
293            budget.limits.max_sse_event_bytes,
294        ),
295        mapper,
296        queue: VecDeque::new(),
297        finished: false,
298        terminal: false,
299        last_event_id: None,
300        recent_events: VecDeque::new(),
301        recent_bytes: 0,
302        replay_events: None,
303        replay_started: false,
304        reconnect: Some(ReconnectState {
305            factory: Box::new(factory),
306            policy,
307            attempts: 0,
308        }),
309        reconnect_future: None,
310        cancellation,
311        cancellation_future,
312        idle_timeout,
313        idle_deadline: idle_deadline(idle_timeout),
314        audit,
315        audit_finished: false,
316        audit_status: Some(metadata.status),
317        audit_provider_request_id: metadata.request_id,
318        total_deadline: budget
319            .deadline
320            .map(|deadline| Box::pin(tokio::time::sleep_until(deadline))),
321        budget,
322        event_count: 0,
323    })
324}
325
326struct SseStream<M> {
327    inner: Pin<Box<dyn Stream<Item = std::result::Result<Bytes, reqwest::Error>> + Send>>,
328    parser: SseParser,
329    mapper: M,
330    queue: VecDeque<Result<StreamEvent>>,
331    finished: bool,
332    terminal: bool,
333    last_event_id: Option<String>,
334    recent_events: VecDeque<Arc<SseMessage>>,
335    recent_bytes: usize,
336    replay_events: Option<VecDeque<Arc<SseMessage>>>,
337    replay_started: bool,
338    reconnect: Option<ReconnectState>,
339    reconnect_future: Option<ReconnectFuture>,
340    cancellation: Option<CancellationToken>,
341    cancellation_future: Option<CancellationFuture>,
342    idle_timeout: Option<Duration>,
343    idle_deadline: Option<IdleDeadline>,
344    audit: Option<AuditContext>,
345    audit_finished: bool,
346    audit_status: Option<u16>,
347    audit_provider_request_id: Option<String>,
348    budget: RequestBudget,
349    total_deadline: Option<IdleDeadline>,
350    event_count: usize,
351}
352
353const MAX_REPLAY_BYTES: usize = 1024 * 1024;
354const MAX_REPLAY_EVENTS: usize = 4096;
355
356impl<M> SseStream<M>
357where
358    M: SseMapper,
359{
360    fn finish_audit(&mut self, error: Option<&Error>, usage: Option<Usage>) {
361        if self.audit_finished {
362            return;
363        }
364        let Some(audit) = &self.audit else {
365            return;
366        };
367        self.audit_finished = true;
368        let outcome = match error {
369            Some(Error::Cancelled) => AuditOutcome::Cancelled,
370            Some(_) => AuditOutcome::Failure,
371            None => AuditOutcome::Success,
372        };
373        audit.request_finished_with_request_id(
374            outcome,
375            self.audit_status,
376            self.audit_provider_request_id.clone(),
377            error,
378            usage,
379        );
380    }
381
382    fn enqueue_events(&mut self, events: Vec<StreamEvent>) {
383        for event in events {
384            if let Some(audit) = &self.audit {
385                match &event {
386                    StreamEvent::TextDelta { .. } => audit.first_token(FirstTokenKind::Text),
387                    StreamEvent::ReasoningDelta { .. } => {
388                        audit.first_token(FirstTokenKind::Reasoning);
389                    }
390                    StreamEvent::ToolCallDelta { .. } | StreamEvent::ToolCallProgress { .. } => {
391                        audit.first_token(FirstTokenKind::ToolCall);
392                    }
393                    _ => {}
394                }
395            }
396            if let StreamEvent::Done { response, .. } = &event {
397                self.terminal = true;
398                self.finish_audit(None, response.usage.clone());
399            }
400            self.queue.push_back(Ok(event));
401        }
402    }
403
404    fn process_sse(&mut self, event: SseEvent) {
405        if self.finished || self.terminal {
406            return;
407        }
408        self.event_count += 1;
409        if self.event_count > self.budget.limits.max_stream_events {
410            self.fail(Error::ResponseLimit {
411                resource: "SSE events",
412                limit: self.budget.limits.max_stream_events,
413            });
414            return;
415        }
416        match event {
417            SseEvent::Retry(delay) => self.queue.push_back(Ok(StreamEvent::Retry { delay })),
418            SseEvent::Message(message) => {
419                self.last_event_id = message.id.clone().filter(|id| !id.is_empty());
420                if self.is_replayed(&message) {
421                    return;
422                }
423                if self
424                    .reconnect
425                    .as_ref()
426                    .is_some_and(|state| state.policy.deduplicate_replay)
427                {
428                    self.remember_event(&message);
429                }
430
431                match self.mapper.map(message) {
432                    Ok(events) => self.enqueue_events(events),
433                    Err(error) => {
434                        self.finish_audit(Some(&error), None);
435                        self.queue.push_back(Err(error));
436                        self.finished = true;
437                    }
438                }
439            }
440        }
441    }
442
443    fn is_replayed(&mut self, message: &SseMessage) -> bool {
444        let Some(replay) = self.replay_events.as_mut() else {
445            return false;
446        };
447        if !self.replay_started {
448            if let Some(index) = replay.iter().position(|old| old.as_ref() == message) {
449                replay.drain(..index);
450                self.replay_started = true;
451            } else {
452                self.replay_events = None;
453                return false;
454            }
455        }
456        if replay.front().is_some_and(|old| old.as_ref() == message) {
457            replay.pop_front();
458            if replay.is_empty() {
459                self.replay_events = None;
460            }
461            true
462        } else {
463            self.replay_events = None;
464            false
465        }
466    }
467
468    fn remember_event(&mut self, message: &SseMessage) {
469        if message.id.as_ref().is_none_or(String::is_empty) {
470            return;
471        }
472        let bytes = message.data.len()
473            + message.id.as_ref().map_or(0, String::len)
474            + message.event.as_ref().map_or(0, String::len);
475        // An oversized event cannot participate in safe bounded replay matching.
476        if bytes > MAX_REPLAY_BYTES {
477            self.recent_events.clear();
478            self.recent_bytes = 0;
479            return;
480        }
481        self.recent_bytes += bytes;
482        self.recent_events.push_back(Arc::new(message.clone()));
483        while self.recent_bytes > MAX_REPLAY_BYTES || self.recent_events.len() > MAX_REPLAY_EVENTS {
484            if let Some(old) = self.recent_events.pop_front() {
485                self.recent_bytes -= old.data.len()
486                    + old.id.as_ref().map_or(0, String::len)
487                    + old.event.as_ref().map_or(0, String::len);
488            }
489        }
490    }
491
492    fn fail(&mut self, error: Error) {
493        self.finish_audit(Some(&error), None);
494        self.queue.push_back(Err(error));
495        self.finished = true;
496    }
497
498    fn process_sse_result(&mut self, result: std::result::Result<Vec<SseEvent>, SseError>) {
499        match result {
500            Ok(events) => {
501                for event in events {
502                    self.process_sse(event);
503                }
504            }
505            Err(error) => {
506                let error = Error::StreamProtocol(error.to_string());
507                self.finish_audit(Some(&error), None);
508                self.queue.push_back(Err(error));
509                self.finished = true;
510            }
511        }
512    }
513
514    fn finish_stream(&mut self) {
515        self.finished = true;
516
517        match self.parser.finish() {
518            Ok(events) => {
519                for event in events {
520                    self.process_sse(event);
521                }
522            }
523            Err(error) => {
524                let error = Error::StreamProtocol(error.to_string());
525                self.finish_audit(Some(&error), None);
526                self.queue.push_back(Err(error));
527                return;
528            }
529        }
530
531        if self.terminal || self.queue.iter().any(Result::is_err) {
532            return;
533        }
534
535        match self.mapper.finish() {
536            Ok(events) => self.enqueue_events(events),
537            Err(error) => {
538                self.finish_audit(Some(&error), None);
539                self.queue.push_back(Err(error));
540            }
541        }
542
543        if !self.terminal && !self.queue.iter().any(Result::is_err) {
544            let error =
545                Error::StreamProtocol("stream ended without a provider terminal event".to_string());
546            self.finish_audit(Some(&error), None);
547            self.queue.push_back(Err(error));
548        }
549    }
550
551    fn schedule_reconnect(&mut self, delay_hint: Option<Duration>) -> bool {
552        if self.terminal || self.finished {
553            return false;
554        }
555        let Some(reconnect) = self.reconnect.as_mut() else {
556            return false;
557        };
558        if reconnect.attempts >= reconnect.policy.max_attempts {
559            return false;
560        }
561        if reconnect.policy.require_event_id && self.last_event_id.is_none() {
562            return false;
563        }
564
565        let last_event_id = self.last_event_id.clone();
566        let delay = delay_hint
567            .or_else(|| self.parser.retry())
568            .unwrap_or(reconnect.policy.delay);
569        if delay > reconnect.policy.max_delay {
570            return false;
571        }
572        if reconnect.policy.deduplicate_replay {
573            self.replay_events = Some(self.recent_events.clone());
574            self.replay_started = false;
575        }
576        reconnect.attempts += 1;
577        if let Some(audit) = &self.audit {
578            audit.stream_reconnect_scheduled(reconnect.attempts, delay, last_event_id.is_some());
579        }
580        let future = reconnect.factory.connect(last_event_id);
581        self.queue.push_back(Ok(StreamEvent::Retry { delay }));
582        self.queue.push_back(Ok(StreamEvent::Retrying {
583            attempt: reconnect.attempts,
584            max_attempts: reconnect.policy.max_attempts,
585            delay,
586            reason: "stream reconnect".to_string(),
587        }));
588        self.idle_deadline = None;
589        let cancellation = self.cancellation.clone();
590        self.reconnect_future = Some(Box::pin(async move {
591            if let Some(cancellation) = cancellation {
592                tokio::select! {
593                    biased;
594                    _ = cancellation.cancelled() => Err(Error::Cancelled),
595                    _ = tokio::time::sleep(delay) => future.await,
596                }
597            } else {
598                tokio::time::sleep(delay).await;
599                future.await
600            }
601        }));
602        true
603    }
604
605    fn cancel(&mut self) {
606        let error = Error::Cancelled;
607        self.finish_audit(Some(&error), None);
608        self.queue.push_back(Err(error));
609        self.finished = true;
610    }
611
612    fn reset_idle_deadline(&mut self) {
613        self.idle_deadline = idle_deadline(self.idle_timeout);
614    }
615
616    fn handle_idle_timeout(&mut self) {
617        if self.schedule_reconnect(None) {
618            self.idle_deadline = None;
619            return;
620        }
621        let error = Error::Timeout("stream idle timeout".to_string());
622        self.finish_audit(Some(&error), None);
623        self.queue.push_back(Err(error));
624        self.finished = true;
625    }
626
627    fn handle_transport_error(&mut self, error: reqwest::Error) {
628        if self.schedule_reconnect(None) {
629            return;
630        }
631        let error = Error::from(error);
632        self.finish_audit(Some(&error), None);
633        self.queue.push_back(Err(error));
634        self.finished = true;
635    }
636}
637
638impl<M> Drop for SseStream<M> {
639    fn drop(&mut self) {
640        if self.audit_finished {
641            return;
642        }
643        let Some(audit) = &self.audit else {
644            return;
645        };
646        audit.request_finished_with_request_id(
647            AuditOutcome::Cancelled,
648            self.audit_status,
649            self.audit_provider_request_id.clone(),
650            None,
651            None,
652        );
653        self.audit_finished = true;
654    }
655}
656
657impl<M> Stream for SseStream<M>
658where
659    M: SseMapper,
660{
661    type Item = Result<StreamEvent>;
662
663    fn poll_next(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Option<Self::Item>> {
664        let this = self.get_mut();
665        loop {
666            if !this.finished && !this.terminal {
667                if this
668                    .cancellation
669                    .as_ref()
670                    .is_some_and(CancellationToken::is_cancelled)
671                {
672                    this.queue.clear();
673                    this.cancel();
674                    continue;
675                }
676                if let Some(mut deadline) = this.total_deadline.take() {
677                    match deadline.as_mut().poll(cx) {
678                        Poll::Pending => this.total_deadline = Some(deadline),
679                        Poll::Ready(()) => {
680                            this.queue.clear();
681                            this.fail(Error::Timeout("total request deadline".into()));
682                            continue;
683                        }
684                    }
685                }
686            }
687            if let Some(event) = this.queue.pop_front() {
688                return Poll::Ready(Some(event));
689            }
690
691            if this.terminal {
692                this.finished = true;
693                return Poll::Ready(None);
694            }
695
696            if this.finished {
697                return Poll::Ready(None);
698            }
699
700            if let Some(mut future) = this.cancellation_future.take() {
701                match future.as_mut().poll(cx) {
702                    Poll::Pending => {
703                        this.cancellation_future = Some(future);
704                    }
705                    Poll::Ready(()) => {
706                        this.cancel();
707                        continue;
708                    }
709                }
710            }
711
712            if this.reconnect_future.is_none()
713                && let Some(mut deadline) = this.idle_deadline.take()
714            {
715                match deadline.as_mut().poll(cx) {
716                    Poll::Pending => {
717                        this.idle_deadline = Some(deadline);
718                    }
719                    Poll::Ready(()) => {
720                        this.handle_idle_timeout();
721                        continue;
722                    }
723                }
724            }
725
726            if let Some(mut future) = this.reconnect_future.take() {
727                match future.as_mut().poll(cx) {
728                    Poll::Pending => {
729                        this.reconnect_future = Some(future);
730                        return Poll::Pending;
731                    }
732                    Poll::Ready(Ok(response)) => {
733                        this.inner = Box::pin(response.bytes_stream());
734                        this.parser.reset_for_reconnect();
735                        this.reset_idle_deadline();
736                        continue;
737                    }
738                    Poll::Ready(Err(error)) => {
739                        if this.schedule_reconnect(error.retry_after()) {
740                            continue;
741                        }
742                        this.finish_audit(Some(&error), None);
743                        this.queue.push_back(Err(error));
744                        this.finished = true;
745                        continue;
746                    }
747                }
748            }
749
750            match this.inner.as_mut().poll_next(cx) {
751                Poll::Pending => return Poll::Pending,
752                Poll::Ready(Some(Ok(bytes))) => {
753                    if let Some(audit) = &this.audit {
754                        audit.add_response_bytes(bytes.len());
755                    }
756                    if let Err(error) = this.budget.add_bytes(bytes.len()) {
757                        this.fail(error);
758                        continue;
759                    }
760                    this.reset_idle_deadline();
761                    let result = this.parser.push(&bytes);
762                    this.process_sse_result(result);
763                }
764                Poll::Ready(Some(Err(error))) => this.handle_transport_error(error),
765                Poll::Ready(None) => {
766                    if !this.terminal
767                        && !this.mapper.eof_is_terminal()
768                        && this.schedule_reconnect(None)
769                    {
770                        continue;
771                    }
772                    this.finish_stream();
773                }
774            }
775        }
776    }
777}
778
779/// Await the next stream event without requiring the caller to import
780/// `futures_util::StreamExt`.
781pub async fn next_event(stream: &mut ModelStream) -> Option<Result<StreamEvent>> {
782    use std::future::poll_fn;
783
784    poll_fn(|cx| stream.as_mut().poll_next(cx)).await
785}
786
787/// Collect a stream into the final response while preserving all events.
788///
789/// This is mainly useful for tests and for applications that intentionally do
790/// not render tokens incrementally.
791pub async fn collect_stream(mut stream: ModelStream) -> Result<ChatResponse> {
792    while let Some(event) = next_event(&mut stream).await {
793        if let StreamEvent::Done { response, .. } = event? {
794            return Ok(*response);
795        }
796    }
797
798    Err(Error::StreamProtocol(
799        "stream ended without a Done event".to_string(),
800    ))
801}
802
803#[cfg(test)]
804mod tests {
805    use super::*;
806    use crate::types::Message;
807
808    struct TestMapper {
809        text: String,
810    }
811
812    impl SseMapper for TestMapper {
813        fn map(&mut self, message: SseMessage) -> Result<Vec<StreamEvent>> {
814            self.text.push_str(&message.data);
815            Ok(vec![StreamEvent::TextDelta { text: message.data }])
816        }
817
818        fn finish(&mut self) -> Result<Vec<StreamEvent>> {
819            Ok(vec![StreamEvent::Done {
820                response: Box::new(ChatResponse::new(Message::assistant(&self.text))),
821                finish_reason: Some("stop".to_string()),
822            }])
823        }
824    }
825
826    #[test]
827    fn sse_stream_handles_split_cjk_and_emits_done() {
828        let payload = "retry: 10\ndata: 你好\n\n";
829        let split = payload.find("你").expect("CJK marker exists") + "你".len() - 1;
830        let chunks = vec![
831            Ok::<_, reqwest::Error>(Bytes::copy_from_slice(&payload.as_bytes()[..split])),
832            Ok::<_, reqwest::Error>(Bytes::copy_from_slice(&payload.as_bytes()[split..])),
833        ];
834        let inner: Pin<Box<dyn Stream<Item = std::result::Result<Bytes, reqwest::Error>> + Send>> =
835            Box::pin(futures_util::stream::iter(chunks));
836        let stream: ModelStream = Box::pin(SseStream {
837            inner,
838            parser: SseParser::new(),
839            mapper: TestMapper {
840                text: String::new(),
841            },
842            queue: VecDeque::new(),
843            finished: false,
844            terminal: false,
845            last_event_id: None,
846            recent_events: VecDeque::new(),
847            recent_bytes: 0,
848            replay_events: None,
849            replay_started: false,
850            reconnect: None,
851            reconnect_future: None,
852            cancellation: None,
853            cancellation_future: None,
854            idle_timeout: None,
855            idle_deadline: None,
856            audit: None,
857            audit_finished: false,
858            audit_status: None,
859            audit_provider_request_id: None,
860            budget: RequestBudget::new(&crate::RequestOptions::default()).unwrap(),
861            total_deadline: None,
862            event_count: 0,
863        });
864
865        let response = futures_executor::block_on(collect_stream(stream)).unwrap();
866        assert_eq!(response.text(), "你好");
867    }
868}