Crate rocket[][src]

Rocket - Core API Documentation

Hello, and welcome to the core Rocket API documentation!

This API documentation is highly technical and is purely a reference. There’s an overview of Rocket on the main site as well as a full, detailed guide. If you’d like pointers on getting started, see the quickstart or getting started chapters of the guide.

You may also be interested in looking at the rocket_contrib documentation, which contains automatic JSON (de)serialiazation, templating support, static file serving, and other useful features.

Libraries

Rocket’s functionality is split into two crates:

  1. Core - This core library. Needed by every Rocket application.
  2. Contrib - Provides useful functionality for many Rocket applications. Completely optional.

Usage

Depend on rocket in Rocket.toml:

[dependencies]
rocket = "0.5.0-dev"

See the guide for more information on how to write Rocket applications. Here’s a simple example to get you started:

#[macro_use] extern crate rocket;

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

#[launch]
fn rocket() -> _ {
    rocket::ignite().mount("/", routes![hello])
}

Features

There are two optional, disabled-by-default features:

The features can be enabled in Rocket.toml:

[dependencies]
rocket = { version = "0.5.0-dev", features = ["secrets", "tls"] }

Configuration

By default, Rocket applications are configured via a Rocket.toml file and/or ROCKET_{PARAM} environment variables. For more information on how to configure Rocket, including how to completely customize configuration sources, see the configuration section of the guide as well as the config module documentation.

Testing

The local module contains structures that facilitate unit and integration testing of a Rocket application. The top-level local module documentation and the testing chapter of the guide include detailed examples.

Re-exports

pub use futures;
pub use tokio;
pub use figment;

Modules

catcher

Types and traits for error catchers, error handlers, and their return values.

config

Server and application configuration.

data

Types and traits for handling incoming body data.

error

Types representing various errors that can occur in a Rocket application.

fairing

Fairings: callbacks at attach, launch, request, and response time.

form

Parsing and validation of HTTP forms and fields.

handler

Types and traits for request handlers and their return values.

http

Types that map to concepts in HTTP.

local

Structures for local dispatching of requests, primarily for testing.

outcome

Success, failure, and forward handling.

request

Types and traits for request parsing and handling.

response

Types and traits to build and send responses.

Macros

catchers

Generates a Vec of Catchers from a set of catcher paths.

local_cache

Store and immediately retrieve a value $v in $request’s local cache using a locally generated anonymous type to avoid type conflicts.

msg

A helper macro for custom validation error messages.

routes

Generates a Vec of Routes from a set of route paths.

try_outcome

Unwraps a Success or propagates a Forward or Failure.

uri

Type-safe, URI-safe generation of an Origin URI from a route.

Structs

Catcher

An error catching route.

Config

Rocket server configuration.

Data

Type representing the body data of a request.

Request

The type of an incoming web request.

Response

A response, as returned by types implementing Responder.

Rocket

The main Rocket type: used to mount routes and catchers and launch the application.

Route

A route: a method, its handler, path, rank, and format/media type.

Shutdown

A request guard to gracefully shutdown a Rocket server.

State

Request guard to retrieve managed state.

Functions

custom

Creates a new instance of Rocket with a custom configuration provider: aliases Rocket::custom().

ignite

Creates a new instance of Rocket: aliases Rocket::ignite().

Attribute Macros

async_test
async_trait
catch

Attribute to generate a Catcher and associated metadata.

delete

Attribute to generate a Route and associated metadata.

get

Attribute to generate a Route and associated metadata.

head

Attribute to generate a Route and associated metadata.

launch
main
options

Attribute to generate a Route and associated metadata.

patch

Attribute to generate a Route and associated metadata.

post

Attribute to generate a Route and associated metadata.

put

Attribute to generate a Route and associated metadata.

route

Attribute to generate a Route and associated metadata.

Derive Macros

FromForm

Derive for the FromForm trait.

FromFormField

Derive for the FromFormField trait.

Responder

Derive for the Responder trait.

UriDisplayPath

Derive for the UriDisplay<Path> trait.

UriDisplayQuery

Derive for the UriDisplay<Query> trait.