Trait FromRequest

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 { ... }
}

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:

• App::app_data()
• Scope::app_data()
• Resource::app_data()

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

Extractor	Configuration
Header	None
Path	PathConfig
Json	JsonConfig
Form	FormConfig
Query	QueryConfig
Bytes	PayloadConfig
String	PayloadConfig
Payload	PayloadConfig

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

type Error: Into<Error>

The associated error which can be returned.

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

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

Create a Self from request parts asynchronously.

Provided Methods

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).

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 FromRequest for ()

type Error = Infallible

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

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

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>>>

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

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

FromRequest implementation for tuple

type Error = Error

type Future = TupleFromRequest1<A>

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

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

FromRequest implementation for tuple

type Error = Error

type Future = TupleFromRequest2<A, B>

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

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>

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

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>

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

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>

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

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>

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

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>

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

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>

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

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>

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

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>

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

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>

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

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>

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

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, M: FromRequest + 'static> FromRequest for (A, B, C, D, E, F, G, H, I, J, K, L, M)

FromRequest implementation for tuple

type Error = Error

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

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

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, M: FromRequest + 'static, N: FromRequest + 'static> FromRequest for (A, B, C, D, E, F, G, H, I, J, K, L, M, N)

FromRequest implementation for tuple

type Error = Error

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

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

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, M: FromRequest + 'static, N: FromRequest + 'static, O: FromRequest + 'static> FromRequest for (A, B, C, D, E, F, G, H, I, J, K, L, M, N, O)

FromRequest implementation for tuple

type Error = Error

type Future = TupleFromRequest15<A, B, C, D, E, F, G, H, I, J, K, L, M, N, O>

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

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, M: FromRequest + 'static, N: FromRequest + 'static, O: FromRequest + 'static, P: FromRequest + 'static> FromRequest for (A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P)

FromRequest implementation for tuple

type Error = Error

type Future = TupleFromRequest16<A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P>

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

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>

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

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(err) => format!("Error extracting thing: {err}"),
    }
}

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>

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

Implementors

impl FromRequest for ConnectionInfo

type Error = Infallible

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

impl FromRequest for PeerAddr

type Error = MissingPeerAddr

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

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));

type Error = Infallible

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

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));

type Error = Infallible

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

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))
);

type Error = Error

type Future = Ready<Result<HttpRequest, Error>>

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>>>

impl FromRequest for Payload

See here for example of usage as an extractor.

type Error = Error

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

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>

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>

impl<T> FromRequest for Header<T>

where T: ParseHeader,

type Error = ParseError

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

impl<T> FromRequest for Path<T>

where T: DeserializeOwned,

See here for example of usage as an extractor.

type Error = Error

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

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

type Error = Error

type Future = Ready<Result<ReqData<T>, Error>>

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

type Error = Error

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

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

See here for example of usage as an extractor.

type Error = Error

type Future = JsonExtractFut<T>

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

See here for example of usage as an extractor.

type Error = Error

type Future = Ready<Result<Query<T>, Error>>

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

type Error = Error

type Future = Ready<Result<Data<T>, Error>>