Skip to main content

acosmi/shared/
errors.rs

1//! 跨域类型化错误。
2//!
3//! 端口自 `acosmi-sdk-ts/src/shared/errors.ts`(其本身端口自 `acosmi-sdk-go/types.go`)。
4//!
5//! TS 侧是 7 个 `Error` 子类(`instanceof` 区分):`RateLimitError` / `BusinessError` /
6//! `OrderTerminalError` / `ModelNotFoundError` / `HTTPError` / `NetworkError` / `StreamError`。
7//! Rust 惯例改为顶层 [`Error`] enum(`match` 替代 `instanceof`):富字段的
8//! `HttpError`/`NetworkError`/`StreamError` 拆为独立结构体并由 enum 包装,其余 4 类内联为变体。
9//! 变体/结构体名 1:1 对齐 TS 类名(跨语言锚点;`HTTPError`→`HttpError` 仅大小写惯例偏移)。
10
11use std::fmt;
12
13/// crate 统一 `Result`。
14pub type Result<T> = std::result::Result<T, Error>;
15
16// =============================================================================
17// 富字段错误结构体(对应 TS 的 HTTPError / NetworkError / StreamError 子类)
18// =============================================================================
19
20/// 结构化 HTTP 非 2xx 错误。对应 TS `HTTPError`。
21#[derive(Debug, Clone)]
22pub struct HttpError {
23    /// HTTP 状态码。
24    pub status_code: u16,
25    /// `anthropic.error.type` / `openai.error.type`,缺失为空串。
26    pub r#type: String,
27    /// `Retry-After` 头解析的秒数,0 表示未提供或解析失败。
28    pub retry_after: i64,
29    /// 原始响应体(截断到 `max_error_body_size`)。
30    pub body: String,
31    /// 解析出的 error.message(TS 仅用于 Display,不作公开字段;Rust 内部持有以复刻 Display)。
32    pub message: String,
33}
34
35impl HttpError {
36    /// 对齐 TS `new HTTPError(statusCode, opts)`。
37    pub fn new(
38        status_code: u16,
39        r#type: impl Into<String>,
40        message: impl Into<String>,
41        retry_after: i64,
42        body: impl Into<String>,
43    ) -> Self {
44        Self {
45            status_code,
46            r#type: r#type.into(),
47            retry_after,
48            body: body.into(),
49            message: message.into(),
50        }
51    }
52}
53
54impl fmt::Display for HttpError {
55    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
56        // 严格对齐 TS constructor 四分支(type → message → body → 仅 status)。
57        if !self.r#type.is_empty() {
58            write!(
59                f,
60                "HTTP {}: [{}] {}",
61                self.status_code, self.r#type, self.message
62            )
63        } else if !self.message.is_empty() {
64            write!(f, "HTTP {}: {}", self.status_code, self.message)
65        } else if !self.body.is_empty() {
66            write!(f, "HTTP {}: {}", self.status_code, self.body)
67        } else {
68            write!(f, "HTTP {}", self.status_code)
69        }
70    }
71}
72
73impl std::error::Error for HttpError {}
74
75/// 结构化网络层错误(传输失败,区别于上游业务错误)。对应 TS `NetworkError`。
76#[derive(Debug, Clone)]
77pub struct NetworkError {
78    /// 操作描述,例如 `"POST /v1/messages"`。
79    pub op: String,
80    /// 请求 URL(脱敏后)。
81    pub url: String,
82    /// 底层 cause 的消息(已解析为字符串)。
83    pub cause: String,
84    pub timeout: bool,
85    pub eof: bool,
86}
87
88impl NetworkError {
89    pub fn new(op: impl Into<String>, url: impl Into<String>, cause: impl Into<String>) -> Self {
90        let cause = cause.into();
91        Self {
92            op: op.into(),
93            url: url.into(),
94            cause: if cause.is_empty() {
95                "network error".to_string()
96            } else {
97                cause
98            },
99            timeout: false,
100            eof: false,
101        }
102    }
103    /// retry policy: `is_timeout() || is_eof()` 任一为 true → 默认可重试。
104    pub fn is_timeout(&self) -> bool {
105        self.timeout
106    }
107    pub fn is_eof(&self) -> bool {
108        self.eof
109    }
110}
111
112impl fmt::Display for NetworkError {
113    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
114        write!(f, "{} {}: {}", self.op, self.url, self.cause)
115    }
116}
117
118impl std::error::Error for NetworkError {}
119
120/// 流式失败事件的结构化表示。对应 TS `StreamError`。
121#[derive(Debug, Clone, Default)]
122pub struct StreamError {
123    /// 例:`"empty_response"` / `"rate_limit"` / `"overloaded"` / `""`。
124    pub code: String,
125    /// 例:`"provider"` / `"settlement"`。
126    pub stage: String,
127    /// 用户友好提示(历史字段,与 `raw_error` 区分)。
128    pub user_message: String,
129    /// gateway 原始 error 字符串。
130    pub raw_error: String,
131    /// 客户端是否值得重试。
132    pub retryable: bool,
133}
134
135impl fmt::Display for StreamError {
136    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
137        let body = if !self.raw_error.is_empty() {
138            &self.raw_error
139        } else {
140            &self.user_message
141        };
142        if !self.stage.is_empty() {
143            write!(f, "stream failed: {}: {}", self.stage, body)
144        } else {
145            write!(f, "stream failed: {body}")
146        }
147    }
148}
149
150impl std::error::Error for StreamError {}
151
152// =============================================================================
153// 顶层 Error enum
154// =============================================================================
155
156/// SDK 统一错误。变体名对齐 TS 的 7 个错误子类 + Rust 传播用工具变体。
157#[derive(Debug, thiserror::Error)]
158pub enum Error {
159    /// 下载限流错误(429)。对应 TS `RateLimitError`。
160    #[error("{message}")]
161    RateLimit {
162        message: String,
163        retry_after: String,
164        raw: String,
165    },
166
167    /// API 业务层错误(HTTP 200 但 `code != 0`)。对应 TS `BusinessError`。
168    #[error("API error (code={code}): {message}")]
169    Business { code: i64, message: String },
170
171    /// 订单到达非成功终态。对应 TS `OrderTerminalError`。
172    #[error("order {order_id} terminated: {status}")]
173    OrderTerminal { order_id: String, status: String },
174
175    /// 模型缓存未命中且刷新后仍未找到。对应 TS `ModelNotFoundError`。
176    #[error(
177        "managed model \"{model_id}\" not found (list models to refresh cache, or verify model id)"
178    )]
179    ModelNotFound { model_id: String },
180
181    /// 结构化 HTTP 非 2xx 错误。
182    #[error(transparent)]
183    Http(#[from] HttpError),
184
185    /// 结构化网络层错误。
186    #[error(transparent)]
187    Network(#[from] NetworkError),
188
189    /// 流式失败事件。
190    #[error(transparent)]
191    Stream(#[from] StreamError),
192
193    /// agent run SSE `error` 事件(`throwOnError` 为 true 时抛出)。对应 TS `AgentRunStreamError`。
194    /// 携带 stage/code/retryable 供调用方判定。
195    #[error("agent run failed: {}{message}", stage.as_ref().map(|s| format!("{s}: ")).unwrap_or_default())]
196    AgentRunStream {
197        code: String,
198        stage: Option<String>,
199        message: String,
200        retryable: bool,
201    },
202
203    /// OAuth token 端点(exchange / refresh)结构化错误。对应 TS `OAuthTokenEndpointError`。
204    /// 携带 OAuth `error` 码用于 `is_invalid_grant_error` 判定。
205    #[error(transparent)]
206    OAuthTokenEndpoint(#[from] crate::auth::auth::OAuthTokenEndpointError),
207
208    // ── Rust 传播用工具变体(TS 无对应;用于 `?` 链路)──
209    #[error(transparent)]
210    Json(#[from] serde_json::Error),
211    #[cfg(feature = "native-http")]
212    #[error(transparent)]
213    Http2(#[from] reqwest::Error),
214    #[error(transparent)]
215    Io(#[from] std::io::Error),
216    /// 其它(含 URL 校验、解析等无专属变体的错误)。
217    #[error("{0}")]
218    Other(String),
219}
220
221impl Error {
222    /// 便捷构造 `RateLimit`。
223    pub fn rate_limit(
224        message: impl Into<String>,
225        retry_after: impl Into<String>,
226        raw: impl Into<String>,
227    ) -> Self {
228        Error::RateLimit {
229            message: message.into(),
230            retry_after: retry_after.into(),
231            raw: raw.into(),
232        }
233    }
234    /// 便捷构造 `Business`。
235    pub fn business(code: i64, message: impl Into<String>) -> Self {
236        Error::Business {
237            code,
238            message: message.into(),
239        }
240    }
241    /// 便捷构造 `Other`。
242    pub fn other(message: impl Into<String>) -> Self {
243        Error::Other(message.into())
244    }
245}