Trait FromRequest

pub trait FromRequest<Err>: Sized {
    type Error;

    // Required method
    fn from_request(
        req: &HttpRequest,
        payload: &mut Payload,
    ) -> impl Future<Output = Result<Self, Self::Error>>;
}

Trait implemented by types that can be extracted from request.

Types that implement this trait can be used with Route handlers.

Required Associated Types

type Error

The associated error which can be returned.

Required Methods

fn from_request( req: &HttpRequest, payload: &mut Payload, ) -> impl Future<Output = Result<Self, Self::Error>>

Convert request to a Self

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementations on Foreign Types

impl<Err: ErrorRenderer> FromRequest<Err> for String

Extract text information from a request’s body.

Text extractor automatically decode body according to the request’s charset.

PayloadConfig allows to configure extraction process.

Example

use ntex::web::{self, App, FromRequest};

/// extract text data from request
async fn index(text: String) -> String {
    format!("Body {}!", text)
}

fn main() {
    let app = App::new().service(
        web::resource("/index.html")
            .state(
                web::types::PayloadConfig::new(4096)  // <- limit size of the payload
            )
            .route(web::get().to(index))  // <- register handler with extractor params
    );
}

type Error = PayloadError

async fn from_request( req: &HttpRequest, payload: &mut Payload, ) -> Result<String, Self::Error>

impl<Err: ErrorRenderer, A: FromRequest<Err> + 'static> FromRequest<Err> for (A,)

where <A as FromRequest<Err>>::Error: Into<Err::Container>,

FromRequest implementation for a tuple

type Error = <Err as ErrorRenderer>::Container

async fn from_request( req: &HttpRequest, payload: &mut Payload, ) -> Result<(A,), Err::Container>

impl<Err: ErrorRenderer, A: FromRequest<Err> + 'static, B: FromRequest<Err> + 'static> FromRequest<Err> for (A, B)

where <A as FromRequest<Err>>::Error: Into<Err::Container>, <B as FromRequest<Err>>::Error: Into<Err::Container>,

FromRequest implementation for a tuple

type Error = <Err as ErrorRenderer>::Container

async fn from_request( req: &HttpRequest, payload: &mut Payload, ) -> Result<(A, B), Err::Container>

impl<Err: ErrorRenderer, A: FromRequest<Err> + 'static, B: FromRequest<Err> + 'static, C: FromRequest<Err> + 'static> FromRequest<Err> for (A, B, C)

where <A as FromRequest<Err>>::Error: Into<Err::Container>, <B as FromRequest<Err>>::Error: Into<Err::Container>, <C as FromRequest<Err>>::Error: Into<Err::Container>,

FromRequest implementation for a tuple

type Error = <Err as ErrorRenderer>::Container

async fn from_request( req: &HttpRequest, payload: &mut Payload, ) -> Result<(A, B, C), Err::Container>

impl<Err: ErrorRenderer, A: FromRequest<Err> + 'static, B: FromRequest<Err> + 'static, C: FromRequest<Err> + 'static, D: FromRequest<Err> + 'static> FromRequest<Err> for (A, B, C, D)

where <A as FromRequest<Err>>::Error: Into<Err::Container>, <B as FromRequest<Err>>::Error: Into<Err::Container>, <C as FromRequest<Err>>::Error: Into<Err::Container>, <D as FromRequest<Err>>::Error: Into<Err::Container>,

FromRequest implementation for a tuple

type Error = <Err as ErrorRenderer>::Container

async fn from_request( req: &HttpRequest, payload: &mut Payload, ) -> Result<(A, B, C, D), Err::Container>

impl<Err: ErrorRenderer, A: FromRequest<Err> + 'static, B: FromRequest<Err> + 'static, C: FromRequest<Err> + 'static, D: FromRequest<Err> + 'static, E: FromRequest<Err> + 'static> FromRequest<Err> for (A, B, C, D, E)

where <A as FromRequest<Err>>::Error: Into<Err::Container>, <B as FromRequest<Err>>::Error: Into<Err::Container>, <C as FromRequest<Err>>::Error: Into<Err::Container>, <D as FromRequest<Err>>::Error: Into<Err::Container>, <E as FromRequest<Err>>::Error: Into<Err::Container>,

FromRequest implementation for a tuple

type Error = <Err as ErrorRenderer>::Container

async fn from_request( req: &HttpRequest, payload: &mut Payload, ) -> Result<(A, B, C, D, E), Err::Container>

