Skip to main content

mojentic/llm/recovery/
types.rs

1//! Safe failure metadata. Payloads and original causes require explicit inspection.
2use 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/// Endpoint facilities declared by a recovery adapter, not permission to retry.
59/// Inspect `RecoveryGateway::capability_evidence` for documentation and limitations.
60#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
61pub struct Capabilities {
62    /// Legacy alias for `remote_request_cancellation`; omitted from serialization.
63    #[serde(skip)]
64    pub request_cancel: Support,
65    /// Local cancellation; this never proves remote termination.
66    pub local_request_cancellation: Support,
67    /// Cancellation of an active remote request.
68    pub remote_request_cancellation: Support,
69    /// Status of an in-flight or ambiguously accepted request.
70    pub request_status: Support,
71    /// Deduplicated replay of this endpoint's request.
72    pub idempotency: Support,
73    /// Proof that one exact wire attempt stopped remotely.
74    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/// Only recognized provider codes and request-ID formats are retained by default.
134#[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        // UUIDs only: arbitrary provider strings can carry echoed credentials.
155        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    /// No adapter has evidence of remote termination for an exact request.
191    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    /// Explicit opt-in to potentially sensitive provider/transport evidence.
201    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    /// Client stream timing and original provider metrics, retained on terminal failure.
278    /// Inspect explicitly: default Debug/serialization omit raw provider usage.
279    #[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    /// Client stream timing and original provider metrics for a completed stream.
311    /// Inspect explicitly: default Debug/serialization omit raw provider usage.
312    #[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
328/// Success and its exact wire accounting; response payload is intentionally not serializable here.
329pub 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/// Concrete decoding/termination causes available through `Failure::inspect_cause`.
361/// Raw provider payloads remain private; serde errors retain their original type.
362#[derive(Debug, Clone, Copy, PartialEq, Eq, thiserror::Error)]
363pub enum CompletionDecodeError {
364    /// The provider reached its output limit; incomplete tools must not execute.
365    #[error("completion reached its output length limit")]
366    Length,
367    /// A structurally invalid response or unsafe terminal proof.
368    #[error("invalid completion: {reason}")]
369    InvalidFrame { reason: &'static str },
370}