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.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. 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.1", features = ["secrets", "tls", "json"] }
Conversely, HTTP/2 can be disabled:
[dependencies]
rocket = { version = "0.5.1", 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.
- mtls
mtls
Support for mutual TLS client certificates. - Success, error, 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
ofCatcher
s from a set of catcher paths. - Generates a
Vec
ofRoute
s 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§
- The initial launch
Phase
. See Rocket#build for phase details. - The second launch
Phase
: post-build but pre-orbit. See Rocket#ignite for details. - The final launch
Phase
. See Rocket#orbit for details.
Traits§
- A marker trait for Rocket’s launch phases.
- An automatic last line of defense against launching an invalid
Rocket
.
Functions§
- Creates a
Rocket
instance with the default config provider: aliasesRocket::build()
. - Creates a
Rocket
instance with a custom config provider: aliasesRocket::custom()
. - Executes a
future
to completion on a new tokio-based Rocket async runtime.
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 returnedRocket<Build>
. - Retrofits
async fn
support inmain
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§
- Derive for the
FromForm
trait. - Derive for the
FromFormField
trait. - Derive for the
Responder
trait. - Derive for the
UriDisplay<Path>
trait. - Derive for the
UriDisplay<Query>
trait.