Skip to main content

cpa_exec/
codex_ws.rs

1//! Codex upstream Responses WebSocket (codex_websockets_executor.go, _connection.go,
2//! _session.go, _stream.go, _errors.go).
3//!
4//! One upstream socket per downstream session, keyed by credential, URL and proxy. A
5//! single reader task per socket enforces the 5-minute idle deadline (pongs are answered
6//! while reading) and hands frames to the turn in progress through a bounded channel;
7//! frames that arrive between turns are dropped, as in Go. Turns on one session are
8//! serialised. The socket stays pooled after a completed response so the next turn can
9//! continue with `previous_response_id` and incremental input.
10//!
11//! Lifecycle: the reader task ends with the socket; [`Pool::close`] (downstream gone)
12//! aborts it and sends a close frame. No task outlives its session.
13
14use std::collections::HashMap;
15use std::sync::{Arc, Mutex, Weak};
16use std::time::{Duration, Instant};
17
18use bytes::Bytes;
19use cpa_core::config::Config;
20use cpa_core::credential::Credential;
21use cpa_core::exec::{
22    ExecError, ExecRequest, ExecResponse, ExecSession, ExecStream, FailureScope, ResponseBody, SessionLease,
23};
24use futures_util::stream::{SplitSink, SplitStream};
25use futures_util::{SinkExt, StreamExt};
26use gjson::Kind;
27use http::HeaderMap;
28use tokio::sync::{OwnedMutexGuard, mpsc, watch};
29use tokio_tungstenite::WebSocketStream;
30use tokio_tungstenite::tungstenite::Message;
31use tokio_tungstenite::tungstenite::protocol::{Role, WebSocketConfig};
32
33use deflate::Inflate;
34
35/// The upstream socket: tungstenite over the upgraded connection, with permessage-deflate
36/// reads when negotiated.
37pub(crate) type WebSocket = WebSocketStream<Inflate<wreq::Upgraded>>;
38
39use crate::codex::CodexExecutor;
40use crate::codex_json::{set_raw, set_str};
41use crate::codex_quota::{self, QuotaSignals};
42use crate::codex_request::{self as request, Call, Settings, View};
43use crate::codex_response::{self as response, OutputItems};
44use crate::proxy::Proxy;
45
46/// `codexResponsesWebsocketIdleTimeout`: read deadline renewed before every read.
47pub(crate) const IDLE_TIMEOUT: Duration = Duration::from_secs(300);
48/// `codexResponsesWebsocketHandshakeTO`.
49const HANDSHAKE_TIMEOUT: Duration = Duration::from_secs(30);
50/// Bound on one upstream frame write (docs/DIFFERENCES-FROM-GO.md). Go sets no write
51/// deadline, so a write into a half-open socket held the turn until the 300 s read
52/// deadline. A large frame gets as long as it takes at `rate` bytes per second.
53#[derive(Debug, Clone, Copy)]
54pub(crate) struct WriteLimit {
55    pub(crate) floor: Duration,
56    pub(crate) rate: usize,
57}
58
59// ponytail: a fixed 128 KiB/s floor rate (about 1 Mbit/s); a slower uplink sending a
60// multi-megabyte frame times out. Make it configurable if such a link shows up.
61pub(crate) const WRITE_LIMIT: WriteLimit = WriteLimit {
62    floor: Duration::from_secs(10),
63    rate: 128 << 10,
64};
65
66impl WriteLimit {
67    fn deadline(self, len: usize) -> Duration {
68        self.floor
69            .max(Duration::from_secs(len.div_ceil(self.rate.max(1)) as u64))
70    }
71}
72/// Go's per-turn read channel capacity.
73const TURN_BUFFER: usize = 4096;
74/// Bound on a handshake rejection body.
75const MAX_HANDSHAKE_BODY: usize = 64 * 1024;
76/// Largest upstream frame or message read.
77// ponytail: Go sets no read limit; 64 MiB (the HTTP body cap) keeps one socket's memory
78// bounded while fitting image-bearing output items.
79const MAX_UPSTREAM_MESSAGE: usize = 64 * 1024 * 1024;
80
81#[derive(Debug, Clone)]
82pub(crate) struct Target {
83    pub(crate) credential: String,
84    pub(crate) url: String,
85    /// The proxy to dial with, parsed from `setting`.
86    pub(crate) proxy: Proxy,
87    /// The trimmed effective setting: the credential's own, else `requests.proxy-url`.
88    /// Go compares these strings (`websocketSessionTargetMatches`), not parsed proxies:
89    /// `direct` and `none` are different targets.
90    setting: String,
91    /// The trimmed `requests.proxy-url` when the target was resolved.
92    global: String,
93    /// Whether `setting` came from `requests.proxy-url` (the credential sets none).
94    inherited: bool,
95}
96
97impl Target {
98    pub(crate) fn new(credential: &Credential, url: String, cfg: &Config) -> Self {
99        let own = Proxy::own_url(credential);
100        let global = Proxy::global_url(cfg);
101        let setting = own.map_or_else(|| global.clone(), str::to_owned);
102        Self {
103            credential: credential.id.clone(),
104            url,
105            proxy: Proxy::parse(&setting),
106            setting,
107            global,
108            inherited: own.is_none(),
109        }
110    }
111
112    /// `websocketSessionTargetMatches` under the current config.
113    pub(crate) fn same(&self, want: &Target) -> bool {
114        self.credential == want.credential && self.url == want.url && self.setting == want.setting
115    }
116
117    /// Whether the live socket dialed for `self` still serves `want`. Go 1e37b52b
118    /// (`effectiveConfig`): for the same credential, the global proxy is the one the
119    /// socket dialed with, so a reload that changes only `requests.proxy-url` keeps the
120    /// socket. New sockets dial with the new setting.
121    pub(crate) fn serves(&self, want: &Target) -> bool {
122        let setting = if want.inherited { &self.global } else { &want.setting };
123        self.credential == want.credential && self.url == want.url && self.setting == *setting
124    }
125}
126
127pub(crate) enum Read {
128    Text(String),
129    /// The socket failed; the reader has already invalidated it.
130    Failed(ExecError),
131}
132
133/// The reader's hand-off to the turn in progress. One lock covers both fields, so a turn
134/// that activates after the reader exited sees why instead of waiting forever.
135#[derive(Default)]
136pub(crate) struct Link {
137    /// The turn currently reading, if any.
138    active: Option<mpsc::Sender<Read>>,
139    /// Why the reader stopped (`upstreamDisconnectError`); set once when it exits.
140    pub(crate) lost: Option<ExecError>,
141    /// Response IDs this socket already finished (`terminalResponseIDs`): a late
142    /// `response.interrupt` for one is done, not an error and not forwarded.
143    // ponytail: grows by one ID per finished response for the socket's life, as Go's
144    // does; bound it if sockets ever outlive thousands of turns.
145    terminal: std::collections::HashSet<String>,
146}
147
148/// `response.completed`, `.done`, `.incomplete` and `.failed` (Go `isTerminalEvent`
149/// without `error`) with a non-empty string `response.id`.
150fn terminal_response_id(payload: &str) -> Option<String> {
151    let kind = gjson::get(payload, "type");
152    if !matches!(
153        kind.str(),
154        "response.completed" | "response.done" | "response.incomplete" | "response.failed"
155    ) {
156        return None;
157    }
158    let id = gjson::get(payload, "response.id");
159    (id.kind() == Kind::String && !id.str().is_empty()).then(|| id.str().to_owned())
160}
161
162/// Go `ErrNoActiveUpstreamWebsocket`.
163pub const NO_ACTIVE_UPSTREAM: &str = "no active upstream websocket for response.interrupt";
164
165/// Why [`CodexExecutor::interrupt`] did not deliver a `response.interrupt`.
166#[derive(Debug, PartialEq, Eq)]
167pub enum InterruptError {
168    /// No turn is reading on the session's current socket ([`NO_ACTIVE_UPSTREAM`]): an
169    /// HTTP turn may still cancel locally.
170    NoActive,
171    /// The socket was lost, the credential is disabled, or the write failed.
172    Rejected(String),
173}
174
175impl std::fmt::Display for InterruptError {
176    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
177        match self {
178            Self::NoActive => f.write_str(NO_ACTIVE_UPSTREAM),
179            Self::Rejected(text) => f.write_str(text),
180        }
181    }
182}
183
184pub(crate) struct Upstream {
185    pub(crate) target: Target,
186    pub(crate) sink: tokio::sync::Mutex<SplitSink<WebSocket, Message>>,
187    pub(crate) link: Mutex<Link>,
188    pub(crate) reader: Mutex<Option<tokio::task::AbortHandle>>,
189    /// The last request that touched the `collaboration` namespace on this socket renamed
190    /// it (`multiAgentV2OptimizedConn`): later continuations restore upstream names too.
191    multi_agent: std::sync::atomic::AtomicBool,
192    /// The Home pick this socket keeps (Go `session.lifecycle`); `true` once the socket
193    /// shut down, after which no pick binds.
194    lease: Mutex<(bool, Option<SessionLease>)>,
195    write: WriteLimit,
196}
197
198impl Upstream {
199    /// A socket for `target`, not yet published to a session and without a reader.
200    pub(crate) fn new(target: Target, sink: SplitSink<WebSocket, Message>, write: WriteLimit) -> Arc<Self> {
201        Arc::new(Self {
202            target,
203            write,
204            sink: tokio::sync::Mutex::new(sink),
205            link: Mutex::default(),
206            reader: Mutex::default(),
207            multi_agent: Default::default(),
208            lease: Mutex::default(),
209        })
210    }
211
212    /// `!conflict && (optimized || isMultiAgentV2Optimized(conn))`.
213    fn restores(&self, optimized: bool, conflict: bool) -> bool {
214        !conflict && (optimized || self.multi_agent.load(std::sync::atomic::Ordering::Acquire))
215    }
216
217    /// `setMultiAgentV2Optimized` after a request that optimized or conflicted.
218    fn note_multi_agent(&self, optimized: bool, conflict: bool) {
219        if optimized || conflict {
220            self.multi_agent
221                .store(optimized && !conflict, std::sync::atomic::Ordering::Release);
222        }
223    }
224
225    pub(crate) fn activate(&self) -> mpsc::Receiver<Read> {
226        let (tx, rx) = mpsc::channel(TURN_BUFFER);
227        let mut link = self.link.lock().expect("link");
228        match &link.lost {
229            Some(error) => {
230                let _ = tx.try_send(Read::Failed(turn_error(error)));
231            }
232            None => link.active = Some(tx),
233        }
234        rx
235    }
236
237    pub(crate) fn deactivate(&self) {
238        self.link.lock().expect("link").active.take();
239    }
240
241    /// `writeCodexWebsocketMessage` + `mapCodexWebsocketWriteError`: a write after the
242    /// upstream closed with 1009 reports the request-scoped 413 instead. A write that
243    /// outlasts [`WriteLimit`] fails like any other write: the caller invalidates the
244    /// socket, so a partly written frame is never followed by another. Cost: one timer
245    /// entry while a write is in flight.
246    pub(crate) async fn send(&self, frame: String) -> Result<(), ExecError> {
247        let len = frame.len();
248        self.write_message(Message::text(frame), len).await
249    }
250
251    /// [`Self::send`] for a client's own bytes: one text frame holding them unchanged,
252    /// UTF-8 or not, as gorilla writes a `TextMessage`.
253    pub(crate) async fn send_raw(&self, payload: Bytes) -> Result<(), ExecError> {
254        use tokio_tungstenite::tungstenite::protocol::frame::{
255            Frame,
256            coding::{Data, OpCode},
257        };
258        let len = payload.len();
259        self.write_message(
260            Message::Frame(Frame::message(payload, OpCode::Data(Data::Text), true)),
261            len,
262        )
263        .await
264    }
265
266    async fn write_message(&self, message: Message, len: usize) -> Result<(), ExecError> {
267        let deadline = self.write.deadline(len);
268        let sent = tokio::time::timeout(deadline, async { self.sink.lock().await.send(message).await }).await;
269        match sent {
270            Ok(Ok(())) => Ok(()),
271            Ok(Err(_)) => Err(write_error(
272                self.link.lock().expect("link").lost.as_ref(),
273                "codex websockets executor: write failed",
274            )),
275            Err(_) => Err(write_error(
276                self.link.lock().expect("link").lost.as_ref(),
277                "codex websockets executor: write timed out",
278            )),
279        }
280    }
281
282    /// Go `bindExecutionLifecycle`: the socket keeps the attempt's Home pick until it is
283    /// invalidated, replaced or closed, and Home draining the pick invalidates the
284    /// socket. A pick bound earlier ends (`target_replaced`).
285    pub(crate) fn bind(
286        self: &Arc<Self>,
287        session: &Arc<Session>,
288        lease: Option<&SessionLease>,
289    ) -> Result<(), ExecError> {
290        let Some(lease) = lease else { return Ok(()) };
291        if self
292            .lease
293            .lock()
294            .expect("lease")
295            .1
296            .as_ref()
297            .is_some_and(|l| l.same(lease))
298        {
299            return Ok(());
300        }
301        let (weak_session, weak_conn) = (Arc::downgrade(session), Arc::downgrade(self));
302        let close = Box::new(move || {
303            if let (Some(session), Some(conn)) = (weak_session.upgrade(), weak_conn.upgrade()) {
304                session.invalidate(
305                    &conn,
306                    &transport("codex websockets executor: execution lifecycle ended"),
307                    false,
308                );
309            }
310        });
311        let unbound = || transport("codex websockets executor: websocket connection closed during lifecycle bind");
312        if !lease.0.retain(close) {
313            session.invalidate(self, &unbound(), false);
314            return Err(unbound());
315        }
316        let previous = {
317            let mut slot = self.lease.lock().expect("lease");
318            if slot.0 {
319                drop(slot);
320                lease.0.end();
321                return Err(unbound());
322            }
323            slot.1.replace(lease.clone())
324        };
325        if let Some(previous) = previous {
326            previous.0.end();
327        }
328        Ok(())
329    }
330
331    /// Stops the reader and closes the socket, ending the Home pick it kept. Idempotent.
332    pub(crate) fn shutdown(self: &Arc<Self>) {
333        if let Some(reader) = self.reader.lock().expect("reader handle").take() {
334            reader.abort();
335        }
336        self.deactivate();
337        let lease = {
338            let mut slot = self.lease.lock().expect("lease");
339            slot.0 = true;
340            slot.1.take()
341        };
342        if let Some(lease) = lease {
343            lease.0.end();
344        }
345        let this = self.clone();
346        tokio::spawn(async move {
347            let _ = tokio::time::timeout(Duration::from_secs(1), async {
348                let mut sink = this.sink.lock().await;
349                let _ = sink.send(Message::Close(None)).await;
350                let _ = sink.close().await;
351            })
352            .await;
353        });
354    }
355}
356
357pub(crate) struct Session {
358    /// Serialises turns (`reqMu`).
359    pub(crate) turn: Arc<tokio::sync::Mutex<()>>,
360    pub(crate) conn: Mutex<Option<Arc<Upstream>>>,
361    /// Set once when the session's socket is lost (`notifyUpstreamDisconnect`).
362    closed: watch::Sender<Option<ExecError>>,
363    /// The downstream connection's client frames when response steering is configured.
364    steering: Mutex<Option<Arc<SteeringInput>>>,
365    /// The credential of the last socket dialed (Go keeps `sess.authID` after the socket
366    /// is gone, and removing that credential still ends the session).
367    credential: Mutex<String>,
368}
369
370impl Session {
371    /// Makes `conn` the session's socket.
372    pub(crate) fn publish(&self, conn: Arc<Upstream>) {
373        let mut slot = self.conn.lock().expect("session conn");
374        conn.target
375            .credential
376            .clone_into(&mut self.credential.lock().expect("session credential"));
377        *slot = Some(conn);
378    }
379
380    pub(crate) fn current(&self) -> Option<Arc<Upstream>> {
381        self.conn.lock().expect("session conn").clone()
382    }
383
384    fn steering(&self) -> Option<Arc<SteeringInput>> {
385        self.steering.lock().expect("session steering").clone()
386    }
387
388    /// `invalidateUpstreamConn`: only the session's current socket is dropped, so a stale
389    /// reader cannot tear down its replacement. `notify` tells the downstream handler.
390    pub(crate) fn invalidate(&self, conn: &Arc<Upstream>, error: &ExecError, notify: bool) {
391        {
392            let mut current = self.conn.lock().expect("session conn");
393            if !current.as_ref().is_some_and(|c| Arc::ptr_eq(c, conn)) {
394                return;
395            }
396            *current = None;
397        }
398        if notify {
399            self.closed.send_if_modified(|slot| {
400                let first = slot.is_none();
401                if first {
402                    *slot = Some(error.clone());
403                }
404                first
405            });
406        }
407        conn.shutdown();
408    }
409}
410
411/// Upstream sockets by downstream session id.
412pub(crate) struct Pool {
413    sessions: Mutex<HashMap<String, Arc<Session>>>,
414    /// Read deadline for each upstream application message.
415    pub(crate) idle: Duration,
416    pub(crate) write: WriteLimit,
417}
418
419impl Default for Pool {
420    fn default() -> Self {
421        Self {
422            sessions: Mutex::default(),
423            idle: IDLE_TIMEOUT,
424            write: WRITE_LIMIT,
425        }
426    }
427}
428
429impl Pool {
430    #[cfg(test)]
431    pub fn with_idle(idle: Duration) -> Self {
432        Self {
433            idle,
434            ..Self::default()
435        }
436    }
437
438    #[cfg(test)]
439    pub(crate) fn with_write(write: WriteLimit) -> Self {
440        Self {
441            write,
442            ..Self::default()
443        }
444    }
445
446    pub(crate) fn session(&self, id: &str) -> Arc<Session> {
447        self.sessions
448            .lock()
449            .expect("sessions")
450            .entry(id.to_owned())
451            .or_insert_with(|| {
452                Arc::new(Session {
453                    turn: Arc::default(),
454                    conn: Mutex::default(),
455                    closed: watch::channel(None).0,
456                    steering: Mutex::default(),
457                    credential: Mutex::default(),
458                })
459            })
460            .clone()
461    }
462
463    /// The session, without creating one.
464    fn get(&self, id: &str) -> Option<Arc<Session>> {
465        self.sessions.lock().expect("sessions").get(id).cloned()
466    }
467
468    /// `WithWebsocketInput`: binds the downstream connection's frames to its session.
469    pub fn attach_steering(&self, id: &str, input: SteeringInput) {
470        *self.session(id).steering.lock().expect("session steering") = Some(Arc::new(input));
471    }
472
473    /// `CloseExecutionSession`: the downstream connection ended.
474    pub fn close(&self, id: &str) {
475        let session = self.sessions.lock().expect("sessions").remove(id);
476        if let Some(conn) = session.and_then(|s| s.conn.lock().expect("session conn").take()) {
477            conn.shutdown();
478        }
479    }
480
481    /// `closeCodexWebsocketSessionsInStoreForAuthID`: ends the sessions whose last socket
482    /// was dialed for `credential` (a removed credential), like [`Self::close`] for each,
483    /// and leaves every other session open.
484    pub(crate) fn close_credential(&self, credential: &str) {
485        self.close_credential_with(credential, |_| {});
486    }
487
488    /// [`Self::close_credential`]; `detached(id)` runs under the pool lock as each session
489    /// leaves it, so state keyed by the session id goes with it before the id can be
490    /// reused (Go deletes xAI's ID state under the session-store mutex). Sockets shut down
491    /// after the lock is released.
492    pub(crate) fn close_credential_with(&self, credential: &str, mut detached: impl FnMut(&str)) {
493        let sessions: Vec<_> = {
494            let sessions = self.sessions.lock().expect("sessions");
495            sessions.iter().map(|(id, s)| (id.clone(), s.clone())).collect()
496        };
497        let matching: Vec<_> = sessions
498            .into_iter()
499            .filter(|(_, s)| *s.credential.lock().expect("session credential") == credential)
500            .collect();
501        let mut closing = Vec::new();
502        {
503            let mut sessions = self.sessions.lock().expect("sessions");
504            for (id, session) in matching {
505                // A session closed or replaced since the snapshot is not this one.
506                if !sessions.get(&id).is_some_and(|s| Arc::ptr_eq(s, &session)) {
507                    continue;
508                }
509                sessions.remove(&id);
510                detached(&id);
511                closing.push(session);
512            }
513        }
514        for session in closing {
515            if let Some(conn) = session.conn.lock().expect("session conn").take() {
516                conn.shutdown();
517            }
518        }
519    }
520
521    /// The error that lost the session's upstream socket, if it was lost.
522    pub fn loss(&self, id: &str) -> Option<ExecError> {
523        let session = self.get(id)?;
524        session.closed.borrow().clone()
525    }
526
527    /// `InterruptExecutionSession`: writes the client's `response.interrupt` unchanged
528    /// to the socket of the session's turn in progress. It never dials, replays or
529    /// selects another credential. `enabled(credential_id)` is the live account check,
530    /// called without holding a session lock.
531    pub async fn interrupt(
532        &self,
533        id: &str,
534        payload: &[u8],
535        enabled: impl FnOnce(&str) -> bool,
536    ) -> Result<(), InterruptError> {
537        let session = Some(id.trim())
538            .filter(|id| !id.is_empty())
539            .and_then(|id| self.get(id))
540            .ok_or(InterruptError::NoActive)?;
541        let conn = session.current().ok_or(InterruptError::NoActive)?;
542        let auth_enabled = enabled(&conn.target.credential);
543        let response_id = cpa_common::json::get(payload, "response_id").bytes();
544        {
545            // One snapshot of the socket's state: a completion landing between the
546            // checks would otherwise turn a late interrupt into a stale error.
547            let current = session.conn.lock().expect("session conn");
548            if !current.as_ref().is_some_and(|c| Arc::ptr_eq(c, &conn)) {
549                return Err(InterruptError::NoActive);
550            }
551            let link = conn.link.lock().expect("link");
552            if let Some(lost) = &link.lost {
553                return Err(InterruptError::Rejected(
554                    String::from_utf8_lossy(&lost.body).into_owned(),
555                ));
556            }
557            if std::str::from_utf8(&response_id).is_ok_and(|id| link.terminal.contains(id)) {
558                return Ok(());
559            }
560            // A socket kept from an earlier turn is not the current upstream.
561            if link.active.is_none() {
562                return Err(InterruptError::NoActive);
563            }
564        }
565        if !auth_enabled {
566            return Err(InterruptError::Rejected(
567                "websocket credential is no longer enabled".into(),
568            ));
569        }
570        // A failed or timed-out write may leave a partial frame: the socket is dropped
571        // like after any failed turn write (Go leaves that to its reader).
572        if let Err(error) = conn.send_raw(Bytes::copy_from_slice(payload)).await {
573            session.invalidate(&conn, &error, true);
574            return Err(InterruptError::Rejected(
575                String::from_utf8_lossy(&error.body).into_owned(),
576            ));
577        }
578        Ok(())
579    }
580
581    /// Resolves with the error that lost the session's upstream socket.
582    pub fn closed(&self, id: &str) -> impl std::future::Future<Output = ExecError> + Send + 'static {
583        let mut rx = self.session(id).closed.subscribe();
584        async move {
585            loop {
586                if let Some(error) = rx.borrow_and_update().clone() {
587                    return error;
588                }
589                if rx.changed().await.is_err() {
590                    return std::future::pending().await;
591                }
592            }
593        }
594    }
595
596    #[cfg(test)]
597    pub fn len(&self) -> usize {
598        self.sessions.lock().expect("sessions").len()
599    }
600}
601
602fn transport(message: &str) -> ExecError {
603    ExecError::local(502, FailureScope::Transport, message)
604}
605
606/// gorilla/websocket `CloseError.Error()`: what Go returns for an upstream close.
607fn close_error_text(code: u16, text: &str) -> String {
608    let name = match code {
609        1000 => " (normal)",
610        1001 => " (going away)",
611        1002 => " (protocol error)",
612        1003 => " (unsupported data)",
613        1005 => " (no status)",
614        1006 => " (abnormal closure)",
615        1007 => " (invalid payload data)",
616        1008 => " (policy violation)",
617        1009 => " (message too big)",
618        1010 => " (mandatory extension missing)",
619        1011 => " (internal server error)",
620        1015 => " (TLS handshake error)",
621        _ => "",
622    };
623    let mut out = format!("websocket: close {code}{name}");
624    if !text.is_empty() {
625        out.push_str(": ");
626        out.push_str(text);
627    }
628    out
629}
630
631/// The session's loss on an upstream close 1009: Go's reader notifies the downstream
632/// handler with gorilla's raw close error, so the client sees close 1009 with the
633/// upstream's reason ("message too big" when empty).
634/// `close_reason` keeps gorilla's `CloseError.Text` verbatim for the handler, which only
635/// trims the message of a mapped 413.
636fn closed_too_big(reason: &str) -> ExecError {
637    let message = if reason.is_empty() { "message too big" } else { reason };
638    ExecError::local(
639        413,
640        FailureScope::Request,
641        serde_json::json!({
642            "error": {"message": message, "type": "invalid_request_error", "code": "message_too_big"},
643            "close_reason": reason,
644        })
645        .to_string(),
646    )
647}
648
649/// `mapCodexWebsocketReadError` / `mapCodexWebsocketWriteError`: what a turn reports
650/// after the upstream closed with 1009, a fixed request-scoped 413.
651fn message_too_big() -> ExecError {
652    ExecError::local(
653        413,
654        FailureScope::Request,
655        r#"{"error":{"message":"upstream websocket message too big","type":"invalid_request_error","code":"message_too_big"}}"#,
656    )
657}
658
659/// The error a turn reads from the session's loss: the mapped 413 for a 1009 close (only
660/// [`closed_too_big`] makes a 413 loss), the loss itself otherwise.
661/// The reader's error for a binary message (Go's `unexpected_binary` stage).
662const UNEXPECTED_BINARY: &str = "codex websockets executor: unexpected binary message";
663
664/// A failed or timed-out write: the request-scoped 413 when the reader already saw the
665/// upstream close with 1009 (the frame was too big), else a transport error.
666pub(crate) fn write_error(lost: Option<&ExecError>, message: &str) -> ExecError {
667    lost.filter(|e| e.status == 413)
668        .map_or_else(|| transport(message), turn_error)
669}
670
671fn turn_error(lost: &ExecError) -> ExecError {
672    if lost.status == 413 {
673        message_too_big()
674    } else {
675        lost.clone()
676    }
677}
678
679/// `buildCodexResponsesWebsocketURL`. Go returns its parse, scheme and empty-host errors
680/// as plain errors before dialing.
681fn ws_url(http_url: &str) -> Result<String, ExecError> {
682    let raw = http_url.trim();
683    let mut parsed = crate::xai_url::parse(raw).map_err(|e| crate::xai_url::url_error(raw, &e))?;
684    parsed.scheme = match parsed.scheme.as_str() {
685        "http" => "ws".to_owned(),
686        "https" => "wss".to_owned(),
687        other => {
688            return Err(crate::xai_url::statusless(format!(
689                "codex websockets executor: unsupported responses websocket URL scheme {}",
690                cpa_common::gostr::quote(other)
691            )));
692        }
693    };
694    if parsed.host.trim().is_empty() {
695        return Err(crate::xai_url::statusless(
696            "codex websockets executor: responses websocket URL host is empty",
697        ));
698    }
699    Ok(crate::xai_url::string(&parsed))
700}
701
702/// A WebSocket turn's body after the prompt cache key, in Go's order:
703/// `SanitizeCodexInputItemIDs`, `applyCodexSIWCWebsocketBodyRules` (the id pass sees
704/// the `configuration_update` items the SIWC rules then drop), then the payload rules.
705pub(crate) fn turn_body(
706    view: &View<'_>,
707    req: &ExecRequest,
708    settings: &Settings,
709    finalize: &request::Finalizer,
710    body: String,
711) -> String {
712    let mut body = request::sanitize_input_ids(body);
713    if view.siwc {
714        body = request::siwc_request_body(body, req, Call::Websocket);
715    }
716    finalize.apply(req, settings, body)
717}
718
719/// `frameCodexWebsocketRequestBody`: every turn is a `response.create`.
720fn request_frame(body: String) -> String {
721    set_str(&body, "type", "response.create")
722}
723
724/// `buildCodexWebsocketErrorPayload` for an `error` frame with a positive status: the
725/// status and the body Go classifies (and clears the reasoning replay with).
726fn ws_error_body(payload: &str) -> Option<(u16, String)> {
727    if gjson::get(payload, "type").str().trim() != "error" {
728        return None;
729    }
730    let mut status = gjson::get(payload, "status").i64();
731    if status == 0 {
732        status = gjson::get(payload, "status_code").i64();
733    }
734    // Go accepts any positive status; larger than u16 cannot be represented here.
735    let Ok(status) = u16::try_from(status) else {
736        return None;
737    };
738    if status == 0 {
739        return None;
740    }
741    let mut out = set_raw("{}", "status", &status.to_string());
742    let body = gjson::get(payload, "body");
743    let error = gjson::get(payload, "error");
744    if body.exists() {
745        out = set_raw(&out, "body", body.json());
746    }
747    if body.exists() && body.get("error").exists() {
748        out = set_raw(&out, "error", body.get("error").json());
749    } else if error.exists() {
750        out = set_raw(&out, "error", error.json());
751    } else {
752        out = set_str(&out, "error.type", "server_error");
753        out = set_str(&out, "error.message", response::go_status_text(status));
754    }
755    Some((status, out))
756}
757
758/// A request's reasoning replay (Claude clients only): the executor's cache and the
759/// request's scope.
760#[derive(Clone, Default)]
761pub(super) struct Replay {
762    cache: Arc<crate::codex_replay::Cache>,
763    scope: crate::codex_replay::Scope,
764}
765
766impl Replay {
767    /// `applyCodexReasoningReplayCacheRequired`: cached turns inserted into `body`.
768    async fn apply(cache: &Arc<crate::codex_replay::Cache>, req: &ExecRequest, body: String) -> (String, Self) {
769        let (body, scope) = crate::codex_replay::apply(cache, req, body).await;
770        let replay = Self {
771            cache: cache.clone(),
772            scope,
773        };
774        (body, replay)
775    }
776
777    /// `clearCodexReasoningReplayOnWebsocketError` or `...OnInvalidSignature` for a
778    /// rejection event: an invalid thinking signature drops the cached reasoning.
779    fn clear(&self, payload: &str, cooling: bool) {
780        if let Some((status, body)) = ws_error_body(payload) {
781            crate::codex_replay::clear_on_invalid_signature(&self.cache, &self.scope, status, body.as_bytes());
782        } else if let Some((error, body)) = response::terminal_failure(payload, cooling) {
783            crate::codex_replay::clear_on_invalid_signature(&self.cache, &self.scope, error.status, body.as_bytes());
784        }
785    }
786
787    /// `cacheCodexReasoningReplayFromCompleted`.
788    fn completed(&self, payload: &str) {
789        crate::codex_replay::cache_completed(&self.cache, &self.scope, payload.as_bytes());
790    }
791}
792
793/// `parseCodexWebsocketErrorWithCooling`: an `error` frame that carries an HTTP status.
794pub(crate) fn ws_error(payload: &str, model_level_cooling: bool) -> Option<ExecError> {
795    let (status, out) = ws_error_body(payload)?;
796    let mut headers = HeaderMap::new();
797    let raw_headers = gjson::get(payload, "headers");
798    if raw_headers.kind() == Kind::Object {
799        raw_headers.each(|k, v| {
800            let value = match v.kind() {
801                Kind::String => v.str().trim().to_owned(),
802                Kind::Number | Kind::True | Kind::False => v.json().trim().to_owned(),
803                _ => String::new(),
804            };
805            if let (Ok(name), Ok(value)) = (
806                http::HeaderName::try_from(k.str().trim()),
807                http::HeaderValue::from_str(&value),
808            ) && !value.is_empty()
809            {
810                headers.insert(name, value);
811            }
812            true
813        });
814    }
815    let connection_limit = [
816        "error.code",
817        "error.type",
818        "body.error.code",
819        "body.error.type",
820        "code",
821        "error",
822    ]
823    .iter()
824    .any(|p| gjson::get(payload, p).str().trim() == "websocket_connection_limit_reached");
825    // Go `statusErrWithHeaders`: the frame's headers reach the client under passthrough.
826    let addon = (!headers.is_empty()).then(|| Box::new(headers.clone()));
827    let mut error = response::status_error_raw(status, &out, headers, model_level_cooling);
828    error.addon = addon;
829    if error.retry_after.is_none() && connection_limit {
830        error.retry_after = Some(Duration::ZERO);
831    }
832    Some(error)
833}
834
835/// One upstream message, classified.
836enum Frame {
837    /// Empty text frame (heartbeat).
838    Skip,
839    Event {
840        out: Bytes,
841        raw_len: usize,
842        bufferable: bool,
843        terminal: bool,
844    },
845    /// The response failed. `read` means the reader already dropped the socket;
846    /// `overload` is a transient capacity rejection another credential may serve.
847    Failed {
848        error: ExecError,
849        overload: bool,
850        read: bool,
851        status_frame: bool,
852    },
853}
854
855/// One turn on a pooled socket. Dropping it releases the turn lock and the reader.
856struct Turn {
857    rx: mpsc::Receiver<Read>,
858    conn: Arc<Upstream>,
859    session: Arc<Session>,
860    _turn: Option<OwnedMutexGuard<()>>,
861    /// The observation of the message being read, while it runs.
862    observing: Option<crate::ws_observation::Observation>,
863    items: OutputItems,
864    saw_delta: bool,
865    native: bool,
866    cooling: bool,
867    quota: Arc<QuotaSignals>,
868    credential: String,
869    /// Handshake headers plus quota headers from this turn's events.
870    observed: HeaderMap,
871    /// The request renamed the `collaboration` namespace (multi-agent v2).
872    restore: bool,
873    /// The attempt's usage record.
874    usage: cpa_core::exec::UsageSink,
875    /// The upstream model, for per-model quota snapshots.
876    model: String,
877    replay: Replay,
878    /// The attempt's wire capture (Go's `api.websocket.*` timeline events).
879    wire: crate::codex_capture::Wire,
880    /// Inside the bootstrap window, where Go records an empty incomplete as a
881    /// WebSocket error rather than a response error.
882    bootstrapping: bool,
883}
884
885impl Drop for Turn {
886    fn drop(&mut self) {
887        // An abandoned turn keeps its session until an observation it started returns,
888        // as Go's executor holds the session lock through the synchronous observer.
889        let conn = self.conn.clone();
890        crate::ws_observation::release_after(self.observing.take(), self._turn.take(), move || conn.deactivate());
891    }
892}
893
894impl Turn {
895    async fn frame(&mut self) -> Frame {
896        let frame = self.read().await;
897        if let Frame::Failed { error, read: true, .. } = &frame {
898            let binary = error.body.as_ref() == UNEXPECTED_BINARY.as_bytes();
899            self.wire
900                .ws_exec_error(if binary { "unexpected_binary" } else { "read" }, error);
901        }
902        frame
903    }
904
905    async fn read(&mut self) -> Frame {
906        let text = match self.rx.recv().await {
907            Some(Read::Text(text)) => text,
908            Some(Read::Failed(error)) => {
909                return Frame::Failed {
910                    error,
911                    overload: false,
912                    read: true,
913                    status_frame: false,
914                };
915            }
916            // A full channel can drop the reader's terminal error; the session still
917            // recorded the loss (Go's reader waits to deliver it).
918            None => {
919                return Frame::Failed {
920                    error: self.loss().map_or_else(
921                        || transport("codex websockets executor: session read channel closed"),
922                        |l| turn_error(&l),
923                    ),
924                    overload: false,
925                    read: true,
926                    status_frame: false,
927                };
928            }
929        };
930        let payload = text.trim();
931        if payload.is_empty() {
932            return Frame::Skip;
933        }
934        self.observe(payload);
935        crate::ws_observation::observe(&mut self.observing, self.wire.ws_response_observation(payload)).await;
936        let raw_len = payload.len();
937        let payload = response::restore(payload, self.restore);
938        let payload = payload.as_ref();
939        if let Some(error) = ws_error(payload, self.cooling) {
940            self.replay.clear(payload, self.cooling);
941            self.wire.ws_exec_error("upstream_error", &error);
942            return Frame::Failed {
943                error,
944                overload: false,
945                read: false,
946                status_frame: true,
947            };
948        }
949        if let Some((error, body)) = response::terminal_failure(payload, self.cooling) {
950            self.replay.clear(payload, self.cooling);
951            self.wire.ws_exec_error("upstream_error", &error);
952            return Frame::Failed {
953                error,
954                overload: response::is_overload(&body),
955                read: false,
956                status_frame: false,
957            };
958        }
959        let kind = gjson::get(payload, "type");
960        let kind = kind.str().to_owned();
961        if response::meaningful_delta(payload) {
962            self.saw_delta = true;
963        }
964        if response::empty_incomplete(payload, self.items.len(), self.saw_delta) {
965            let error = response::request_scoped(502, response::EMPTY_INCOMPLETE_MESSAGE);
966            if self.bootstrapping {
967                self.wire.ws_exec_error("upstream_error", &error);
968            } else {
969                self.wire.exec_error(&error);
970            }
971            return Frame::Failed {
972                error,
973                overload: false,
974                read: false,
975                status_frame: false,
976            };
977        }
978        let bufferable = response::bufferable(payload);
979        let mut out = payload.to_owned();
980        let terminal = matches!(
981            kind.as_str(),
982            "response.completed" | "response.done" | "response.incomplete"
983        );
984        if kind == "response.output_item.done" {
985            self.items.collect(payload);
986        }
987        if terminal {
988            out = response::normalize_completion(out);
989            if !self.native {
990                out = self.items.patch(out);
991            }
992            if kind != "response.incomplete" {
993                self.replay.completed(&out);
994            }
995        }
996        Frame::Event {
997            raw_len,
998            out: Bytes::from(response::ensure_usage_details(out)),
999            bufferable,
1000            terminal,
1001        }
1002    }
1003
1004    /// Quota headers and usage from one upstream event, observed before collaboration
1005    /// names are restored (as Go does).
1006    fn observe(&mut self, payload: &str) {
1007        if let Some(headers) = codex_quota::event_headers(payload) {
1008            codex_quota::merge(&mut self.observed, &headers);
1009            self.quota.observe(&self.credential, &self.model, &self.observed);
1010        }
1011        if self.usage.enabled() {
1012            self.usage
1013                .response_line(cpa_core::format::Format::Codex, payload.as_bytes());
1014        }
1015    }
1016
1017    fn invalidate(&self, error: &ExecError, notify: bool) {
1018        self.session.invalidate(&self.conn, error, notify);
1019    }
1020
1021    /// The raw error that lost the session's socket, as the reader recorded it (the
1022    /// duplex wraps gorilla's close error unmapped).
1023    fn loss(&self) -> Option<ExecError> {
1024        self.session.closed.borrow().clone()
1025    }
1026}
1027
1028/// The rest of a turn as a stream; ends after the terminal event or the first error.
1029fn rest(turn: Turn) -> ExecStream {
1030    futures_util::stream::unfold(Some(turn), |turn| async move {
1031        let mut turn = turn?;
1032        loop {
1033            match turn.frame().await {
1034                Frame::Skip => continue,
1035                Frame::Event { out, terminal, .. } => {
1036                    return Some((Ok(out), (!terminal).then_some(turn)));
1037                }
1038                Frame::Failed { error, read, .. } => {
1039                    if !read {
1040                        turn.invalidate(&error, true);
1041                    }
1042                    return Some((Err(error), None));
1043                }
1044            }
1045        }
1046    })
1047    .boxed()
1048}
1049
1050/// Bootstrap buffering over WebSocket messages (codex_websockets_stream.go): every
1051/// message read counts toward the 48-frame window, held frames are bounded by 1 MiB.
1052async fn bootstrap(mut turn: Turn, timeout: Option<Duration>, started: Instant) -> Result<ExecStream, ExecError> {
1053    turn.bootstrapping = true;
1054    let mut held: Vec<Result<Bytes, ExecError>> = Vec::new();
1055    let (mut frames, mut bytes) = (0usize, 0usize);
1056    loop {
1057        let frame = turn.frame().await;
1058        frames += 1;
1059        let timed_out = timeout.is_some_and(|t| started.elapsed() >= t);
1060        let window_open = frames <= response::BOOTSTRAP_MAX_FRAMES && !timed_out;
1061        match frame {
1062            Frame::Skip if window_open => continue,
1063            Frame::Skip => break,
1064            Frame::Failed { error, read: true, .. } => return Err(error),
1065            Frame::Failed {
1066                error,
1067                status_frame: true,
1068                ..
1069            } => {
1070                turn.invalidate(&error, true);
1071                if !timed_out {
1072                    return Err(error);
1073                }
1074                held.push(Err(error));
1075                return Ok(futures_util::stream::iter(held).boxed());
1076            }
1077            Frame::Failed { error, overload, .. } => {
1078                if overload && !timed_out {
1079                    // Fail over before anything was shown; the downstream session survives.
1080                    turn.invalidate(&error, false);
1081                    let body = String::from_utf8_lossy(&error.body).into_owned();
1082                    return Err(response::bootstrap_overload(&body));
1083                }
1084                turn.invalidate(&error, true);
1085                held.push(Err(error));
1086                return Ok(futures_util::stream::iter(held).boxed());
1087            }
1088            Frame::Event {
1089                out,
1090                raw_len,
1091                bufferable,
1092                terminal,
1093            } => {
1094                let size = raw_len + out.len();
1095                if window_open && bufferable && !terminal && bytes + size <= response::BOOTSTRAP_MAX_BYTES {
1096                    bytes += size;
1097                    held.push(Ok(out));
1098                    continue;
1099                }
1100                held.push(Ok(out));
1101                if terminal {
1102                    return Ok(futures_util::stream::iter(held).boxed());
1103                }
1104                break;
1105            }
1106        }
1107    }
1108    turn.bootstrapping = false;
1109    Ok(futures_util::stream::iter(held).chain(rest(turn)).boxed())
1110}
1111
1112impl CodexExecutor {
1113    /// Opens (or reuses) the session's socket for `target`. Returns the handshake
1114    /// headers when a new socket was dialed (`ensureUpstreamConn`).
1115    /// `wire` records a refused upgrade and a dial failure (the first dial of a turn;
1116    /// Go's retry records only `dial_retry`).
1117    async fn ensure(
1118        &self,
1119        session: &Arc<Session>,
1120        target: &Target,
1121        headers: &HeaderMap,
1122        model: &str,
1123        model_level_cooling: bool,
1124        wire: Option<&crate::codex_capture::Wire>,
1125    ) -> Result<(Arc<Upstream>, Option<HeaderMap>), ExecError> {
1126        if let Some(current) = session.current() {
1127            if current.target.serves(target) {
1128                return Ok((current, None));
1129            }
1130            // target_changed: another credential, URL or proxy now serves this session.
1131            let mut slot = session.conn.lock().expect("session conn");
1132            if slot.as_ref().is_some_and(|c| Arc::ptr_eq(c, &current)) {
1133                *slot = None;
1134            }
1135            drop(slot);
1136            current.shutdown();
1137        }
1138        let (socket, handshake) = self.dial(target, headers, model, model_level_cooling, wire).await?;
1139        let (sink, stream) = socket.split();
1140        let conn = Upstream::new(target.clone(), sink, self.ws.write);
1141        // Publish before the reader runs, so a reader that fails at once still finds its
1142        // socket current and invalidates it; holding the handle slot keeps a concurrent
1143        // shutdown from missing the abort handle.
1144        let mut reader = conn.reader.lock().expect("reader handle");
1145        session.publish(conn.clone());
1146        let task = tokio::spawn(read_loop(stream, Arc::downgrade(session), conn.clone(), self.ws.idle));
1147        *reader = Some(task.abort_handle());
1148        drop(reader);
1149        Ok((conn, Some(handshake)))
1150    }
1151
1152    async fn dial(
1153        &self,
1154        target: &Target,
1155        request: &HeaderMap,
1156        model: &str,
1157        model_level_cooling: bool,
1158        wire: Option<&crate::codex_capture::Wire>,
1159    ) -> Result<(WebSocket, HeaderMap), ExecError> {
1160        // `newProxyAwareWebsocketDialer`: Go's standard dialer, environment proxies
1161        // included when none is configured, with `EnableCompression`.
1162        let mut headers = request.clone();
1163        let key = offer_compression(&mut headers);
1164        let builder = self
1165            .transport
1166            .standard(&target.proxy)
1167            .websocket(&target.url)
1168            .headers(headers)
1169            .accept_key(key.clone());
1170        let mut rejected = false;
1171        let attempt = async {
1172            let mut res = builder
1173                .send()
1174                .await
1175                .map_err(|_| transport("codex websockets executor: dial failed"))?;
1176            let status = res.status().as_u16();
1177            let handshake = res.headers().clone();
1178            if status != 101 {
1179                let inner = std::mem::replace(&mut *res, wreq::Response::from(http::Response::new(Vec::<u8>::new())));
1180                let mut body = Vec::new();
1181                let mut stream = inner.bytes_stream();
1182                while let Some(Ok(chunk)) = stream.next().await {
1183                    body.extend_from_slice(&chunk[..chunk.len().min(MAX_HANDSHAKE_BODY - body.len())]);
1184                    if body.len() >= MAX_HANDSHAKE_BODY {
1185                        break;
1186                    }
1187                }
1188                self.quota_observe(&target.credential, model, &handshake);
1189                rejected = true;
1190                if let Some(wire) = wire {
1191                    wire.upgrade_rejection(&target.url, request, status, &handshake, &body);
1192                }
1193                if status == 426 {
1194                    // Go returns a plain statusErr for 426 on downstream WebSockets.
1195                    let text = String::from_utf8_lossy(&body).into_owned();
1196                    return Err(response::status_error_raw(status, &text, handshake, false));
1197                }
1198                return Err(response::status_error(status, &body, handshake, model_level_cooling));
1199            }
1200            // ponytail: Go reports a failed negotiation (and a bad handshake) as a status
1201            // error carrying 101; here both are transport failures.
1202            let socket = upgrade(&mut res, &key, &handshake).await.map_err(|e| match e {
1203                UpgradeError::Handshake => transport("codex websockets executor: websocket handshake failed"),
1204                UpgradeError::Compression => {
1205                    transport("codex websockets executor: websocket: invalid compression negotiation")
1206                }
1207            })?;
1208            Ok((socket, handshake))
1209        };
1210        let dialed = tokio::time::timeout(HANDSHAKE_TIMEOUT, attempt)
1211            .await
1212            .unwrap_or_else(|_| Err(transport("codex websockets executor: handshake timed out")));
1213        // A refused upgrade was recorded as an HTTP attempt; anything else is a dial error.
1214        if let (Err(error), Some(wire)) = (&dialed, wire)
1215            && !rejected
1216        {
1217            wire.ws_exec_error("dial", error);
1218        }
1219        dialed
1220    }
1221
1222    fn quota_observe(&self, credential: &str, model: &str, headers: &HeaderMap) {
1223        self.quota().observe(credential, model, headers);
1224    }
1225
1226    /// One Responses turn over the session's upstream socket (`ExecuteStream` on
1227    /// `CodexWebsocketsExecutor` with a downstream WebSocket).
1228    pub(crate) async fn stream_ws(
1229        &self,
1230        view: &View<'_>,
1231        settings: &Settings,
1232        req: ExecRequest,
1233        exec_session: &ExecSession,
1234        cfg: &Config,
1235    ) -> Result<ExecResponse, ExecError> {
1236        let model = request::base_model(&req.model).to_owned();
1237        let request::Shaped {
1238            body,
1239            optimized,
1240            conflict,
1241            finalize,
1242        } = request::shape(&req, view, settings, Call::Websocket)?;
1243        let (body, replay) = Replay::apply(&self.replay, &req, body).await;
1244        let (body, cache) = request::prompt_cache(&req, body, Some(&exec_session.id), true);
1245        let body = turn_body(view, &req, settings, &finalize, body);
1246        crate::codex::report_request(&req, cpa_core::format::Format::Codex, &body);
1247        let native = request::is_native(&req);
1248        let headers = request::ws_headers(view, settings, &req.headers, &body, &model, cache.as_deref(), native);
1249        let target = Target::new(view.credential, ws_url(&format!("{}/responses", view.base_url))?, cfg);
1250        let session = self.ws.session(&exec_session.id);
1251        // `WebsocketInputFromContext(ctx) != nil && cfg.Codex.ResponseSteering`.
1252        let steering = settings
1253            .response_steering
1254            .then(|| session.steering())
1255            .flatten()
1256            .map(|input| {
1257                let initial =
1258                    duplex::Prepared::new(&body, &req.original_body, optimized, conflict, native, replay.clone());
1259                (input, initial)
1260            });
1261        let guard = session.turn.clone().lock_owned().await;
1262        let frame = request_frame(body);
1263        let wire = crate::codex_capture::Wire::new(req.capture(), view.credential)
1264            .with_websocket(req.websocket_emitter("codex", view.credential));
1265        wire.ws_request(&target.url, &headers, frame.as_bytes());
1266        let (mut conn, mut handshake) = if exec_session.continuation {
1267            match session.current().filter(|c| c.target.serves(&target)) {
1268                Some(conn) => (conn, None),
1269                None => return Err(ExecError::replay_required()),
1270            }
1271        } else {
1272            self.ensure(
1273                &session,
1274                &target,
1275                &headers,
1276                &model,
1277                settings.model_level_cooling,
1278                Some(&wire),
1279            )
1280            .await?
1281        };
1282        conn.bind(&session, exec_session.lease.as_ref())?;
1283        if let Some(handshake) = &handshake {
1284            wire.ws_handshake(101, handshake);
1285        }
1286        let started = Instant::now();
1287        let mut rx = conn.activate();
1288        let mut restore = conn.restores(optimized, conflict);
1289        if let Err(error) = conn.send(frame.clone()).await {
1290            wire.ws_exec_error("send", &error);
1291            // `shouldRetryCodexWebsocketSend`: request-scoped failures (413) never retry.
1292            let retry = error.scope != FailureScope::Request;
1293            if exec_session.continuation {
1294                session.invalidate(&conn, &error, false);
1295                return Err(if retry { ExecError::replay_required() } else { error });
1296            }
1297            session.invalidate(&conn, &error, true);
1298            if !retry {
1299                return Err(error);
1300            }
1301            // Retry once on a fresh socket: upstream may have closed it between turns.
1302            let (fresh, fresh_handshake) = match self
1303                .ensure(&session, &target, &headers, &model, settings.model_level_cooling, None)
1304                .await
1305            {
1306                Ok(fresh) => fresh,
1307                Err(error) => {
1308                    wire.ws_exec_error("dial_retry", &error);
1309                    return Err(error);
1310                }
1311            };
1312            fresh.bind(&session, exec_session.lease.as_ref())?;
1313            rx = fresh.activate();
1314            restore = fresh.restores(optimized, conflict);
1315            wire.ws_request(&target.url, &headers, frame.as_bytes());
1316            if let Some(handshake) = &fresh_handshake {
1317                wire.ws_handshake(101, handshake);
1318            }
1319            if let Err(error) = fresh.send(frame).await {
1320                wire.ws_exec_error("send_retry", &error);
1321                session.invalidate(&fresh, &error, true);
1322                return Err(error);
1323            }
1324            conn = fresh;
1325            handshake = fresh_handshake;
1326        }
1327        conn.note_multi_agent(optimized, conflict);
1328        let observed = handshake.clone().unwrap_or_default();
1329        if !observed.is_empty() {
1330            self.quota_observe(&view.credential.id, &model, &observed);
1331        }
1332        let turn = Turn {
1333            rx,
1334            conn,
1335            session,
1336            _turn: Some(guard),
1337            observing: None,
1338            items: OutputItems::default(),
1339            saw_delta: false,
1340            native,
1341            cooling: settings.model_level_cooling,
1342            quota: self.quota_handle(),
1343            credential: view.credential.id.clone(),
1344            observed,
1345            restore,
1346            usage: req.usage.clone(),
1347            model: model.clone(),
1348            replay,
1349            wire,
1350            bootstrapping: false,
1351        };
1352        if let Some((input, initial)) = steering {
1353            // The socket now belongs to this connection; bootstrap buffering does not apply.
1354            let stream = duplex::Duplex::start(turn, input, initial, req, view, settings, &exec_session.id).await;
1355            return Ok(ExecResponse {
1356                status: 200,
1357                headers: handshake.unwrap_or_default(),
1358                body: ResponseBody::Stream(stream),
1359            });
1360        }
1361        // The response waits for the Home replay writes it caused, as on HTTP.
1362        let writes = turn.replay.scope.writes.clone();
1363        let stream = if settings.bootstrap_buffering {
1364            match bootstrap(turn, settings.bootstrap_timeout, started).await {
1365                Ok(stream) => stream,
1366                Err(error) => {
1367                    writes.settle().await;
1368                    return Err(error);
1369                }
1370            }
1371        } else {
1372            rest(turn)
1373        };
1374        Ok(ExecResponse {
1375            status: 200,
1376            headers: handshake.unwrap_or_default(),
1377            body: ResponseBody::Stream(writes.gate(stream)),
1378        })
1379    }
1380}
1381
1382/// tungstenite's reports of a peer that went away without a close frame, which
1383/// gorilla/websocket reads as close 1006 "unexpected EOF".
1384fn ends_without_close(error: &tokio_tungstenite::tungstenite::Error) -> bool {
1385    use tokio_tungstenite::tungstenite::Error;
1386    use tokio_tungstenite::tungstenite::error::ProtocolError;
1387    match error {
1388        Error::Protocol(ProtocolError::ResetWithoutClosingHandshake) => true,
1389        Error::Io(io) => io.kind() == std::io::ErrorKind::UnexpectedEof,
1390        _ => false,
1391    }
1392}
1393
1394/// The socket's single reader. Exits on error, idle timeout, or abort.
1395///
1396/// Like Go's read deadline, `idle` starts when the read for the next application message
1397/// begins; control frames answered meanwhile do not extend it.
1398pub(crate) async fn read_loop(
1399    mut stream: SplitStream<WebSocket>,
1400    session: Weak<Session>,
1401    conn: Arc<Upstream>,
1402    idle: Duration,
1403) {
1404    let error = 'read: loop {
1405        let deadline = tokio::time::Instant::now() + idle;
1406        let text = loop {
1407            let message = match tokio::time::timeout_at(deadline, stream.next()).await {
1408                Err(_) => break 'read transport("codex websockets executor: read idle timeout"),
1409                // gorilla/websocket reports a connection that ends without a close frame
1410                // as close 1006; Go surfaces its text, which marks a lifecycle failure.
1411                Ok(None) => break 'read transport(&close_error_text(1006, "unexpected EOF")),
1412                Ok(Some(Err(error))) if ends_without_close(&error) => {
1413                    break 'read transport(&close_error_text(1006, "unexpected EOF"));
1414                }
1415                Ok(Some(Err(_))) => break 'read transport("codex websockets executor: read failed"),
1416                Ok(Some(Ok(message))) => message,
1417            };
1418            match message {
1419                Message::Text(text) => break text.as_str().to_owned(),
1420                Message::Binary(_) => break 'read transport(UNEXPECTED_BINARY),
1421                Message::Close(frame) => {
1422                    if let Some(frame) = frame.as_ref().filter(|f| u16::from(f.code) == 1009) {
1423                        break 'read closed_too_big(frame.reason.as_str());
1424                    }
1425                    let text = match frame {
1426                        Some(frame) => close_error_text(u16::from(frame.code), frame.reason.as_str()),
1427                        None => close_error_text(1005, ""),
1428                    };
1429                    break 'read transport(&text);
1430                }
1431                Message::Ping(_) | Message::Pong(_) | Message::Frame(_) => continue,
1432            }
1433        };
1434        // Terminal IDs are recorded before delivery: the handler may still be forwarding
1435        // the turn after its read channel was released.
1436        let terminal = terminal_response_id(text.trim());
1437        let active = {
1438            let mut link = conn.link.lock().expect("link");
1439            if let Some(id) = terminal {
1440                link.terminal.insert(id);
1441            }
1442            link.active.clone()
1443        };
1444        if let Some(tx) = active {
1445            // Waits while the turn is busy: backpressure instead of unbounded queueing.
1446            let _ = tx.send(Read::Text(text)).await;
1447        }
1448    };
1449    let active = {
1450        let mut link = conn.link.lock().expect("link");
1451        link.lost = Some(error.clone());
1452        link.active.clone()
1453    };
1454    // The session records the loss before the turn reads its error, so a handler that
1455    // sees the turn fail also finds the loss (Go's notifier closes the client first).
1456    match session.upgrade() {
1457        Some(session) => session.invalidate(&conn, &error, true),
1458        None => conn.deactivate(),
1459    }
1460    if let Some(tx) = active {
1461        let _ = tx.try_send(Read::Failed(turn_error(&error)));
1462    }
1463}
1464
1465/// Why [`upgrade`] refused a 101 answer.
1466pub(crate) enum UpgradeError {
1467    /// gorilla `Dial`'s checks failed (Upgrade, Connection, Sec-WebSocket-Accept) or the
1468    /// connection could not be taken over.
1469    Handshake,
1470    /// The permessage-deflate answer does not match the offer.
1471    Compression,
1472}
1473
1474/// gorilla `Dialer` with `EnableCompression`: offers permessage-deflate on the request
1475/// and returns the `Sec-WebSocket-Key` to send with it. Shared by the Codex and xAI
1476/// WebSocket executors (Go's xAI dialer also enables compression).
1477pub(crate) fn offer_compression(headers: &mut HeaderMap) -> String {
1478    headers.insert(
1479        http::header::SEC_WEBSOCKET_EXTENSIONS,
1480        http::HeaderValue::from_static(deflate::OFFER),
1481    );
1482    tokio_tungstenite::tungstenite::handshake::client::generate_key()
1483}
1484
1485/// gorilla `Dial`'s checks on a 101 answer, then its permessage-deflate agreement;
1486/// wraps the upgraded connection for [`Upstream`] and [`read_loop`].
1487pub(crate) async fn upgrade(
1488    res: &mut wreq::ws::WebSocketResponse,
1489    key: &str,
1490    handshake: &HeaderMap,
1491) -> Result<WebSocket, UpgradeError> {
1492    let accept = tokio_tungstenite::tungstenite::handshake::derive_accept_key(key.as_bytes());
1493    if !token_list_contains(handshake, http::header::UPGRADE, "websocket")
1494        || !token_list_contains(handshake, http::header::CONNECTION, "upgrade")
1495        || handshake.get(http::header::SEC_WEBSOCKET_ACCEPT).map(|v| v.as_bytes()) != Some(accept.as_bytes())
1496    {
1497        return Err(UpgradeError::Handshake);
1498    }
1499    let compressed = deflate::negotiated(handshake).map_err(|()| UpgradeError::Compression)?;
1500    let response = std::mem::replace(&mut **res, wreq::Response::from(http::Response::new(Vec::<u8>::new())));
1501    let upgraded = response.upgrade().await.map_err(|_| UpgradeError::Handshake)?;
1502    let config = WebSocketConfig::default()
1503        .max_frame_size(Some(MAX_UPSTREAM_MESSAGE))
1504        .max_message_size(Some(MAX_UPSTREAM_MESSAGE));
1505    Ok(WebSocketStream::from_raw_socket(
1506        Inflate::new(upgraded, compressed, MAX_UPSTREAM_MESSAGE),
1507        Role::Client,
1508        Some(config),
1509    )
1510    .await)
1511}
1512
1513/// gorilla `tokenListContainsValue`: a comma-separated token list holds `value`
1514/// (ASCII case-insensitive).
1515fn token_list_contains(headers: &HeaderMap, name: http::HeaderName, value: &str) -> bool {
1516    headers.get_all(name).iter().any(|v| {
1517        v.to_str().is_ok_and(|v| {
1518            v.split(',')
1519                .any(|t| t.trim_matches([' ', '\t']).eq_ignore_ascii_case(value))
1520        })
1521    })
1522}
1523
1524#[path = "codex_ws_deflate.rs"]
1525pub(crate) mod deflate;
1526#[path = "codex_duplex.rs"]
1527mod duplex;
1528pub use duplex::{ClientFrames, SteeringInput};
1529
1530#[cfg(test)]
1531#[path = "codex_ws_tests.rs"]
1532mod tests;
1533
1534#[cfg(test)]
1535mod close_text_tests {
1536    use super::close_error_text;
1537
1538    /// gorilla/websocket `CloseError.Error()` texts, which Go returns unchanged.
1539    #[test]
1540    fn close_errors_read_like_gorilla() {
1541        assert_eq!(close_error_text(1000, ""), "websocket: close 1000 (normal)");
1542        assert_eq!(close_error_text(1001, "bye"), "websocket: close 1001 (going away): bye");
1543        assert_eq!(
1544            close_error_text(1006, "unexpected EOF"),
1545            "websocket: close 1006 (abnormal closure): unexpected EOF"
1546        );
1547        assert_eq!(close_error_text(4000, "x"), "websocket: close 4000: x");
1548    }
1549}