Rocket's main task is to route incoming requests to the appropriate request handler using your application's declared routes. Routes are declared using Rocket's route attributes. The attribute describes the requests that match the route. The attribute is placed on top of a function that is the request handler for that route.
As an example, consider the simple route below:
| #[get("/")]
fn index() -> &'static str {
"Hello, world!"
}
|
This route, named index
, will match against incoming HTTP GET
requests to the /
path, the index. The request handler returns a string. Rocket will use the string as the body of a fully formed HTTP response.
Rocket allows you to interpret segments of a request path dynamically. To illustrate, let's use the following route:
| #[get("/hello/<name>/<age>")]
fn hello(name: &str, age: u8) -> String {
format!("Hello, {} year old named {}!", age, name)
}
|
The hello
route above matches two dynamic path segments declared inside brackets in the path: <name>
and <age>
. Dynamic means that the segment can be any value the end-user desires.
Each dynamic parameter (name
and age
) must have a type, here &str
and u8
, respectively. Rocket will attempt to parse the string in the parameter's position in the path into that type. The route will only be called if parsing succeeds. To parse the string, Rocket uses the FromParam trait, which you can implement for your own types!
Request body data is handled in a special way in Rocket: via the FromData trait. Any type that implements FromData
can be derived from incoming body data. To tell Rocket that you're expecting request body data, the data
route argument is used with the name of the parameter in the request handler:
| #[post("/login", data = "<user_form>")]
fn login(user_form: Form<UserLogin>) -> String {
// Use `user_form`, return a String.
}
|
The login
route above says that it expects data
of type Form<UserLogin>
in the user_form
parameter. The Form type is a built-in Rocket type that knows how to parse web forms into structures. Rocket will automatically attempt to parse the request body into the Form
and call the login
handler if parsing succeeds. Other built-in FromData
types include Data
, Json
, and Flash
In addition to dynamic path and data parameters, request handlers can also contain a third type of parameter: request guards. Request guards aren't declared in the route attribute, and any number of them can appear in the request handler signature.
Request guards protect the handler from running unless some set of conditions are met by the incoming request metadata. For instance, if you are writing an API that requires sensitive calls to be accompanied by an API key in the request header, Rocket can protect those calls via a custom ApiKey
request guard:
| #[get("/sensitive")]
fn sensitive(key: ApiKey) -> &'static str { ... }
|
ApiKey
protects the sensitive
handler from running incorrectly. In order for Rocket to call the sensitive
handler, the ApiKey
type needs to be derived through a FromRequest implementation, which in this case, validates the API key header. Request guards are a powerful and unique Rocket concept; they centralize application policy and invariants through types.
The return type of a request handler can be any type that implements Responder:
| #[get("/")]
fn route() -> T { ... }
|
Above, T must implement Responder
. Rocket implements Responder
for many of the standard library types including &str
, String
, File
, Option
, and Result
. Rocket also implements custom responders such as Redirect, Flash, and Template.
The task of a Responder
is to generate a Response
, if possible. Responder
s can fail with a status code. When they do, Rocket calls the corresponding error catcher, a catch
route, which can be declared as follows:
| #[catch(404)]
fn not_found() -> T { ... }
|
Launching a Rocket application is the funnest part! For Rocket to begin dispatching requests to routes, the routes need to be mounted. After mounting, the application needs to be launched. These two steps, usually done in main
, look like:
| rocket::ignite()
.mount("/base", routes![index, another])
.launch()
|
The mount
call takes a base path and a set of routes via the routes!
macro. The base path (/base
above) is prepended to the path of every route in the list. This effectively namespaces the routes, allowing for easier composition.
The launch
call starts the server. In development, Rocket prints useful information to the console to let you know everything is okay.
| 🚀 Rocket has launched from http://localhost:8000...
|