Skip to main content

rig_core/providers/openai/responses_api/
websocket.rs

1//! Stateful Responses WebSocket sessions over caller-supplied connections.
2//! Sessions permit one in-flight turn and chain completed or incomplete response IDs.
3//!
4//! ```
5//! use rig_core::providers::openai::responses_api::websocket::ResponsesWebSocketCreateOptions;
6//! let options = ResponsesWebSocketCreateOptions::warmup();
7//! assert_eq!(options.generate, Some(false));
8//! ```
9
10use crate::completion;
11use crate::completion::options::FinalBody;
12use crate::driver::Model;
13use crate::error::{EncodeError, ProviderError};
14use crate::http_client::{self, NoBody};
15use crate::json_utils::remove_preserving_order;
16use crate::operation::{Completion, ReplyFold};
17use crate::providers::openai::responses_api::streaming::{
18    ResponsesDecoder, ResponsesEvent, classify_responses_payload, document, is_lifecycle_event,
19};
20use crate::providers::openai::responses_api::wire::Responses;
21use crate::streaming::Item;
22use crate::wire::{Call, Flow, Mode, Operation, Reply, Shared, Wire, WireFrame};
23use crate::ws_client::{
24    BoxedWebSocketConnection, ConnectOptions, Frame, WebSocketClientExt, WebSocketConnection,
25};
26use serde::{Deserialize, Serialize};
27use serde_json::{Map, Value};
28use std::time::Duration;
29
30/// The websocket endpoint's path, appended to the client's configured base URL.
31const WEBSOCKET_PATH: &str = "responses";
32
33const DEFAULT_CONNECT_TIMEOUT: Duration = Duration::from_secs(30);
34
35/// Request-ID header read from rejected WebSocket upgrades.
36const REQUEST_ID_HEADER: Option<&'static str> =
37    crate::providers::openai::wire::OPENAI.request_id_header;
38
39/// Options for a `response.create` message sent over OpenAI WebSocket mode.
40#[derive(Debug, Clone, Default, Serialize, Deserialize)]
41pub struct ResponsesWebSocketCreateOptions {
42    /// When set to `false`, OpenAI prepares request state without generating a model output.
43    ///
44    /// This is the "warmup" mode described in the OpenAI WebSocket mode guide.
45    #[serde(skip_serializing_if = "Option::is_none")]
46    pub generate: Option<bool>,
47}
48
49impl ResponsesWebSocketCreateOptions {
50    /// Creates warmup options equivalent to `generate: false`.
51    #[must_use]
52    pub fn warmup() -> Self {
53        Self {
54            generate: Some(false),
55        }
56    }
57}
58
59#[derive(Debug, Clone, Serialize)]
60#[serde(tag = "type")]
61enum ClientEvent {
62    #[serde(rename = "response.create")]
63    Create(FinalBody),
64}
65
66/// A protocol error event emitted by OpenAI WebSocket mode.
67#[derive(Debug, Clone, Serialize, Deserialize)]
68pub struct ResponsesWebSocketErrorEvent {
69    /// The event type.
70    #[serde(rename = "type")]
71    pub kind: ResponsesWebSocketErrorEventKind,
72    /// The provider error payload.
73    pub error: ResponsesWebSocketErrorPayload,
74}
75
76impl std::fmt::Display for ResponsesWebSocketErrorEvent {
77    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
78        self.error.fmt(f)
79    }
80}
81
82/// The event kind for an OpenAI WebSocket protocol error.
83#[derive(Debug, Clone, Serialize, Deserialize)]
84pub enum ResponsesWebSocketErrorEventKind {
85    #[serde(rename = "error")]
86    Error,
87}
88
89/// The payload carried by an OpenAI WebSocket protocol error event.
90#[derive(Debug, Clone, Default, Serialize, Deserialize)]
91pub struct ResponsesWebSocketErrorPayload {
92    /// Provider-specific error code when supplied.
93    #[serde(skip_serializing_if = "Option::is_none")]
94    pub code: Option<String>,
95    /// Human-readable error message.
96    #[serde(skip_serializing_if = "Option::is_none")]
97    pub message: Option<String>,
98    /// Any extra fields supplied by the provider.
99    #[serde(flatten, default)]
100    pub extra: Map<String, Value>,
101}
102
103impl std::fmt::Display for ResponsesWebSocketErrorPayload {
104    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
105        match (&self.code, &self.message) {
106            (Some(code), Some(message)) => write!(f, "{code}: {message}"),
107            (None, Some(message)) => f.write_str(message),
108            (Some(code), None) => f.write_str(code),
109            (None, None) => f.write_str("OpenAI websocket error"),
110        }
111    }
112}
113
114/// The optional `response.done` event emitted by OpenAI WebSocket mode.
115#[derive(Debug, Clone, Serialize, Deserialize)]
116pub struct ResponsesWebSocketDoneEvent {
117    /// The event type.
118    #[serde(rename = "type")]
119    pub kind: ResponsesWebSocketDoneEventKind,
120    /// The provider payload for the finished response.
121    pub response: Value,
122}
123
124impl ResponsesWebSocketDoneEvent {
125    /// Returns the response ID if the payload includes one.
126    #[must_use]
127    pub fn response_id(&self) -> Option<&str> {
128        self.response.get("id").and_then(Value::as_str)
129    }
130
131    fn status(&self) -> Option<&str> {
132        self.response.get("status").and_then(Value::as_str)
133    }
134}
135
136/// The event kind for the terminal websocket event.
137#[derive(Debug, Clone, Serialize, Deserialize)]
138pub enum ResponsesWebSocketDoneEventKind {
139    #[serde(rename = "response.done")]
140    ResponseDone,
141}
142
143/// A server event emitted by OpenAI WebSocket mode.
144#[derive(Debug, Clone)]
145pub enum ResponsesWebSocketEvent {
146    /// A response lifecycle event such as `response.created` or
147    /// `response.completed`, with the response object it carries.
148    Response {
149        /// The event's `type`.
150        kind: String,
151        /// The response object, as the provider sent it.
152        response: Value,
153    },
154    /// A streaming item or delta event such as `response.output_text.delta`,
155    /// as the provider sent it.
156    Item(Value),
157    /// A protocol-level websocket error event.
158    Error(ResponsesWebSocketErrorEvent),
159    /// An optional `response.done` event emitted by OpenAI over WebSockets.
160    Done(ResponsesWebSocketDoneEvent),
161    /// Unrecognized event retained for [`Item::Unknown`] passthrough.
162    Unknown(crate::streaming::UnknownPayload),
163}
164
165impl ResponsesWebSocketEvent {
166    /// Returns the response ID when the event includes one.
167    #[must_use]
168    pub fn response_id(&self) -> Option<&str> {
169        match self {
170            Self::Response { response, .. } => response.get("id").and_then(Value::as_str),
171            Self::Done(done) => done.response_id(),
172            Self::Item(_) | Self::Error(_) | Self::Unknown(_) => None,
173        }
174    }
175
176    /// Returns `true` when this event ends the current in-flight websocket turn.
177    #[must_use]
178    pub fn is_terminal(&self) -> bool {
179        match self {
180            Self::Response { kind, .. } => is_terminal_kind(kind),
181            Self::Error(_) | Self::Done(_) => true,
182            Self::Item(_) | Self::Unknown(_) => false,
183        }
184    }
185}
186
187/// Whether a lifecycle event of `kind` ends the turn.
188fn is_terminal_kind(kind: &str) -> bool {
189    matches!(
190        kind,
191        "response.completed" | "response.failed" | "response.incomplete"
192    )
193}
194
195/// A builder for an OpenAI Responses WebSocket session.
196///
197/// The default builder applies a 30 second connection timeout and the
198/// driver's [`STREAM_IDLE_TIMEOUT`](crate::driver::STREAM_IDLE_TIMEOUT) to
199/// each wait for an event.
200pub struct ResponsesWebSocketSessionBuilder {
201    wire: Responses,
202    connect_timeout: Option<Duration>,
203    event_timeout: Option<Duration>,
204    cache_key: Option<String>,
205}
206
207impl ResponsesWebSocketSessionBuilder {
208    pub(crate) fn new(wire: Responses) -> Self {
209        Self {
210            wire,
211            connect_timeout: Some(DEFAULT_CONNECT_TIMEOUT),
212            event_timeout: Some(crate::driver::STREAM_IDLE_TIMEOUT),
213            cache_key: None,
214        }
215    }
216
217    /// Sets the timeout for establishing the websocket connection.
218    #[must_use]
219    pub fn connect_timeout(mut self, timeout: Duration) -> Self {
220        self.connect_timeout = Some(timeout);
221        self
222    }
223
224    /// Waits for the websocket connection with no deadline. The event
225    /// timeout is unchanged.
226    #[must_use]
227    pub fn without_connect_timeout(mut self) -> Self {
228        self.connect_timeout = None;
229        self
230    }
231
232    /// Sets how long the turn in flight may send no event before it fails
233    /// as [`ProviderError::Stalled`], counted from when it was sent or its
234    /// last event; pings do not restart it.
235    #[must_use]
236    pub fn event_timeout(mut self, timeout: Duration) -> Self {
237        self.event_timeout = Some(timeout);
238        self
239    }
240
241    /// Waits for each websocket event with no deadline.
242    #[must_use]
243    pub fn without_event_timeout(mut self) -> Self {
244        self.event_timeout = None;
245        self
246    }
247
248    /// Set the prompt-cache routing key, as
249    /// [`GenerationOptions::cache_key`](crate::completion::GenerationOptions::cache_key)
250    /// does on HTTP: a dialect with a session header sends it as the session
251    /// id at the handshake. Without one each connection draws a fresh id.
252    #[must_use]
253    pub fn cache_key(mut self, key: impl Into<String>) -> Self {
254        self.cache_key = Some(key.into());
255        self
256    }
257}
258
259impl ResponsesWebSocketSessionBuilder {
260    /// Open a session over the bundled tungstenite backend with the configured
261    /// timeouts. Return handshake construction, transport, or provider errors.
262    #[cfg(all(feature = "tungstenite", not(target_family = "wasm")))]
263    #[cfg_attr(docsrs, doc(cfg(feature = "tungstenite")))]
264    pub async fn connect(self) -> Result<ResponsesWebSocketSession, ProviderError> {
265        self.connect_with(&rig_tungstenite::TungsteniteClient::new())
266            .await
267    }
268
269    /// Open a session over `backend` with the configured timeouts.
270    /// Return handshake construction, transport, or provider errors.
271    pub async fn connect_with<W>(
272        self,
273        backend: &W,
274    ) -> Result<ResponsesWebSocketSession, ProviderError>
275    where
276        W: WebSocketClientExt,
277    {
278        let request = websocket_request(&self.wire, self.cache_key.as_deref())?;
279        let options = ConnectOptions::new().with_timeout(self.connect_timeout);
280        let socket = backend
281            .connect(request, options)
282            .await
283            .map_err(websocket_provider_error)?;
284        Ok(ResponsesWebSocketSession::from_connection(
285            self.wire,
286            socket,
287            self.event_timeout,
288        ))
289    }
290}
291
292/// Sequential Responses session with automatic response-ID chaining.
293/// Completed and incomplete responses update the chain unless a request supplies
294/// its own `previous_response_id`. Call [`Self::close`] to perform a close handshake.
295pub struct ResponsesWebSocketSession {
296    wire: Responses,
297    previous_response_id: Option<String>,
298    /// The id of the turn whose trailing `response.done` may still arrive,
299    /// `Some(None)` when that turn's response had no id.
300    pending_done: Option<Option<String>>,
301    socket: BoxedWebSocketConnection,
302    in_flight: bool,
303    /// The fold of the turn in flight, opened when it was sent.
304    turn: Option<ReplyFold>,
305    event_timeout: Option<Duration>,
306    /// When the turn in flight was sent or last sent an event.
307    last_event: web_time::Instant,
308    closed: bool,
309    failed: bool,
310}
311
312impl ResponsesWebSocketSession {
313    /// Build a session over an already-open, authenticated connection.
314    /// A turn in flight that sends no event for `event_timeout` fails as
315    /// [`ProviderError::Stalled`]; `None` waits indefinitely.
316    pub fn from_connection(
317        wire: Responses,
318        connection: BoxedWebSocketConnection,
319        event_timeout: Option<Duration>,
320    ) -> Self {
321        Self {
322            wire,
323            previous_response_id: None,
324            pending_done: None,
325            socket: connection,
326            in_flight: false,
327            turn: None,
328            event_timeout,
329            last_event: web_time::Instant::now(),
330            closed: false,
331            failed: false,
332        }
333    }
334
335    /// Return the response ID retained for automatic chaining, if any.
336    #[must_use]
337    pub fn previous_response_id(&self) -> Option<&str> {
338        self.previous_response_id.as_deref()
339    }
340
341    /// Clears the cached `previous_response_id` so the next turn starts a fresh chain.
342    pub fn clear_previous_response_id(&mut self) {
343        self.previous_response_id = None;
344    }
345
346    /// Sends a `response.create` event for a Rig completion request.
347    pub async fn send(
348        &mut self,
349        completion_request: crate::completion::CompletionRequest,
350    ) -> Result<(), ProviderError> {
351        self.send_with_options(
352            completion_request,
353            ResponsesWebSocketCreateOptions::default(),
354        )
355        .await
356    }
357
358    /// Sends a `response.create` event with explicit websocket-mode options.
359    pub async fn send_with_options(
360        &mut self,
361        completion_request: crate::completion::CompletionRequest,
362        options: ResponsesWebSocketCreateOptions,
363    ) -> Result<(), ProviderError> {
364        self.ensure_open()?;
365
366        if self.in_flight {
367            return Err(ProviderError::Provider(
368                "An OpenAI websocket response is already in flight on this session".to_string(),
369            ));
370        }
371
372        // A request that names no `previous_response_id` continues the
373        // session's chain, so the history is shaped as a stored
374        // continuation's.
375        let mut completion_request = completion_request;
376        // Null params are no params, so the session's own fields can be added.
377        completion_request
378            .additional_params
379            .take_if(|params| params.is_null());
380        if let Some(generate) = options.generate {
381            let params = completion_request
382                .additional_params
383                .get_or_insert_with(|| Value::Object(Map::new()));
384            if let Some(params) = params.as_object_mut() {
385                params.insert("generate".to_owned(), Value::Bool(generate));
386            }
387        }
388        if let Some(previous) = &self.previous_response_id {
389            let params = completion_request
390                .additional_params
391                .get_or_insert_with(|| Value::Object(Map::new()));
392            if let Some(params) = params.as_object_mut()
393                && params
394                    .get("previous_response_id")
395                    .is_none_or(Value::is_null)
396            {
397                params.insert(
398                    "previous_response_id".to_owned(),
399                    Value::String(previous.clone()),
400                );
401            }
402        }
403        // The session sends without the driver, so it shapes the history
404        // for the model the way the driver does.
405        let describe = self.wire.describe();
406        let completion_request = Completion::prepare(completion_request, &describe)?;
407        let turn = Completion::fold(
408            &completion_request,
409            &mut Call::new(&describe, Mode::Streaming),
410        );
411        // The HTTP body, without the `stream` and `background` flags an
412        // event-driven session ignores.
413        let payload = ClientEvent::Create(
414            self.wire
415                .responses_request(&completion_request, super::Delivery::WebSocket)?,
416        );
417
418        crate::providers::internal::trace_json(
419            crate::providers::internal::LogTarget::Completions,
420            "OpenAI websocket request",
421            &payload,
422        );
423
424        let payload = serde_json::to_string(&payload)?;
425
426        if let Err(error) = self.socket.send(Frame::Text(payload)).await {
427            return Err(self.fail_session(websocket_provider_error(error)));
428        }
429        self.in_flight = true;
430        self.turn = Some(turn);
431        self.last_event = web_time::Instant::now();
432
433        Ok(())
434    }
435
436    /// Reads the next server event for the current in-flight turn.
437    pub async fn next_event(&mut self) -> Result<ResponsesWebSocketEvent, ProviderError> {
438        self.next_event_with_payload().await.map(|(event, _)| event)
439    }
440
441    /// Reads the next lifecycle event and retains its payload for content decoding
442    /// by [`ResponsesDecoder`]. Returns the same session errors as [`Self::next_event`].
443    async fn next_event_with_payload(
444        &mut self,
445    ) -> Result<(ResponsesWebSocketEvent, String), ProviderError> {
446        self.ensure_open()?;
447
448        if !self.in_flight {
449            return Err(ProviderError::Provider(
450                "No OpenAI websocket response is currently in flight on this session".to_string(),
451            ));
452        }
453
454        loop {
455            let message = match self.read_next_frame().await? {
456                Ok(message) => message,
457                Err(error) => return Err(self.fail_session(websocket_provider_error(error))),
458            };
459
460            let Some(message) = message else {
461                self.mark_closed();
462                return Err(ProviderError::Provider(
463                    "The OpenAI websocket connection closed before the turn finished".to_string(),
464                ));
465            };
466
467            let payload = match websocket_frame_to_text(message) {
468                Ok(Some(payload)) => {
469                    self.last_event = web_time::Instant::now();
470                    payload
471                }
472                Ok(None) => continue,
473                Err(error) => return Err(self.fail_session(error)),
474            };
475            let event = match parse_server_event(&payload) {
476                Ok(Some(event)) => event,
477                Ok(None) => continue,
478                Err(error) => return Err(self.fail_session(error)),
479            };
480            if let ResponsesWebSocketEvent::Done(done) = &event {
481                // OpenAI may emit `response.done` after the turn has already ended at
482                // `response.completed`. Ignore that trailing event on the next turn.
483                if self
484                    .pending_done
485                    .as_ref()
486                    .is_some_and(|pending| pending.as_deref() == done.response_id())
487                {
488                    self.pending_done = None;
489                    continue;
490                }
491            }
492            self.update_state_for_event(&event);
493            return Ok((event, payload));
494        }
495    }
496
497    /// Sends a warmup turn (`generate: false`) and returns the resulting response ID.
498    pub async fn warmup(
499        &mut self,
500        completion_request: crate::completion::CompletionRequest,
501    ) -> Result<String, ProviderError> {
502        self.send_with_options(
503            completion_request,
504            ResponsesWebSocketCreateOptions::warmup(),
505        )
506        .await?;
507        let response = self.wait_for_terminal_response().await?.0;
508        Ok(response
509            .get("id")
510            .and_then(Value::as_str)
511            .unwrap_or_default()
512            .to_owned())
513    }
514
515    /// Sends a completion turn and collects the final OpenAI response,
516    /// normalized; its `raw` is the `Response` the turn's events rebuild.
517    pub async fn completion(
518        &mut self,
519        completion_request: crate::completion::CompletionRequest,
520    ) -> Result<completion::CompletionResponse, ProviderError> {
521        self.send(completion_request).await?;
522        Ok(self.wait_for_terminal_response().await?.1)
523    }
524
525    /// Closes the websocket connection.
526    ///
527    /// Call this when you are finished with the session so the websocket can
528    /// terminate with a clean close handshake.
529    pub async fn close(&mut self) -> Result<(), ProviderError> {
530        if self.closed {
531            return Ok(());
532        }
533
534        let result = self
535            .socket
536            .close(None)
537            .await
538            .map_err(websocket_provider_error);
539        self.mark_closed();
540        result
541    }
542
543    /// Decode the turn's events as they arrive, and return the provider's
544    /// completed or incomplete response with the reply they fold into.
545    /// Transport, protocol, and decoder failures return an error. A terminal
546    /// event without a response body is an error.
547    async fn wait_for_terminal_response(
548        &mut self,
549    ) -> Result<(Value, completion::CompletionResponse), ProviderError> {
550        let provider = self.wire.describe().name.to_owned();
551        let Some(turn) = self.turn.take() else {
552            return Err(ProviderError::Provider(
553                "No OpenAI websocket response is currently in flight on this session".to_string(),
554            ));
555        };
556        // The reply's state and its decoder live for this turn only.
557        let reply = std::sync::Mutex::new(Shared::new(turn));
558        let mut decoder = self.wire.decoder();
559        let mut document = self.wire.reassembler();
560        loop {
561            let (event, payload) = self.next_event_with_payload().await?;
562            match event {
563                ResponsesWebSocketEvent::Response { kind, response } => {
564                    if !is_terminal_kind(&kind) {
565                        feed(&mut decoder, &mut document, &reply, payload)?;
566                        continue;
567                    }
568                    // A failed turn is reported from its own envelope; only a
569                    // completed or incomplete one reaches the decoder, whose
570                    // end closes the turn.
571                    let response = terminal_response_result(response)?;
572                    let ended = feed(&mut decoder, &mut document, &reply, payload)?;
573                    let folded = fold_reply(reply, ended, &provider, document)?;
574                    return Ok((response, folded));
575                }
576                ResponsesWebSocketEvent::Done(done) => {
577                    if done.response.is_object() {
578                        // A failed turn is reported from its own envelope, as
579                        // on the `response.failed` path.
580                        let response = terminal_response_result(done.response)?;
581                        // `response.done` carries the response object itself,
582                        // which is the decoder's whole-body shape: hand it
583                        // over as the frame it is.
584                        let body = serde_json::to_string(&response)?;
585                        let ended = feed(&mut decoder, &mut document, &reply, body)?;
586                        let folded = fold_reply(reply, ended, &provider, document)?;
587                        return Ok((response, folded));
588                    }
589
590                    let message = if let Some(response_id) = done.response_id() {
591                        format!(
592                            "OpenAI websocket turn ended with response.done before a terminal response body was available (response_id={response_id})"
593                        )
594                    } else {
595                        "OpenAI websocket turn ended with response.done before a terminal response body was available"
596                            .to_string()
597                    };
598
599                    return Err(ProviderError::Provider(message));
600                }
601                ResponsesWebSocketEvent::Error(error) => {
602                    // Genuine provider error event: preserve the serialized payload
603                    // (code + message + any extra fields) so provider_response_json()
604                    // parses it, matching the response.failed path. No HTTP status on
605                    // the websocket stream, so status: None.
606                    return Err(provider_error_from_event(&error));
607                }
608                // Unknown frames keep their raw payload.
609                ResponsesWebSocketEvent::Item(_) | ResponsesWebSocketEvent::Unknown(_) => {
610                    feed(&mut decoder, &mut document, &reply, payload)?;
611                }
612            }
613        }
614    }
615
616    fn update_state_for_event(&mut self, event: &ResponsesWebSocketEvent) {
617        match event {
618            ResponsesWebSocketEvent::Response { kind, response } => {
619                let response_id = response
620                    .get("id")
621                    .and_then(Value::as_str)
622                    .map(str::to_owned);
623                match kind.as_str() {
624                    // An incomplete turn still produced a response the next
625                    // turn can chain from, so it keeps
626                    // `previous_response_id` like a completed one.
627                    "response.completed" | "response.incomplete" => {
628                        self.previous_response_id.clone_from(&response_id);
629                        self.pending_done = Some(response_id);
630                        self.in_flight = false;
631                    }
632                    "response.failed" => {
633                        self.pending_done = Some(response_id);
634                        self.previous_response_id = None;
635                        self.in_flight = false;
636                    }
637                    _ => {}
638                }
639            }
640            ResponsesWebSocketEvent::Done(done) => {
641                match done.status() {
642                    Some("completed" | "incomplete") => {
643                        if let Some(response_id) = done.response_id() {
644                            self.previous_response_id = Some(response_id.to_string());
645                        }
646                    }
647                    Some("in_progress" | "queued") | None => {}
648                    Some(_) => {
649                        self.previous_response_id = None;
650                    }
651                }
652                self.pending_done = None;
653                self.in_flight = false;
654            }
655            ResponsesWebSocketEvent::Error(_) => {
656                self.previous_response_id = None;
657                self.pending_done = None;
658                self.in_flight = false;
659            }
660            // An unknown frame carries no turn-lifecycle signal.
661            ResponsesWebSocketEvent::Item(_) | ResponsesWebSocketEvent::Unknown(_) => {}
662        }
663    }
664
665    fn abort_turn(&mut self) {
666        self.turn = None;
667        self.previous_response_id = None;
668        self.pending_done = None;
669        self.in_flight = false;
670    }
671
672    fn mark_closed(&mut self) {
673        self.abort_turn();
674        self.closed = true;
675        self.failed = false;
676    }
677
678    fn mark_failed(&mut self) {
679        self.abort_turn();
680        self.failed = true;
681    }
682
683    fn ensure_open(&self) -> Result<(), ProviderError> {
684        if self.closed || self.failed {
685            return Err(ProviderError::Provider(
686                "The OpenAI websocket session is closed".to_string(),
687            ));
688        }
689
690        Ok(())
691    }
692
693    fn fail_session(&mut self, error: ProviderError) -> ProviderError {
694        self.mark_failed();
695        error
696    }
697
698    /// Read a frame within the event timeout, timed as the driver times a
699    /// streamed reply. A stall marks the session failed; transport results
700    /// remain nested.
701    async fn read_next_frame(
702        &mut self,
703    ) -> Result<http_client::Result<Option<Frame>>, ProviderError> {
704        let next =
705            crate::driver::idle_within(self.event_timeout, self.last_event, self.socket.recv());
706        match next.await {
707            Ok(message) => Ok(message),
708            Err(stalled) => Err(self.fail_session(stalled)),
709        }
710    }
711}
712
713impl Drop for ResponsesWebSocketSession {
714    fn drop(&mut self) {
715        if !self.closed {
716            tracing::warn!(
717                target: "rig::completions",
718                in_flight = self.in_flight,
719                "Dropping an OpenAI websocket session without calling close(); the connection will end without a close handshake"
720            );
721        }
722    }
723}
724
725/// Feed one message to the turn's reassembler and decoder. Returns whether
726/// it ended the turn.
727fn feed(
728    decoder: &mut ResponsesDecoder,
729    document: &mut document::Response,
730    reply: &std::sync::Mutex<Shared<Completion>>,
731    payload: String,
732) -> Result<bool, ProviderError> {
733    crate::driver::step(decoder, Some(document), reply, WireFrame::Text(payload))
734        .map(|step| matches!(step, Flow::Ended(_)))
735}
736
737/// Fold the turn's events and end into the normalized response, whose raw
738/// is the `Response` the turn's events rebuild, as a stream's is.
739fn fold_reply(
740    reply: std::sync::Mutex<Shared<Completion>>,
741    ended: bool,
742    provider: &str,
743    document: document::Response,
744) -> Result<completion::CompletionResponse, ProviderError> {
745    let fed = if ended {
746        Ok(())
747    } else {
748        Err(ProviderError::Truncated)
749    };
750    let reply_of = Reply {
751        provider: provider.to_owned(),
752        raw: crate::wire::document::Reassemble::finish(document),
753        // The websocket carries no reply headers past the handshake.
754        provider_request_id: None,
755    };
756    crate::driver::settle(reply, fed, reply_of).outcome
757}
758
759fn terminal_response_result(response: Value) -> Result<Value, ProviderError> {
760    match response.get("status").and_then(Value::as_str) {
761        // An incomplete response (e.g. hitting `max_output_tokens`) is a
762        // genuine terminal: the partial output and usage are kept, and the
763        // decoder maps its status and reason to the finish.
764        Some("completed" | "incomplete") | None => Ok(response),
765        // Preserve provider error envelopes as reserialized JSON without an HTTP status.
766        // Without an error object, return a local diagnostic instead.
767        Some("failed") => match response.get("error").filter(|error| !error.is_null()) {
768            Some(_) => Err(ProviderError::from_provider_body(response.to_string())),
769            None => Err(ProviderError::Provider(
770                "OpenAI websocket returned a failed response".to_owned(),
771            )),
772        },
773        Some(other) => Err(ProviderError::Provider(format!(
774            "OpenAI websocket response ended in state `{other}`"
775        ))),
776    }
777}
778
779/// Preserve an error event as reserialized provider JSON without an HTTP status.
780/// Fall back to its display text if serialization fails.
781fn provider_error_from_event(error: &ResponsesWebSocketErrorEvent) -> ProviderError {
782    ProviderError::from_provider_body(
783        serde_json::to_string(&error).unwrap_or_else(|_| error.to_string()),
784    )
785}
786
787/// Decode WebSocket error and done events or delegate to Responses classification.
788/// Return parsing and triage errors; preserve unknown payloads.
789fn parse_server_event(payload: &str) -> Result<Option<ResponsesWebSocketEvent>, ProviderError> {
790    #[derive(Deserialize)]
791    struct EventType {
792        #[serde(rename = "type")]
793        kind: String,
794    }
795
796    let event_type = serde_json::from_str::<EventType>(payload)?;
797    match event_type.kind.as_str() {
798        "error" => serde_json::from_str(payload)
799            .map(|e| Some(ResponsesWebSocketEvent::Error(e)))
800            .map_err(ProviderError::from),
801        "response.done" => serde_json::from_str(payload)
802            .map(|d| Some(ResponsesWebSocketEvent::Done(d)))
803            .map_err(ProviderError::from),
804        _ => Ok(
805            match crate::driver::triage(classify_responses_payload(payload))? {
806                Item::Event(ResponsesEvent::Frame {
807                    kind, mut frame, ..
808                }) => {
809                    if is_lifecycle_event(&kind) {
810                        let response = frame
811                            .as_object_mut()
812                            .and_then(|frame| remove_preserving_order(frame, "response"))
813                            .unwrap_or_else(|| Value::Object(Map::new()));
814                        Some(ResponsesWebSocketEvent::Response { kind, response })
815                    } else {
816                        Some(ResponsesWebSocketEvent::Item(frame))
817                    }
818                }
819                // Only the event types above reach here: a frame without a
820                // `type` is not a websocket event.
821                Item::Event(ResponsesEvent::Whole(value)) => {
822                    Some(ResponsesWebSocketEvent::Unknown(value.into()))
823                }
824                Item::Event(ResponsesEvent::Failure(body)) => {
825                    return Err(ProviderError::from_provider_body(body));
826                }
827                Item::Event(ResponsesEvent::Sentinel) => None,
828                Item::Unknown(value) => Some(ResponsesWebSocketEvent::Unknown(value)),
829            },
830        ),
831    }
832}
833
834/// Lower one websocket frame onto the JSON payload the protocol carries.
835///
836/// `Ok(None)` is a frame with no protocol payload (a keepalive), which the
837/// session skips; a close frame mid-turn is an error naming the peer's reason.
838fn websocket_frame_to_text(frame: Frame) -> Result<Option<String>, ProviderError> {
839    match frame {
840        Frame::Text(text) => Ok(Some(text)),
841        Frame::Binary(bytes) => String::from_utf8(bytes.to_vec())
842            .map(Some)
843            .map_err(|error| ProviderError::Response(error.to_string())),
844        Frame::Ping(_) | Frame::Pong(_) => Ok(None),
845        Frame::Close(frame) => {
846            let reason = frame
847                .map(|frame| frame.reason)
848                .filter(|reason| !reason.is_empty())
849                .unwrap_or_else(|| "without a close reason".to_string());
850            Err(ProviderError::Provider(format!(
851                "The OpenAI websocket connection closed {reason}"
852            )))
853        }
854    }
855}
856
857/// Build the handshake request: the websocket URL derived from the client's
858/// base URL, carrying the client's own auth headers and the session id
859/// `cache_key` gives, or a fresh one.
860///
861/// The backend supplies the websocket-specific handshake headers; this only
862/// states where to connect and who is connecting.
863fn websocket_request(
864    wire: &Responses,
865    cache_key: Option<&str>,
866) -> Result<http_client::Request<NoBody>, EncodeError> {
867    let url = crate::ws_client::websocket_url(&wire.provider.base_url, WEBSOCKET_PATH)
868        .map_err(EncodeError::request)?;
869
870    let request = wire.provider.headers_in_session(
871        http_client::Request::builder()
872            .method(http::Method::GET)
873            .uri(url),
874        cache_key,
875    );
876
877    request.body(NoBody).map_err(|error| {
878        EncodeError::request(format!("Failed to build OpenAI websocket request: {error}"))
879    })
880}
881
882/// Convert transport errors, retaining rejected-upgrade status, body, and request ID.
883/// Failures without a provider response retain transport error classification.
884fn websocket_provider_error(error: http_client::Error) -> ProviderError {
885    let provider_request_id = error.non_success_headers().and_then(|headers| {
886        crate::driver::http_transport::request_id_from(headers, REQUEST_ID_HEADER)
887    });
888    ProviderError::from_transport_error(error).with_provider_request_id(provider_request_id)
889}
890
891impl<T> Model<Responses, T> {
892    /// Start configuring a Responses WebSocket session for this model. Open
893    /// it with [`connect_with`](ResponsesWebSocketSessionBuilder::connect_with)
894    /// and a backend, or, under the `tungstenite` feature, with
895    /// [`connect`](ResponsesWebSocketSessionBuilder::connect).
896    pub fn responses_websocket(&self) -> ResponsesWebSocketSessionBuilder {
897        ResponsesWebSocketSessionBuilder::new(self.wire.clone())
898    }
899}
900
901/// Native sessions and builders satisfy Send and Sync.
902#[cfg(not(target_family = "wasm"))]
903const _: fn() = || {
904    fn assert_send_sync<T: Send + Sync>() {}
905    assert_send_sync::<ResponsesWebSocketSession>();
906    assert_send_sync::<ResponsesWebSocketSessionBuilder>();
907};
908
909#[cfg(test)]
910#[allow(clippy::expect_used, clippy::panic)]
911mod tests;