introduce Error::Simple and Error::Response

bump version to 0.2.2

1 files changed, 31 insertions, 3 deletions

diff --git a/README.md b/README.md
index ff001c9..2b006e6 100644
--- a/README.md
+++ b/README.md
@@ -10,7 +10,8 @@ Sputnik provides:
       (powered by the [cookie](https://crates.io/crates/cookie) crate)
     * parse query strings and HTML form data (powered by the
       [serde_urlencoded](https://crates.io/crates/serde_urlencoded) crate)
-* an `Error` struct that makes it easy to centrally control the presentation of all error messages
+* [an `Error` enum](#error-handling) that makes it easy to centrally control
+  the presentation of all error messages
 * cookie-based [CSRF](https://en.wikipedia.org/wiki/Cross-site_request_forgery) tokens
 * `Key`: a convenience wrapper around HMAC (stolen from the cookie crate, so
   that you don't have to use `CookieJar`s if you don't need them)
@@ -25,6 +26,28 @@ Sputnik does **not**:
 * handle persistence: we recommend [diesel](https://diesel.rs/)
 * handle templating: we recommend [maud](https://maud.lambda.xyz/)
 
+## Error handling
+
+Sputnik defines the following error types:
+
+```rust
+pub struct SimpleError {
+    pub code: StatusCode,
+    pub message: String,
+}
+
+pub enum Error {
+    Simple(SimpleError),
+    Response(hyper::Response<hyper::Body>),
+}
+```
+
+Sputnik implements `Into<Error::Simple>` for all of its client error types
+(e.g. deserialization errors), allowing you to easily customize the error
+presentation. Sometimes however a `SimpleError` doesn't suffice, e.g. you
+might want to redirect unauthorized users to your login page instead of
+showing them an error, for such cases you can return an `Error::Response`.
+
 ## CsrfToken example
 
 ```rust
@@ -67,8 +90,13 @@ async fn service(req: hyper::Request<hyper::Body>) -> Result<hyper::Response<hyp
     let (mut parts, body) = sputnik::request::adapt(req);
     match route(&mut parts, body).await {
         Ok(res) => Ok(res.into()),
-        Err(err) => Ok(err.response_builder().body(err.message.into()).unwrap())
-        // you can easily wrap or log errors here
+        Err(err) => match err {
+            Error::Simple(err) => {
+                Ok(err.response_builder().body(err.message.into()).unwrap())
+                // you can easily wrap or log errors here
+            }
+            Error::Response(err) => Ok(err)
+        }
     }
 }