1use serde::Serialize;
3use std::{error::Error, fmt, sync::Arc, time::Duration};
4use uuid::Uuid;
5
6#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
7#[serde(rename_all = "snake_case")]
8pub enum Provider {
9 Ollama,
10 Omlx,
11 OpenAi,
12}
13impl Provider {
14 pub(crate) fn local(self) -> bool {
15 self != Self::OpenAi
16 }
17}
18#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
19#[serde(rename_all = "snake_case")]
20pub enum Operation {
21 Ordinary,
22 Structured,
23 Streaming,
24}
25#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Serialize)]
26#[serde(rename_all = "snake_case")]
27pub enum Category {
28 Transport,
29 Http,
30 ProviderResponse,
31 Protocol,
32 Cancellation,
33 ClientTimeout,
34}
35#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
36#[serde(rename_all = "snake_case")]
37pub enum Phase {
38 Connecting,
39 Sending,
40 AwaitingHeaders,
41 Streaming,
42 Decoding,
43}
44#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
45#[serde(rename_all = "snake_case")]
46pub enum Acceptance {
47 Yes,
48 No,
49 Unknown,
50}
51#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
52#[serde(rename_all = "snake_case")]
53pub enum Support {
54 Supported,
55 Unsupported,
56 Unknown,
57}
58#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
61pub struct Capabilities {
62 #[serde(skip)]
64 pub request_cancel: Support,
65 pub local_request_cancellation: Support,
67 pub remote_request_cancellation: Support,
69 pub request_status: Support,
71 pub idempotency: Support,
73 pub exact_attempt_termination: Support,
75}
76impl Default for Capabilities {
77 fn default() -> Self {
78 Self {
79 request_cancel: Support::Unsupported,
80 local_request_cancellation: Support::Unknown,
81 remote_request_cancellation: Support::Unsupported,
82 request_status: Support::Unsupported,
83 idempotency: Support::Unknown,
84 exact_attempt_termination: Support::Unknown,
85 }
86 }
87}
88#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize)]
89pub struct SemanticProgress {
90 pub reasoning_bytes: u64,
91 pub content_bytes: u64,
92 pub tool_fragments: u64,
93 pub completed_tool_calls: u64,
94}
95impl SemanticProgress {
96 pub fn any(self) -> bool {
97 self != Self::default()
98 }
99}
100#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize)]
101pub struct Progress {
102 pub headers_received: bool,
103 pub raw_bytes: u64,
104 pub observed: SemanticProgress,
105 pub delivered: SemanticProgress,
106}
107#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
108pub struct Identity {
109 pub logical_request_id: Uuid,
110 pub attempt_id: Uuid,
111 pub wire_attempt: u32,
112}
113#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
114#[serde(rename_all = "snake_case")]
115pub enum RetryAfter {
116 Absent,
117 Invalid,
118 Seconds(u64),
119 Date {
120 unix_seconds: i64,
121 remaining: Duration,
122 },
123}
124impl RetryAfter {
125 pub(crate) fn delay(&self) -> Option<Duration> {
126 match self {
127 Self::Seconds(s) => Some(Duration::from_secs(*s)),
128 Self::Date { remaining, .. } => Some(*remaining),
129 _ => None,
130 }
131 }
132}
133#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
135pub struct ValidatedMetadata(String);
136impl ValidatedMetadata {
137 pub fn as_str(&self) -> &str {
138 &self.0
139 }
140 pub(crate) fn code(value: &str) -> Option<Self> {
141 matches!(
142 value,
143 "rate_limit_exceeded"
144 | "server_error"
145 | "invalid_request_error"
146 | "invalid_api_key"
147 | "model_not_found"
148 | "insufficient_quota"
149 | "overloaded_error"
150 )
151 .then(|| Self(value.into()))
152 }
153 pub(crate) fn request_id(value: &str) -> Option<Self> {
154 Uuid::parse_str(value.strip_prefix("req_").unwrap_or(value))
156 .ok()
157 .map(|_| Self(value.to_owned()))
158 }
159}
160#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
161#[serde(rename_all = "snake_case")]
162pub enum Reason {
163 Transient,
164 Permanent,
165 Malformed,
166 SemanticOutput,
167 PartialResponse,
168 Cancelled,
169 InvalidConfiguration,
170}
171#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
172pub struct Classification {
173 pub eligible: bool,
174 pub reason: Reason,
175}
176#[derive(Clone, Serialize)]
177pub struct Failure {
178 pub provider: Provider,
179 pub operation: Operation,
180 pub category: Category,
181 pub http_status: Option<u16>,
182 pub provider_code: Option<ValidatedMetadata>,
183 pub retry_after: RetryAfter,
184 pub provider_request_id: Option<ValidatedMetadata>,
185 pub phase: Option<Phase>,
186 pub acceptance: Acceptance,
187 pub progress: Progress,
188 pub classification: Classification,
189 pub identity: Option<Identity>,
190 pub remote_termination_confirmed: bool,
192 #[serde(skip)]
193 response_bytes: Arc<[u8]>,
194 #[serde(skip)]
195 response_headers: Option<Arc<reqwest::header::HeaderMap>>,
196 #[serde(skip)]
197 cause: Option<Arc<dyn Error + Send + Sync>>,
198}
199impl Failure {
200 pub fn inspect_cause(&self) -> Option<&(dyn Error + Send + Sync + 'static)> {
202 self.cause.as_deref()
203 }
204 pub fn inspect_response_bytes(&self) -> &[u8] {
205 &self.response_bytes
206 }
207 pub fn inspect_response_headers(&self) -> Option<&reqwest::header::HeaderMap> {
208 self.response_headers.as_deref()
209 }
210 pub(crate) fn set_response_bytes(&mut self, bytes: &[u8]) {
211 self.response_bytes = Arc::from(bytes);
212 }
213 pub(crate) fn set_response_headers(&mut self, headers: &reqwest::header::HeaderMap) {
214 self.response_headers = Some(Arc::new(headers.clone()));
215 }
216 pub(crate) fn with_boxed_cause(mut self, cause: Box<dyn Error + Send + Sync>) -> Self {
217 self.cause = Some(Arc::from(cause));
218 self
219 }
220 pub(crate) fn with_cause(mut self, cause: impl Error + Send + Sync + 'static) -> Self {
221 self.cause = Some(Arc::new(cause));
222 self
223 }
224 pub(crate) fn new(provider: Provider, operation: Operation, category: Category) -> Self {
225 Self {
226 provider,
227 operation,
228 category,
229 http_status: None,
230 provider_code: None,
231 retry_after: RetryAfter::Absent,
232 provider_request_id: None,
233 phase: None,
234 acceptance: Acceptance::Unknown,
235 progress: Progress::default(),
236 classification: Classification {
237 eligible: false,
238 reason: Reason::Permanent,
239 },
240 identity: None,
241 remote_termination_confirmed: false,
242 response_bytes: Arc::from([]),
243 response_headers: None,
244 cause: None,
245 }
246 }
247}
248impl fmt::Debug for Failure {
249 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
250 f.debug_struct("Failure")
251 .field("provider", &self.provider)
252 .field("operation", &self.operation)
253 .field("category", &self.category)
254 .field("http_status", &self.http_status)
255 .field("classification", &self.classification)
256 .field("identity", &self.identity)
257 .field("progress", &self.progress)
258 .finish()
259 }
260}
261#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
262#[serde(rename_all = "snake_case")]
263pub enum Outcome {
264 Failed,
265 Exhausted,
266 Interrupted,
267 Cancelled,
268 AdmissionRequired,
269 AdmissionRejected,
270 AdmissionUnresolved,
271 DelayCeiling,
272 BudgetExpired,
273 ObserverFailed,
274}
275#[derive(Clone, Serialize)]
276pub struct RecoveryError {
277 #[serde(skip_serializing)]
280 pub stream_metrics: Option<Box<crate::llm::gateway::StreamMetrics>>,
281 pub outcome: Outcome,
282 pub failure: Box<Failure>,
283 pub history: Vec<Failure>,
284}
285impl fmt::Debug for RecoveryError {
286 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
287 f.debug_struct("RecoveryError")
288 .field("outcome", &self.outcome)
289 .field("failure", &self.failure)
290 .field("history", &self.history)
291 .finish()
292 }
293}
294
295impl fmt::Display for RecoveryError {
296 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
297 write!(
298 f,
299 "completion recovery {:?}: {:?} ({:?}, HTTP {:?})",
300 self.outcome,
301 self.failure.classification.reason,
302 self.failure.provider,
303 self.failure.http_status
304 )
305 }
306}
307impl Error for RecoveryError {}
308#[derive(Clone, Serialize)]
309pub struct RecoveryReport {
310 #[serde(skip_serializing)]
313 pub stream_metrics: Option<Box<crate::llm::gateway::StreamMetrics>>,
314 pub identity: Identity,
315 pub progress: Progress,
316 pub history: Vec<Failure>,
317}
318impl fmt::Debug for RecoveryReport {
319 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
320 f.debug_struct("RecoveryReport")
321 .field("identity", &self.identity)
322 .field("progress", &self.progress)
323 .field("history", &self.history)
324 .finish()
325 }
326}
327
328pub struct Recovered<T> {
330 pub value: T,
331 pub report: RecoveryReport,
332}
333#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
334#[serde(rename_all = "snake_case")]
335pub enum Transition {
336 AttemptStarted,
337 AttemptSucceeded,
338 AttemptFailed,
339 AdmissionPending,
340 AdmissionAllowed,
341 AdmissionRejected,
342 AdmissionUnresolved,
343 AdmissionRequired,
344 DelayScheduled,
345 RetryStarted,
346 Exhausted,
347 Interrupted,
348 Cancelled,
349}
350#[derive(Debug, Clone, Serialize)]
351pub struct LifecycleEvent {
352 pub transition: Transition,
353 pub identity: Option<Identity>,
354 pub phase: Option<Phase>,
355 pub progress: Progress,
356 pub failure: Option<Failure>,
357 pub delay: Option<Duration>,
358}
359
360#[derive(Debug, Clone, Copy, PartialEq, Eq, thiserror::Error)]
363pub enum CompletionDecodeError {
364 #[error("completion reached its output length limit")]
366 Length,
367 #[error("invalid completion: {reason}")]
369 InvalidFrame { reason: &'static str },
370}