impl<Err: ErrorRenderer, A: FromRequest<Err> + 'static, B: FromRequest<Err> + 'static, C: FromRequest<Err> + 'static, D: FromRequest<Err> + 'static, E: FromRequest<Err> + 'static, F: FromRequest<Err> + 'static> FromRequest<Err> for (A, B, C, D, E, F)

where <A as FromRequest<Err>>::Error: Into<Err::Container>, <B as FromRequest<Err>>::Error: Into<Err::Container>, <C as FromRequest<Err>>::Error: Into<Err::Container>, <D as FromRequest<Err>>::Error: Into<Err::Container>, <E as FromRequest<Err>>::Error: Into<Err::Container>, <F as FromRequest<Err>>::Error: Into<Err::Container>,

FromRequest implementation for a tuple

type Error = <Err as ErrorRenderer>::Container

async fn from_request( req: &HttpRequest, payload: &mut Payload, ) -> Result<(A, B, C, D, E, F), Err::Container>

impl<Err: ErrorRenderer, A: FromRequest<Err> + 'static, B: FromRequest<Err> + 'static, C: FromRequest<Err> + 'static, D: FromRequest<Err> + 'static, E: FromRequest<Err> + 'static, F: FromRequest<Err> + 'static, G: FromRequest<Err> + 'static> FromRequest<Err> for (A, B, C, D, E, F, G)

where <A as FromRequest<Err>>::Error: Into<Err::Container>, <B as FromRequest<Err>>::Error: Into<Err::Container>, <C as FromRequest<Err>>::Error: Into<Err::Container>, <D as FromRequest<Err>>::Error: Into<Err::Container>, <E as FromRequest<Err>>::Error: Into<Err::Container>, <F as FromRequest<Err>>::Error: Into<Err::Container>, <G as FromRequest<Err>>::Error: Into<Err::Container>,

FromRequest implementation for a tuple

type Error = <Err as ErrorRenderer>::Container

async fn from_request( req: &HttpRequest, payload: &mut Payload, ) -> Result<(A, B, C, D, E, F, G), Err::Container>

impl<Err: ErrorRenderer, A: FromRequest<Err> + 'static, B: FromRequest<Err> + 'static, C: FromRequest<Err> + 'static, D: FromRequest<Err> + 'static, E: FromRequest<Err> + 'static, F: FromRequest<Err> + 'static, G: FromRequest<Err> + 'static, H: FromRequest<Err> + 'static> FromRequest<Err> for (A, B, C, D, E, F, G, H)

where <A as FromRequest<Err>>::Error: Into<Err::Container>, <B as FromRequest<Err>>::Error: Into<Err::Container>, <C as FromRequest<Err>>::Error: Into<Err::Container>, <D as FromRequest<Err>>::Error: Into<Err::Container>, <E as FromRequest<Err>>::Error: Into<Err::Container>, <F as FromRequest<Err>>::Error: Into<Err::Container>, <G as FromRequest<Err>>::Error: Into<Err::Container>, <H as FromRequest<Err>>::Error: Into<Err::Container>,

FromRequest implementation for a tuple

type Error = <Err as ErrorRenderer>::Container

async fn from_request( req: &HttpRequest, payload: &mut Payload, ) -> Result<(A, B, C, D, E, F, G, H), Err::Container>

impl<Err: ErrorRenderer, A: FromRequest<Err> + 'static, B: FromRequest<Err> + 'static, C: FromRequest<Err> + 'static, D: FromRequest<Err> + 'static, E: FromRequest<Err> + 'static, F: FromRequest<Err> + 'static, G: FromRequest<Err> + 'static, H: FromRequest<Err> + 'static, I: FromRequest<Err> + 'static> FromRequest<Err> for (A, B, C, D, E, F, G, H, I)

where <A as FromRequest<Err>>::Error: Into<Err::Container>, <B as FromRequest<Err>>::Error: Into<Err::Container>, <C as FromRequest<Err>>::Error: Into<Err::Container>, <D as FromRequest<Err>>::Error: Into<Err::Container>, <E as FromRequest<Err>>::Error: Into<Err::Container>, <F as FromRequest<Err>>::Error: Into<Err::Container>, <G as FromRequest<Err>>::Error: Into<Err::Container>, <H as FromRequest<Err>>::Error: Into<Err::Container>, <I as FromRequest<Err>>::Error: Into<Err::Container>,

FromRequest implementation for a tuple

type Error = <Err as ErrorRenderer>::Container

async fn from_request( req: &HttpRequest, payload: &mut Payload, ) -> Result<(A, B, C, D, E, F, G, H, I), Err::Container>

