Guide

The ins and outs of Rocket, in detail.

Overview#

Rocket provides primitives to build web servers and applications with Rust: the rest is up to you. In short, Rocket provides routing, pre-processing of requests, and post-processing of responses. Your application code instructs Rocket on what to pre-process and post-process and fills the gaps between pre-processing and post-processing.

Lifecycle#

Rocket’s main task is to listen for incoming web requests, dispatch the request to the application code, and return a response to the client. We call the process that goes from request to response: the lifecycle. We summarize the lifecycle as the sequence of steps:

  1. Routing

    Rocket parses an incoming HTTP request into native structures that your code operates on indirectly. Rocket determines which request handler to invoke by matching against route attributes declared by the application.

  2. Validation

    Rocket validates the incoming request against types and request guards present in the matched route. If validation fails, Rocket forwards the request to the next matching route or calls an error handler.

  3. Processing

    The request handler associated with the route is invoked with validated arguments. This is the main business logic of the application. Processing completes by returning a Response.

  4. Response

    The returned Response is processed. Rocket generates the appropriate HTTP response and sends it to the client. This completes the lifecycle. Rocket continues listening for requests, restarting the lifecycle for each incoming request.

The remainder of this section details the routing phase as well as additional components needed for Rocket to begin dispatching requests to request handlers. The sections following describe the request and response phases.

Routing#

Rocket applications are centered around routes and handlers.

A handler is simply a function that takes an arbitrary number of arguments and returns any arbitrary type. A route is a combination of:

The parameters to match against include static paths, dynamic paths, path segments, forms, query strings, request format specifiers, and body data. Rocket uses attributes, which look like function decorators in other languages, to make declaring routes easy. Routes are declared by annotating a function, the handler, with the set of parameters to match against. A complete route declaration looks like this:

1
2
3
4
#[get("/world")]              // <- route attribute
fn world() -> &'static str {  // <- request handler
    "Hello, world!"
}

This declares the world route to match against the static path "/world" on incoming GET requests. The world route is simple, but additional route parameters are necessary when building more interesting applications. The Requests section describes the available options for constructing routes.

Mounting#

Before Rocket can dispatch requests to a route, the route needs to be mounted. Mounting a route is like namespacing it. Routes are mounted via the mount method on a Rocket instance. Rocket instances can be created with the ignite() static method.

The mount method takes 1) a path to namespace a list of routes under, and 2) a list of route handlers through the routes! macro. The routes! macro ties Rocket’s code generation to your application.

For instance, to mount the world route we declared above, we would use the following code:

1
rocket::ignite().mount("/hello", routes![world])

Altogether, this creates a new Rocket instance via the ignite function and mounts the world route to the "/hello" path. As a result, GET requests to the "/hello/world" path will be directed to the world function.

Launching#

Now that Rocket knows about the route, you can tell Rocket to start accepting requests via the launch method. The method starts up the server and waits for incoming requests. When a request arrives, Rocket finds the matching route and dispatches the request to the route’s handler.

We typically call launch from the main function. Our complete Hello, world! application thus looks like:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
#![feature(plugin)]
#![plugin(rocket_codegen)]

extern crate rocket;

#[get("/world")]
fn world() -> &'static str {
    "Hello, world!"
}

fn main() {
    rocket::ignite().mount("/hello", routes![world]).launch();
}

Note that we’ve added the #![feature(plugin)] and #![plugin(rocket_codegen)] lines to tell Rust that we’ll be using Rocket’s code generation plugin. We’ve also imported the rocket crate into our namespace via extern crate rocket. Finally, we call the launch method in the main function.

Running the application, the console shows:

1
2
3
4
5
6
🔧  Configured for development.
    => listening: localhost:8000
    => logging: Normal
🛰  Mounting '/world':
    => GET /hello/world
🚀  Rocket has launched from http://localhost:8000...

If we visit localhost:8000/hello/world, we see Hello, world!, exactly as we expected.

A version of this example’s complete crate, ready to cargo run, can be found on GitHub. You can find dozens of other complete examples, spanning all of Rocket’s features, in the GitHub examples directory.

Configuration#

At any point in time, a Rocket application is operating in a given configuration environment. There are three such environments:

Without any action, Rocket applications run in the development environment. The environment can be changed via the ROCKET_ENV environment variable. For example, to launch the Hello, world! application in the staging environment, we can run:

1
ROCKET_ENV=stage cargo run

You’ll likely need sudo for the command to succeed since staging defaults to listening on port 80. Note that you can use the short or long form of the environment name to specify the environment, stage or staging here. Rocket tells us the environment we have chosen and its configuration when it launches:

1
2
3
4
5
6
7
8
$ sudo ROCKET_ENV=staging cargo run

🔧  Configured for staging.
    => listening: 0.0.0.0:80
    => logging: Normal
🛰  Mounting '/':
    => GET /
🚀  Rocket has launched from http://0.0.0.0:80...

We can change these settings via the Rocket.toml configuration file. For example, to make Rocket listen on port 4000 when staging, we create a Rocket.toml file in the root of our Cargo project (in the same directory as the Cargo.toml file) with the following contents:

1
2
[staging]
port = 4000

The changes are reflected when the application is run in staging mode once again:

1
2
3
4
5
$ ROCKET_ENV=stage cargo run

🔧  Configured for staging.
    => listening: 0.0.0.0:4000
   ...

The key/value pairs in the Rocket.toml file can be used to redefine the default values for address, port, and log. Additionally, any number of extra key/value pairs are allowed. Although they aren’t used by Rocket, these extra values can be read by external libraries and used for configuration. The config API documentation describes configuration in further detail.