solari/
error.rs

1//! Typed error hierarchy for the Solari SDK.
2//!
3//! Mirrors the reference `errors.ts`: gateway HTTP status codes and control-WS
4//! RPC failures are mapped onto a single enum so callers can `match` broadly.
5//! `SolariError` is the base type carrying every failure this crate raises.
6
7use crate::types::GatewayErrorBody;
8
9/// Every error raised by the SDK. Corresponds to the `SolariError` hierarchy in
10/// the TypeScript reference (AuthError / PlanError / ConcurrencyLimitError /
11/// NoCapacityError / GatewayError / ActionError / TimeoutError / ConnectionError).
12#[derive(Debug, thiserror::Error)]
13// Non-exhaustive so a future variant is a non-breaking addition for downstream
14// crates that match on this type. It does NOT constrain matches inside this
15// crate (Rust only enforces the wildcard arm on out-of-crate matches), so keep
16// it: its whole purpose is to make the next variant free rather than breaking.
17#[non_exhaustive]
18pub enum SolariError {
19    /// HTTP 401 — the API key was missing, malformed, or rejected.
20    #[error("{message}")]
21    Auth { status: u16, message: String, code: Option<String> },
22
23    /// The plan does not allow this: HTTP 402 (`FeatureRequiresPlan`, `InsufficientCredit`) or 403 `NotEntitled` (the plan
24    /// does not include sandboxes/desktops). `status` is the status the gateway really sent.
25    #[error("{message}")]
26    Plan { status: u16, message: String, code: Option<String> },
27
28    /// HTTP 429 `ConcurrencyLimitExceeded` (or a 429 with no code) — the org is at its session cap. NOT retryable. Other 429s
29    /// (`TooManyExecutions`, a per-sandbox limit, `ObjectLimit`, the template caps) are `Gateway` errors with the gateway's `code`.
30    #[error("{message}")]
31    ConcurrencyLimit { status: u16, message: String, code: Option<String> },
32
33    /// HTTP 503 `NoCapacity` / `StartTimeout` (or a 503 with no code) — no host available (retryable). Other 503s
34    /// (`SandboxUnavailable`, `StoreUnavailable`, `AdmissionUnavailable`, `DependencyUnavailable`) are `Gateway` errors: the
35    /// sandbox, store or admission service is unavailable, which is not a capacity problem.
36    #[error("{message}")]
37    NoCapacity { status: u16, message: String, code: Option<String> },
38
39    /// Any other non-2xx gateway response (incl. 404/405/409/501).
40    #[error("{message}")]
41    Gateway { status: u16, message: String, code: Option<String> },
42
43    /// A control-WS RPC replied `{ok:false}`.
44    #[error("{message}")]
45    Action { method: String, message: String, code: Option<String> },
46
47    /// A call (or connect) did not complete within its timeout.
48    #[error("Action \"{method}\" timed out after {timeout_ms}ms")]
49    Timeout { method: String, timeout_ms: u64 },
50
51    /// The control WebSocket is not open (never connected, or dropped).
52    #[error("{message}")]
53    Connection { message: String },
54
55    /// A git subcommand exited non-zero (message includes sub/exit/detail).
56    #[error("{message}")]
57    Git { message: String },
58
59    /// Anything else (bad response body, internal invariant).
60    #[error("{0}")]
61    Other(String),
62    /// A caller passed an invalid argument (e.g. a blank session id). Distinct
63    /// from `Other`: this is the caller's input to fix, not an unexpected
64    /// server response.
65    #[error("{message}")]
66    Validation { message: String },
67}
68
69impl SolariError {
70    pub(crate) fn connection(msg: impl Into<String>) -> Self {
71        SolariError::Connection { message: msg.into() }
72    }
73
74    /// The gateway HTTP status this error carries, when it is a gateway error.
75    pub fn status(&self) -> Option<u16> {
76        match self {
77            SolariError::Auth { status, .. }
78            | SolariError::Plan { status, .. }
79            | SolariError::ConcurrencyLimit { status, .. }
80            | SolariError::NoCapacity { status, .. }
81            | SolariError::Gateway { status, .. } => Some(*status),
82            _ => None,
83        }
84    }
85}
86
87/// Map a gateway HTTP response onto the appropriate typed error. Falls back to a
88/// generic `Gateway` for unrecognized statuses. Mirrors `mapGatewayError`.
89pub(crate) fn map_gateway_error(status: u16, body: Option<GatewayErrorBody>) -> SolariError {
90    let code = body.as_ref().and_then(|b| b.code.clone());
91    let message = body
92        .as_ref()
93        .and_then(|b| b.message.clone().or_else(|| b.error.clone()).or_else(|| b.code.clone()))
94        .unwrap_or_else(|| format!("Gateway request failed with status {status}"));
95    // `code` is the discriminator (PROTOCOL.md section 4); the status alone is not enough because one status carries
96    // several meanings. A response with no code keeps the type its status has always had.
97    match (status, code.as_deref()) {
98        (401, _) => SolariError::Auth { status, message, code },
99        (402, _) => SolariError::Plan { status, message, code },
100        // The gateway's only JSON 403 is NotEntitled (the plan does not include sandboxes/desktops).
101        (403, Some("NotEntitled")) => SolariError::Plan { status, message, code },
102        (429, None | Some("ConcurrencyLimitExceeded")) => SolariError::ConcurrencyLimit { status, message, code },
103        (503, None | Some("NoCapacity" | "StartTimeout")) => SolariError::NoCapacity { status, message, code },
104        _ => SolariError::Gateway { status, message, code },
105    }
106}
107
108/// True when an error means the one-shot `/exec` route is not served (an older
109/// gateway) — the only case where `run` retries over the control WS. A real
110/// host/command failure is NOT route-unavailable and must propagate. Mirrors
111/// `isRouteUnavailable` (GatewayError with status 404/405/501).
112pub(crate) fn is_route_unavailable(err: &SolariError) -> bool {
113    matches!(err.status(), Some(404) | Some(405) | Some(501))
114}
115
116#[cfg(test)]
117mod tests {
118    use super::*;
119
120    #[derive(Debug, PartialEq)]
121    enum Kind {
122        Auth,
123        Plan,
124        Concurrency,
125        NoCapacity,
126        Plain,
127    }
128
129    fn kind(e: &SolariError) -> Kind {
130        match e {
131            SolariError::Auth { .. } => Kind::Auth,
132            SolariError::Plan { .. } => Kind::Plan,
133            SolariError::ConcurrencyLimit { .. } => Kind::Concurrency,
134            SolariError::NoCapacity { .. } => Kind::NoCapacity,
135            SolariError::Gateway { .. } => Kind::Plain,
136            other => panic!("not a gateway error: {other:?}"),
137        }
138    }
139
140    /// Gateway status + body code -> typed error (PROTOCOL.md section 4).
141    #[test]
142    fn maps_by_code_first() {
143        let cases: &[(&str, u16, Option<&str>, Kind)] = &[
144            ("401", 401, Some("Unauthorized"), Kind::Auth),
145            ("402-plan", 402, Some("FeatureRequiresPlan"), Kind::Plan),
146            ("402-credit", 402, Some("InsufficientCredit"), Kind::Plan),
147            ("403-not-entitled", 403, Some("NotEntitled"), Kind::Plan),
148            ("403-other", 403, Some("Forbidden"), Kind::Plain),
149            ("404", 404, Some("NotFound"), Kind::Plain),
150            ("409-sandbox-stopped", 409, Some("SandboxStopped"), Kind::Plain),
151            ("410-gone", 410, Some("SandboxGone"), Kind::Plain),
152            ("429-concurrency-cap", 429, Some("ConcurrencyLimitExceeded"), Kind::Concurrency),
153            ("429-no-code", 429, None, Kind::Concurrency),
154            ("429-too-many-executions", 429, Some("TooManyExecutions"), Kind::Plain),
155            ("429-object-limit", 429, Some("ObjectLimit"), Kind::Plain),
156            ("500-internal", 500, Some("InternalError"), Kind::Plain),
157            ("501-not-supported", 501, Some("NotSupported"), Kind::Plain),
158            ("503-no-capacity", 503, Some("NoCapacity"), Kind::NoCapacity),
159            ("503-start-timeout", 503, Some("StartTimeout"), Kind::NoCapacity),
160            ("503-no-code", 503, None, Kind::NoCapacity),
161            ("503-sandbox-unavailable", 503, Some("SandboxUnavailable"), Kind::Plain),
162            ("503-store-unavailable", 503, Some("StoreUnavailable"), Kind::Plain),
163            ("503-admission-unavailable", 503, Some("AdmissionUnavailable"), Kind::Plain),
164            ("503-dependency-unavailable", 503, Some("DependencyUnavailable"), Kind::Plain),
165            ("507-insufficient-capacity", 507, Some("InsufficientCapacity"), Kind::Plain),
166        ];
167        for (id, status, code, want) in cases {
168            let body = GatewayErrorBody { code: code.map(str::to_string), ..Default::default() };
169            let e = map_gateway_error(*status, Some(body));
170            assert_eq!(&kind(&e), want, "errors/{id}");
171            assert_eq!(e.status(), Some(*status), "errors/{id}: the status the gateway sent is kept");
172            let kept = match &e {
173                SolariError::Auth { code, .. }
174                | SolariError::Plan { code, .. }
175                | SolariError::ConcurrencyLimit { code, .. }
176                | SolariError::NoCapacity { code, .. }
177                | SolariError::Gateway { code, .. } => code.clone(),
178                _ => unreachable!(),
179            };
180            assert_eq!(kept.as_deref(), *code, "errors/{id}: the gateway's code is kept");
181        }
182    }
183}
solari/error.rs

solari/
error.rs
