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.6.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 feature-gates optional functionality, some enabled by default:

Feature	Default?	Description
trace	Yes	Enables the default Rocket tracing subscriber.
http2	Yes	Support for HTTP/2 (enabled by default).
secrets	No	Support for authenticated, encrypted private cookies.
tls	No	Support for TLS encrypted connections.
mtls	No	Support for verified clients via mutual TLS.
json	No	Support for JSON (de)serialization.
msgpack	No	Support for MessagePack (de)serialization.
uuid	No	Support for UUID value parsing and (de)serialization.
tokio-macros	No	Enables the macros feature in the exported tokio
http3-preview	No	Experimental preview support for HTTP/3.

Disabled features can be selectively enabled in Cargo.toml:

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

Conversely, HTTP/2 can be disabled:

[dependencies]
rocket = { version = "0.6.0-dev", 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;
• pub use tracing;
• pub use either;

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.
• listener
• local
  Structures for local dispatching of requests, primarily for testing.
• mtlsmtls
  Support for mutual TLS client certificates.
• outcome
  Success, error, 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.
• shutdown
  Shutdown configuration and notification handle.
• tlstls
• trace

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 occurred during launch or ignition.
• 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.
• Sentry
  Information resolved at compile-time from eligible Sentinel types.
• 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.
• suppress
  Suppress a warning generated by a Rocket lint.

Derive Macros

• FromForm
  Derive for the FromForm trait.
• FromFormField
  Derive for the FromFormField trait.
• FromParam
  Derive for the FromParam trait.
• Responder
  Derive for the Responder trait.
• UriDisplayPath
  Derive for the UriDisplay<Path> trait.
• UriDisplayQuery
  Derive for the UriDisplay<Query> trait.