use std::fmt;
use std::time::Duration;
use bytes::Bytes;
use futures_util::stream::BoxStream;
use http::HeaderMap;
use crate::format::Format;
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Operation {
Generate,
CountTokens,
}
#[derive(Clone, PartialEq, Eq)]
pub struct Caller {
pub principal: String,
pub source: &'static str,
pub provider: String,
}
impl fmt::Debug for Caller {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
f.debug_struct("Caller")
.field("source", &self.source)
.finish_non_exhaustive()
}
}
#[derive(Clone)]
pub struct ExecRequest {
pub operation: Operation,
pub source_format: Format,
pub response_format: Format,
pub requested_model: String,
pub model: String,
pub original_body: Bytes,
pub body: Bytes,
pub stream: bool,
pub stream_payloads: bool,
pub alt: Option<String>,
pub session: Option<String>,
pub execution_session: Option<String>,
pub derived_session: Option<String>,
pub request_path: String,
pub headers: HeaderMap,
pub caller: Caller,
pub resolved_model: Option<ResolvedModel>,
pub usage: UsageSink,
}
pub trait UsageObserver: Send + Sync {
fn wants_claude_cache(&self) -> bool {
false
}
fn claude_cache(&self, telemetry: ClaudeCacheTelemetry) {
let _ = telemetry;
}
fn response_body(&self, format: Format, body: &[u8]);
fn response_line(&self, format: Format, line: &[u8]);
fn response_usage_line(&self, format: Format, line: &[u8]) {
let _ = (format, line);
}
fn request(&self, format: Format, payload: &[u8]);
fn plugin_executor(&self, provider: &str) {
let _ = provider;
}
fn delegated_executor(&self, executor_type: &str, model: &str) {
let _ = (executor_type, model);
}
fn plugin_response_body(&self, protocol: &str, body: &[u8]) {
let _ = (protocol, body);
}
fn plugin_response_line(&self, protocol: &str, line: &[u8]) {
let _ = (protocol, line);
}
fn request_for(&self, identifier: &str, payload: &[u8]) {
let _ = (identifier, payload);
}
fn upstream_model(&self, model: &str) {
let _ = model;
}
fn response_model(&self, model: &str) {
let _ = model;
}
fn response_model_line(&self, line: &[u8]) {
let _ = line;
}
fn round_trip_started(&self) {}
fn first_byte(&self) {}
fn token_event(&self, is_token: bool) {
let _ = is_token;
}
fn publish(&self) {}
fn publish_failure(&self, status: u16, body: &str) {
let _ = (status, body);
}
fn publish_failure_with_usage(&self, status: u16, body: &str) {
let _ = (status, body);
}
fn usage_required(&self) {}
fn discard(&self) {}
fn upstream_stage(&self, stage: UpstreamStage) {
let _ = stage;
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum UpstreamStage {
Started,
Hop { hop: u32, body: bool },
Connected { hop: u32 },
BodySent { hop: u32, bytes: u64 },
Headers { dialled: bool },
FirstByte,
BodyRead { bytes: u64 },
}
#[derive(Clone, Default)]
pub struct UsageSink(
Option<std::sync::Arc<dyn UsageObserver>>,
CaptureSink,
Option<std::sync::Arc<dyn WebSocketObserver>>,
);
pub trait WebSocketObserver: Send + Sync {
fn response<'a>(
&'a self,
provider: &'a str,
credential: &'a crate::credential::Credential,
model: &'a str,
payload: &'a [u8],
) -> futures_util::future::BoxFuture<'a, ()>;
}
#[derive(Debug, Clone, Default, serde::Serialize)]
pub struct CacheFingerprint {
pub hash: String,
pub bytes: usize,
}
#[derive(Debug, Clone, serde::Serialize)]
pub struct CacheBreakpoint {
pub path: String,
pub ttl: String,
pub prefix: CacheFingerprint,
pub lookback: Vec<CacheFingerprint>,
}
#[derive(Debug, Clone, Default, serde::Serialize)]
pub struct ClaudeCacheTelemetry {
pub schema_version: u8,
pub media_present: bool,
pub session_hash: String,
pub account_hash: String,
pub scope_hash: String,
pub model: String,
pub thinking_type: String,
pub thinking_budget: Option<i64>,
pub thinking_hash: String,
pub effort: String,
pub betas: Vec<String>,
pub speed: String,
pub service_tier: String,
pub request_type: String,
pub base_request_type: String,
pub attempt: usize,
pub tools: CacheFingerprint,
pub system: CacheFingerprint,
pub history_prefix: CacheFingerprint,
pub automatic_cache_ttl: Option<String>,
pub breakpoints: Vec<CacheBreakpoint>,
pub request_start_unix_ms: Option<i64>,
pub first_response_byte_unix_ms: Option<i64>,
pub end_unix_ms: Option<i64>,
}
impl UsageSink {
pub fn new(observer: std::sync::Arc<dyn UsageObserver>) -> Self {
Self(Some(observer), CaptureSink::default(), None)
}
pub fn with_websocket(mut self, observer: Option<std::sync::Arc<dyn WebSocketObserver>>) -> Self {
self.2 = observer;
self
}
pub fn websocket(&self) -> Option<std::sync::Arc<dyn WebSocketObserver>> {
self.2.clone()
}
pub fn with_capture(mut self, capture: CaptureSink) -> Self {
self.1 = capture;
self
}
pub fn enabled(&self) -> bool {
self.0.is_some()
}
pub fn wants_claude_cache(&self) -> bool {
self.0.as_ref().is_some_and(|o| o.wants_claude_cache())
}
pub fn claude_cache(&self, telemetry: ClaudeCacheTelemetry) {
if let Some(o) = &self.0 {
o.claude_cache(telemetry);
}
}
pub fn response_body(&self, format: Format, body: &[u8]) {
if let Some(o) = &self.0 {
o.response_body(format, body);
}
}
pub fn response_line(&self, format: Format, line: &[u8]) {
if let Some(o) = &self.0 {
o.response_line(format, line);
}
}
pub fn response_usage_line(&self, format: Format, line: &[u8]) {
if let Some(o) = &self.0 {
o.response_usage_line(format, line);
}
}
pub fn request(&self, format: Format, payload: &[u8]) {
if let Some(o) = &self.0 {
o.request(format, payload);
}
}
pub fn plugin_executor(&self, provider: &str) {
if let Some(o) = &self.0 {
o.plugin_executor(provider);
}
}
pub fn delegated_executor(&self, executor_type: &str, model: &str) {
if let Some(o) = &self.0 {
o.delegated_executor(executor_type, model);
}
}
pub fn plugin_response_body(&self, protocol: &str, body: &[u8]) {
if let Some(o) = &self.0 {
o.plugin_response_body(protocol, body);
}
}
pub fn plugin_response_line(&self, protocol: &str, line: &[u8]) {
if let Some(o) = &self.0 {
o.plugin_response_line(protocol, line);
}
}
pub fn publish_failure_with_usage(&self, status: u16, body: &str) {
if let Some(o) = &self.0 {
o.publish_failure_with_usage(status, body);
}
}
pub fn request_for(&self, identifier: &str, payload: &[u8]) {
if let Some(o) = &self.0 {
o.request_for(identifier, payload);
}
}
pub fn upstream_model(&self, model: &str) {
if let Some(o) = &self.0 {
o.upstream_model(model);
}
}
pub fn response_model(&self, model: &str) {
if let Some(o) = &self.0 {
o.response_model(model);
}
}
pub fn response_model_line(&self, line: &[u8]) {
if let Some(o) = &self.0 {
o.response_model_line(line);
}
}
pub fn round_trip_started(&self) {
if let Some(o) = &self.0 {
o.round_trip_started();
}
}
pub fn first_byte(&self) {
if let Some(o) = &self.0 {
o.first_byte();
}
}
pub fn token_event(&self, is_token: bool) {
if let Some(o) = &self.0 {
o.token_event(is_token);
}
}
pub fn publish(&self) {
if let Some(o) = &self.0 {
o.publish();
}
}
pub fn publish_failure(&self, status: u16, body: &str) {
if let Some(o) = &self.0 {
o.publish_failure(status, body);
}
}
pub fn usage_required(&self) {
if let Some(o) = &self.0 {
o.usage_required();
}
}
pub fn discard(&self) {
if let Some(o) = &self.0 {
o.discard();
}
}
pub fn upstream_stage(&self, stage: UpstreamStage) {
if let Some(o) = &self.0 {
o.upstream_stage(stage);
}
}
}
impl fmt::Debug for UsageSink {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
f.debug_tuple("UsageSink").field(&self.enabled()).finish()
}
}
impl ExecRequest {
pub fn capture(&self) -> &CaptureSink {
&self.usage.1
}
pub fn websocket_emitter(
&self,
provider: &'static str,
credential: &crate::credential::Credential,
) -> Option<WebSocketEmitter> {
self.usage.2.clone().map(|observer| WebSocketEmitter {
observer,
provider,
credential: std::sync::Arc::new(credential.clone()),
model: self.model.clone(),
})
}
}
#[derive(Clone)]
pub struct WebSocketEmitter {
observer: std::sync::Arc<dyn WebSocketObserver>,
provider: &'static str,
credential: std::sync::Arc<crate::credential::Credential>,
model: String,
}
impl WebSocketEmitter {
pub async fn emit(&self, payload: &[u8]) {
if !payload.is_empty() {
self.observer
.response(self.provider, &self.credential, &self.model, payload)
.await;
}
}
}
#[derive(Default)]
pub struct UpstreamRequest<'a> {
pub url: &'a str,
pub method: &'a str,
pub headers: &'a [(String, String)],
pub body: &'a [u8],
pub provider: &'a str,
pub auth_id: &'a str,
pub auth_label: &'a str,
pub auth_type: &'a str,
pub auth_value: &'a str,
}
pub enum CaptureEvent<'a> {
Request(UpstreamRequest<'a>),
ResponseMetadata(u16, &'a [(String, String)]),
ResponseError(&'a str),
ResponseChunk(&'a [u8]),
WebsocketRequest(UpstreamRequest<'a>),
WebsocketHandshake(u16, &'a [(String, String)]),
WebsocketResponse(&'a [u8]),
WebsocketError { stage: &'a str, error: &'a str },
}
pub trait CaptureObserver: Send + Sync {
fn record(&self, event: CaptureEvent<'_>);
fn record_request(&self, info: UpstreamRequest<'_>, body: &Bytes) {
self.record(CaptureEvent::Request(UpstreamRequest {
body: &body[..],
..info
}));
}
fn logs_responses(&self) -> bool {
true
}
}
#[derive(Clone, Default)]
pub struct CaptureSink(Option<std::sync::Arc<dyn CaptureObserver>>);
impl CaptureSink {
pub fn new(observer: std::sync::Arc<dyn CaptureObserver>) -> Self {
Self(Some(observer))
}
pub fn enabled(&self) -> bool {
self.0.is_some()
}
pub fn logs_responses(&self) -> bool {
self.0.as_ref().is_some_and(|observer| observer.logs_responses())
}
pub fn record(&self, event: CaptureEvent<'_>) {
if let Some(observer) = &self.0 {
observer.record(event);
}
}
pub fn record_request(&self, info: UpstreamRequest<'_>, body: &Bytes) {
if let Some(observer) = &self.0 {
observer.record_request(info, body);
}
}
}
#[derive(Debug, Clone)]
pub struct ResolvedModel {
pub info: crate::registry::ModelInfo,
pub source: ResolvedSource,
}
impl ResolvedModel {
pub fn is_compat(&self) -> bool {
self.info.is_compat()
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ResolvedSource {
ApiKey,
CodexOAuth,
Home,
}
impl fmt::Debug for ExecRequest {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
f.debug_struct("ExecRequest")
.field("operation", &self.operation)
.field("source_format", &self.source_format)
.field("response_format", &self.response_format)
.field("model", &self.model)
.field("stream", &self.stream)
.field("alt", &self.alt)
.field("execution_session", &self.execution_session)
.field("derived_session", &self.derived_session)
.field("request_path", &self.request_path)
.field(
"resolved_model",
&self.resolved_model.as_ref().map(|r| (&r.info.id, r.source)),
)
.field("body_len", &self.body.len())
.finish_non_exhaustive()
}
}
pub type ExecStream = BoxStream<'static, Result<Bytes, ExecError>>;
pub enum ResponseBody {
Buffered(Bytes),
Stream(ExecStream),
}
pub struct ExecResponse {
pub status: u16,
pub headers: HeaderMap,
pub body: ResponseBody,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum FailureScope {
Request,
Model,
Credential,
Transport,
}
#[derive(Debug, Clone)]
pub struct ExecError {
pub status: u16,
pub scope: FailureScope,
pub body: Bytes,
pub headers: Box<HeaderMap>,
pub retry_after: Option<Duration>,
pub direct: bool,
pub addon: Option<Box<HeaderMap>>,
}
impl ExecError {
pub fn local(status: u16, scope: FailureScope, message: impl Into<String>) -> Self {
Self {
status,
scope,
body: Bytes::from(message.into()),
headers: Box::default(),
retry_after: None,
direct: false,
addon: None,
}
}
}
impl fmt::Display for ExecError {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
write!(
f,
"{} ({:?}): {}",
self.status,
self.scope,
String::from_utf8_lossy(&self.body)
)
}
}
impl std::error::Error for ExecError {}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ExecSession {
pub id: String,
pub continuation: bool,
pub lease: Option<SessionLease>,
}
pub trait Retainable: Send + Sync {
fn retain(&self, close: Box<dyn FnOnce() + Send>) -> bool;
fn end(&self);
}
#[derive(Clone)]
pub struct SessionLease(pub std::sync::Arc<dyn Retainable>);
impl SessionLease {
pub fn same(&self, other: &SessionLease) -> bool {
std::sync::Arc::ptr_eq(&self.0, &other.0)
}
}
impl PartialEq for SessionLease {
fn eq(&self, other: &Self) -> bool {
self.same(other)
}
}
impl Eq for SessionLease {}
impl fmt::Debug for SessionLease {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
f.write_str("SessionLease")
}
}
impl ExecError {
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}}"#;
pub fn replay_required() -> Self {
Self::local(426, FailureScope::Request, Self::REPLAY_REQUIRED)
}
pub fn is_replay_required(&self) -> bool {
self.status == 426
&& self.scope == FailureScope::Request
&& self.body.as_ref() == Self::REPLAY_REQUIRED.as_bytes()
}
}