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-rc.1"

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:

Feature	Description
`secrets`	Support for authenticated, encrypted private cookies.
`tls`	Support for TLS encrypted connections.
`json`	Support for JSON (de)serialization.
`msgpack`	Support for MessagePack (de)serialization.
`uuid`	Support for UUID value parsing and (de)serialization.

Features can be selectively enabled in Cargo.toml:

[dependencies]
rocket = { version = "0.5.0-rc.1", 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 `Catcher`s from a set of catcher paths.
routes	Generates a `Vec` of `Route`s 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.