vld-rocket

Data and request guards for Rocket 0.5, and catchers that turn their failures into the shared JSON error body. Shared behaviour (status codes, error body, coercion, header/cookie rules) is in the web adapters overview.

Install

[dependencies]
vld = "0.5"
vld-rocket = "0.5"
rocket = { version = "0.5", features = ["json"] }

No features. MSRV 1.85 (see MSRV).

Example

use vld_rocket::prelude::*;

vld::schema! {
    #[derive(Debug, Clone)]
    pub struct CreateUser {
        pub name: String  => vld::string().min(2).max(50),
        pub email: String => vld::string().email(),
    }
}

vld::schema! {
    #[derive(Debug, Clone)]
    pub struct UserPath {
        pub id: i64 => vld::number().int().min(1),
    }
}

#[rocket::post("/users", data = "<user>")]
fn create_user(user: VldJson<CreateUser>) -> String {
    format!("created {}", user.name)
}

/// Rocket needs every `<param>` as an argument too; `VldPath` validates them.
#[rocket::get("/users/<id>")]
fn get_user(id: &str, p: VldPath<UserPath>) -> String {
    let _ = id;
    format!("user #{}", p.id)
}

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

The full example is crates/vld-rocket/examples/rocket_basic.rs (cargo run -p vld-rocket --example rocket_basic).

API

Error catchers

A failed guard only sets the status; Rocket renders the response through a catcher. Without vld_catchers() clients get Rocket's default HTML page. The vld catchers answer with the error body the guard stored for that status; when another guard failed with the same status (Rocket's own Json, for example) they answer {"error": "<reason>"}.

Body limits

VldJson reads up to Rocket's json limit and VldForm up to the form limit, configured in Rocket.toml or ROCKET_LIMITS:

[default.limits]
json = "8 MiB"
form = "256 KiB"

While a limit is left at Rocket's built-in default (1 MiB for json, 32 KiB for form), the shared 2 MiB applies instead, like in every other vld adapter.

Gotchas

• Setting a limit to exactly Rocket's built-in value counts as "unset" and gives 2 MiB.
• VldPath works under any mount point (/api/v1/users/<id>), and field names must match the <param> names.
• VldJson / VldForm errors are 415, 413 or 422 like everywhere else, but only become JSON with the catchers registered.