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