Crate rocket[][src]

Expand description

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.

Usage

Depend on rocket in Cargo.toml:

[dependencies]
rocket = "0.5.0-dev"

Note that development versions, tagged with -dev, are not published and need to be specified as git dependencies.

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::build().mount("/", routes![hello])
}

Features

To avoid compiling unused dependencies, Rocket gates certain features, all of which are disabled by default:

FeatureDescription
secretsSupport for authenticated, encrypted private cookies.
tlsSupport for TLS encrypted connections.
jsonSupport for JSON (de)serialization.
msgpackSupport for MessagePack (de)serialization.
uuidSupport for UUID value parsing and (de)serialization.

Features can be selectively enabled in Cargo.toml:

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

Configuration

Rocket offers a rich, extensible configuration system built on Figment. By default, Rocket applications are configured via a Rocket.toml file and/or ROCKET_{PARAM} environment variables, but applications may configure their own sources. See the configuration guide for full details.

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 guide include detailed examples.

Re-exports

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

Modules

catcher

Types and traits for error catchers and their handlers and return types.

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 launch, liftoff, request, and response time.

form

Parsing and validation of HTTP forms and fields.

fs

File serving, file accepting, and file metadata types.

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.

route

Types and traits for routes and their request handlers and return types.

serde

Automatic serialization and deserialization support.

shield

Security and privacy headers for all outgoing responses.

Macros

catchers

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

routes

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

uri

Type-safe, encoding-safe route and non-route URI generation.

Structs

Catcher

An error catching route.

Config

Rocket server configuration.

Data

Type representing the body data of a request.

Error

An error that occurs during launch.

Request

The type of an incoming web request.

Response

A response, as returned by types implementing Responder.

Rocket

The application server itself.

Route

A request handling route.

Shutdown

A request guard and future for graceful shutdown.

State

Request guard to retrieve managed state.

Enums

Build

The initial launch Phase.

Ignite

The second launch Phase: post-build but pre-orbit.

Orbit

The final launch Phase.

Traits

Phase

A marker trait for Rocket’s launch phases.

Sentinel

An automatic last line of defense against launching an invalid Rocket.

Functions

build

Creates a Rocket instance with the default config provider: aliases Rocket::build().

custom

Creates a Rocket instance with a custom config provider: aliases Rocket::custom().

Attribute Macros

async_test

Retrofits supports for async fn in unit tests.

async_trait

Retrofits support for async fn in trait impls and declarations.

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

Generates a main function that launches a returned Rocket<Build>.

main

Retrofits async fn support in main functions.

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.