Skip to main content

cpa_core/
exec.rs

1//! The execution envelope: what the runtime hands an executor and what comes back.
2//!
3//! Transport-neutral on purpose. Executors own their HTTP clients; nothing here knows
4//! about wreq or axum (sdk/cliproxy/executor/types.go).
5//!
6//! Ownership: the executor owns request translation, provider preparation (cloak,
7//! aliases) and response restoration, in that order. Nothing before the executor
8//! translates; nothing after it un-aliases.
9
10use std::fmt;
11use std::time::Duration;
12
13use bytes::Bytes;
14use futures_util::stream::BoxStream;
15use http::HeaderMap;
16
17use crate::format::Format;
18
19#[derive(Debug, Clone, Copy, PartialEq, Eq)]
20pub enum Operation {
21    /// Generate a response (Messages, Chat Completions, Responses, generateContent).
22    Generate,
23    CountTokens,
24}
25
26/// The authenticated downstream caller. Private request context: it seeds stable
27/// per-caller state such as Claude tool aliases and must never be sent upstream.
28#[derive(Clone, PartialEq, Eq)]
29pub struct Caller {
30    /// The configured client key that matched, or empty when client auth is disabled.
31    pub principal: String,
32    /// Where the key came from: `authorization`, `x-api-key`, `query-key`, ...
33    pub source: &'static str,
34    /// The access provider that accepted the key (Go gin `accessProvider`): `config-inline`
35    /// for a configured client key, else the plugin's provider; empty when access is open.
36    pub provider: String,
37}
38
39impl fmt::Debug for Caller {
40    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
41        f.debug_struct("Caller")
42            .field("source", &self.source)
43            .finish_non_exhaustive()
44    }
45}
46
47#[derive(Clone)]
48pub struct ExecRequest {
49    pub operation: Operation,
50    /// Format of the inbound request.
51    pub source_format: Format,
52    /// Format the client expects back.
53    pub response_format: Format,
54    /// Model named by the client, trimmed.
55    pub requested_model: String,
56    /// Model after alias resolution, sent upstream.
57    pub model: String,
58    /// Inbound body exactly as received.
59    pub original_body: Bytes,
60    /// Body in `source_format`, after request-level rewrites (payload rules) but before
61    /// any translation. The executor translates it.
62    pub body: Bytes,
63    /// The client asked for a stream. The upstream mode is the executor's decision.
64    pub stream: bool,
65    /// Return Go executor chunks before HTTP framing, for internal model callbacks.
66    /// Captured when preparing the attempt, independent of plugin interceptor lifetime.
67    pub stream_payloads: bool,
68    /// Alternate operation from `alt` / `$alt` (for example `responses/compact`).
69    pub alt: Option<String>,
70    /// Session key for affinity and provider session identity, when one was derived:
71    /// Go `ExtractSessionID` (see `cpa_common::session`). Explicit client sessions carry
72    /// their family prefix (`claude:`, `codex:`, `header:`, `pck:`, ...); `derived:<id>`
73    /// means Go's `derived_session_id` metadata is `<id>`; `msg:` is the first-messages
74    /// hash.
75    pub session: Option<String>,
76    /// Go `execution_session_id` metadata: a long-lived execution session that outlives
77    /// one HTTP request. Set only by transports that own such a session (the Responses
78    /// WebSocket uses its connection's session ID); `None` for ordinary HTTP routes.
79    /// Provider replay caches (Codex and Kimi reasoning replay) key on
80    /// `execution:<id>` before falling back to payload or header identity.
81    pub execution_session: Option<String>,
82    /// Go `derived_session_id` metadata (`ctx:v1:<sha256>`, from
83    /// `cpa_common::session::derive_id`): set only when the request carries no explicit
84    /// session signal and no execution session, exactly when Go's `session.Enrich` sets
85    /// it. Go `helps.ProviderSessionUUID` falls back to it after the execution session.
86    pub derived_session: Option<String>,
87    /// Go `request_path` metadata (gin `FullPath()`): the matched route template, for
88    /// example `/v1/chat/completions` or `/v1beta/models/*action`; the URI path when no
89    /// route matched; empty for internal executions. Pass it to
90    /// `cpa_common::payload::Request::request_path` (the `disable-image-generation: chat`
91    /// gate keeps image generation on `/v1/images/*`).
92    pub request_path: String,
93    /// Inbound headers. Executors forward only what their provider profile allows.
94    /// Contains client credentials: never log or forward wholesale.
95    pub headers: HeaderMap,
96    pub caller: Caller,
97    /// Go `cliproxyauth.ResolvedModelInfo(req)`: the model capabilities the dispatch
98    /// loop bound to this attempt for the selected credential and upstream model (Go
99    /// `attachResolvedExecutionModelInfo`, sdk/cliproxy/auth/api_key_model_capabilities.go).
100    /// `None` when Go binds nothing; executors then fall back to the registry lookup
101    /// (`cpa_core::registry::lookup_model`), as Go's helpers do. Callers outside the
102    /// dispatch loop set `None`.
103    pub resolved_model: Option<ResolvedModel>,
104    /// Usage accounting for this attempt (Go's per-executor `UsageReporter`). Optional:
105    /// without reports the server parses the client-format response, which matches Go
106    /// whenever the upstream speaks the client's format. Executors that translate
107    /// should forward the upstream payloads Go parses; `UsageSink::default()` is a
108    /// no-op.
109    pub usage: UsageSink,
110}
111
112/// Receives the upstream payloads Go's executors feed their usage reporter.
113pub trait UsageObserver: Send + Sync {
114    fn wants_claude_cache(&self) -> bool {
115        false
116    }
117    /// Content-free Claude cache facts, taken after every request rewrite.
118    fn claude_cache(&self, telemetry: ClaudeCacheTelemetry) {
119        let _ = telemetry;
120    }
121    /// A whole upstream response body in `format` (Go `Parse*Usage` on the body).
122    fn response_body(&self, format: Format, body: &[u8]);
123    /// One upstream stream line in `format`, as received (Go feeds each scanner line to
124    /// its `StreamUsageBuffer` and `ObserveResponseModel`).
125    fn response_line(&self, format: Format, line: &[u8]);
126    /// [`UsageObserver::response_line`] for usage only (Go's `StreamUsageBuffer`): the
127    /// executor observes the served model on whole payloads instead.
128    fn response_usage_line(&self, format: Format, line: &[u8]) {
129        let _ = (format, line);
130    }
131    /// The translated payload sent upstream in `format` (Go
132    /// `SetTranslatedReasoningEffort`: the record's `reasoning_effort`).
133    fn request(&self, format: Format, payload: &[u8]);
134    /// The attempt runs on a plugin executor registered for `provider` (Go
135    /// `NewExecutorUsageReporter` with the host's `executorAdapter`): the record's
136    /// provider is that identifier and its executor type `executorAdapter`.
137    fn plugin_executor(&self, provider: &str) {
138        let _ = provider;
139    }
140    /// The attempt runs on another built-in executor's code (Go's Vertex openapi route
141    /// calls `OpenAICompatExecutor.executeWithCredentials`, whose reporter names its
142    /// own `executor_type`, picking the token rule, and `model`).
143    fn delegated_executor(&self, executor_type: &str, model: &str) {
144        let _ = (executor_type, model);
145    }
146    /// Go `ParsePluginExecutorResponseUsage`: a plugin executor's whole response in its
147    /// output `protocol`, which may be a format cliproxy-rs does not know.
148    fn plugin_response_body(&self, protocol: &str, body: &[u8]) {
149        let _ = (protocol, body);
150    }
151    /// Go `ObservePluginExecutorStreamUsage` on one trimmed, non-empty line of a plugin
152    /// executor's stream in its output `protocol`.
153    fn plugin_response_line(&self, protocol: &str, line: &[u8]) {
154        let _ = (protocol, line);
155    }
156    /// [`UsageObserver::request`] where Go passes an executor identifier instead of a
157    /// format (Kimi passes `kimi`).
158    fn request_for(&self, identifier: &str, payload: &[u8]) {
159        let _ = (identifier, payload);
160    }
161    /// Go `SetUpstreamModel`: the model the upstream is expected to serve, for the
162    /// substitution warning only.
163    fn upstream_model(&self, model: &str) {
164        let _ = model;
165    }
166    /// Go `SetResponseModel`: the served model, unless a terminal event fixed it.
167    fn response_model(&self, model: &str) {
168        let _ = model;
169    }
170    /// Go `ObserveResponseModel` on a payload whose usage is not observed (an
171    /// Antigravity payload joined from several stream lines).
172    fn response_model_line(&self, line: &[u8]) {
173        let _ = line;
174    }
175    /// Go `StartResponseTTFT`: the upstream request is being sent.
176    fn round_trip_started(&self) {}
177    /// Go `MarkFirstResponseByte`: the first upstream body byte arrived.
178    fn first_byte(&self) {}
179    /// Go `ObserveTokenEvent`: an upstream frame arrived; `is_token` when it carried
180    /// output (Codex SSE marks TTFT at the first token, the first frame as fallback).
181    fn token_event(&self, is_token: bool) {
182        let _ = is_token;
183    }
184    /// Go `Publish`/`EnsurePublished` now, with the usage reported so far. The first
185    /// publish of an attempt wins (Go `once.Do`); the server's later outcome is ignored.
186    fn publish(&self) {}
187    /// Go `PublishFailure` now with `status` (0 when the error carries none) and
188    /// `body`; no usage. The first publish of an attempt wins.
189    fn publish_failure(&self, status: u16, body: &str) {
190        let _ = (status, body);
191    }
192    /// Go `StreamUsageBuffer.PublishFailure`: [`UsageObserver::publish_failure`] with the
193    /// usage reported so far.
194    fn publish_failure_with_usage(&self, status: u16, body: &str) {
195        let _ = (status, body);
196    }
197    /// The Go path has no `EnsurePublished`: an attempt that ends without reported
198    /// usage (a reported body, or a stream line carrying usage) publishes nothing
199    /// unless it fails.
200    fn usage_required(&self) {}
201    /// Go returned before creating its usage reporter (Claude's `responses/compact`
202    /// 501): this attempt publishes no record at all, whatever its outcome.
203    fn discard(&self) {}
204    /// The attempt's upstream exchange reached `stage` now. Not in Go: cliproxy-rs adds
205    /// these timings and sizes to the usage record.
206    fn upstream_stage(&self, stage: UpstreamStage) {
207        let _ = stage;
208    }
209}
210
211/// A stage of one upstream exchange, as the shared HTTP client sees it
212/// (`cpa_exec::proxy::send_routed`). A redirect sends the request again: `Started`
213/// comes once, `Hop`, `Connected` and `BodySent` for each hop, the rest for the final
214/// response.
215#[derive(Debug, Clone, Copy, PartialEq, Eq)]
216pub enum UpstreamStage {
217    /// The exchange is about to send its first request.
218    Started,
219    /// Hop `hop` (0 for the request, then one per redirect followed) is about to be
220    /// sent, with a request body when `body`: what an earlier hop measured no longer
221    /// applies. `Connected` and `BodySent` name their hop, because the client may still
222    /// take an earlier hop's body after its redirect arrived.
223    Hop { hop: u32, body: bool },
224    /// The client has a connection, new or pooled, and has started writing the
225    /// request: it asked for the body for the first time. `Connected` and `BodySent`
226    /// come only from a hop that speaks HTTP/1.1 and sends a body.
227    Connected { hop: u32 },
228    /// The client took the last of the request body, `bytes` in all, into its write
229    /// buffer. Handed to the transport is not acknowledged by the peer: the client's
230    /// own buffer (it takes another 64 KiB piece while it holds less than 408 KiB, so
231    /// under 472 KiB) and the kernel's socket buffer may still hold the end of the body,
232    /// and nothing here learns when the peer received it.
233    BodySent { hop: u32, bytes: u64 },
234    /// The final response head arrived. `dialled`: a connection was dialled while the
235    /// request waited for one. The client may still have sent it on a pooled connection
236    /// that came free first, so only `false` says which connection served it: a pooled
237    /// one.
238    Headers { dialled: bool },
239    /// The first response body bytes arrived.
240    FirstByte,
241    /// The response body ended or was dropped after `bytes`, as received (before any
242    /// content decoding).
243    BodyRead { bytes: u64 },
244}
245
246/// A handle executors report usage through; cloning shares the observer.
247#[derive(Clone, Default)]
248pub struct UsageSink(
249    Option<std::sync::Arc<dyn UsageObserver>>,
250    CaptureSink,
251    Option<std::sync::Arc<dyn WebSocketObserver>>,
252);
253
254/// Receives the upstream WebSocket frames Go's executors pass to
255/// `helps.EmitWebSocketResponseEvent` (the Codex and xAI WebSockets).
256pub trait WebSocketObserver: Send + Sync {
257    /// One non-empty upstream frame as the executor read it, on `credential` for the
258    /// upstream `model`; `provider` is the executor identifier. The executor awaits the
259    /// returned future before it handles the frame, as Go calls the observer inside its
260    /// read loop.
261    fn response<'a>(
262        &'a self,
263        provider: &'a str,
264        credential: &'a crate::credential::Credential,
265        model: &'a str,
266        payload: &'a [u8],
267    ) -> futures_util::future::BoxFuture<'a, ()>;
268}
269
270/// No payloads or credentials: keyed fingerprints and serialized byte lengths only.
271/// Replay estimates token positions offline from returned aggregate usage.
272#[derive(Debug, Clone, Default, serde::Serialize)]
273pub struct CacheFingerprint {
274    pub hash: String,
275    pub bytes: usize,
276}
277
278#[derive(Debug, Clone, serde::Serialize)]
279pub struct CacheBreakpoint {
280    pub path: String,
281    pub ttl: String,
282    pub prefix: CacheFingerprint,
283    /// Earlier boundaries within 20 lookup positions including this breakpoint;
284    /// consecutive tool_use/tool_result blocks share a position.
285    pub lookback: Vec<CacheFingerprint>,
286}
287
288#[derive(Debug, Clone, Default, serde::Serialize)]
289pub struct ClaudeCacheTelemetry {
290    pub schema_version: u8,
291    pub media_present: bool,
292    pub session_hash: String,
293    pub account_hash: String,
294    pub scope_hash: String,
295    pub model: String,
296    pub thinking_type: String,
297    pub thinking_budget: Option<i64>,
298    pub thinking_hash: String,
299    pub effort: String,
300    pub betas: Vec<String>,
301    pub speed: String,
302    pub service_tier: String,
303    pub request_type: String,
304    pub base_request_type: String,
305    pub attempt: usize,
306    pub tools: CacheFingerprint,
307    pub system: CacheFingerprint,
308    pub history_prefix: CacheFingerprint,
309    pub automatic_cache_ttl: Option<String>,
310    pub breakpoints: Vec<CacheBreakpoint>,
311    pub request_start_unix_ms: Option<i64>,
312    pub first_response_byte_unix_ms: Option<i64>,
313    pub end_unix_ms: Option<i64>,
314}
315
316impl UsageSink {
317    pub fn new(observer: std::sync::Arc<dyn UsageObserver>) -> Self {
318        Self(Some(observer), CaptureSink::default(), None)
319    }
320
321    /// Attach the attempt's WebSocket response observer.
322    pub fn with_websocket(mut self, observer: Option<std::sync::Arc<dyn WebSocketObserver>>) -> Self {
323        self.2 = observer;
324        self
325    }
326
327    /// The attached WebSocket response observer, if any.
328    pub fn websocket(&self) -> Option<std::sync::Arc<dyn WebSocketObserver>> {
329        self.2.clone()
330    }
331
332    /// Attach request capture without changing ExecRequest construction sites.
333    pub fn with_capture(mut self, capture: CaptureSink) -> Self {
334        self.1 = capture;
335        self
336    }
337
338    /// Whether anyone listens; executors can skip the work otherwise.
339    pub fn enabled(&self) -> bool {
340        self.0.is_some()
341    }
342
343    pub fn wants_claude_cache(&self) -> bool {
344        self.0.as_ref().is_some_and(|o| o.wants_claude_cache())
345    }
346
347    pub fn claude_cache(&self, telemetry: ClaudeCacheTelemetry) {
348        if let Some(o) = &self.0 {
349            o.claude_cache(telemetry);
350        }
351    }
352
353    pub fn response_body(&self, format: Format, body: &[u8]) {
354        if let Some(o) = &self.0 {
355            o.response_body(format, body);
356        }
357    }
358
359    pub fn response_line(&self, format: Format, line: &[u8]) {
360        if let Some(o) = &self.0 {
361            o.response_line(format, line);
362        }
363    }
364
365    /// [`UsageObserver::response_usage_line`].
366    pub fn response_usage_line(&self, format: Format, line: &[u8]) {
367        if let Some(o) = &self.0 {
368            o.response_usage_line(format, line);
369        }
370    }
371
372    pub fn request(&self, format: Format, payload: &[u8]) {
373        if let Some(o) = &self.0 {
374            o.request(format, payload);
375        }
376    }
377
378    pub fn plugin_executor(&self, provider: &str) {
379        if let Some(o) = &self.0 {
380            o.plugin_executor(provider);
381        }
382    }
383
384    pub fn delegated_executor(&self, executor_type: &str, model: &str) {
385        if let Some(o) = &self.0 {
386            o.delegated_executor(executor_type, model);
387        }
388    }
389
390    pub fn plugin_response_body(&self, protocol: &str, body: &[u8]) {
391        if let Some(o) = &self.0 {
392            o.plugin_response_body(protocol, body);
393        }
394    }
395
396    pub fn plugin_response_line(&self, protocol: &str, line: &[u8]) {
397        if let Some(o) = &self.0 {
398            o.plugin_response_line(protocol, line);
399        }
400    }
401
402    pub fn publish_failure_with_usage(&self, status: u16, body: &str) {
403        if let Some(o) = &self.0 {
404            o.publish_failure_with_usage(status, body);
405        }
406    }
407
408    pub fn request_for(&self, identifier: &str, payload: &[u8]) {
409        if let Some(o) = &self.0 {
410            o.request_for(identifier, payload);
411        }
412    }
413
414    pub fn upstream_model(&self, model: &str) {
415        if let Some(o) = &self.0 {
416            o.upstream_model(model);
417        }
418    }
419
420    pub fn response_model(&self, model: &str) {
421        if let Some(o) = &self.0 {
422            o.response_model(model);
423        }
424    }
425
426    /// [`UsageObserver::response_model_line`].
427    pub fn response_model_line(&self, line: &[u8]) {
428        if let Some(o) = &self.0 {
429            o.response_model_line(line);
430        }
431    }
432
433    pub fn round_trip_started(&self) {
434        if let Some(o) = &self.0 {
435            o.round_trip_started();
436        }
437    }
438
439    pub fn first_byte(&self) {
440        if let Some(o) = &self.0 {
441            o.first_byte();
442        }
443    }
444
445    pub fn token_event(&self, is_token: bool) {
446        if let Some(o) = &self.0 {
447            o.token_event(is_token);
448        }
449    }
450
451    pub fn publish(&self) {
452        if let Some(o) = &self.0 {
453            o.publish();
454        }
455    }
456
457    pub fn publish_failure(&self, status: u16, body: &str) {
458        if let Some(o) = &self.0 {
459            o.publish_failure(status, body);
460        }
461    }
462
463    pub fn usage_required(&self) {
464        if let Some(o) = &self.0 {
465            o.usage_required();
466        }
467    }
468
469    /// See [`UsageObserver::discard`].
470    pub fn discard(&self) {
471        if let Some(o) = &self.0 {
472            o.discard();
473        }
474    }
475
476    /// See [`UsageObserver::upstream_stage`].
477    pub fn upstream_stage(&self, stage: UpstreamStage) {
478        if let Some(o) = &self.0 {
479            o.upstream_stage(stage);
480        }
481    }
482}
483
484impl fmt::Debug for UsageSink {
485    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
486        f.debug_tuple("UsageSink").field(&self.enabled()).finish()
487    }
488}
489
490impl ExecRequest {
491    /// Optional per-call wire capture, independent of usage accounting. Capture
492    /// the handle before spawning a stream task; clones retain the same observer.
493    pub fn capture(&self) -> &CaptureSink {
494        &self.usage.1
495    }
496
497    /// The attempt's WebSocket response observer bound to the executor `provider`, the
498    /// selected credential and this request's upstream model; `None` without one.
499    pub fn websocket_emitter(
500        &self,
501        provider: &'static str,
502        credential: &crate::credential::Credential,
503    ) -> Option<WebSocketEmitter> {
504        self.usage.2.clone().map(|observer| WebSocketEmitter {
505            observer,
506            provider,
507            credential: std::sync::Arc::new(credential.clone()),
508            model: self.model.clone(),
509        })
510    }
511}
512
513/// Go `helps.EmitWebSocketResponseEvent` for one attempt.
514#[derive(Clone)]
515pub struct WebSocketEmitter {
516    observer: std::sync::Arc<dyn WebSocketObserver>,
517    provider: &'static str,
518    credential: std::sync::Arc<crate::credential::Credential>,
519    model: String,
520}
521
522impl WebSocketEmitter {
523    /// One upstream frame, delivered before the executor goes on; empty frames are not
524    /// reported, as in Go.
525    pub async fn emit(&self, payload: &[u8]) {
526        if !payload.is_empty() {
527            self.observer
528                .response(self.provider, &self.credential, &self.model, payload)
529                .await;
530        }
531    }
532}
533
534/// Go helps.UpstreamRequestLog. Credentials and bodies intentionally have no
535/// Debug implementation. The observer owns Go's masking and formatting policy.
536#[derive(Default)]
537pub struct UpstreamRequest<'a> {
538    pub url: &'a str,
539    pub method: &'a str,
540    pub headers: &'a [(String, String)],
541    pub body: &'a [u8],
542    pub provider: &'a str,
543    pub auth_id: &'a str,
544    pub auth_label: &'a str,
545    pub auth_type: &'a str,
546    pub auth_value: &'a str,
547}
548
549pub enum CaptureEvent<'a> {
550    Request(UpstreamRequest<'a>),
551    ResponseMetadata(u16, &'a [(String, String)]),
552    ResponseError(&'a str),
553    ResponseChunk(&'a [u8]),
554    WebsocketRequest(UpstreamRequest<'a>),
555    WebsocketHandshake(u16, &'a [(String, String)]),
556    WebsocketResponse(&'a [u8]),
557    WebsocketError { stage: &'a str, error: &'a str },
558}
559
560pub trait CaptureObserver: Send + Sync {
561    fn record(&self, event: CaptureEvent<'_>);
562    /// [`CaptureEvent::Request`] for a body the caller already holds as [`Bytes`]: an
563    /// observer that keeps the body may keep this handle instead of a copy of it.
564    fn record_request(&self, info: UpstreamRequest<'_>, body: &Bytes) {
565        self.record(CaptureEvent::Request(UpstreamRequest {
566            body: &body[..],
567            ..info
568        }));
569    }
570    /// Whether response events are kept right now (Go's `requestLogCaptureEnabled`).
571    /// An observer that drops them while logging is off says so, so executors need not
572    /// buffer data that exists only to be logged.
573    fn logs_responses(&self) -> bool {
574        true
575    }
576}
577
578/// Default no-op; providers call this at Go's logging_helpers call sites.
579#[derive(Clone, Default)]
580pub struct CaptureSink(Option<std::sync::Arc<dyn CaptureObserver>>);
581
582impl CaptureSink {
583    pub fn new(observer: std::sync::Arc<dyn CaptureObserver>) -> Self {
584        Self(Some(observer))
585    }
586    pub fn enabled(&self) -> bool {
587        self.0.is_some()
588    }
589    /// Whether response chunks reach a log now: an observer is attached and keeps them.
590    pub fn logs_responses(&self) -> bool {
591        self.0.as_ref().is_some_and(|observer| observer.logs_responses())
592    }
593    pub fn record(&self, event: CaptureEvent<'_>) {
594        if let Some(observer) = &self.0 {
595            observer.record(event);
596        }
597    }
598    /// [`CaptureObserver::record_request`].
599    pub fn record_request(&self, info: UpstreamRequest<'_>, body: &Bytes) {
600        if let Some(observer) = &self.0 {
601            observer.record_request(info, body);
602        }
603    }
604}
605
606/// Capabilities bound to one execution attempt (Go `*registry.ModelInfo` stored under a
607/// request metadata key).
608#[derive(Debug, Clone)]
609pub struct ResolvedModel {
610    /// Go's `modelconfig.ResolveModelInfo` snapshot for configured API-key models (the
611    /// static definition of the suffix-free upstream name, renamed to it, typed for the
612    /// provider, configured thinking normalized, never user-defined), or the static
613    /// Codex plan catalog entry for Codex OAuth. `info.raw` carries `is_compat` and
614    /// `support_configuration_update` when set; `info.is_compat()` is Go's
615    /// `helps.APIKeyModelIsCompat`.
616    pub info: crate::registry::ModelInfo,
617    pub source: ResolvedSource,
618}
619
620impl ResolvedModel {
621    /// Go `ModelInfo.IsCompat` of the bound model (`helps.APIKeyModelIsCompat`).
622    pub fn is_compat(&self) -> bool {
623        self.info.is_compat()
624    }
625}
626
627/// Which request metadata key Go stores the binding under. Go's `ResolvedModelInfo`
628/// reads either; `ResolvedAPIKeyModelInfo` reads only [`ResolvedSource::ApiKey`].
629#[derive(Debug, Clone, Copy, PartialEq, Eq)]
630pub enum ResolvedSource {
631    /// `cliproxy.resolved_api_key_model_info`: a configured API-key model (any
632    /// family, OpenAI compatibility included) or an unlisted Codex API-key model.
633    ApiKey,
634    /// `cliproxy.resolved_codex_oauth_model_info`: a Codex OAuth credential's plan
635    /// catalog model.
636    CodexOAuth,
637    /// `cliproxy.resolved_home_model_info`: Home's definition of the model it
638    /// dispatched (Go `attachResolvedHomeModelInfo`); Go's `ResolvedModelInfo` reads it
639    /// before the other two.
640    Home,
641}
642
643impl fmt::Debug for ExecRequest {
644    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
645        f.debug_struct("ExecRequest")
646            .field("operation", &self.operation)
647            .field("source_format", &self.source_format)
648            .field("response_format", &self.response_format)
649            .field("model", &self.model)
650            .field("stream", &self.stream)
651            .field("alt", &self.alt)
652            .field("execution_session", &self.execution_session)
653            .field("derived_session", &self.derived_session)
654            .field("request_path", &self.request_path)
655            .field(
656                "resolved_model",
657                &self.resolved_model.as_ref().map(|r| (&r.info.id, r.source)),
658            )
659            .field("body_len", &self.body.len())
660            .finish_non_exhaustive()
661    }
662}
663
664/// One framed unit of a streaming response (for SSE: one complete event).
665/// An `Err` item is terminal: consumers stop polling after it.
666pub type ExecStream = BoxStream<'static, Result<Bytes, ExecError>>;
667
668pub enum ResponseBody {
669    Buffered(Bytes),
670    Stream(ExecStream),
671}
672
673pub struct ExecResponse {
674    pub status: u16,
675    /// Upstream headers. The server decides which, if any, reach the client.
676    pub headers: HeaderMap,
677    pub body: ResponseBody,
678}
679
680/// What a failure says about the attempt, for retry and cooldown decisions.
681#[derive(Debug, Clone, Copy, PartialEq, Eq)]
682pub enum FailureScope {
683    /// The request itself is bad; retrying with another credential will not help.
684    Request,
685    /// This credential cannot serve this model right now.
686    Model,
687    /// This credential is unusable right now (auth, quota, upstream fault).
688    Credential,
689    /// Connection/transport lifecycle fault: may fail over, must not cool credentials.
690    Transport,
691}
692
693#[derive(Debug, Clone)]
694pub struct ExecError {
695    pub status: u16,
696    pub scope: FailureScope,
697    /// Upstream error body (bounded), or a message for locally generated errors.
698    pub body: Bytes,
699    /// Upstream response headers, for the scheduler and passthrough policy. The server
700    /// never emits these by default. Boxed: errors are the cold path.
701    pub headers: Box<HeaderMap>,
702    /// Scheduler hint parsed from upstream. Not permission to send `Retry-After` downstream.
703    pub retry_after: Option<Duration>,
704    /// Send status, body and filtered headers to the client unchanged instead of the
705    /// route's normal error shape (claude_executor_fast_error.go).
706    pub direct: bool,
707    /// Headers this error hands the client under `requests.passthrough-headers` (Go
708    /// `ErrorMessage.Addon`, filled only from errors with `Headers()`: Codex and xAI
709    /// WebSocket error frames and stream bootstrap failures). `headers` stays the
710    /// classification copy and is never sent, except as a `direct` response's headers.
711    pub addon: Option<Box<HeaderMap>>,
712}
713
714impl ExecError {
715    pub fn local(status: u16, scope: FailureScope, message: impl Into<String>) -> Self {
716        Self {
717            status,
718            scope,
719            body: Bytes::from(message.into()),
720            headers: Box::default(),
721            retry_after: None,
722            direct: false,
723            addon: None,
724        }
725    }
726}
727
728impl fmt::Display for ExecError {
729    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
730        write!(
731            f,
732            "{} ({:?}): {}",
733            self.status,
734            self.scope,
735            String::from_utf8_lossy(&self.body)
736        )
737    }
738}
739
740impl std::error::Error for ExecError {}
741
742/// A long-lived downstream connection (the Responses WebSocket, `GET /v1/responses`)
743/// whose turns can share upstream state. It travels next to an [`ExecRequest`] in
744/// `cpa_exec::Executors::execute_in_session`. Executors that pool upstream sockets key
745/// them by `id` and release them in `Executors::close_session` when the downstream
746/// connection ends (Go: execution session id and `CloseExecutionSession`).
747#[derive(Debug, Clone, PartialEq, Eq)]
748pub struct ExecSession {
749    /// Stable for the whole downstream connection.
750    pub id: String,
751    /// This turn continues upstream state (`previous_response_id` or `response.append`
752    /// passed through unchanged), so it must run on the session's current upstream socket.
753    /// An executor that cannot honour that fails with [`ExecError::replay_required`]
754    /// instead of opening a fresh connection (Go: `RequiredUpstreamWebsocket`).
755    pub continuation: bool,
756    /// The Home pick this attempt runs on, when it came from Home (Go
757    /// `Options.ExecutionLifecycle`). An executor that pools the upstream socket hands
758    /// the pick to it; the pick then lasts as long as the socket.
759    pub lease: Option<SessionLease>,
760}
761
762/// A Home pick a pooled upstream socket can keep beyond the turn (Go
763/// `ExecutionLifecycle` with `Retain`).
764pub trait Retainable: Send + Sync {
765    /// Go `Bind` + `Retain`: the socket takes the pick over. Home draining the pick runs
766    /// `close` once, before the pick is released. False when the pick already ended; the
767    /// socket must not be kept then.
768    fn retain(&self, close: Box<dyn FnOnce() + Send>) -> bool;
769    /// Go `End`: the socket that kept the pick was invalidated, replaced or closed.
770    fn end(&self);
771}
772
773/// A shared [`Retainable`], compared by identity.
774#[derive(Clone)]
775pub struct SessionLease(pub std::sync::Arc<dyn Retainable>);
776
777impl SessionLease {
778    pub fn same(&self, other: &SessionLease) -> bool {
779        std::sync::Arc::ptr_eq(&self.0, &other.0)
780    }
781}
782
783impl PartialEq for SessionLease {
784    fn eq(&self, other: &Self) -> bool {
785        self.same(other)
786    }
787}
788
789impl Eq for SessionLease {}
790
791impl fmt::Debug for SessionLease {
792    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
793        f.write_str("SessionLease")
794    }
795}
796
797impl ExecError {
798    /// Body of the replay signal (Go `UpstreamWebsocketReplayRequiredError`).
799    pub const REPLAY_REQUIRED: &'static str = r#"{"error":{"message":"upstream transport requires full HTTP replay","type":"server_error","code":"upstream_http_replay_required","status":426}}"#;
800
801    /// A continuation turn lost its upstream socket: the client must resend the full
802    /// conversation. Request-scoped: no credential is at fault.
803    pub fn replay_required() -> Self {
804        Self::local(426, FailureScope::Request, Self::REPLAY_REQUIRED)
805    }
806
807    pub fn is_replay_required(&self) -> bool {
808        self.status == 426
809            && self.scope == FailureScope::Request
810            && self.body.as_ref() == Self::REPLAY_REQUIRED.as_bytes()
811    }
812}