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}