logo

Trait actix_web::FromRequest[−][src]

pub trait FromRequest: Sized {
    type Error: Into<Error>;
    type Future: Future<Output = Result<Self, Self::Error>>;
    type Config: Default + 'static;
    fn from_request(req: &HttpRequest, payload: &mut Payload) -> Self::Future;

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

    fn configure<F>(f: F) -> Self::Config
    where
        F: FnOnce(Self::Config) -> Self::Config,
    { ... }
}
Expand description

Trait implemented by types that can be extracted from request.

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

Associated Types

The associated error which can be returned.

Future that resolves to a Self

Configuration for this extractor

Required methods

Convert request to a Self

Provided methods

Convert request to a Self

This method uses Payload::None as payload stream.

Create and configure config instance.

Implementations on Foreign Types

Optionally extract a field from the request

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

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

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

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

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

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

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 actix_web::{web, dev, App, Result, Error, HttpRequest, FromRequest};
use actix_web::error::ErrorBadRequest;
use futures_util::future::{ok, err, Ready};
use serde_derive::Deserialize;
use rand;

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

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

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

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

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 actix_web::{web, 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")
            .app_data(String::configure(|cfg| {  // <- limit size of the payload
                cfg.limit(4096)
            }))
            .route(web::get().to(index))  // <- register handler with extractor params
    );
}

Implementors

Request binary data from a request’s payload.

Loads request’s payload and construct Bytes instance.

PayloadConfig allows to configure extraction process.

Example
use bytes::Bytes;
use actix_web::{web, App};

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

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

It is possible to get HttpRequest as an extractor handler parameter

Example
use actix_web::{web, App, HttpRequest};
use serde_derive::Deserialize;

/// extract `Thing` 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))
    );
}

Get request’s payload stream

Example
use actix_web::{web, error, App, Error, HttpResponse};
use std::future::Future;
use futures_core::stream::Stream;
use futures_util::StreamExt;

/// extract binary data from request
async fn index(mut body: web::Payload) -> Result<HttpResponse, Error>
{
    let mut bytes = web::BytesMut::new();
    while let Some(item) = body.next().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))
    );
}

Provides a mechanism for trying two extractors, a primary and a fallback. Useful for “polymorphic payloads” where, for example, a form might be JSON or URL encoded.

It is important to note that this extractor, by necessity, buffers the entire request payload as part of its implementation. Though, it does respect a PayloadConfig’s maximum size limit.

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 actix_web::{web, App};
use serde_derive::Deserialize;

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

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

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

Extract typed information from the request’s path.

Example
use actix_web::{web, App};

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

fn main() {
    let app = 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 actix_web::{web, App, Error};
use serde_derive::Deserialize;

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

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

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

Extract typed information from the request’s query.

Example
use actix_web::{web, App};
use serde_derive::Deserialize;

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

#[derive(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 `id` and `response_type` fields.
// The correct request for this handler would be `/index.html?id=64&response_type=Code"`
async fn index(info: web::Query<AuthRequest>) -> String {
    format!("Authorization request for client with id={} and type={:?}!", info.id, info.response_type)
}

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