Crate rocket

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.3"

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. With the exception of http2, all are disabled by default:

Feature	Description
secrets	Support for authenticated, encrypted private cookies.
tls	Support for TLS encrypted connections.
mtls	Support for verified clients via mutual TLS.
http2	Support for HTTP/2 (enabled by default).
json	Support for JSON (de)serialization.
msgpack	Support for MessagePack (de)serialization.
uuid	Support for UUID value parsing and (de)serialization.

Disabled features can be selectively enabled in Cargo.toml:

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

Conversely, HTTP/2 can be disabled:

[dependencies]
rocket = { version = "=0.5.0-rc.3", default-features = false }

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;
• pub use time;

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.
• mtlsmtls
  Support for mutual TLS client certificates.
• 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
  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. See Rocket#build for phase details.
• Ignite
  The second launch Phase: post-build but pre-orbit. See Rocket#ignite for details.
• Orbit
  The final launch Phase. See Rocket#orbit for details.

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().
• execute
  Executes a future to completion on a new tokio-based Rocket async runtime.

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.