Skip to main content

Crate rkt

Crate rkt 

Source
Expand description

§rkt - Core API Documentation

Hello, and welcome to the core rkt API documentation!

This API documentation is highly technical and is purely a reference. There’s an overview of rkt 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 rkt in Cargo.toml:

[dependencies]
rkt = { package = version = "1.1.0" }

See the guide for more information on how to write rkt applications. Here’s a simple example to get you started:


#[get("/")]
fn hello() -> &'static str {
    "Hello, world!"
}

#[launch]
fn rocket() -> _ {
    rkt::build().mount("/", routes![hello])
}

§Features

To avoid compiling unused dependencies, rkt feature-gates optional functionality, some enabled by default:

FeatureDefault?Description
traceYesEnables the default rkt tracing subscriber.
http2YesSupport for HTTP/2 (enabled by default).
secretsNoSupport for authenticated, encrypted private cookies.
tlsNoSupport for TLS encrypted connections.
mtlsNoSupport for verified clients via mutual TLS.
jsonNoSupport for JSON (de)serialization.
msgpackNoSupport for MessagePack (de)serialization.
uuidNoSupport for UUID value parsing and (de)serialization.
tokio-macrosNoEnables the macros feature in the exported tokio
http3-previewNoExperimental preview support for HTTP/3.

Disabled features can be selectively enabled in Cargo.toml:

[dependencies]
rkt = { version = "1.1.0", features = ["secrets", "tls", "json"] }

Conversely, HTTP/2 can be disabled:

[dependencies]
rkt = { version = "1.1.0", default-features = false }

§Configuration

rkt offers a rich, extensible configuration system built on Figment. By default, rkt 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 rkt application. The top-level local module documentation and the testing guide include detailed examples.

Re-exports§

pub use either;
pub use figment;
pub use futures;
pub use time;
pub use tokio;
pub use tracing;

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 rkt 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
rkt 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 rkt#build for phase details.
Ignite
The second launch Phase: post-build but pre-orbit. See rkt#ignite for details.
Orbit
The final launch Phase. See rkt#orbit for details.

Traits§

Phase
A marker trait for rkt’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 rkt 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 rkt 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.