Crate rocket

source ·
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.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:

FeatureDescription
secretsSupport for authenticated, encrypted private cookies.
tlsSupport for TLS encrypted connections.
mtlsSupport for verified clients via mutual TLS.
http2Support for HTTP/2 (enabled by default).
jsonSupport for JSON (de)serialization.
msgpackSupport for MessagePack (de)serialization.
uuidSupport 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

Modules

  • Types and traits for error catchers and their handlers and return types.
  • Server and application configuration.
  • Types and traits for handling incoming body data.
  • Types representing various errors that can occur in a Rocket application.
  • Fairings: callbacks at launch, liftoff, request, and response time.
  • Parsing and validation of HTTP forms and fields.
  • File serving, file accepting, and file metadata types.
  • Types that map to concepts in HTTP.
  • Structures for local dispatching of requests, primarily for testing.
  • mtlsmtls
    Support for mutual TLS client certificates.
  • Success, failure, and forward handling.
  • Types and traits for request parsing and handling.
  • Types and traits to build and send responses.
  • Types and traits for routes and their request handlers and return types.
  • Serialization and deserialization support.
  • Security and privacy headers for all outgoing responses.

Macros

  • Generates a Vec of Catchers from a set of catcher paths.
  • Generates a Vec of Routes from a set of route paths.
  • Type-safe, encoding-safe route and non-route URI generation.

Structs

  • An error catching route.
  • Rocket server configuration.
  • Type representing the body data of a request.
  • An error that occurs during launch.
  • The type of an incoming web request.
  • A response, as returned by types implementing Responder.
  • The application server itself.
  • A request handling route.
  • A request guard and future for graceful shutdown.
  • Request guard to retrieve managed state.

Enums

Traits

  • A marker trait for Rocket’s launch phases.
  • An automatic last line of defense against launching an invalid Rocket.

Functions

Attribute Macros

  • Retrofits supports for async fn in unit tests.
  • Retrofits support for async fn in trait impls and declarations.
  • Attribute to generate a Catcher and associated metadata.
  • Attribute to generate a Route and associated metadata.
  • Attribute to generate a Route and associated metadata.
  • Attribute to generate a Route and associated metadata.
  • Generates a main function that launches a returned Rocket<Build>.
  • Retrofits async fn support in main functions.
  • Attribute to generate a Route and associated metadata.
  • Attribute to generate a Route and associated metadata.
  • Attribute to generate a Route and associated metadata.
  • Attribute to generate a Route and associated metadata.
  • Attribute to generate a Route and associated metadata.

Derive Macros