Rocket Web Framework

Rocket provides specific examples for individual features to help you understand their implementation details:

• config: Extracting values from Figment, using AdHoc::config() to store application-specific configuration in managed state, and setting values in Rocket.toml.
• cookies: Implementing client-side message boxes and using private cookies for session-based authentication.
• databases: Implementing CRUD APIs backed by SQLite using sqlx, diesel, or rusqlite. Demonstrates using rocket_db_pools (for sqlx) and rocket_sync_db_pools (for diesel/rusqlite), including automatic migrations.
• error-handling: Using scoped catchers and customizing error displays.
• fairings: Creating custom fairings (e.g., a Counter) and using AdHoc fairings.
• forms: Handling multipart file uploads, ad-hoc validations, field renaming, and staged forms using form context.
• hello: Core features including route declaration (path and query parameters), mounting, launching, testing, and returning simple responses.
• manual-routing: Implementing routing without Rocket's codegen (use with caution as it bypasses some automatic security guarantees).
• responders: Using built-in responders like Stream, Redirect, File, NamedFile, content (for manual Content-Types), and Either. Also shows custom derived Responder implementations and using TempFile for uploads.
• serialization: JSON and MessagePack (de)serialization, including UUID parsing support.
• state: Using request-local state for caching per-request operations and managed state for global data like hit counters or concurrent queues.
• static-files: Serving static files using FileServer or manual safe implementations.
• templating: Using contrib templates support with handlebars or tera.
• testing: Using Rocket's local libraries and the async Client to test applications.
• tls: Configuring TLS with various key pair types.
• upgrade: Implementing WebSocket support using the connection upgrade API and tungstenite.

Rocket supports complex, nested form data using dot notation (.) or bracket notation ([]).

Nesting

To parse nested structs, use parent.child or parent[child] syntax.

Vectors

To parse into a Vec<T>, use name[$k] where $k is a key. If the key is the same as the previous one, the value is pushed to the current element; otherwise, a new element is created. name[] (empty key) always creates a new element.

Maps

To parse into a HashMap<K, V>, use name[$key]. Unlike vectors, the key $key is semantically meaningful and is stored in the map. If the key is a complex type (a struct), use name[k:$key].field to define the key's components.

// Nesting example
#[derive(FromForm)]
struct MyForm<'r> {
    owner: Person<'r>,
    pet: Pet<'r>,
}
// Form fields: owner.name=Bob&pet.name=Sally

// Vector example
#[derive(FromForm)]
struct MyForm {
    numbers: Vec<usize>,
}
// Form fields: numbers[]=1&numbers[]=2

// Map example
#[derive(FromForm)]
struct MyForm {
    ids: HashMap<String, usize>,
}
// Form fields: ids[a]=1&ids[b]=2

When a parameter type mismatch occurs (e.g., a route expects a u8 but receives a string), Rocket forwards the request to the next matching route. This process continues in increasing rank order until a route succeeds or no more matching routes exist. If no routes match, the error catcher associated with the last forwarding guard's status is called.

To prevent a route from forwarding on a type mismatch, you can use Result or Option types in the handler signature. Using Result<T, E> or Option<T> catches the failure within that specific route instead of triggering a forward to the next rank.

#[get("/hello/<name>/<age>/<cool>")]
fn hello(name: &str, age: u8, cool: bool) { /* ... */ }

// If 'age' is not a u8, Rocket forwards to the next route with a matching path.
// To catch the error instead of forwarding, use:
#[get("/hello/<name>/<age>/<cool>")]
fn hello(name: &str, age: Result<u8, &str>, cool: bool) { /* ... */ }

Managed state allows you to maintain data that is accessible throughout your entire application. Rocket manages state on a per-type basis: you can only manage at most one value of any given type.

Requirements:

• All managed state must be thread-safe (must implement Send + Sync) because Rocket parallelizes request handling.

Workflow:

1. Add State: Call .manage(value) on your Rocket instance during initialization. Each call must use a different type.
2. Retrieve State: Add &State<T> as an argument to any request handler, where T is the type of the managed value.

use std::sync::atomic::AtomicUsize;

struct HitCount {
    count: AtomicUsize
}

// 1. Adding State
rocket::build().manage(HitCount { count: AtomicUsize::new(0) });

// 2. Retrieving State
use rocket::State;

#[get("/count")]
fn count(hit_count: &State<HitCount>) -> String {
    let current_count = hit_count.count.load(std::sync::atomic::Ordering::Relaxed);
    format!("Number of visits: {}", current_count)
}