impl<Err: ErrorRenderer, A: FromRequest<Err> + 'static, B: FromRequest<Err> + 'static, C: FromRequest<Err> + 'static, D: FromRequest<Err> + 'static, E: FromRequest<Err> + 'static, F: FromRequest<Err> + 'static, G: FromRequest<Err> + 'static, H: FromRequest<Err> + 'static, I: FromRequest<Err> + 'static, J: FromRequest<Err> + 'static> FromRequest<Err> for (A, B, C, D, E, F, G, H, I, J)

where <A as FromRequest<Err>>::Error: Into<Err::Container>, <B as FromRequest<Err>>::Error: Into<Err::Container>, <C as FromRequest<Err>>::Error: Into<Err::Container>, <D as FromRequest<Err>>::Error: Into<Err::Container>, <E as FromRequest<Err>>::Error: Into<Err::Container>, <F as FromRequest<Err>>::Error: Into<Err::Container>, <G as FromRequest<Err>>::Error: Into<Err::Container>, <H as FromRequest<Err>>::Error: Into<Err::Container>, <I as FromRequest<Err>>::Error: Into<Err::Container>, <J as FromRequest<Err>>::Error: Into<Err::Container>,

FromRequest implementation for a tuple

type Error = <Err as ErrorRenderer>::Container

async fn from_request( req: &HttpRequest, payload: &mut Payload, ) -> Result<(A, B, C, D, E, F, G, H, I, J), Err::Container>

impl<T, E> FromRequest<E> for Result<T, T::Error>

where T: FromRequest<E>, E: ErrorRenderer,

Optionally extract a field from the request or extract the Error if unsuccessful

If the FromRequest for T fails, inject Err into handler rather than returning an error response

Example

use ntex::http;
use ntex::web::{self, error, App, HttpRequest, FromRequest};
use rand;

#[derive(Debug, serde::Deserialize)]
struct Thing {
    name: String
}

impl<Err> FromRequest<Err> for Thing {
    type Error = error::Error;

    async fn from_request(req: &HttpRequest, payload: &mut http::Payload) -> Result<Thing, Self::Error> {
        if rand::random() {
            Ok(Thing { name: "thingy".into() })
        } else {
            Err(error::ErrorBadRequest("no luck").into())
        }
    }
}

/// extract `Thing` from request
async fn index(supplied_thing: Result<Thing, error::Error>) -> String {
    match supplied_thing {
        Ok(thing) => format!("Got thing: {:?}", thing),
        Err(e) => format!("Error extracting thing: {}", e)
    }
}

fn main() {
    let app = App::new().service(
        web::resource("/users/:first").route(web::post().to(index))
    );
}

type Error = <T as FromRequest<E>>::Error

async fn from_request( req: &HttpRequest, payload: &mut Payload, ) -> Result<Self, Self::Error>

impl<T, Err> FromRequest<Err> for Option<T>

where T: FromRequest<Err>, Err: ErrorRenderer, <T as FromRequest<Err>>::Error: Into<Err::Container>,

Optionally extract a field from the request

If the FromRequest for T fails, return None rather than returning an error response

Example

use ntex::http;
use ntex::web::{self, error, App, HttpRequest, FromRequest, DefaultError};
use rand;

#[derive(Debug, serde::Deserialize)]
struct Thing {
    name: String
}

impl<Err> FromRequest<Err> for Thing {
    type Error = error::Error;

    async fn from_request(req: &HttpRequest, payload: &mut http::Payload) -> Result<Self, Self::Error> {
        if rand::random() {
            Ok(Thing { name: "thingy".into() })
        } else {
            Err(error::ErrorBadRequest("no luck").into())
        }
    }
}

/// extract `Thing` from request
async fn index(supplied_thing: Option<Thing>) -> String {
    match supplied_thing {
        // Puns not intended
        Some(thing) => format!("Got something: {:?}", thing),
        None => format!("No thing!")
    }
}

fn main() {
    let app = App::new().service(
        web::resource("/users/:first").route(
            web::post().to(index))
    );
}

type Error = <Err as ErrorRenderer>::Container

async fn from_request( req: &HttpRequest, payload: &mut Payload, ) -> Result<Option<T>, Self::Error>

Implementors

impl<Err: ErrorRenderer> FromRequest<Err> for Bytes

Request binary data from a request’s payload.

Loads request’s payload and construct Bytes instance.

PayloadConfig allows to configure extraction process.

Example

use ntex::{web, util::Bytes};

/// extract binary data from request
async fn index(body: Bytes) -> String {
    format!("Body {:?}!", body)
}

