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

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 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) -> Self::Future

Create a Self from request parts asynchronously.

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

Create a Self from request head asynchronously.

impl Stream for Payload

type Item = Result<Bytes, PayloadError>

Values yielded by the stream.

fn poll_next( self: Pin<&mut Self>, cx: &mut Context<'_>, ) -> Poll<Option<Self::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.