1use libsy::LibsyError;
7use strum_macros::IntoStaticStr;
8use switchyard_protocol::{LlmClientError, ModelId};
9
10use crate::RunnerError;
11
12#[non_exhaustive]
17#[derive(Clone, Copy, Debug, IntoStaticStr)]
18#[strum(serialize_all = "snake_case")]
19pub enum RouteErrorKind {
20 UpstreamHttp,
22 ContextWindowExceeded,
24 TemporarilyUnavailable,
26 Timeout,
28 Transport,
30 InvalidResponse,
32 RequestTranslation,
34 RequestEncoding,
36 ResponseTranslation,
38 InvalidRequest,
40 Configuration,
42 Algorithm,
44 Other,
46}
47
48impl RouteErrorKind {
49 pub fn as_str(self) -> &'static str {
51 self.into()
52 }
53}
54
55#[non_exhaustive]
57#[derive(Clone, Copy, Debug, IntoStaticStr)]
58#[strum(serialize_all = "snake_case")]
59pub enum RouteErrorPhase {
60 BeforeResponse,
62 DuringStream,
64}
65
66impl RouteErrorPhase {
67 pub fn as_str(self) -> &'static str {
69 self.into()
70 }
71}
72
73#[non_exhaustive]
75#[derive(Clone, Debug)]
76pub struct RouteErrorSummary {
77 pub kind: RouteErrorKind,
79 pub phase: RouteErrorPhase,
81 pub upstream_status: Option<u16>,
83 pub target: Option<ModelId>,
85}
86
87impl RunnerError {
88 pub fn execution_error_summary(&self) -> RouteErrorSummary {
90 match self {
91 Self::Algorithm(LibsyError::ClientCall { target, source }) => {
92 client_error_summary(source, RouteErrorPhase::BeforeResponse, Some(target))
93 }
94 Self::Client(source) => {
95 client_error_summary(source, RouteErrorPhase::BeforeResponse, None)
96 }
97 Self::Configuration { .. } => summary(
98 RouteErrorKind::Configuration,
99 RouteErrorPhase::BeforeResponse,
100 None,
101 None,
102 ),
103 Self::UnknownRouteModel(_)
104 | Self::IncompatibleCallerFormat(_)
105 | Self::AuxiliaryUnsupported => summary(
106 RouteErrorKind::InvalidRequest,
107 RouteErrorPhase::BeforeResponse,
108 None,
109 None,
110 ),
111 Self::Algorithm(_) => summary(
112 RouteErrorKind::Algorithm,
113 RouteErrorPhase::BeforeResponse,
114 None,
115 None,
116 ),
117 }
118 }
119}
120
121pub fn stream_error_summary(
125 error: &LlmClientError,
126 served_model: Option<&ModelId>,
127) -> RouteErrorSummary {
128 client_error_summary(error, RouteErrorPhase::DuringStream, served_model)
129}
130
131fn client_error_summary(
132 error: &LlmClientError,
133 phase: RouteErrorPhase,
134 target: Option<&ModelId>,
135) -> RouteErrorSummary {
136 let target = target.or(match error {
137 LlmClientError::ContextWindowExceeded { model, .. } => Some(model),
140 _ => None,
141 });
142 let (kind, upstream_status) = match error {
143 LlmClientError::UpstreamHttp { status, .. } => {
144 (RouteErrorKind::UpstreamHttp, Some(status.as_u16()))
145 }
146 LlmClientError::ContextWindowExceeded { .. } => {
147 (RouteErrorKind::ContextWindowExceeded, None)
148 }
149 LlmClientError::TemporarilyUnavailable => (RouteErrorKind::TemporarilyUnavailable, None),
150 LlmClientError::Timeout { .. } => (RouteErrorKind::Timeout, None),
151 LlmClientError::Transport { .. } => (RouteErrorKind::Transport, None),
152 LlmClientError::InvalidResponse { .. } => (RouteErrorKind::InvalidResponse, None),
153 LlmClientError::RequestTranslation(_) => (RouteErrorKind::RequestTranslation, None),
154 LlmClientError::RequestEncoding(_) => (RouteErrorKind::RequestEncoding, None),
155 LlmClientError::ResponseTranslation(_) => (RouteErrorKind::ResponseTranslation, None),
156 LlmClientError::InvalidRequest { .. } => (RouteErrorKind::InvalidRequest, None),
157 LlmClientError::Configuration { .. } => (RouteErrorKind::Configuration, None),
158 LlmClientError::Ffi { .. } | LlmClientError::General(_) => (RouteErrorKind::Other, None),
159 _ => (RouteErrorKind::Other, None),
160 };
161 summary(kind, phase, upstream_status, target)
162}
163
164fn summary(
165 kind: RouteErrorKind,
166 phase: RouteErrorPhase,
167 upstream_status: Option<u16>,
168 target: Option<&ModelId>,
169) -> RouteErrorSummary {
170 RouteErrorSummary {
171 kind,
172 phase,
173 upstream_status,
174 target: target.cloned(),
175 }
176}
177
178#[cfg(test)]
179mod tests {
180 use super::*;
181
182 const SECRET: &str = "patient name is Jane Doe";
183
184 #[test]
185 fn execution_error_summary_keeps_http_status_and_target_without_body() {
186 let error = RunnerError::Algorithm(LibsyError::ClientCall {
187 target: ModelId::from("strong"),
188 source: LlmClientError::UpstreamHttp {
189 status: reqwest::StatusCode::SERVICE_UNAVAILABLE,
190 body: format!("upstream response: {SECRET}"),
191 headers: Box::default(),
192 },
193 });
194
195 let summary = error.execution_error_summary();
196
197 assert!(matches!(summary.kind, RouteErrorKind::UpstreamHttp));
198 assert!(matches!(summary.phase, RouteErrorPhase::BeforeResponse));
199 assert_eq!(summary.upstream_status, Some(503));
200 assert_eq!(summary.target.as_ref().map(ModelId::as_str), Some("strong"));
201 assert!(!format!("{summary:?}").contains(SECRET));
202 }
203
204 #[test]
205 fn execution_error_summary_reduces_untrusted_messages_to_kinds() {
206 let error = RunnerError::Algorithm(LibsyError::AlgorithmError {
207 message: SECRET.to_string(),
208 });
209
210 let summary = error.execution_error_summary();
211
212 assert!(matches!(summary.kind, RouteErrorKind::Algorithm));
213 assert_eq!(summary.target, None);
214 assert!(!format!("{summary:?}").contains(SECRET));
215 }
216
217 #[test]
218 fn stream_error_summary_preserves_served_target_without_source_text() {
219 let error = LlmClientError::Timeout {
220 source: std::io::Error::other(SECRET).into(),
221 };
222
223 let summary = stream_error_summary(&error, Some(&ModelId::from("fallback")));
224
225 assert!(matches!(summary.kind, RouteErrorKind::Timeout));
226 assert!(matches!(summary.phase, RouteErrorPhase::DuringStream));
227 assert_eq!(
228 summary.target.as_ref().map(ModelId::as_str),
229 Some("fallback")
230 );
231 assert!(!format!("{summary:?}").contains(SECRET));
232 }
233
234 #[test]
235 fn stream_error_summary_uses_context_window_model_without_a_served_target() {
236 let error = LlmClientError::ContextWindowExceeded {
237 model: ModelId::from("weak"),
238 message: SECRET.to_string(),
239 };
240
241 let summary = stream_error_summary(&error, None);
242
243 assert!(matches!(
244 summary.kind,
245 RouteErrorKind::ContextWindowExceeded
246 ));
247 assert!(matches!(summary.phase, RouteErrorPhase::DuringStream));
248 assert_eq!(summary.target.as_ref().map(ModelId::as_str), Some("weak"));
249 assert!(!format!("{summary:?}").contains(SECRET));
250 }
251
252 #[test]
253 fn client_error_kinds_have_stable_telemetry_values() {
254 let cases = vec![
255 (
256 LlmClientError::ContextWindowExceeded {
257 model: ModelId::from("weak"),
258 message: SECRET.to_string(),
259 },
260 "context_window_exceeded",
261 ),
262 (
263 LlmClientError::Transport {
264 source: std::io::Error::other(SECRET).into(),
265 },
266 "transport",
267 ),
268 (
269 LlmClientError::InvalidResponse {
270 source: std::io::Error::other(SECRET).into(),
271 },
272 "invalid_response",
273 ),
274 (
275 LlmClientError::RequestTranslation(SECRET.to_string()),
276 "request_translation",
277 ),
278 (
279 LlmClientError::RequestEncoding(SECRET.to_string()),
280 "request_encoding",
281 ),
282 (
283 LlmClientError::ResponseTranslation(SECRET.to_string()),
284 "response_translation",
285 ),
286 (
287 LlmClientError::Configuration {
288 message: SECRET.to_string(),
289 },
290 "configuration",
291 ),
292 (
293 LlmClientError::InvalidRequest {
294 message: SECRET.to_string(),
295 },
296 "invalid_request",
297 ),
298 (LlmClientError::General(SECRET.to_string()), "other"),
299 ];
300
301 for (error, value) in cases {
302 let summary = stream_error_summary(&error, None);
303 assert_eq!(summary.kind.as_str(), value);
304 assert!(!format!("{summary:?}").contains(SECRET));
305 }
306 }
307
308 #[test]
309 fn route_error_phases_have_stable_telemetry_values() {
310 assert_eq!(RouteErrorPhase::BeforeResponse.as_str(), "before_response");
311 assert_eq!(RouteErrorPhase::DuringStream.as_str(), "during_stream");
312 }
313
314 #[test]
315 fn direct_client_errors_do_not_claim_a_target() {
316 let error = RunnerError::Client(LlmClientError::Timeout {
317 source: std::io::Error::other(SECRET).into(),
318 });
319
320 let summary = error.execution_error_summary();
321
322 assert!(matches!(summary.kind, RouteErrorKind::Timeout));
323 assert!(matches!(summary.phase, RouteErrorPhase::BeforeResponse));
324 assert_eq!(summary.target, None);
325 assert!(!format!("{summary:?}").contains(SECRET));
326 }
327
328 #[test]
329 fn runner_request_and_configuration_errors_are_classified() {
330 let configuration = RunnerError::configuration(SECRET);
331 assert!(matches!(
332 configuration.execution_error_summary().kind,
333 RouteErrorKind::Configuration
334 ));
335
336 let unsupported = RunnerError::AuxiliaryUnsupported;
337 assert!(matches!(
338 unsupported.execution_error_summary().kind,
339 RouteErrorKind::InvalidRequest
340 ));
341 }
342}