pub trait FromData<'r>: Sized {
type Error: Send + Debug;
// Required method
fn from_data<'life0, 'async_trait>(
req: &'r Request<'life0>,
data: Data<'r>
) -> Pin<Box<dyn Future<Output = Outcome<'r, Self>> + Send + 'async_trait>>
where Self: 'async_trait,
'r: 'async_trait,
'life0: 'async_trait;
}Expand description
Trait implemented by data guards to derive a value from request body data.
Data Guards
A data guard is a guard that operates on a request’s body data. Data guards
validate and parse request body data via implementations of FromData. In
other words, a type is a data guard iff it implements FromData.
Data guards are the target of the data route attribute parameter:
#[post("/submit", data = "<var>")]
fn submit(var: DataGuard) { /* ... */ }A route can have at most one data guard. Above, var is used as the
argument name for the data guard type DataGuard. When the submit route
matches, Rocket will call the FromData implementation for the type T.
The handler will only be called if the guard returns successfully.
Async Trait
FromData is an async trait. Implementations of FromData must be
decorated with an attribute of #[rocket::async_trait]:
use rocket::request::Request;
use rocket::data::{self, Data, FromData};
#[rocket::async_trait]
impl<'r> FromData<'r> for MyType {
type Error = MyError;
async fn from_data(req: &'r Request<'_>, data: Data<'r>) -> data::Outcome<'r, Self> {
/* .. */
}
}Example
Say that you have a custom type, Person:
struct Person<'r> {
name: &'r str,
age: u16
}Person has a custom serialization format, so the built-in Json type
doesn’t suffice. The format is <name>:<age> with Content-Type: application/x-person. You’d like to use Person as a data guard, so that
you can retrieve it directly from a client’s request body:
#[post("/person", data = "<person>")]
fn person(person: Person<'_>) -> &'static str {
"Saved the new person to the database!"
}A FromData implementation for such a type might look like:
use rocket::request::{self, Request};
use rocket::data::{self, Data, FromData, ToByteUnit};
use rocket::http::{Status, ContentType};
#[derive(Debug)]
enum Error {
TooLarge,
NoColon,
InvalidAge,
Io(std::io::Error),
}
#[rocket::async_trait]
impl<'r> FromData<'r> for Person<'r> {
type Error = Error;
async fn from_data(req: &'r Request<'_>, data: Data<'r>) -> data::Outcome<'r, Self> {
use Error::*;
use rocket::outcome::Outcome::*;
// Ensure the content type is correct before opening the data.
let person_ct = ContentType::new("application", "x-person");
if req.content_type() != Some(&person_ct) {
return Forward(data);
}
// Use a configured limit with name 'person' or fallback to default.
let limit = req.limits().get("person").unwrap_or(256.bytes());
// Read the data into a string.
let string = match data.open(limit).into_string().await {
Ok(string) if string.is_complete() => string.into_inner(),
Ok(_) => return Failure((Status::PayloadTooLarge, TooLarge)),
Err(e) => return Failure((Status::InternalServerError, Io(e))),
};
// We store `string` in request-local cache for long-lived borrows.
let string = request::local_cache!(req, string);
// Split the string into two pieces at ':'.
let (name, age) = match string.find(':') {
Some(i) => (&string[..i], &string[(i + 1)..]),
None => return Failure((Status::UnprocessableEntity, NoColon)),
};
// Parse the age.
let age: u16 = match age.parse() {
Ok(age) => age,
Err(_) => return Failure((Status::UnprocessableEntity, InvalidAge)),
};
Success(Person { name, age })
}
}
// The following routes now typecheck...
#[post("/person", data = "<person>")]
fn person(person: Person<'_>) { /* .. */ }
#[post("/person", data = "<person>")]
fn person2(person: Result<Person<'_>, Error>) { /* .. */ }
#[post("/person", data = "<person>")]
fn person3(person: Option<Person<'_>>) { /* .. */ }
#[post("/person", data = "<person>")]
fn person4(person: Person<'_>) -> &str {
// Note that this is only possible because the data in `person` live
// as long as the request through request-local cache.
person.name
}Required Associated Types§
Required Methods§
sourcefn from_data<'life0, 'async_trait>(
req: &'r Request<'life0>,
data: Data<'r>
) -> Pin<Box<dyn Future<Output = Outcome<'r, Self>> + Send + 'async_trait>>where
Self: 'async_trait,
'r: 'async_trait,
'life0: 'async_trait,
fn from_data<'life0, 'async_trait>( req: &'r Request<'life0>, data: Data<'r> ) -> Pin<Box<dyn Future<Output = Outcome<'r, Self>> + Send + 'async_trait>>where Self: 'async_trait, 'r: 'async_trait, 'life0: 'async_trait,
Asynchronously validates, parses, and converts an instance of Self
from the incoming request body data.
If validation and parsing succeeds, an outcome of Success is returned.
If the data is not appropriate given the type of Self, Forward is
returned. If parsing fails, Failure is returned.
Implementations on Foreign Types§
Implementors§
source§impl<'r, T: Deserialize<'r>> FromData<'r> for Json<T>
Available on crate feature json only.
impl<'r, T: Deserialize<'r>> FromData<'r> for Json<T>
json only.source§impl<'r, T: Deserialize<'r>> FromData<'r> for MsgPack<T>
Available on crate feature msgpack only.
impl<'r, T: Deserialize<'r>> FromData<'r> for MsgPack<T>
msgpack only.