tenant.openagents/omega

1/// Some helpers for structured error handling.
2///
3/// The helpers defined here allow you to pass type-safe error codes from
4/// the collab server to the client; and provide a mechanism for additional
5/// structured data alongside the message.
6///
7/// When returning an error, it can be as simple as:
8///
9/// `return Err(Error::Forbidden.into())`
10///
11/// If you'd like to log more context, you can set a message. These messages
12/// show up in our logs, but are not shown visibly to users.
13///
14/// `return Err(Error::Forbidden.message("not an admin").into())`
15///
16/// If you'd like to provide enough context that the UI can render a good error
17/// message (or would be helpful to see in a structured format in the logs), you
18/// can use .with_tag():
19///
20/// `return Err(Error::WrongReleaseChannel.with_tag("required", "stable").into())`
21///
22/// When handling an error you can use .error_code() to match which error it was
23/// and .error_tag() to read any tags.
24///
25/// ```ignore
26/// use proto::{ErrorCode, ErrorExt};
27///
28/// match err.error_code() {
29///   ErrorCode::Forbidden => alert("I'm sorry I can't do that."),
30///   ErrorCode::WrongReleaseChannel =>
31///     alert(format!("You need to be on the {} release channel.", err.error_tag("required").unwrap())),
32///   ErrorCode::Internal => alert("Sorry, something went wrong"),
33/// }
34/// ```
35///
36pub use crate::ErrorCode;
37
38/// ErrorCodeExt provides some helpers for structured error handling.
39///
40/// The primary implementation is on the proto::ErrorCode to easily convert
41/// that into an anyhow::Error, which we use pervasively.
42///
43/// The RpcError struct provides support for further metadata if needed.
44pub trait ErrorCodeExt {
45    /// Return an anyhow::Error containing this.
46    /// (useful in places where .into() doesn't have enough type information)
47    fn anyhow(self) -> anyhow::Error;
48
49    /// Add a message to the error (by default the error code is used)
50    fn message(self, msg: String) -> RpcError;
51
52    /// Add a tag to the error. Tags are key value pairs that can be used
53    /// to send semi-structured data along with the error.
54    fn with_tag(self, k: &str, v: &str) -> RpcError;
55}
56
57impl ErrorCodeExt for ErrorCode {
58    fn anyhow(self) -> anyhow::Error {
59        self.into()
60    }
61
62    fn message(self, msg: String) -> RpcError {
63        let err: RpcError = self.into();
64        err.message(msg)
65    }
66
67    fn with_tag(self, k: &str, v: &str) -> RpcError {
68        let err: RpcError = self.into();
69        err.with_tag(k, v)
70    }
71}
72
73/// ErrorExt provides helpers for structured error handling.
74///
75/// The primary implementation is on the anyhow::Error, which is
76/// what we use throughout our codebase. Though under the hood this
77pub trait ErrorExt {
78    /// error_code() returns the ErrorCode (or ErrorCode::Internal if there is none)
79    fn error_code(&self) -> ErrorCode;
80    /// error_tag() returns the value of the tag with the given key, if any.
81    fn error_tag(&self, k: &str) -> Option<&str>;
82    /// to_proto() converts the error into a crate::Error
83    fn to_proto(&self) -> crate::Error;
84    /// Clones the error and turns into an [anyhow::Error].
85    fn cloned(&self) -> anyhow::Error;
86}
87
88impl ErrorExt for anyhow::Error {
89    fn error_code(&self) -> ErrorCode {
90        if let Some(rpc_error) = self.downcast_ref::<RpcError>() {
91            rpc_error.code
92        } else {
93            ErrorCode::Internal
94        }
95    }
96
97    fn error_tag(&self, k: &str) -> Option<&str> {
98        if let Some(rpc_error) = self.downcast_ref::<RpcError>() {
99            rpc_error.error_tag(k)
100        } else {
101            None
102        }
103    }
104
105    fn to_proto(&self) -> crate::Error {
106        if let Some(rpc_error) = self.downcast_ref::<RpcError>() {
107            rpc_error.to_proto()
108        } else {
109            ErrorCode::Internal
110                .message(
111                    format!("{self:#}")
112                        .lines()
113                        .fold(String::new(), |mut message, line| {
114                            if !message.is_empty() {
115                                message.push(' ');
116                            }
117                            message.push_str(line);
118                            message
119                        }),
120                )
121                .to_proto()
122        }
123    }
124
125    fn cloned(&self) -> anyhow::Error {
126        if let Some(rpc_error) = self.downcast_ref::<RpcError>() {
127            rpc_error.cloned()
128        } else {
129            anyhow::anyhow!("{self:#}")
130        }
131    }
132}
133
134impl From<ErrorCode> for anyhow::Error {
135    fn from(value: ErrorCode) -> Self {
136        RpcError {
137            request: None,
138            code: value,
139            msg: format!("{:?}", value),
140            tags: Default::default(),
141        }
142        .into()
143    }
144}
145
146#[derive(Clone, Debug)]
147pub struct RpcError {
148    request: Option<String>,
149    msg: String,
150    code: ErrorCode,
151    tags: Vec<String>,
152}
153
154/// RpcError is a structured error type that is returned by the collab server.
155/// In addition to a message, it lets you set a specific ErrorCode, and attach
156/// small amounts of metadata to help the client handle the error appropriately.
157///
158/// This struct is not typically used directly, as we pass anyhow::Error around
159/// in the app; however it is useful for chaining .message() and .with_tag() on
160/// ErrorCode.
161impl RpcError {
162    /// Returns the raw server-provided error message without any RPC framing
163    /// (e.g. without the "RPC request X failed: " prefix that `Display` adds).
164    pub fn raw_message(&self) -> &str {
165        &self.msg
166    }
167
168    /// from_proto converts a crate::Error into an anyhow::Error containing
169    /// an RpcError.
170    pub fn from_proto(error: &crate::Error, request: &str) -> anyhow::Error {
171        RpcError {
172            request: Some(request.to_string()),
173            code: error.code(),
174            msg: error.message.clone(),
175            tags: error.tags.clone(),
176        }
177        .into()
178    }
179}
180
181impl ErrorCodeExt for RpcError {
182    fn message(mut self, msg: String) -> RpcError {
183        self.msg = msg;
184        self
185    }
186
187    fn with_tag(mut self, k: &str, v: &str) -> RpcError {
188        self.tags.push(format!("{}={}", k, v));
189        self
190    }
191
192    fn anyhow(self) -> anyhow::Error {
193        self.into()
194    }
195}
196
197impl ErrorExt for RpcError {
198    fn error_tag(&self, k: &str) -> Option<&str> {
199        for tag in &self.tags {
200            let mut parts = tag.split('=');
201            if let Some(key) = parts.next()
202                && key == k
203            {
204                return parts.next();
205            }
206        }
207        None
208    }
209
210    fn error_code(&self) -> ErrorCode {
211        self.code
212    }
213
214    fn to_proto(&self) -> crate::Error {
215        crate::Error {
216            code: self.code as i32,
217            message: self.msg.clone(),
218            tags: self.tags.clone(),
219        }
220    }
221
222    fn cloned(&self) -> anyhow::Error {
223        self.clone().into()
224    }
225}
226
227impl std::error::Error for RpcError {
228    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
229        None
230    }
231}
232
233impl std::fmt::Display for RpcError {
234    fn fmt(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result {
235        if let Some(request) = &self.request {
236            write!(f, "RPC request {} failed: {}", request, self.msg)?
237        } else {
238            write!(f, "{}", self.msg)?
239        }
240        for tag in &self.tags {
241            write!(f, " {}", tag)?
242        }
243        Ok(())
244    }
245}
246
247impl From<ErrorCode> for RpcError {
248    fn from(code: ErrorCode) -> Self {
249        RpcError {
250            request: None,
251            code,
252            msg: format!("{:?}", code),
253            tags: Default::default(),
254        }
255    }
256}
257