pub trait FromRequest: Sized {
    type Error: Into<Error>;
    type Future: Future<Output = Result<Self, Self::Error>>;

    // Required method
    fn from_request(req: &HttpRequest, payload: &mut Payload) -> Self::Future;

    // Provided method
    fn extract(req: &HttpRequest) -> Self::Future { ... }
}
Expand description

A type that implements FromRequest is called an extractor and can extract data from the request. Some types that implement this trait are: Json, Header, and Path.

Check out ServiceRequest::extract if you want to leverage extractors when implementing middlewares.

Configuration

An extractor can be customized by injecting the corresponding configuration with one of:

Here are some built-in extractors and their corresponding configuration. Please refer to the respective documentation for details.

Implementing An Extractor

To reduce duplicate code in handlers where extracting certain parts of a request has a common structure, you can implement FromRequest for your own types.

Note that the request payload can only be consumed by one extractor.

Required Associated Types§

source

type Error: Into<Error>

The associated error which can be returned.

source

type Future: Future<Output = Result<Self, Self::Error>>

Future that resolves to a Self.

To use an async function or block, the futures must be boxed. The following snippet will be common when creating async/await extractors (that do not consume the body).

type Future = Pin<Box<dyn Future<Output = Result<Self, Self::Error>>>>;
// or
type Future = futures_util::future::LocalBoxFuture<'static, Result<Self, Self::Error>>;

fn from_request(req: HttpRequest, ...) -> Self::Future {
    let req = req.clone();
    Box::pin(async move {
        ...
    })
}

Required Methods§

source

fn from_request(req: &HttpRequest, payload: &mut Payload) -> Self::Future

Create a Self from request parts asynchronously.

Provided Methods§

source

fn extract(req: &HttpRequest) -> Self::Future

Create a Self from request head asynchronously.

This method is short for T::from_request(req, &mut Payload::None).

Implementations on Foreign Types§

source§

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

FromRequest implementation for tuple

§

type Error = Error

§

type Future = TupleFromRequest5<A, B, C, D, E>

source§

fn from_request(req: &HttpRequest, payload: &mut Payload) -> Self::Future

source§

impl FromRequest for ()

source§

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

FromRequest implementation for tuple

§

type Error = Error

§

type Future = TupleFromRequest11<A, B, C, D, E, F, G, H, I, J, K>

source§

fn from_request(req: &HttpRequest, payload: &mut Payload) -> Self::Future

source§

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

FromRequest implementation for tuple

§

type Error = Error

§

type Future = TupleFromRequest8<A, B, C, D, E, F, G, H>

source§

fn from_request(req: &HttpRequest, payload: &mut Payload) -> Self::Future

source§

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

FromRequest implementation for tuple

§

type Error = Error

§

type Future = TupleFromRequest9<A, B, C, D, E, F, G, H, I>

source§

fn from_request(req: &HttpRequest, payload: &mut Payload) -> Self::Future

source§

impl<T> FromRequest for Option<T>where T: FromRequest,

Optionally extract from the request.

If the inner T::from_request returns an error, handler will receive None instead.

Examples

use actix_web::{web, dev, App, Error, HttpRequest, FromRequest};
use actix_web::error::ErrorBadRequest;
use futures_util::future::{ok, err, Ready};
use serde::Deserialize;
use rand;

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

impl FromRequest for Thing {
    type Error = Error;
    type Future = Ready<Result<Self, Self::Error>>;

    fn from_request(req: &HttpRequest, payload: &mut dev::Payload) -> Self::Future {
        if rand::random() {
            ok(Thing { name: "thingy".into() })
        } else {
            err(ErrorBadRequest("no luck"))
        }

    }
}

/// 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!")
    }
}

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

type Error = Infallible

§

type Future = FromRequestOptFuture<<T as FromRequest>::Future>

source§

fn from_request(req: &HttpRequest, payload: &mut Payload) -> Self::Future

source§

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

FromRequest implementation for tuple

§

type Error = Error

§

type Future = TupleFromRequest10<A, B, C, D, E, F, G, H, I, J>

source§

fn from_request(req: &HttpRequest, payload: &mut Payload) -> Self::Future

source§

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

FromRequest implementation for tuple

§

type Error = Error

§

type Future = TupleFromRequest7<A, B, C, D, E, F, G>

source§

fn from_request(req: &HttpRequest, payload: &mut Payload) -> Self::Future

source§

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

FromRequest implementation for tuple

§

type Error = Error

§

type Future = TupleFromRequest1<A>

source§

fn from_request(req: &HttpRequest, payload: &mut Payload) -> Self::Future

source§

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

Extract from the request, passing error type through to handler.

If the inner T::from_request returns an error, allow handler to receive the error rather than immediately returning an error response.

Examples

