From 1c00793d0df937571b55fc0bdb1e661c0b59b824 Mon Sep 17 00:00:00 2001 From: Sergio Benitez Date: Tue, 13 Sep 2016 16:32:57 -0700 Subject: [PATCH] Add overview to README. --- README.md | 32 ++++++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) diff --git a/README.md b/README.md index e1216243..30d211cf 100644 --- a/README.md +++ b/README.md @@ -26,6 +26,38 @@ route resulting in the string `Hello, 58 year old named John!` being sent to the browser. If an `` string was passed in that can't be parsed as a `u8`, the route won't get called, resulting in a 404 error. +## Overview + +Rocket employs code generation to remove the need for boilerplate involved with +parsing requests and request parameters, prevent invalid and/or incorrect +requests from invoking a user's request handler, and allow the user to define +what is valid and/or correct. + +Rocket uses type _guards_, or _constraints_, on request handlers to +accomplishing it's safety and correctness goals. In Rocket, handlers are _only_ +invoked if all types that appear in the request handler's argument list can be +derived from the incoming request. + +In their simplest incarnation, guards can be types expected of parameters in a +matched path. This is illustrated in the previous example where the `hello` +request handler is only be invoked if the dynamic path parameter `` parses +as a `u8`. Guards can also be derived directly from a request. For instance, you +can define an `AdminUser` type that can be derived only if the proper cookies +were sent along with the request. Then, by simply including the type in a +handler's argument list as follows: + + #[get("/admin/post/")] + fn admin(user: AdminUser, id: isize) -> { .. } + +you can be assured that the handler will be invoked _only_ if an administrative +user is logged in. Any number of such guards can be included. For example, to +retrieve the request's cookies along with the admin user, simply include the +`&Cookies` type in the argument list: + + #[get("/admin/post/")] + fn admin(user: AdminUser, cookies: &Cookies, id: isize) -> { .. } + +Full documentation about built-in request guards is coming soon. ## Building