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 mut parsed = crate::xai_url::parse(http_url.trim()).map_err(crate::xai_url::statusless)?;
683    parsed.scheme = match parsed.scheme.as_str() {
684        "http" => "ws".to_owned(),
685        "https" => "wss".to_owned(),
686        other => {
687            return Err(crate::xai_url::statusless(format!(
688                "codex websockets executor: unsupported responses websocket URL scheme {}",
689                cpa_common::gostr::quote(other)
690            )));
691        }
692    };
693    if parsed.host.trim().is_empty() {
694        return Err(crate::xai_url::statusless(
695            "codex websockets executor: responses websocket URL host is empty",
696        ));
697    }
698    Ok(crate::xai_url::string(&parsed))
699}
700
701/// A WebSocket turn's body after the prompt cache key, in Go's order:
702/// `SanitizeCodexInputItemIDs`, `applyCodexSIWCWebsocketBodyRules` (the id pass sees
703/// the `configuration_update` items the SIWC rules then drop), then the payload rules.
704pub(crate) fn turn_body(
705    view: &View<'_>,
706    req: &ExecRequest,
707    settings: &Settings,
708    finalize: &request::Finalizer,
709    body: String,
710) -> String {
711    let mut body = request::sanitize_input_ids(body);
712    if view.siwc {
713        body = request::siwc_request_body(body, req, Call::Websocket);
714    }
715    finalize.apply(req, settings, body)
716}
717
718/// `frameCodexWebsocketRequestBody`: every turn is a `response.create`.
719fn request_frame(body: String) -> String {
720    set_str(&body, "type", "response.create")
721}
722
723/// `buildCodexWebsocketErrorPayload` for an `error` frame with a positive status: the
724/// status and the body Go classifies (and clears the reasoning replay with).
725fn ws_error_body(payload: &str) -> Option<(u16, String)> {
726    if gjson::get(payload, "type").str().trim() != "error" {
727        return None;
728    }
729    let mut status = gjson::get(payload, "status").i64();
730    if status == 0 {
731        status = gjson::get(payload, "status_code").i64();
732    }
733    // Go accepts any positive status; larger than u16 cannot be represented here.
734    let Ok(status) = u16::try_from(status) else {
735        return None;
736    };
737    if status == 0 {
738        return None;
739    }
740    let mut out = set_raw("{}", "status", &status.to_string());
741    let body = gjson::get(payload, "body");
742    let error = gjson::get(payload, "error");
743    if body.exists() {
744        out = set_raw(&out, "body", body.json());
745    }
746    if body.exists() && body.get("error").exists() {
747        out = set_raw(&out, "error", body.get("error").json());
748    } else if error.exists() {
749        out = set_raw(&out, "error", error.json());
750    } else {
751        out = set_str(&out, "error.type", "server_error");
752        out = set_str(&out, "error.message", response::go_status_text(status));
753    }
754    Some((status, out))
755}
756
757/// A request's reasoning replay (Claude clients only): the executor's cache and the
758/// request's scope.
759#[derive(Clone, Default)]
760pub(super) struct Replay {
761    cache: Arc<crate::codex_replay::Cache>,
762    scope: crate::codex_replay::Scope,
763}
764
765impl Replay {
766    /// `applyCodexReasoningReplayCacheRequired`: cached turns inserted into `body`.
767    async fn apply(cache: &Arc<crate::codex_replay::Cache>, req: &ExecRequest, body: String) -> (String, Self) {
768        let (body, scope) = crate::codex_replay::apply(cache, req, body).await;
769        let replay = Self {
770            cache: cache.clone(),
771            scope,
772        };
773        (body, replay)
774    }
775
776    /// `clearCodexReasoningReplayOnWebsocketError` or `...OnInvalidSignature` for a
777    /// rejection event: an invalid thinking signature drops the cached reasoning.
778    fn clear(&self, payload: &str, cooling: bool) {
779        if let Some((status, body)) = ws_error_body(payload) {
780            crate::codex_replay::clear_on_invalid_signature(&self.cache, &self.scope, status, body.as_bytes());
781        } else if let Some((error, body)) = response::terminal_failure(payload, cooling) {
782            crate::codex_replay::clear_on_invalid_signature(&self.cache, &self.scope, error.status, body.as_bytes());
783        }
784    }
785
786    /// `cacheCodexReasoningReplayFromCompleted`.
787    fn completed(&self, payload: &str) {
788        crate::codex_replay::cache_completed(&self.cache, &self.scope, payload.as_bytes());
789    }
790}
791
792/// `parseCodexWebsocketErrorWithCooling`: an `error` frame that carries an HTTP status.
793pub(crate) fn ws_error(payload: &str, model_level_cooling: bool) -> Option<ExecError> {
794    let (status, out) = ws_error_body(payload)?;
795    let mut headers = HeaderMap::new();
796    let raw_headers = gjson::get(payload, "headers");
797    if raw_headers.kind() == Kind::Object {
798        raw_headers.each(|k, v| {
799            let value = match v.kind() {
800                Kind::String => v.str().trim().to_owned(),
801                Kind::Number | Kind::True | Kind::False => v.json().trim().to_owned(),
802                _ => String::new(),
803            };
804            if let (Ok(name), Ok(value)) = (
805                http::HeaderName::try_from(k.str().trim()),
806                http::HeaderValue::from_str(&value),
807            ) && !value.is_empty()
808            {
809                headers.insert(name, value);
810            }
811            true
812        });
813    }
814    let connection_limit = [
815        "error.code",
816        "error.type",
817        "body.error.code",
818        "body.error.type",
819        "code",
820        "error",
821    ]
822    .iter()
823    .any(|p| gjson::get(payload, p).str().trim() == "websocket_connection_limit_reached");
824    // Go `statusErrWithHeaders`: the frame's headers reach the client under passthrough.
825    let addon = (!headers.is_empty()).then(|| Box::new(headers.clone()));
826    let mut error = response::status_error_raw(status, &out, headers, model_level_cooling);
827    error.addon = addon;
828    if error.retry_after.is_none() && connection_limit {
829        error.retry_after = Some(Duration::ZERO);
830    }
831    Some(error)
832}
833
834/// One upstream message, classified.
835enum Frame {
836    /// Empty text frame (heartbeat).
837    Skip,
838    Event {
839        out: Bytes,
840        raw_len: usize,
841        bufferable: bool,
842        terminal: bool,
843    },
844    /// The response failed. `read` means the reader already dropped the socket;
845    /// `overload` is a transient capacity rejection another credential may serve.
846    Failed {
847        error: ExecError,
848        overload: bool,
849        read: bool,
850        status_frame: bool,
851    },
852}
853
854/// One turn on a pooled socket. Dropping it releases the turn lock and the reader.
855struct Turn {
856    rx: mpsc::Receiver<Read>,
857    conn: Arc<Upstream>,
858    session: Arc<Session>,
859    _turn: Option<OwnedMutexGuard<()>>,
860    /// The observation of the message being read, while it runs.
861    observing: Option<crate::ws_observation::Observation>,
862    items: OutputItems,
863    saw_delta: bool,
864    native: bool,
865    cooling: bool,
866    quota: Arc<QuotaSignals>,
867    credential: String,
868    /// Handshake headers plus quota headers from this turn's events.
869    observed: HeaderMap,
870    /// The request renamed the `collaboration` namespace (multi-agent v2).
871    restore: bool,
872    /// The attempt's usage record.
873    usage: cpa_core::exec::UsageSink,
874    /// The upstream model, for per-model quota snapshots.
875    model: String,
876    replay: Replay,
877    /// The attempt's wire capture (Go's `api.websocket.*` timeline events).
878    wire: crate::codex_capture::Wire,
879    /// Inside the bootstrap window, where Go records an empty incomplete as a
880    /// WebSocket error rather than a response error.
881    bootstrapping: bool,
882}
883
884impl Drop for Turn {
885    fn drop(&mut self) {
886        // An abandoned turn keeps its session until an observation it started returns,
887        // as Go's executor holds the session lock through the synchronous observer.
888        let conn = self.conn.clone();
889        crate::ws_observation::release_after(self.observing.take(), self._turn.take(), move || conn.deactivate());
890    }
891}
892
893impl Turn {
894    async fn frame(&mut self) -> Frame {
895        let frame = self.read().await;
896        if let Frame::Failed { error, read: true, .. } = &frame {
897            let binary = error.body.as_ref() == UNEXPECTED_BINARY.as_bytes();
898            self.wire
899                .ws_exec_error(if binary { "unexpected_binary" } else { "read" }, error);
900        }
901        frame
902    }
903
904    async fn read(&mut self) -> Frame {
905        let text = match self.rx.recv().await {
906            Some(Read::Text(text)) => text,
907            Some(Read::Failed(error)) => {
908                return Frame::Failed {
909                    error,
910                    overload: false,
911                    read: true,
912                    status_frame: false,
913                };
914            }
915            // A full channel can drop the reader's terminal error; the session still
916            // recorded the loss (Go's reader waits to deliver it).
917            None => {
918                return Frame::Failed {
919                    error: self.loss().map_or_else(
920                        || transport("codex websockets executor: session read channel closed"),
921                        |l| turn_error(&l),
922                    ),
923                    overload: false,
924                    read: true,
925                    status_frame: false,
926                };
927            }
928        };
929        let payload = text.trim();
930        if payload.is_empty() {
931            return Frame::Skip;
932        }
933        self.observe(payload);
934        crate::ws_observation::observe(&mut self.observing, self.wire.ws_response_observation(payload)).await;
935        let raw_len = payload.len();
936        let payload = response::restore(payload, self.restore);
937        let payload = payload.as_ref();
938        if let Some(error) = ws_error(payload, self.cooling) {
939            self.replay.clear(payload, self.cooling);
940            self.wire.ws_exec_error("upstream_error", &error);
941            return Frame::Failed {
942                error,
943                overload: false,
944                read: false,
945                status_frame: true,
946            };
947        }
948        if let Some((error, body)) = response::terminal_failure(payload, self.cooling) {
949            self.replay.clear(payload, self.cooling);
950            self.wire.ws_exec_error("upstream_error", &error);
951            return Frame::Failed {
952                error,
953                overload: response::is_overload(&body),
954                read: false,
955                status_frame: false,
956            };
957        }
958        let kind = gjson::get(payload, "type");
959        let kind = kind.str().to_owned();
960        if response::meaningful_delta(payload) {
961            self.saw_delta = true;
962        }
963        if response::empty_incomplete(payload, self.items.len(), self.saw_delta) {
964            let error = response::request_scoped(502, response::EMPTY_INCOMPLETE_MESSAGE);
965            if self.bootstrapping {
966                self.wire.ws_exec_error("upstream_error", &error);
967            } else {
968                self.wire.exec_error(&error);
969            }
970            return Frame::Failed {
971                error,
972                overload: false,
973                read: false,
974                status_frame: false,
975            };
976        }
977        let bufferable = response::bufferable(payload);
978        let mut out = payload.to_owned();
979        let terminal = matches!(
980            kind.as_str(),
981            "response.completed" | "response.done" | "response.incomplete"
982        );
983        if kind == "response.output_item.done" {
984            self.items.collect(payload);
985        }
986        if terminal {
987            out = response::normalize_completion(out);
988            if !self.native {
989                out = self.items.patch(out);
990            }
991            if kind != "response.incomplete" {
992                self.replay.completed(&out);
993            }
994        }
995        Frame::Event {
996            raw_len,
997            out: Bytes::from(response::ensure_usage_details(out)),
998            bufferable,
999            terminal,
1000        }
1001    }
1002
1003    /// Quota headers and usage from one upstream event, observed before collaboration
1004    /// names are restored (as Go does).
1005    fn observe(&mut self, payload: &str) {
1006        if let Some(headers) = codex_quota::event_headers(payload) {
1007            codex_quota::merge(&mut self.observed, &headers);
1008            self.quota.observe(&self.credential, &self.model, &self.observed);
1009        }
1010        if self.usage.enabled() {
1011            self.usage
1012                .response_line(cpa_core::format::Format::Codex, payload.as_bytes());
1013        }
1014    }
1015
1016    fn invalidate(&self, error: &ExecError, notify: bool) {
1017        self.session.invalidate(&self.conn, error, notify);
1018    }
1019
1020    /// The raw error that lost the session's socket, as the reader recorded it (the
1021    /// duplex wraps gorilla's close error unmapped).
1022    fn loss(&self) -> Option<ExecError> {
1023        self.session.closed.borrow().clone()
1024    }
1025}
1026
1027/// The rest of a turn as a stream; ends after the terminal event or the first error.
1028fn rest(turn: Turn) -> ExecStream {
1029    futures_util::stream::unfold(Some(turn), |turn| async move {
1030        let mut turn = turn?;
1031        loop {
1032            match turn.frame().await {
1033                Frame::Skip => continue,
1034                Frame::Event { out, terminal, .. } => {
1035                    return Some((Ok(out), (!terminal).then_some(turn)));
1036                }
1037                Frame::Failed { error, read, .. } => {
1038                    if !read {
1039                        turn.invalidate(&error, true);
1040                    }
1041                    return Some((Err(error), None));
1042                }
1043            }
1044        }
1045    })
1046    .boxed()
1047}
1048
1049/// Bootstrap buffering over WebSocket messages (codex_websockets_stream.go): every
1050/// message read counts toward the 48-frame window, held frames are bounded by 1 MiB.
1051async fn bootstrap(mut turn: Turn, timeout: Option<Duration>, started: Instant) -> Result<ExecStream, ExecError> {
1052    turn.bootstrapping = true;
1053    let mut held: Vec<Result<Bytes, ExecError>> = Vec::new();
1054    let (mut frames, mut bytes) = (0usize, 0usize);
1055    loop {
1056        let frame = turn.frame().await;
1057        frames += 1;
1058        let timed_out = timeout.is_some_and(|t| started.elapsed() >= t);
1059        let window_open = frames <= response::BOOTSTRAP_MAX_FRAMES && !timed_out;
1060        match frame {
1061            Frame::Skip if window_open => continue,
1062            Frame::Skip => break,
1063            Frame::Failed { error, read: true, .. } => return Err(error),
1064            Frame::Failed {
1065                error,
1066                status_frame: true,
1067                ..
1068            } => {
1069                turn.invalidate(&error, true);
1070                if !timed_out {
1071                    return Err(error);
1072                }
1073                held.push(Err(error));
1074                return Ok(futures_util::stream::iter(held).boxed());
1075            }
1076            Frame::Failed { error, overload, .. } => {
1077                if overload && !timed_out {
1078                    // Fail over before anything was shown; the downstream session survives.
1079                    turn.invalidate(&error, false);
1080                    let body = String::from_utf8_lossy(&error.body).into_owned();
1081                    return Err(response::bootstrap_overload(&body));
1082                }
1083                turn.invalidate(&error, true);
1084                held.push(Err(error));
1085                return Ok(futures_util::stream::iter(held).boxed());
1086            }
1087            Frame::Event {
1088                out,
1089                raw_len,
1090                bufferable,
1091                terminal,
1092            } => {
1093                let size = raw_len + out.len();
1094                if window_open && bufferable && !terminal && bytes + size <= response::BOOTSTRAP_MAX_BYTES {
1095                    bytes += size;
1096                    held.push(Ok(out));
1097                    continue;
1098                }
1099                held.push(Ok(out));
1100                if terminal {
1101                    return Ok(futures_util::stream::iter(held).boxed());
1102                }
1103                break;
1104            }
1105        }
1106    }
1107    turn.bootstrapping = false;
1108    Ok(futures_util::stream::iter(held).chain(rest(turn)).boxed())
1109}
1110
1111impl CodexExecutor {
1112    /// Opens (or reuses) the session's socket for `target`. Returns the handshake
1113    /// headers when a new socket was dialed (`ensureUpstreamConn`).
1114    /// `wire` records a refused upgrade and a dial failure (the first dial of a turn;
1115    /// Go's retry records only `dial_retry`).
1116    async fn ensure(
1117        &self,
1118        session: &Arc<Session>,
1119        target: &Target,
1120        headers: &HeaderMap,
1121        model: &str,
1122        model_level_cooling: bool,
1123        wire: Option<&crate::codex_capture::Wire>,
1124    ) -> Result<(Arc<Upstream>, Option<HeaderMap>), ExecError> {
1125        if let Some(current) = session.current() {
1126            if current.target.serves(target) {
1127                return Ok((current, None));
1128            }
1129            // target_changed: another credential, URL or proxy now serves this session.
1130            let mut slot = session.conn.lock().expect("session conn");
1131            if slot.as_ref().is_some_and(|c| Arc::ptr_eq(c, &current)) {
1132                *slot = None;
1133            }
1134            drop(slot);
1135            current.shutdown();
1136        }
1137        let (socket, handshake) = self.dial(target, headers, model, model_level_cooling, wire).await?;
1138        let (sink, stream) = socket.split();
1139        let conn = Upstream::new(target.clone(), sink, self.ws.write);
1140        // Publish before the reader runs, so a reader that fails at once still finds its
1141        // socket current and invalidates it; holding the handle slot keeps a concurrent
1142        // shutdown from missing the abort handle.
1143        let mut reader = conn.reader.lock().expect("reader handle");
1144        session.publish(conn.clone());
1145        let task = tokio::spawn(read_loop(stream, Arc::downgrade(session), conn.clone(), self.ws.idle));
1146        *reader = Some(task.abort_handle());
1147        drop(reader);
1148        Ok((conn, Some(handshake)))
1149    }
1150
1151    async fn dial(
1152        &self,
1153        target: &Target,
1154        request: &HeaderMap,
1155        model: &str,
1156        model_level_cooling: bool,
1157        wire: Option<&crate::codex_capture::Wire>,
1158    ) -> Result<(WebSocket, HeaderMap), ExecError> {
1159        // `newProxyAwareWebsocketDialer`: Go's standard dialer, environment proxies
1160        // included when none is configured, with `EnableCompression`.
1161        let mut headers = request.clone();
1162        let key = offer_compression(&mut headers);
1163        let builder = self
1164            .transport
1165            .standard(&target.proxy)
1166            .websocket(&target.url)
1167            .headers(headers)
1168            .accept_key(key.clone());
1169        let mut rejected = false;
1170        let attempt = async {
1171            let mut res = builder
1172                .send()
1173                .await
1174                .map_err(|_| transport("codex websockets executor: dial failed"))?;
1175            let status = res.status().as_u16();
1176            let handshake = res.headers().clone();
1177            if status != 101 {
1178                let inner = std::mem::replace(&mut *res, wreq::Response::from(http::Response::new(Vec::<u8>::new())));
1179                let mut body = Vec::new();
1180                let mut stream = inner.bytes_stream();
1181                while let Some(Ok(chunk)) = stream.next().await {
1182                    body.extend_from_slice(&chunk[..chunk.len().min(MAX_HANDSHAKE_BODY - body.len())]);
1183                    if body.len() >= MAX_HANDSHAKE_BODY {
1184                        break;
1185                    }
1186                }
1187                self.quota_observe(&target.credential, model, &handshake);
1188                rejected = true;
1189                if let Some(wire) = wire {
1190                    wire.upgrade_rejection(&target.url, request, status, &handshake, &body);
1191                }
1192                if status == 426 {
1193                    // Go returns a plain statusErr for 426 on downstream WebSockets.
1194                    let text = String::from_utf8_lossy(&body).into_owned();
1195                    return Err(response::status_error_raw(status, &text, handshake, false));
1196                }
1197                return Err(response::status_error(status, &body, handshake, model_level_cooling));
1198            }
1199            // ponytail: Go reports a failed negotiation (and a bad handshake) as a status
1200            // error carrying 101; here both are transport failures.
1201            let socket = upgrade(&mut res, &key, &handshake).await.map_err(|e| match e {
1202                UpgradeError::Handshake => transport("codex websockets executor: websocket handshake failed"),
1203                UpgradeError::Compression => {
1204                    transport("codex websockets executor: websocket: invalid compression negotiation")
1205                }
1206            })?;
1207            Ok((socket, handshake))
1208        };
1209        let dialed = tokio::time::timeout(HANDSHAKE_TIMEOUT, attempt)
1210            .await
1211            .unwrap_or_else(|_| Err(transport("codex websockets executor: handshake timed out")));
1212        // A refused upgrade was recorded as an HTTP attempt; anything else is a dial error.
1213        if let (Err(error), Some(wire)) = (&dialed, wire)
1214            && !rejected
1215        {
1216            wire.ws_exec_error("dial", error);
1217        }
1218        dialed
1219    }
1220
1221    fn quota_observe(&self, credential: &str, model: &str, headers: &HeaderMap) {
1222        self.quota().observe(credential, model, headers);
1223    }
1224
1225    /// One Responses turn over the session's upstream socket (`ExecuteStream` on
1226    /// `CodexWebsocketsExecutor` with a downstream WebSocket).
1227    pub(crate) async fn stream_ws(
1228        &self,
1229        view: &View<'_>,
1230        settings: &Settings,
1231        req: ExecRequest,
1232        exec_session: &ExecSession,
1233        cfg: &Config,
1234    ) -> Result<ExecResponse, ExecError> {
1235        let model = request::base_model(&req.model).to_owned();
1236        let request::Shaped {
1237            body,
1238            optimized,
1239            conflict,
1240            finalize,
1241        } = request::shape(&req, view, settings, Call::Websocket)?;
1242        let (body, replay) = Replay::apply(&self.replay, &req, body).await;
1243        let (body, cache) = request::prompt_cache(&req, body, Some(&exec_session.id), true);
1244        let body = turn_body(view, &req, settings, &finalize, body);
1245        crate::codex::report_request(&req, cpa_core::format::Format::Codex, &body);
1246        let native = request::is_native(&req);
1247        let headers = request::ws_headers(view, settings, &req.headers, &body, &model, cache.as_deref(), native);
1248        let target = Target::new(view.credential, ws_url(&format!("{}/responses", view.base_url))?, cfg);
1249        let session = self.ws.session(&exec_session.id);
1250        // `WebsocketInputFromContext(ctx) != nil && cfg.Codex.ResponseSteering`.
1251        let steering = settings
1252            .response_steering
1253            .then(|| session.steering())
1254            .flatten()
1255            .map(|input| {
1256                let initial =
1257                    duplex::Prepared::new(&body, &req.original_body, optimized, conflict, native, replay.clone());
1258                (input, initial)
1259            });
1260        let guard = session.turn.clone().lock_owned().await;
1261        let frame = request_frame(body);
1262        let wire = crate::codex_capture::Wire::new(req.capture(), view.credential)
1263            .with_websocket(req.websocket_emitter("codex", view.credential));
1264        wire.ws_request(&target.url, &headers, frame.as_bytes());
1265        let (mut conn, mut handshake) = if exec_session.continuation {
1266            match session.current().filter(|c| c.target.serves(&target)) {
1267                Some(conn) => (conn, None),
1268                None => return Err(ExecError::replay_required()),
1269            }
1270        } else {
1271            self.ensure(
1272                &session,
1273                &target,
1274                &headers,
1275                &model,
1276                settings.model_level_cooling,
1277                Some(&wire),
1278            )
1279            .await?
1280        };
1281        conn.bind(&session, exec_session.lease.as_ref())?;
1282        if let Some(handshake) = &handshake {
1283            wire.ws_handshake(101, handshake);
1284        }
1285        let started = Instant::now();
1286        let mut rx = conn.activate();
1287        let mut restore = conn.restores(optimized, conflict);
1288        if let Err(error) = conn.send(frame.clone()).await {
1289            wire.ws_exec_error("send", &error);
1290            // `shouldRetryCodexWebsocketSend`: request-scoped failures (413) never retry.
1291            let retry = error.scope != FailureScope::Request;
1292            if exec_session.continuation {
1293                session.invalidate(&conn, &error, false);
1294                return Err(if retry { ExecError::replay_required() } else { error });
1295            }
1296            session.invalidate(&conn, &error, true);
1297            if !retry {
1298                return Err(error);
1299            }
1300            // Retry once on a fresh socket: upstream may have closed it between turns.
1301            let (fresh, fresh_handshake) = match self
1302                .ensure(&session, &target, &headers, &model, settings.model_level_cooling, None)
1303                .await
1304            {
1305                Ok(fresh) => fresh,
1306                Err(error) => {
1307                    wire.ws_exec_error("dial_retry", &error);
1308                    return Err(error);
1309                }
1310            };
1311            fresh.bind(&session, exec_session.lease.as_ref())?;
1312            rx = fresh.activate();
1313            restore = fresh.restores(optimized, conflict);
1314            wire.ws_request(&target.url, &headers, frame.as_bytes());
1315            if let Some(handshake) = &fresh_handshake {
1316                wire.ws_handshake(101, handshake);
1317            }
1318            if let Err(error) = fresh.send(frame).await {
1319                wire.ws_exec_error("send_retry", &error);
1320                session.invalidate(&fresh, &error, true);
1321                return Err(error);
1322            }
1323            conn = fresh;
1324            handshake = fresh_handshake;
1325        }
1326        conn.note_multi_agent(optimized, conflict);
1327        let observed = handshake.clone().unwrap_or_default();
1328        if !observed.is_empty() {
1329            self.quota_observe(&view.credential.id, &model, &observed);
1330        }
1331        let turn = Turn {
1332            rx,
1333            conn,
1334            session,
1335            _turn: Some(guard),
1336            observing: None,
1337            items: OutputItems::default(),
1338            saw_delta: false,
1339            native,
1340            cooling: settings.model_level_cooling,
1341            quota: self.quota_handle(),
1342            credential: view.credential.id.clone(),
1343            observed,
1344            restore,
1345            usage: req.usage.clone(),
1346            model: model.clone(),
1347            replay,
1348            wire,
1349            bootstrapping: false,
1350        };
1351        if let Some((input, initial)) = steering {
1352            // The socket now belongs to this connection; bootstrap buffering does not apply.
1353            let stream = duplex::Duplex::start(turn, input, initial, req, view, settings, &exec_session.id).await;
1354            return Ok(ExecResponse {
1355                status: 200,
1356                headers: handshake.unwrap_or_default(),
1357                body: ResponseBody::Stream(stream),
1358            });
1359        }
1360        // The response waits for the Home replay writes it caused, as on HTTP.
1361        let writes = turn.replay.scope.writes.clone();
1362        let stream = if settings.bootstrap_buffering {
1363            match bootstrap(turn, settings.bootstrap_timeout, started).await {
1364                Ok(stream) => stream,
1365                Err(error) => {
1366                    writes.settle().await;
1367                    return Err(error);
1368                }
1369            }
1370        } else {
1371            rest(turn)
1372        };
1373        Ok(ExecResponse {
1374            status: 200,
1375            headers: handshake.unwrap_or_default(),
1376            body: ResponseBody::Stream(writes.gate(stream)),
1377        })
1378    }
1379}
1380
1381/// tungstenite's reports of a peer that went away without a close frame, which
1382/// gorilla/websocket reads as close 1006 "unexpected EOF".
1383fn ends_without_close(error: &tokio_tungstenite::tungstenite::Error) -> bool {
1384    use tokio_tungstenite::tungstenite::Error;
1385    use tokio_tungstenite::tungstenite::error::ProtocolError;
1386    match error {
1387        Error::Protocol(ProtocolError::ResetWithoutClosingHandshake) => true,
1388        Error::Io(io) => io.kind() == std::io::ErrorKind::UnexpectedEof,
1389        _ => false,
1390    }
1391}
1392
1393/// The socket's single reader. Exits on error, idle timeout, or abort.
1394///
1395/// Like Go's read deadline, `idle` starts when the read for the next application message
1396/// begins; control frames answered meanwhile do not extend it.
1397pub(crate) async fn read_loop(
1398    mut stream: SplitStream<WebSocket>,
1399    session: Weak<Session>,
1400    conn: Arc<Upstream>,
1401    idle: Duration,
1402) {
1403    let error = 'read: loop {
1404        let deadline = tokio::time::Instant::now() + idle;
1405        let text = loop {
1406            let message = match tokio::time::timeout_at(deadline, stream.next()).await {
1407                Err(_) => break 'read transport("codex websockets executor: read idle timeout"),
1408                // gorilla/websocket reports a connection that ends without a close frame
1409                // as close 1006; Go surfaces its text, which marks a lifecycle failure.
1410                Ok(None) => break 'read transport(&close_error_text(1006, "unexpected EOF")),
1411                Ok(Some(Err(error))) if ends_without_close(&error) => {
1412                    break 'read transport(&close_error_text(1006, "unexpected EOF"));
1413                }
1414                Ok(Some(Err(_))) => break 'read transport("codex websockets executor: read failed"),
1415                Ok(Some(Ok(message))) => message,
1416            };
1417            match message {
1418                Message::Text(text) => break text.as_str().to_owned(),
1419                Message::Binary(_) => break 'read transport(UNEXPECTED_BINARY),
1420                Message::Close(frame) => {
1421                    if let Some(frame) = frame.as_ref().filter(|f| u16::from(f.code) == 1009) {
1422                        break 'read closed_too_big(frame.reason.as_str());
1423                    }
1424                    let text = match frame {
1425                        Some(frame) => close_error_text(u16::from(frame.code), frame.reason.as_str()),
1426                        None => close_error_text(1005, ""),
1427                    };
1428                    break 'read transport(&text);
1429                }
1430                Message::Ping(_) | Message::Pong(_) | Message::Frame(_) => continue,
1431            }
1432        };
1433        // Terminal IDs are recorded before delivery: the handler may still be forwarding
1434        // the turn after its read channel was released.
1435        let terminal = terminal_response_id(text.trim());
1436        let active = {
1437            let mut link = conn.link.lock().expect("link");
1438            if let Some(id) = terminal {
1439                link.terminal.insert(id);
1440            }
1441            link.active.clone()
1442        };
1443        if let Some(tx) = active {
1444            // Waits while the turn is busy: backpressure instead of unbounded queueing.
1445            let _ = tx.send(Read::Text(text)).await;
1446        }
1447    };
1448    let active = {
1449        let mut link = conn.link.lock().expect("link");
1450        link.lost = Some(error.clone());
1451        link.active.clone()
1452    };
1453    // The session records the loss before the turn reads its error, so a handler that
1454    // sees the turn fail also finds the loss (Go's notifier closes the client first).
1455    match session.upgrade() {
1456        Some(session) => session.invalidate(&conn, &error, true),
1457        None => conn.deactivate(),
1458    }
1459    if let Some(tx) = active {
1460        let _ = tx.try_send(Read::Failed(turn_error(&error)));
1461    }
1462}
1463
1464/// Why [`upgrade`] refused a 101 answer.
1465pub(crate) enum UpgradeError {
1466    /// gorilla `Dial`'s checks failed (Upgrade, Connection, Sec-WebSocket-Accept) or the
1467    /// connection could not be taken over.
1468    Handshake,
1469    /// The permessage-deflate answer does not match the offer.
1470    Compression,
1471}
1472
1473/// gorilla `Dialer` with `EnableCompression`: offers permessage-deflate on the request
1474/// and returns the `Sec-WebSocket-Key` to send with it. Shared by the Codex and xAI
1475/// WebSocket executors (Go's xAI dialer also enables compression).
1476pub(crate) fn offer_compression(headers: &mut HeaderMap) -> String {
1477    headers.insert(
1478        http::header::SEC_WEBSOCKET_EXTENSIONS,
1479        http::HeaderValue::from_static(deflate::OFFER),
1480    );
1481    tokio_tungstenite::tungstenite::handshake::client::generate_key()
1482}
1483
1484/// gorilla `Dial`'s checks on a 101 answer, then its permessage-deflate agreement;
1485/// wraps the upgraded connection for [`Upstream`] and [`read_loop`].
1486pub(crate) async fn upgrade(
1487    res: &mut wreq::ws::WebSocketResponse,
1488    key: &str,
1489    handshake: &HeaderMap,
1490) -> Result<WebSocket, UpgradeError> {
1491    let accept = tokio_tungstenite::tungstenite::handshake::derive_accept_key(key.as_bytes());
1492    if !token_list_contains(handshake, http::header::UPGRADE, "websocket")
1493        || !token_list_contains(handshake, http::header::CONNECTION, "upgrade")
1494        || handshake.get(http::header::SEC_WEBSOCKET_ACCEPT).map(|v| v.as_bytes()) != Some(accept.as_bytes())
1495    {
1496        return Err(UpgradeError::Handshake);
1497    }
1498    let compressed = deflate::negotiated(handshake).map_err(|()| UpgradeError::Compression)?;
1499    let response = std::mem::replace(&mut **res, wreq::Response::from(http::Response::new(Vec::<u8>::new())));
1500    let upgraded = response.upgrade().await.map_err(|_| UpgradeError::Handshake)?;
1501    let config = WebSocketConfig::default()
1502        .max_frame_size(Some(MAX_UPSTREAM_MESSAGE))
1503        .max_message_size(Some(MAX_UPSTREAM_MESSAGE));
1504    Ok(WebSocketStream::from_raw_socket(
1505        Inflate::new(upgraded, compressed, MAX_UPSTREAM_MESSAGE),
1506        Role::Client,
1507        Some(config),
1508    )
1509    .await)
1510}
1511
1512/// gorilla `tokenListContainsValue`: a comma-separated token list holds `value`
1513/// (ASCII case-insensitive).
1514fn token_list_contains(headers: &HeaderMap, name: http::HeaderName, value: &str) -> bool {
1515    headers.get_all(name).iter().any(|v| {
1516        v.to_str().is_ok_and(|v| {
1517            v.split(',')
1518                .any(|t| t.trim_matches([' ', '\t']).eq_ignore_ascii_case(value))
1519        })
1520    })
1521}
1522
1523#[path = "codex_ws_deflate.rs"]
1524pub(crate) mod deflate;
1525#[path = "codex_duplex.rs"]
1526mod duplex;
1527pub use duplex::{ClientFrames, SteeringInput};
1528
1529#[cfg(test)]
1530#[path = "codex_ws_tests.rs"]
1531mod tests;
1532
1533#[cfg(test)]
1534mod close_text_tests {
1535    use super::close_error_text;
1536
1537    /// gorilla/websocket `CloseError.Error()` texts, which Go returns unchanged.
1538    #[test]
1539    fn close_errors_read_like_gorilla() {
1540        assert_eq!(close_error_text(1000, ""), "websocket: close 1000 (normal)");
1541        assert_eq!(close_error_text(1001, "bye"), "websocket: close 1001 (going away): bye");
1542        assert_eq!(
1543            close_error_text(1006, "unexpected EOF"),
1544            "websocket: close 1006 (abnormal closure): unexpected EOF"
1545        );
1546        assert_eq!(close_error_text(4000, "x"), "websocket: close 4000: x");
1547    }
1548}