use actix_web::{web, dev, App, Result, Error, HttpRequest, FromRequest};
use actix_web::error::ErrorBadRequest;
use futures_util::future::{ok, err, Ready};
use serde::Deserialize;
use rand;

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

impl FromRequest for Thing {
    type Error = Error;
    type Future = Ready<Result<Thing, Error>>;

    fn from_request(req: &HttpRequest, payload: &mut dev::Payload) -> Self::Future {
        if rand::random() {
            ok(Thing { name: "thingy".into() })
        } else {
            err(ErrorBadRequest("no luck"))
        }
    }
}

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

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

type Error = Infallible

§

type Future = FromRequestResFuture<<T as FromRequest>::Future, E>

source§

fn from_request(req: &HttpRequest, payload: &mut Payload) -> Self::Future

source§

impl FromRequest for String

Extract text information from a request’s body.

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

Use PayloadConfig to configure extraction process.

Examples

use actix_web::{post, web, FromRequest};

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

type Error = Error

§

type Future = Either<StringExtractFut, Ready<Result<String, Error>>>

source§

fn from_request(req: &HttpRequest, payload: &mut Payload) -> Self::Future

source§

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

FromRequest implementation for tuple

§

type Error = Error

§

type Future = TupleFromRequest2<A, B>

source§

fn from_request(req: &HttpRequest, payload: &mut Payload) -> Self::Future

source§

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

FromRequest implementation for tuple

§

type Error = Error

§

type Future = TupleFromRequest4<A, B, C, D>

source§

fn from_request(req: &HttpRequest, payload: &mut Payload) -> Self::Future

source§

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

FromRequest implementation for tuple

§

type Error = Error

§

type Future = TupleFromRequest12<A, B, C, D, E, F, G, H, I, J, K, L>

source§

fn from_request(req: &HttpRequest, payload: &mut Payload) -> Self::Future

source§

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

FromRequest implementation for tuple

§

type Error = Error

§

type Future = TupleFromRequest3<A, B, C>

source§

fn from_request(req: &HttpRequest, payload: &mut Payload) -> Self::Future

source§

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

FromRequest implementation for tuple

§

type Error = Error

§

type Future = TupleFromRequest6<A, B, C, D, E, F>

source§

fn from_request(req: &HttpRequest, payload: &mut Payload) -> Self::Future

Implementors§

source§

impl FromRequest for ConnectionInfo

source§

impl FromRequest for PeerAddr

§

type Error = MissingPeerAddr

§

type Future = Ready<Result<PeerAddr, <PeerAddr as FromRequest>::Error>>

source§

impl FromRequest for Method

Extract the request’s method.

Examples

use actix_web::{http::Method, web, App, Responder};

async fn handler(method: Method) -> impl Responder {
    format!("Request method: {}", method)
}

let app = App::new().default_service(web::to(handler));
source§

impl FromRequest for Uri

Extract the request’s URI.

Examples

use actix_web::{http::Uri, web, App, Responder};

async fn handler(uri: Uri) -> impl Responder {
    format!("Requested path: {}", uri.path())
}

let app = App::new().default_service(web::to(handler));
source§

impl FromRequest for HttpRequest

It is possible to get HttpRequest as an extractor handler parameter

Examples

use actix_web::{web, App, HttpRequest};
use serde::Deserialize;

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

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

impl FromRequest for Bytes

Extract binary data from a request’s payload.

Collects request payload stream into a Bytes instance.

Use PayloadConfig to configure extraction process.

Examples

use actix_web::{post, web};

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

type Error = Error

§

type Future = Either<BytesExtractFut, Ready<Result<Bytes, Error>>>

source§

impl FromRequest for Payload

See here for example of usage as an extractor.

source§

impl<L, R> FromRequest for Either<L, R>where L: FromRequest + 'static, R: FromRequest + 'static,

See here for example of usage as an extractor.

§

type Error = EitherExtractError<<L as FromRequest>::Error, <R as FromRequest>::Error>

§

type Future = EitherExtractFut<L, R>

source§

impl<T> FromRequest for Form<T>where T: DeserializeOwned + 'static,

See here for example of usage as an extractor.

§

type Error = Error

§

type Future = FormExtractFut<T>

source§

impl<T> FromRequest for Header<T>where T: ParseHeader,

source§

impl<T> FromRequest for Path<T>where T: DeserializeOwned,

See here for example of usage as an extractor.

source§

impl<T: DeserializeOwned> FromRequest for Json<T>

See here for example of usage as an extractor.

§

type Error = Error

§

type Future = JsonExtractFut<T>

source§

impl<T: DeserializeOwned> FromRequest for Query<T>

See here for example of usage as an extractor.

source§

impl<T: Clone + 'static> FromRequest for ReqData<T>

source§

impl<T: ?Sized + 'static> FromRequest for Data<T>