Overview

A brief look at what makes Rocket special.

Anatomy of a Rocket Application#

Rocket applications are incredibly easy to write! Tab through the examples below to get a glimpse into how a Rocket application is structured.

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
#[get("/")]
fn index() -> &'static str {
   "Hello, world!"
}

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
#[get("/hello/<name>/<age>")]
fn hello(name: &str, age: u8) -> String {
    format!("Hello, {} year old named {}!", age, name)
}

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
#[post("/login", data = "<login>")]
fn login(login: Form<UserLogin>) -> String {
    format!("Hello, {}!", login.name)
}

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
#[get("/sensitive")]
fn sensitive(key: ApiKey) { ... }

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
#[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. Responders 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
#[catch(404)]
fn not_found() -> T { ... }

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
#[launch]
fn rocket() -> _ {
    rocket::build().mount("/base", routes![index, another])
}

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
🚀 Rocket has launched from http://127.0.0.1:8000

How Rocket Works#

Every request received by a Rocket web application follows a simple 3-step process from request to response.

1

Validation

First, Rocket validates a matching request by ensuring that all of the types in a given handler can be derived from the incoming request. If the types cannot be derived, the request is forwarded to the next matching route until a route’s types validate or there are no more routes to try. If all routes fail, a customizable 404 error is returned.

1
2
3
4
#[post("/user", data = "<new_user>")]
fn new_user(admin: AdminUser, new_user: Form<User>) -> T {
   ...
}

For the new_user handler above to be called, the following conditions must hold:

  • The request method must be POST.
  • The request path must be /user.
  • The request must contain data in its body.
  • The request metadata must authenticate an AdminUser.
  • The request body must be a form that parses into a User struct.
2

Processing

Next, the request is processed by an arbitrary handler. This is where most of the business logic in an application resides, and the part of your applications you’ll likely spend the most time writing. In Rocket, handlers are simply functions - that’s it! The only caveat is that the function’s return type must implement the Responder trait. The new_user function above is an example of a handler.

3

Response

Finally, Rocket responds to the client by transforming the return value of the handler into an HTTP response. The HTTP response generated from the returned value depends on the type’s specific Responder trait implementation.

1
fn route() -> T { ... }

If the function above is used as a handler, for instance, then the type T must implement Responder. Rocket provides many useful responder types out of the box. They include:

  • Json<T>: Serializes the structure T into JSON and returns it to the client.
  • Template: Renders a template file and returns it to the client.
  • Redirect: Returns a properly formatted HTTP redirect.
  • NamedFile: Streams a given file to the client with the Content-Type taken from the file’s extension.
  • Stream: Streams data to the client from an arbitrary Read value.
  • Many Primitive Types: String, &str, File, Option, Result, and others all implement the Responder trait.