1# Chapter 4 - Errors Handling
2 
3Rust enforces a strict error handling approach, but *how* you handle them defines where your code feels ergonomic, consistent and safe - as opposing cryptic and painful. This chapter dives into best practices for modeling and managing fallible operations across libraries and binaries.
4 
5> Even if you decide to crash you application with `unwrap` or `expect`, Rust forces you to declare that intentionally.
6 
7## 4.1 Prefer `Result`, avoid panic 🫨
8 
9Rust has a powerful type that wraps fallible data, [`Result<T, E>`](https://doc.rust-lang.org/std/result/), this allows us to handle Error cases according to our needs and manage the state of the application based on that.
10 
11* If your function can fail, prefer to return a `Result`:
12```rust
13fn divide(x: f64, y: f64) -> Result<f64, DivisionError> {
14    if y == 0.0 {
15        Err(DivisionError::DividedByZero)
16    } else {
17        Ok(x / y)
18    }
19}
20```
21 
22* Use `panic!` only in unrecoverable conditions - typically tests, assertions, bugs or a need to crash the application for some explicit reason.
23* There are 3 relevant macros that can replace `panic!` in appropriate conditions:
24    * `todo!`, similar to panic, but alerts the compiler that you are aware that there is code missing.
25    * `unreachable!`, you have reasoned about the code block and are sure that condition `xyz` is not possible and if ever becomes possible you want to be alerted.
26    * `unimplemented!`, specially useful for alerting that a block is not yet implement with a reason.
27 
28## 4.2 Avoid `unwrap`/`expect` in Production
29 
30Although `expect` is preferred to `unwrap`, as it can have context, they should be avoided in production code as there are smarter alternatives to them. Considering that, they should be used in the following scenarios:
31- In tests, assertions or test helper functions.
32- When failure is impossible.
33- When the smarter options can't handle the specific case.
34 
35### 🚨 Alternative ways of handling `unwrap`/`expect`:
36 
37* If your `Result` (or `Option`) can have a predefined early return value in case of `Result::Err`, that doesn't need to know the `Err` value, use `let Ok(..) = else { return ... }` pattern, as it helps with flatten functions:
38```rust
39let Ok(json) = serde_json::from_str(&input) else {
40    return Err(MyError::InvalidJson);
41}
42```
43* If your `Result` (or `Option`) needs error recovery in case of `Result::Err`, that doesn't need to know the `Err` value, use `if let Ok(..) else { ... }` pattern:
44```rust
45if let Ok(json) = serde_json::from_str(&input) else {
46    ...
47} else {
48    Err(do_something_with_input(&input))
49}
50```
51* Functions that can have to handle `Option::None` values are recommended to return `Result<T, E>`, where `E` is a crate or module level error, like the examples above.
52* Lastly `unwrap_or`, `unwrap_or_else` or `unwrap_or_default`, these functions help you create alternative exits to unwrap that manage the uninitialized values.
53 
54## 4.3 `thiserror` for Crate level errors
55 
56Deriving Error manually is verbose and error prone, the rust ecosystem has a really good crate to help with this, `thiserror`. It allows you to create error types that easily implement `From` trait as well as easy error message (`Display`), improving developer experience while working seamlessly with `?` and integrating with `std::error::Error`:
57 
58```rust
59#[derive(Debug, thiserror::Error)]
60pub enum MyError {
61    #[error("Network Timeout")]
62    Timeout,
63    #[error("Invalid data: {0}")]
64    InvalidData(String),
65    #[error(transparent)]
66    Serialization(#[from] serde_json::Error),
67    #[error("Invalid request information. Header: {headers}, Metadata: {metadata}")]
68    InvalidRequest {
69        headers: Headers,
70        metadata: Metadata
71    }
72}
73```
74 
75### Error Hierarchies and Wrapping
76 
77For layered systems the best practice is to use nested `enum/struct` errors with `#[from]`:
78 
79```rust
80use crate::database::DbError;
81use crate::external_services::ExternalHttpError;
82 
83#[derive(Debug, thiserror::Error)]
84pub enum ServiceError {
85    #[error("Database handler error: {0}")]
86    Db(#[from] DbError),
87    #[error("External services error: {0}")]
88    ExternalServices(#[from] ExternalHttpError)
89}
90```
91 
92## 4.4 Reserve `anyhow` for Binaries
93 
94`anyhow` is an amazing crate, and quite useful for projects that are beginning and need accelerated speed. However, there is a turning point where it just painfully propagates through your code, considering this, `anyhow` is recommended only for **binaries**, where ergonomic error handling is needed and there is no need for precise error types:
95 
96```rust
97use anyhow::{Context, Result, anyhow};
98 
99fn main() -> Result<()> {
100    let content = std::fs::read_to_string("config.json")
101        .context("Failed to read config file")?;
102    Config::from_str(&content)
103        .map_err(|err| anyhow!("Config parsing error: {err}"))
104}
105```
106 
107### 🚨 `Anyhow` Gotchas
108 
109* Keeping the `context` and `anyhow` strings up-to-date in all code base is harder than keeping `thiserror` messages as you don't have a single point of entry.
110* `anyhow::Result` erases context that a caller might need, so avoid using it in a library.
111* test helper functions can use `anyhow` with little to no issues.
112 
113## 4.5 Use `?` to Bubble Errors
114 
115Prefer using `?` over verbose alternatives like `match` chains:
116```rust
117fn handle_request(req: &Request) -> Result<ValidatedRequest, MyError> {
118    validate_headers(req)?;
119    validate_body_format(req)?;
120    validate_credentials(req)?;
121    let body = Body::try_from(req)?;
122 
123    Ok(ValidatedRequest::try_from((req, body))?)
124}
125```
126 
127> In case error recovery is needed, use `or_else`, `map_err`, `if let Ok(..) else`. To **inspect or log your error**, use `inspect_err`.
128 
129## 4.6 Unit Test should exercise errors
130 
131While many errors don't implement PartialEq and Eq, making it hard to do direct assertions between them, it is possible to check the error messages with `format!` or `to_string()`, making the errors meaningful and test validated:
132 
133```rust
134#[test]
135fn error_does_not_implement_partial_eq() {
136    let err = divide(10., 0.0).unwrap_err();
137    assert_eq!(err.to_string(), "division by zero");
138}
139 
140#[test]
141fn error_implements_partial_eq() {
142    let err = process(my_value).unwrap_err();
143 
144    assert_eq!(
145        err,
146        MyError {
147            ..
148        }
149    )
150}
151```
152 
153## 4.7 Important Topics
154 
155### Custom Error Structs
156 
157Sometimes you don't need an enum to handle your errors, as there is only one type of error that your module can have. This can be solved with `struct Errors`:
158 
159```rust
160#[derive(Debug, thiserror::Error, PartialEq)]
161#[error("Request failed with code `{code}`: {message}")]
162struct HttpError {
163    code: u16,
164    message: String
165}
166```
167 
168### Async Errors
169 
170When using async runtimes, like Tokio, make sure that your errors implement `Send + Sync + 'static` where needed, specially in tasks or across `.await` boundaries:
171 
172```rust
173#[tokio::main]
174async fn main() -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
175    ...
176    Ok(())
177}
178```
179 
180> Avoid `Box<dyn std::error::Error>` in libraries unless it is really needed
181