This is a complete Rocket application. It does exactly what you would expect. If you were to visit /hello/John/58, you’d see:
1
Hello, 58 year old named John!
If someone visits a path with an <age>
that isn’t a u8
, Rocket doesn’t naively call hello
. Instead, it tries other matching routes or returns a 404.
1 2 3 4 5 6 7 8 9 10 11
extern crate rocket;
Form handling is simple, declarative, and complete: derive FromForm
for your structure and set the data
parameter to a Form
type. Rocket automatically parses and validates the form data into your structure and calls your function.
File uploads? A breeze with TempFile
. Bad form request? Rocket doesn’t call your function! Need to know what went wrong? Use a data
parameter of Result
! Want to rerender the form with user input and errors? Use Context
!
1 2 3 4 5 6 7 8 9 10 11
Rocket has first-class support for JSON, right out of the box. Simply derive Deserialize
or Serialize
to receive or return JSON, respectively.
Look familiar? Forms, JSON, and all kinds of body data types work through Rocket’s FromData
trait, Rocket’s approach to deriving types from body data. A data
route parameter can be any type that implements FromData
. A value of that type will be deserialized automatically from the incoming request body. You can even implement FromData
for your own types!
1 2 3 4 5 6 7 8 9 10 11 12 13 14
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:
1 2 3 4
This index
route matches any incoming HTTP GET
request to /
, the index. The handler returns a String
. Rocket automatically converts the string into a well-formed HTTP response that includes the appropriate Content-Type
and body encoding metadata.
Rocket automatically parses dynamic data in path segments into any desired type. To illustrate, let's use the following route:
1 2 3 4
This hello
route has two dynamic parameters, identified with angle brackets, declared in the route URI: <name>
and <age>
. Rocket maps each parameter to an identically named function argument: name: &str
and age: u8
. The dynamic data in the incoming request is parsed automatically into a value of the argument's type. The route is called only when parsing succeeds.
Parsing is directed by the FromParam
trait. Rocket implements FromParam
for many standard types, including both &str
and u8
. You can implement it for your own types, too!
Rocket can automatically parse body data, too!
1 2 3 4
The dynamic parameter declared in the data
route attribute parameter again maps to a function argument. Here, login
maps to login: Form<UserLogin>
. Parsing is again trait-directed, this time by the FromData
trait.
The Form
type is Rocket's robust form data parser. It automatically parses the request body into the internal type, here UserLogin
. Other built-in FromData
types include Data
, Json
, and MsgPack
. As always, you can implement FromData
for your own types, too!
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:
1 2
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
:
1 2
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:
1 2
Finally, we get to launch our application! Rocket begins dispatching requests to routes after they've been mounted and the application has been launched. These two steps, usually wrtten in a rocket
function, look like:
1 2 3 4
The mount
call takes a base 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, effectively namespacing the routes. #[launch]
creates a main
function that starts the server. In development, Rocket prints useful information to the console to let you know everything is okay.
1