fn main() {
    let app = web::App::new().service(
        web::resource("/index.html").route(
            web::get().to(index))
    );
}

type Error = PayloadError

impl<Err: ErrorRenderer> FromRequest<Err> for HttpRequest

It is possible to get HttpRequest as an extractor handler parameter

Example

use ntex::web::{self, App, HttpRequest};

/// extract `HttpRequest` from request
async fn index(req: HttpRequest) -> String {
   format!("Got thing: {:?}", req)
}

fn main() {
    let app = App::new().service(
        web::resource("/users/{first}").route(
            web::get().to(index))
    );
}

type Error = <Err as ErrorRenderer>::Container

impl<Err: ErrorRenderer> FromRequest<Err> for Payload

Get request’s payload stream

Example

use std::future::Future;
use ntex::util::{BytesMut, Stream};
use ntex::web::{self, error, App, Error, HttpResponse};

/// extract binary data from request
async fn index(mut body: web::types::Payload) -> Result<HttpResponse, error::PayloadError>
{
    let mut bytes = BytesMut::new();
    while let Some(item) = ntex::util::stream_recv(&mut body).await {
        bytes.extend_from_slice(&item?);
    }

    format!("Body {:?}!", bytes);
    Ok(HttpResponse::Ok().finish())
}

fn main() {
    let app = App::new().service(
        web::resource("/index.html").route(
            web::get().to(index))
    );
}

type Error = <Err as ErrorRenderer>::Container

impl<T, Err> FromRequest<Err> for Form<T>

where T: DeserializeOwned + 'static, Err: ErrorRenderer,

type Error = UrlencodedError

impl<T, Err> FromRequest<Err> for Query<T>

where T: DeserializeOwned, Err: ErrorRenderer,

Extract typed information from the request’s query.

Example

use ntex::web;

#[derive(Debug, serde::Deserialize)]
pub enum ResponseType {
   Token,
   Code
}

#[derive(serde::Deserialize)]
pub struct AuthRequest {
   id: u64,
   response_type: ResponseType,
}

// Use `Query` extractor for query information.
// This handler get called only if request's query contains `username` field
// The correct request for this handler would be `/index.html?id=64&response_type=Code"`
async fn index(info: web::types::Query<AuthRequest>) -> String {
    format!("Authorization request for client with id={} and type={:?}!", info.id, info.response_type)
}

fn main() {
    let app = web::App::new().service(
       web::resource("/index.html")
           .route(web::get().to(index))); // <- use `Query` extractor
}

type Error = QueryPayloadError

impl<T, Err: ErrorRenderer> FromRequest<Err> for Json<T>

where T: DeserializeOwned + 'static,

Json extractor. Allow to extract typed information from request’s payload.

To extract typed information from request’s body, the type T must implement the Deserialize trait from serde.

JsonConfig allows to configure extraction process.

Example

use ntex::web;

#[derive(serde::Deserialize)]
struct Info {
    username: String,
}

/// deserialize `Info` from request's body
async fn index(info: web::types::Json<Info>) -> String {
    format!("Welcome {}!", info.username)
}

fn main() {
    let app = web::App::new().service(
        web::resource("/index.html").route(
           web::post().to(index))
    );
}

type Error = JsonPayloadError

impl<T, Err: ErrorRenderer> FromRequest<Err> for Path<T>

where T: DeserializeOwned,

Extract typed information from the request’s path.

Example

use ntex::web;

/// extract path info from "/{username}/{count}/index.html" url
/// {username} - deserializes to a String
/// {count} -  - deserializes to a u32
async fn index(info: web::types::Path<(String, u32)>) -> String {
    format!("Welcome {}! {}", info.0, info.1)
}

fn main() {
    let app = web::App::new().service(
        web::resource("/{username}/{count}/index.html") // <- define path parameters
             .route(web::get().to(index)) // <- register handler with `Path` extractor
    );
}

It is possible to extract path information to a specific type that implements Deserialize trait from serde.

use ntex::web;

#[derive(serde::Deserialize)]
struct Info {
    username: String,
}

/// extract `Info` from a path using serde
async fn index(info: web::types::Path<Info>) -> Result<String, web::Error> {
    Ok(format!("Welcome {}!", info.username))
}

fn main() {
    let app = web::App::new().service(
        web::resource("/{username}/index.html") // <- define path parameters
             .route(web::get().to(index)) // <- use handler with Path` extractor
    );
}

type Error = PathError

impl<T: 'static, E: ErrorRenderer> FromRequest<E> for State<T>

type Error = StateExtractorError