Rocket Core Knowledge

Full Reference: See advanced.md for custom guards (authentication, API key), fairings (CORS, timing), database state, error catchers, and testing patterns.

Deep Knowledge: Use mcp__documentation__fetch_docs with technology: rocket for comprehensive documentation.

Basic Setup

Cargo.toml

[dependencies] rocket = { version = "0.5", features = ["json"] } serde = { version = "1", features = ["derive"] } serde_json = "1" tokio = { version = "1", features = ["full"] }

#[macro_use] extern crate rocket;

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

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

Routing

#[get("/users/<id>")] fn get_user(id: u32) -> String { format!("User {}", id) }

#[post("/users", data = "<user>")] fn create_user(user: Json<CreateUser>) -> Json<User> { Json(User::from(user.into_inner())) }

#[get("/files/<path..>")] fn get_file(path: PathBuf) -> Option<NamedFile> { NamedFile::open(Path::new("static/").join(path)).ok() }

// Query parameters #[derive(FromForm)] struct Pagination { page: Option<u32>, per_page: Option<u32> }

#[get("/users?<pagination..>")] fn list_users(pagination: Pagination) -> Json<Vec<User>> { let page = pagination.page.unwrap_or(1); Json(fetch_users(page, pagination.per_page.unwrap_or(20))) }

// Mounting #[launch] fn rocket() -> _ { rocket::build() .mount("/", routes![index]) .mount("/api/v1", routes![list_users, get_user, create_user]) }

Request Guards

// JSON body #[post("/users", data = "<user>")] fn create_user(user: Json<CreateUser>) -> Json<User> { Json(User::from(user.into_inner())) }

// Form data #[post("/login", data = "<login>")] fn login(login: Form<LoginForm>) -> String { format!("Welcome, {}", login.username) }

// Cookies #[get("/session")] fn session(cookies: &CookieJar<'_>) -> Option<String> { cookies.get("session_id").map(|c| c.value().to_string()) }

State Management

use std::sync::atomic::{AtomicU64, Ordering};

struct HitCount(AtomicU64);

#[get("/count")] fn count(hit_count: &State<HitCount>) -> String { let count = hit_count.0.fetch_add(1, Ordering::Relaxed); format!("Hits: {}", count) }

#[launch] fn rocket() -> _ { rocket::build() .manage(HitCount(AtomicU64::new(0))) .mount("/", routes![count]) }

Fairings (Middleware)

use rocket::fairing::AdHoc;

#[launch] fn rocket() -> _ { rocket::build() .attach(AdHoc::on_liftoff("Liftoff", |_| Box::pin(async { println!("Rocket has launched!"); }))) }

When NOT to Use This Skill

• Axum projects - Axum integrates better with Tower ecosystem

• Actix-web projects - Actix has more performance optimizations

• Stable Rust requirement - Rocket requires nightly (though v0.5 works on stable)

Anti-Patterns

Anti-Pattern Why It's Bad Solution

Using Outcome::Forward everywhere Routes become hard to trace Use specific error types

Not using request guards Repetitive validation code Create custom FromRequest guards

Mutable state without sync primitives Data races Use Mutex or RwLock with State

No database connection pooling Resource exhaustion Use rocket_db_pools

Hardcoded secrets in Rocket.toml Security risk Use environment variables

Quick Troubleshooting

Problem Diagnosis Fix

"Use of unstable library feature" Wrong Rust version Install nightly or use Rocket 0.5+

Route not matching Rank conflict Specify rank attribute or reorder routes

Guard returns error Validation failed Check guard implementation logic

Database error on startup Wrong connection string Verify Rocket.toml database config

CORS issues No fairing Add CORS fairing with proper config

Production Checklist

• Rocket.toml configured for production

• CORS fairing attached

• Custom error catchers registered

• Request guards for authentication

• Database pool configured

• Health/readiness endpoints

• Secret key set for release

Reference Documentation

• Guards

• Fairings