Struct Payload

pub struct Payload(/* private fields */);

Extract a request’s raw payload stream.

See PayloadConfig for important notes when using this advanced extractor.

Examples

use std::future::Future;
use futures_util::StreamExt as _;
use actix_web::{post, web};

// `body: web::Payload` parameter extracts raw payload stream from request
#[post("/")]
async fn index(mut body: web::Payload) -> actix_web::Result<String> {
    // for demonstration only; in a normal case use the `Bytes` extractor
    // collect payload stream into a bytes object
    let mut bytes = web::BytesMut::new();
    while let Some(item) = body.next().await {
        bytes.extend_from_slice(&item?);
    }

    Ok(format!("Request Body Bytes:\n{:?}", bytes))
}

Implementations

impl Payload

pub fn into_inner(self) -> Payload

Unwrap to inner Payload type.

pub async fn to_bytes_limited( self, limit: usize, ) -> Result<Result<Bytes, Error>, BodyLimitExceeded>

Buffers payload from request up to limit bytes.

This method is preferred over Payload::to_bytes() since it will not lead to unexpected memory exhaustion from massive payloads. Note that the other primitive extractors such as Bytes and String, as well as extractors built on top of them, already have this sort of protection according to the configured (or default) PayloadConfig.

Errors

• The outer error type, BodyLimitExceeded, is returned when the payload is larger than limit.
• The inner error type is the normal Actix Web error and is only returned if the payload stream yields an error for some reason. Such cases are usually caused by unrecoverable connection issues.

Examples

use actix_web::{error, web::Payload, Responder};

async fn limited_payload_handler(pl: Payload) -> actix_web::Result<impl Responder> {
    match pl.to_bytes_limited(5).await {
        Ok(res) => res,
        Err(err) => Err(error::ErrorPayloadTooLarge(err)),
    }
}

pub async fn to_bytes(self) -> Result<Bytes, Error>

Buffers entire payload from request.

Use of this method is discouraged unless you know for certain that requests will not be large enough to exhaust memory. If this is not known, prefer Payload::to_bytes_limited() or one of the higher level extractors like Bytes or String that implement size limits according to the configured (or default) PayloadConfig.

Errors

An error is only returned if the payload stream yields an error for some reason. Such cases are usually caused by unrecoverable connection issues.

Examples

use actix_web::{error, web::Payload, Responder};

async fn payload_handler(pl: Payload) -> actix_web::Result<impl Responder> {
    pl.to_bytes().await
}

Trait Implementations

impl Apiv2Schema for Payload

fn name() -> Option<String>

Name of this schema. This is the name to which the definition of the object is mapped.

fn description() -> &'static str

Description of this schema. In case the trait is derived, uses the documentation on the type.

fn required() -> bool

Indicates the requirement of this schema.

fn raw_schema() -> DefaultSchemaRaw

Returns the raw schema for this object.

fn schema_with_ref() -> DefaultSchemaRaw

Returns the schema with a reference (if this is an object).

fn security_scheme() -> Option<SecurityScheme>

Returns the security scheme for this object.

fn header_parameter_schema() -> Vec<Parameter<DefaultSchemaRaw>>

impl FromRequest for Payload

See here for example of usage as an extractor.

type Error = Error

The associated error which can be returned.

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

Future that resolves to a Self.

fn from_request( _: &HttpRequest, payload: &mut Payload, ) -> <Payload as FromRequest>::Future

Create a Self from request parts asynchronously.

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

Create a Self from request head asynchronously.

impl OperationModifier for Payload

fn update_parameter( op: &mut Operation<Parameter<DefaultSchemaRaw>, Response<DefaultSchemaRaw>>, )

Update the parameters list in the given operation (if needed).

fn update_response( _op: &mut Operation<Parameter<DefaultSchemaRaw>, Response<DefaultSchemaRaw>>, )

Update the responses map in the given operation (if needed).

fn update_definitions(map: &mut BTreeMap<String, DefaultSchemaRaw>)

Update the definitions map (if needed).

fn update_security( op: &mut Operation<Parameter<DefaultSchemaRaw>, Response<DefaultSchemaRaw>>, )

Update the security map in the given operation (if needed).

fn update_security_definitions(map: &mut BTreeMap<String, SecurityScheme>)

Update the security definition map (if needed).

impl Stream for Payload

type Item = Result<Bytes, PayloadError>

Values yielded by the stream.

fn poll_next( self: Pin<&mut Payload>, cx: &mut Context<'_>, ) -> Poll<Option<<Payload as Stream>::Item>>

Attempt to pull out the next value of this stream, registering the current task for wakeup if the value is not yet available, and returning None if the stream is exhausted.

fn size_hint(&self) -> (usize, Option<usize>)

Returns the bounds on the remaining length of the stream.