Parial Update for docs

Author: the10thWiz

docs/guide/01-upgrading.md

@@ -6,6 +6,61 @@ summary = "a migration guide from Rocket v0.5 to v0.6"
 
 This a placeholder for an eventual migration guide from v0.5 to v0.6.
 
+## Typed Errors and Catchers
+
+Whenever a guard fails with a type, such as a `FromParam`, `FromRequest`, etc
+implementation, the error type is boxed up, and can be retrieved by catchers.
+This well-requested feature makes providing useful error types much easier.
+
+The following example mounts a single route, and a catcher that will catch any
+invalid integer parameters. The catcher then formats the error into a JSON
+object and returns it.
+
+TODO: add tests, and make this run?
+```rust,no_run
+# #[macro_use] extern crate rocket;
+use std::num::ParseIntError;
+
+use rocket::Responder;
+use rocket::serde::{Serialize, json::Json};
+use rocket::request::FromParamError;
+
+#[derive(Responder)]
+#[response(status = 422)]
+struct ParameterError<T>(T);
+
+#[derive(Serialize)]
+#[serde(crate = "rocket::serde")]
+struct ErrorInfo<'a> {
+    invalid_value: &'a str,
+    description: String,
+}
+
+#[catch(422, error = "<int_error>")]
+fn catch_invalid_int<'a>(
+    // `&ParseIntError` would also work here, but `&FromParamError<ParseIntError>`
+    // also gives us access to `raw`, the specific segment that failed to parse.
+    int_error: &FromParamError<'a, ParseIntError>
+) -> ParameterError<Json<ErrorInfo<'a>>> {
+    ParameterError(Json(ErrorInfo {
+        invalid_value: int_error.raw,
+        description: format!("{}", int_error.error),
+    }))
+}
+
+/// A simple route with a single parameter. If you pass this a valid `u8`,
+/// it will return a string. However, if you pass it something invalid as a `u8`,
+/// such as `-1`, `1234`, or `apple`, the catcher above will be respond with
+/// details on the error.
+#[get("/<number>")]
+fn number(number: u8) -> String {
+    format!("You selected {}", number)
+}
+```
+
+To see a full demonstration of this feature, check out the error-handling
+(TODO: link) example.
+
 ## Getting Help
 
 If you run into any issues upgrading, we encourage you to ask questions via

docs/guide/05-requests.md

@@ -519,22 +519,57 @@ As an example, for the `User` guard above, instead of allowing the guard to
 forward in `admin_panel_user`, we might want to detect it and handle it
 dynamically:
 
+TODO: typed: This would actually make much more sense via a typed catcher
+
 ```rust
 # #[macro_use] extern crate rocket;
 # fn main() {}
 
+use rocket::response::Redirect;
+use rocket::request::{self, Request, FromRequest, Outcome};
+use rocket::either::Either;
+use rocket::http::Status;
+
 # type Template = ();
-# type AdminUser = rocket::http::Method;
-# type User = rocket::http::Method;
+// # type AdminUser = rocket::http::Method;
+// # type User = rocket::http::Method;
 # #[get("/login")]
 # fn login() -> Template { /* .. */ }
+# fn is_logged_in_as_admin(r: &Request<'_>) -> bool { true }
+# fn is_logged_in(r: &Request<'_>) -> bool { true }
+
+#[derive(Debug, TypedError)]
+enum LoginError {
+    NotLoggedIn,
+    NotAdmin,
+}
+
+struct AdminUser {}
+#[async_trait]
+impl<'r> FromRequest<'r> for AdminUser {
+    type Error = LoginError;
+    async fn from_request(r: &'r Request<'_>) -> Outcome<Self, Self::Error> {
+        if is_logged_in_as_admin(r) {
+            Outcome::Success(Self {})
+        } else if is_logged_in(r) {
+            Outcome::Error((Status::Unauthorized, LoginError::NotAdmin))
+        } else {
+            Outcome::Error((Status::Unauthorized, LoginError::NotLoggedIn))
+        }
+    }
+}
 
-use rocket::response::Redirect;
+#[get("/admin")]
+fn admin_panel(user: AdminUser) -> &'static str {
+    "Welcome to the admin panel"
+}
 
-#[get("/admin", rank = 2)]
-fn admin_panel_user(user: Option<User>) -> Result<&'static str, Redirect> {
-    let user = user.ok_or_else(|| Redirect::to(uri!(login)))?;
-    Ok("Sorry, you must be an administrator to access this page.")
+#[catch(401, error = "<e>")]
+fn catch_login_error(e: &LoginError) -> Either<&'static str, Redirect> {
+    match e {
+        LoginError::NotLoggedIn => Either::Right(Redirect::to(uri!(login))),
+        LoginError::NotAdmin => Either::Left("Admin permissions are required to view this page."),
+    }
 }
 ```
 

docs/guide/06-responses.md

@@ -318,15 +318,14 @@ async fn files(file: PathBuf) -> Option<NamedFile> {
 
 ### `Result`
 
-`Result` is another _wrapping_ responder: a `Result<T, E>` can only be returned
-when `T` implements `Responder` and `E` implements `Responder`.
+`Result` is a special responder, used to throw typed errors, so that they can
+later be caught by a typed catcher. `Result<T, E>` can only be used as a
+responder when `T` implements `Responder` and `E` implements `TypedError`.
 
-The wrapped `Responder` in `Ok` or `Err`, whichever it might be, is used to
-respond to the client. This means that the responder can be chosen dynamically
-at run-time, and two different kinds of responses can be used depending on the
-circumstances. Revisiting our file server, for instance, we might wish to
-provide more feedback to the user when a file isn't found. We might do this as
-follows:
+The wrapped `Responder` in `Ok` will be used to respond directly to the client,
+but an `Err` value can be caught by a typed catcher. Revisiting our file server,
+for instance, we might wish to format error values when the file isn't found.
+We might do this as follows:
 
 ```rust
 # #[macro_use] extern crate rocket;
@@ -336,10 +335,17 @@ follows:
 use rocket::fs::NamedFile;
 use rocket::response::status::NotFound;
 
+// `NotFound` is a wrapper over either responders or typed errors, that
+// sets the status to 404.
 #[get("/<file..>")]
-async fn files(file: PathBuf) -> Result<NamedFile, NotFound<String>> {
+async fn files(file: PathBuf) -> Result<NamedFile, NotFound<std::io::Error>> {
     let path = Path::new("static/").join(file);
-    NamedFile::open(&path).await.map_err(|e| NotFound(e.to_string()))
+    NamedFile::open(&path).await.map_err(|e| NotFound(e))
+}
+
+#[catch(404, error = "<e>")]
+fn catch_std_io(e: &std::io::Error) -> String {
+    format!("{}", e)
 }
 ```